Google is committed to advancing racial equity for Black communities. See how.

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

NameType
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

NameType
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

NameType
rx vector<RxBuffer>

StatusChanged

Notifies interface of changes to device status.

Request

NameType
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

NameType

Response

NameType
info DeviceInfo

GetStatus

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

Request

NameType

Response

NameType
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

NameType
iface NetworkDeviceIfc

Response

NameType
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

NameType
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

NameType
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

NameType
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

NameType
vmo_id uint8

SetSnoop

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

Request

NameType
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

NameType

Response

NameType

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

NameType

Response

NameType

STRUCTS

BufferData

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

A buffer representation that references the data inside a VMO.

NameTypeDescriptionDefault
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.

NameTypeDescriptionDefault
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.

NameTypeDescriptionDefault
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.

NameTypeDescriptionDefault
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.

NameTypeDescriptionDefault
nothing uint8 No default

RxBuffer

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

A buffer containing a single frame received by the device.

NameTypeDescriptionDefault
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.

NameTypeDescriptionDefault
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.

NameTypeDescriptionDefault
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.

NameTypeDescriptionDefault
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.

NameTypeDescriptionDefault
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

NameTypeDescriptionDefault
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.

NameTypeDescription
no_info NoInfo

No extra frame metadata.

CONSTANTS

NameValueTypeDescription
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)