lneto Userspace Networking Library

The StackNode interface is the core abstraction implemented by networking stack nodes and the stack itself. It defines how data is encapsulated, demultiplexed, and identified within the stack.

Implementations of StackNode are used to build up the layers of the networking stack (e.g., moving from Ethernet to IPv4 to TCP).

type StackNode interface {
    // Encapsulate receives a buffer the receiver must fill with data.
    // The receiver's start byte is at carrierData[offsetToFrame].
    Encapsulate(carrierData []byte, offsetToIP, offsetToFrame int) (int, error)
    // Demux receives a buffer the receiver must decode and pass on to corresponding child StackNode(s).
    // The receiver's start byte is at carrierData[offsetToFrame].
    Demux(carrierData []byte, offsetToFrame int) error
    // LocalPort returns the port of the node if applicable or zero. Used for UDP/TCP nodes.
    LocalPort() uint16
    // Protocol returns the protocol of this node if applicable or zero. Usually either an ethernet.Type (EtherType) or lneto.IPProto (IP Protocol number).
    Protocol() uint64
    // ConnectionID returns a pointer to the connection ID of the StackNode.
    // A change in the ID means the node is no longer valid and should be discarded.
    // A change in the ID could mean the connection was closed by the user or that the node will not send nor receive any more data over said connection ID.
    ConnectionID() *uint64
}

The RMII receive path uses RXD[1:0] for data and CRS_DV as a combined carrier sense and data valid signal.

Signal Behaviors

• CRS_DV: Combines Carrier Sense (CRS) and Data Valid (DV).
  • CRS: Asserted when the medium is non-idle. Loss of carrier deasserts CRS_DV synchronously to REF_CLK.
  • DV: Indicates data is valid. Note that RXD[1:0] is considered valid once CRS_DV is asserted, but may be asynchronous to REF_CLK initially (appearing as 0b00 until decoding occurs).
  • End of packet toggle: If the carrier ends before the PHY's elasticity buffer is empty, CRS_DV may toggle at a nibble rate (HIGH on the second dibit, LOW on the first dibit of each nibble) to indicate carrier loss while data is still valid.
• RXD[1:0]: Transitions synchronously to REF_CLK. It transfers two bits (a dibit) per clock period while CRS_DV is asserted. When idle (CRS_DV low), it remains 0b00.
• RX_ER: A synchronous signal to REF_CLK. It is asserted for one or more periods to indicate a frame error (e.g., 4B/5B invalid code, bad SFD, signal amplitude issues, or FIFO overflow). If RX_ER is not checkable, the MAC should rely on CRC validation.
• RX_DV (Optional): Some PHYs provide a dedicated RX_DV signal. It is asserted with the first recovered data (preamble) and deasserted after the final dibit. Full-duplex MACs can use this to avoid deriving DV from CRS_DV.

RMII requires a continuous 50 MHz reference clock. There are two primary modes for managing this clock:

1. Clock Source Mode (PHY is clock source)

In this mode, the PHY generates the 50 MHz clock for the MAC.

• Setup: The PHY takes a 25 MHz crystal/oscillator on its XI/XO pins and uses an internal PLL to multiply it to 50 MHz.
• Output: The PHY outputs the 50 MHz signal on the REF_CLK pin to the MAC.
• Examples: KSZ8081RNA (default), LAN8720A (with nINTSEL pin low at reset).

2. Clock Follower Mode (MAC is clock source)

In this mode, an external clock source drives both the PHY and the MAC.

• Setup: An external 50 MHz oscillator feeds both the PHY (XI pin) and the MAC.
• PHY Connection: The PHY REF_CLK pin is either left unconnected or used as an input.
• Example: DP83826 in RMII follower mode.

Typical Clock Specifications:

• Frequency: 50 MHz ±50 ppm
• Duty cycle: 40-60%
• Jitter: <150 ps peak-to-peak

To correctly receive frames via the RMII interface, follow this sequence:

1. Monitor CRS_DV: Watch for the signal to assert.
2. Detect SFD: Wait for the Start of Frame Delimiter (SFD) pattern, which consists of dibits ending in 11 (representing the 0xD5 byte).
3. Sample Data: Sample RXD[1:0] on every REF_CLK rising edge while DV is asserted (note that CRS_DV may toggle if the carrier drops before the buffer is empty).
4. Error Checking: Ensure RX_ER was not asserted during the frame. Some PHYs may emit invalid data on RX[1:0] after an error.
5. Reassemble Bytes: Assemble the received dibits into bytes using LSB first order.
6. Validate: Perform a CRC32 check on the assembled frame to ensure integrity.

1. Monitor CRS_DV for assertion
2. Wait for SFD pattern: dibits ending in "11" (0xD5 byte)
3. Sample RXD[1:0] on each REF_CLK rising while DV asserted (CRS_DV may toggle for DV assert)
4. Check RX_ER was never asserted during frame.
5. Assemble dibits into bytes (LSB first, same as Tx)
6. Validate CRC32 on assembled frame

To use httphi, you define your routes using a httphi.MuxSlice, configure a httphi.Router with fixed resource limits, and then manually pass connections (implementing io.ReadWriteCloser) to the router's Handle method.

Note that accepting connections is the responsibility of the caller. If router.Handle(conn) returns an error, the connection should be closed immediately. This error typically indicates the router has refused the connection because it has reached its pre-allocated capacity.

var mux httphi.MuxSlice
mux.Handle("GET /", func(ex *httphi.Exchange) {
	ex.WriteBody([]byte("hello world"))
})

var router httphi.Router
// numWorkers, memoryPerConn, and mux.MaxPathValues() are configuration parameters
cfg := httphi.DefaultRouterConfig(numWorkers, memoryPerConn, mux.MaxPathValues())
err := router.Configure(&mux, cfg)
if err != nil {
	log.Fatal(err)
}

for {
	conn, err := listener.Accept() // Accepting is the caller's job.
	if err != nil {
		log.Fatal(err)
	}
	if err = router.Handle(conn); err != nil {
		conn.Close() // Refused: never blocks, never queues unboundedly.
	}
}