fuchsia.hardware.network.device

Generic Network Device interface.

The definitions herein provide the API surface to expose a hardware device as a network device interface to the system through the FIDL protocol fuchsia.hardware.network/Device. A network device interface is the data-plane contract that allows the networking stack to send and receive frames on a physical or virtual network. A device exposes this capability by implementing the NetworkDeviceImpl protocol, which allows a middleware implementation to bind to it and offer the FIDL protocol to applications.

The API contract is based on three key concepts:

Frame Types
Receive and Transmit buffers
BufferData memory layout

Frame Types are the defined contract that is exposed to applications, which convey the data type contained in a tx or rx buffer. The supported frame types are defined in fuchsia.hardware.network/FrameType. Upon initialization, the middleware implementation will fetch the supported frame types from the device through the GetInfo call.

Receive and Transmit buffers are buffers that are headed to different directions: a receive buffer is a piece of data that is received from the network, and makes its way to the application layer. A transmit buffer travels in the opposite direction: it originates in the application layer and makes its way out into the network. The device implementation receives buffers from the NetworkDeviceIfc, which is offered by the middleware implementation.

A receive buffer flows from NetworkDeviceIfc into NetworkDeviceImpl through the NetworkDeviceImpl.QueueRxSpace method, which gives access to receive buffers. The diagram below illustrates the mechanism:

++++++++++++++++++++++++++++ +++++++++++++++++++++++ | (1) | => RxSpaceBuffer => | (2) | | NetworkDeviceIfc | | NetworkDeviceImpl | | (4) | <= RxBuffer <= | (3) | <= Network data ++++++++++++++++++++++++++++ +++++++++++++++++++++++

(1) NetworkDeviceIfc pushes available rx buffer space to NetworkDeviceImpl through NetworkDeviceImpl.QueueRxSpace. (2) NetworkDeviceImpl retains the available space buffers until network data comes in. (3) NetworkDeviceImpl receives data from the network, stores it in one of its available RxSpaceBuffers, making it an NetworkDeviceImpl.RxBuffer. (4) NetworkDeviceImpl sends the fulfilled RxBuffer to NetworkDeviceIfc through NetworkDeviceIfc.CompleteRx, which, in turn, sends that data over to applications.

A receive buffer flows from NetworkDeviceIfc into NetworkDeviceImpl through the NetworkDeviceImpl.QueueTx method, and it's returned to NetworkDeviceIfc as a TxResult. The diagram below illustrates the mechanism:

++++++++++++++++++++++++++++ +++++++++++++++++++++++ | (1) | => TxBuffer => | (2) | | NetworkDeviceIfc | | NetworkDeviceImpl | | (4) | <= TxResult <= | (3) | => Network data ++++++++++++++++++++++++++++ +++++++++++++++++++++++

(1) NetworkDeviceIfc receives a transmit buffer from applications filled with data intended to be delivered to the network. (2) NetworkDeviceIfc pushes the buffer into NetworkDeviceImpl through the NetworkDeviceImpl.QueueTx call. (3) NetworkDeviceImpl sends the data contained in the buffer out into the network. (4) When the data is successfully transmitted, NetworkDeviceImpl marks the transmission as complete referencing the buffer's identifier to NetworkDeviceIfc.CompleteTx.

PROTOCOLS

NetworkDeviceIfc

Defined in fuchsia.hardware.network.device/network-device.banjo

CompleteRx

Notifies interface of incoming rx data, contained in RxBuffer. Callers should attempt to batch as many buffers as possible in a single call. Number of buffers in a single call must be limited to the DeviceInfo.rx_depth reported by the NetworkDeviceImpl that is returning the buffers. By calling CompleteRx the caller relinquishes ownership of all buffers that are being marked as complete.

Request

Name	Type
`rx`	`vector<RxBuffer>`

CompleteTx

Notifies interface of complete transmit buffers. Callers should attempt to batch as many buffers as possible in a single call. Number of buffers in a single call must be limited to the DeviceInfo.tx_depth reported by the NetworkDeviceImpl that is returning the buffers. By calling CompleteTx the caller relinquishes ownership of all buffers that are being returned.

Request

Name	Type
`tx`	`vector<TxResult>`

Snoop

Notifies interface of a snooped tx frame. Typically used by implementations that have the FEATURE_NO_AUTO_SNOOP bit set in DeviceInfo.device_features. Implementations that generate transmit traffic internally should use Snoop regardless of FEATURE_NO_AUTO_SNOOP being set. Snooped frames are ALWAYS outbound frames that are being fed back into the interface for traffic snooping. Device implementations need to call NetworkDeviceIfc.Snoop ONLY if NetworkDeviceImpl.SetSnoop was set to true by the interface, otherwise any buffers in Snoop will be ignored.

Request

Name	Type
`rx`	`vector<RxBuffer>`

StatusChanged

Notifies interface of changes to device status.

Request

Name	Type
`new_status`	`Status`

NetworkDeviceImpl

Defined in fuchsia.hardware.network.device/network-device.banjo

GetInfo

Gets information about the device. Device information must not change over the course of the lifetime of the device.

Request

Name	Type

Response

Name	Type
`info`	`DeviceInfo`

GetStatus

Gets operational status on the device. Changes to operational status must be reported on NetworkDeviceIfc.StatusChanged

Request

Name	Type

Response

Name	Type
`status`	`Status`

Init

Initializes the network device. Init is only called once during the lifetime of the device to register iface as the callback target for the Network Device implementation. Upon initialization, the device is expected to be in a "Stopped" state, the Start method will be called once the data path needs to be opened.

Request

Name	Type
`iface`	`NetworkDeviceIfc`

Response

Name	Type
`s`	`zx/status`

PrepareVmo

Informs device that a new VMO is being used to store frame data. Implementers must store the VMO handle referenced by vmo_id until NetworkDeviceImpl.ReleaseVmo is called with the same vmo_id.

Request

Name	Type
`vmo_id`	`uint8`
`vmo`	`handle<vmo>`

QueueRxSpace

Enqueues a list of rx buffer space on the network device. The driver takes ownership of the buffer and must complete the transaction (once network data arrives) using NetworkDeviceIfc.CompleteRx. The total number of outstanding rx buffers given to a device will never exceed the reported DeviceInfo.rx_depth value. Which also means that no more than rx_depth buffers are going to be informed at once in a single call to QueueRxSpace.

Request

Name	Type
`buffers`	`vector<RxSpaceBuffer>`

QueueTx

Enqueues a list of buffers for transmission on the network device. The driver takes ownership of the buffer and must complete the tx transaction by using NetworkDeviceIfc.CompleteTx operations once it is done with each buffer in buffers. The total number of outstanding tx buffers given to a device will never exceed the reported DeviceInfo.tx_depth value. Which also means that no more than tx_depth buffers are going to be informed at once in a single call to QueueTx.

Request

Name	Type
`buffers`	`vector<TxBuffer>`

ReleaseVmo

Device may dispose of all references to the VMO referenced by vmo_id, no more buffers will be sent with this identifier. ReleaseVmo is guaranteed to only be called when the implementation holds no buffers that reference that vmo_id.

Request

Name	Type
`vmo_id`	`uint8`

SetSnoop

Informs the device that it should start or stop reporting snooped transmit frames through NetworkDeviceIfc.Snoop.

Request

Name	Type
`snoop`	`bool`

Start

Starts the device's data path. start signals to the device implementation that it should bring up its data path and be ready to receive tx frames and iface will start accepting rx frames. The device is only considered started once Start returns. Until then, the contract guarantees that no other data-path calls will be made to the device (QueueTx, RxAvailable, Stop), implementers can safely assume or assert that this contract is upheld.

Request

Name	Type

Response

Name	Type

Stop

Stops the network device, data-path callbacks to the NetworkDeviceIfc are no longer allowed after Stop returns. Implementation may turn off the rx path on the underlying hardware upon receiving this call. Upon completion, no more calls can be made to open data path sessions with NetworkDeviceIfc (doing so is a logic error and may be protected by assertions) and all the data buffers that were previously held by the implementation are automatically returned back. Pending tx buffers will be returned with an incomplete error, and pending rx buffers will be reclaimed.

Request

Name	Type

Response

Name	Type

STRUCTS

BufferData

Defined in fuchsia.hardware.network.device/network-device.banjo

A buffer representation that references the data inside a VMO.

Name	Type	Description	Default
`vmo_id`	`uint8`	Identifier of VMO backing the data in this buffer. The VMO identifier matches the one reported to devices through NetworkDeviceImpl.PrepareVmo.	No default
`parts`	`vector<BufferRegion>[4]`	Regions of VMO holding frame data.	No default

BufferMetadata

Defined in fuchsia.hardware.network.device/network-device.banjo

Metadata associated with a TxBuffer or RxBuffer.

Name	Type	Description	Default
`info`	`FrameInfo`	Extra frame metadata information. The type of the FrameInfo union is defined by the value in `info_type`.	No default
`info_type`	`uint32`	Type of data in `info`, as defined in fuchsia.hardware.network/InfoType.	No default
`flags`	`uint32`	Frame tx or rx flags, as defined in fuchsia.hardware.network/RxFlags, fuchsia.hardware.network/txFlags, and fuchsia.hardware.network/TxReturnFlags.	No default
`frame_type`	`uint8`	Type of frame contained in this buffer, as defined in fuchsia.hardware.network/FrameType.	No default

BufferRegion

Defined in fuchsia.hardware.network.device/network-device.banjo

A contiguous memory region in BufferData.

Note that a BufferRegion is only contiguous in terms of the VMO it references, it does not necessarily translate into contiguous physical memory.

Name	Type	Description	Default
`offset`	`uint64`	Offset, in bytes, of data chunk in VMO.	No default
`length`	`uint64`	Length, in bytes, of data chunk in VMO.	No default

DeviceInfo

Defined in fuchsia.hardware.network.device/network-device.banjo

Static device information. DeviceInfo must not change for the entire lifetime of a device.

Name	Type	Description	Default
`device_features`	`uint32`	Device features	No default
`tx_depth`	`uint16`	Maximum depth of tx frames in device's outgoing queue.	No default
`rx_depth`	`uint16`	Maximum number of rx frames in a device's incoming queue.	No default
`rx_threshold`	`uint16`	Rx depth threshold at which the device should be fed new rx buffers. New buffer notifications from NetworkDeviceIfc may be skipped while the number of rx buffers held by the implementation is larger than `rx_threshold`. It is invalid to provide a value larger than `rx_depth`. `rx_threshold = rx_depth` is functionally equivalent to `rx_threshold = rx_depth - 1`. A large value (close to `rx_depth`) may cause considerable CPU thrash for small rx completion transaction sizes, while a small value may cause the implementation to be starved of buffers. The typical choice of value is `rx_depth / 2`.	No default
`device_class`	`uint8`	Device class, as defined in fuchsia.hardware.network/DeviceClass.	No default
`rx_types`	`vector<uint8>`	Supported rx frame types, as defined by fuchsia.hardware.network/FrameType.	No default
`tx_types`	`vector<TxSupport>`	Supported tx frame types.	No default
`max_buffer_length`	`uint32`	Maximum total length of buffers. May be set to zero for no maximum. Devices that do not support scatter-gather DMA may set this to a value smaller than a page size to guarantee compatibility. Can't be larger than `MAX_PHYSICAL_PARTS` pages.	No default
`buffer_alignment`	`uint32`	Alignment requirement for buffers relative to the start of VMOs. Must be greater than zero.	No default
`min_rx_buffer_length`	`uint32`	The minimum rx buffer length for correct operation, in bytes.	No default
`min_tx_buffer_length`	`uint32`	The minimum tx buffer length for correct operation, in bytes. This length accounts only for the buffer's body, and should not account for `tx_head_length` or `tx_tail_length`.	No default
`tx_head_length`	`uint16`	Number of bytes requested as header bytes on tx buffers. If set to zero, tx buffers will never contain header space. Otherwise, tx buffers will start at the beginning of the header space, and the header region will be informed.	No default
`tx_tail_length`	`uint16`	Number of bytes requested as tail bytes on tx buffers. If set to zero, tx buffers will never contain tail space. Otherwise, tx buffers will end at the end of the tail space, and the tail region will be informed.	No default
`rx_accel`	`vector<uint8>`	Available Rx acceleration flags for this device, as defined in fuchsia.hardware.network/RxAcceleration. `rx_accel` maps the `RX_ACCEL_*` flags in the frame descriptors with semantic acceleration features described by `RxAcceleration`. Position `n` of `rx_accel` conveys the meaning of the `RX_ACCEL_n` flag.	No default
`tx_accel`	`vector<uint8>`	Available tx acceleration flags for this device, as defined in fuchsia.hardware.network/TxAcceleration. `tx_accel` maps the `TX_ACCEL_*` flags in the frame descriptors with semantic acceleration features described by `TxAcceleration`. Position `n` of `tx_accel` conveys the meaning of the `TX_ACCEL_n` flag.	No default

NoInfo

Defined in fuchsia.hardware.network.device/network-device.banjo

No extra frame metadata, FrameInfo.info_type must be fuchsia.hardware.network/InfoType.NO_INFO.

Name	Type	Description	Default
`nothing`	`uint8`		No default

RxBuffer

Defined in fuchsia.hardware.network.device/network-device.banjo

A buffer containing a single frame received by the device.

Name	Type	Description	Default
`id`	`uint32`	The buffer identifier informed in the RxSpaceBuffer that originated this `RxBuffer`.	No default
`total_length`	`uint64`	The total length of bytes written in the RxSpaceBuffer referenced by `id`.	No default
`meta`	`BufferMetadata`	Metadata associated with buffer.	No default

RxSpaceBuffer

Defined in fuchsia.hardware.network.device/network-device.banjo

A buffer with allocated space to receive frames in. An RxSpaceBuffer must always be returned as an RxBuffer using NetworkDeviceIfc.CompleteRx.

Name	Type	Description	Default
`id`	`uint32`	Unique buffer identifier.	No default
`data`	`BufferData`	Description of data in this buffer.	No default

Status

Defined in fuchsia.hardware.network.device/network-device.banjo

Dynamic device information. Status reflects the operational status of a device, changes to status are reported through StatusChanged.

Name	Type	Description	Default
`mtu`	`uint32`	Device's maximum transmission unit.	No default
`flags`	`uint32`	Device status flags Status flags, as defined in fuchsia.hardware.network/Status.	No default

TxBuffer

Defined in fuchsia.hardware.network.device/network-device.banjo

A transmit buffer containing a single frame.

Name	Type	Description	Default
`id`	`uint32`	Unique buffer identifier.	No default
`data`	`BufferData`	Description of data in this buffer.	No default
`meta`	`BufferMetadata`	Metadata associated with this buffer.	No default
`head_length`	`uint16`	Length of header bytes in the data contained in this buffer. Will always be either 0 or the requested DeviceInfo.tx_head_length value. The head bytes are always at the beginning of the buffer.	No default
`tail_length`	`uint16`	Length of tail bytes in the data contained in this buffer. Will always be either 0 or the requested tx_tail_length value. The tail bytes are always at the end of the buffer.	No default

TxResult

Defined in fuchsia.hardware.network.device/network-device.banjo

The result of a tx operation, reported to NetworkDeviceIfc through NetworkDeviceIfc.CompleteTx.

Name Type Description Default

Name	Type	Description	Default
`id`	`uint32`	The buffer identifier informed in the TxBuffer that originated this `TxResult`.	No default
`status`	`zx/status`	The result status to report. `ZX_OK` if the frame was sent successfully. `ZX_ERR_NOT_SUPPORTED` if any of the frame's flags are not supported. `ZX_ERR_NO_RESOURCES` if the transmit failed to allocate space in its output queue for the frame. `ZX_ERR_UNAVAILABLE` if the device is offline (or went offline before getting a confirmation that the frame was sent).	No default

id

uint32

The buffer identifier informed in the TxBuffer that originated this TxResult.

No default

status

zx/status

The result status to report.

ZX_OK if the frame was sent successfully.
ZX_ERR_NOT_SUPPORTED if any of the frame's flags are not supported.
ZX_ERR_NO_RESOURCES if the transmit failed to allocate space in its output queue for the frame.
ZX_ERR_UNAVAILABLE if the device is offline (or went offline before getting a confirmation that the frame was sent).

No default

TxSupport

Defined in fuchsia.hardware.network.device/network-device.banjo

Supported tx frame types

Name	Type	Description	Default
`type`	`uint8`	The frame type this support entry refers to.	No default
`features`	`uint32`	The frame type-specific features supported.	No default
`supported_flags`	`uint32`	The flags supported for the given frame type.	No default

UNIONS

FrameInfo

Defined in fuchsia.hardware.network.device/network-device.banjo

Extra frame sidecar metadata stored in BufferMetadata.

Name	Type	Description
`no_info`	`NoInfo`	No extra frame metadata.

CONSTANTS

Name	Value	Type	Description
FEATURE_NO_AUTO_SNOOP	`1`	`uint32`	Disables automatic snooping for the device. The generic NetworkDevice layer typically automatically copies all tx traffic to any snooping clients. Devices may turn off that behavior by setting the `FEATURE_NO_AUTO_SNOOP` flag. Devices that disable auto-snooping SHOULD use the NetworkDeviceIfc.Snoop interface method to expose any tx frames they receive.
MAX_BUFFER_PARTS	`4`	`uint32`	Maximum number of BufferRegion parts in a BufferData.
MAX_VMOS	`32`	`uint8`	The maximum number of concurrent shared VMOs that may exist. Every vmo_id is guaranteed to exist in the range `[0, MAX_VMOS)`