fuchsia.hardware.network.driver

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
  • 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 a NetworkDeviceImpl.RxBuffer.
  • (4) NetworkDeviceImpl sends the fulfilled RxBuffer to NetworkDeviceIfc through NetworkDeviceIfc.CompleteRx, which, in turn, sends that data over to applications.

A transmit 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.
Added: HEAD

PROTOCOLS

MacAddr

Defined in fuchsia.hardware.network.driver/network-mac.fidl

GetAddress

Gets this device's MAC address.

Request

<EMPTY>

Response

NameType
mac fuchsia.net/MacAddress

GetFeatures

Gets this device's features.

Request

<EMPTY>

Response

NameType
features Features

SetMode

Sets this device's operating mode.

mode is one of the variants in Mode, it's guaranteed to be one of the reported modes in this device's reported features. multicast_macs is only provided (though it can still be empty) when mode is MULTICAST_FILTER. multicast_macs is always guaranteed to be at most multicast_filter_count entries.

Request

NameType
mode fuchsia.hardware.network/MacFilterMode
multicast_macs vector<fuchsia.net/MacAddress>:64

Response

<EMPTY>

NetworkDeviceIfc

Defined in fuchsia.hardware.network.driver/network-device.fidl

AddPort

Instantiates a new port with id.

id must not be currently in use by any other ports. ids may be reused once the provided port is destroyed by NetworkPort.Removed.

Port identifiers do not need to be stable across instantiations or reboots. Port identifiers don't need to be allocated in any specific order as long as MAX_PORTS is not exceeded.

  • request id new port identifier.
  • request port handle to network port implementation.

Request

NameType
id fuchsia.hardware.network/BasePortId
port client_end:NetworkPort

Response

NameType
status zx/Status

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.

Buffers with zero length are considered "unfulfilled". They're not reported to any sessions and the buffer space comprising them may be reused. Devices should return any outstanding buffer space as unfulfilled on stop. See NetworkDeviceImpl.Stop.

By calling CompleteRx the caller relinquishes ownership of all buffers that are being marked as complete.

  • request rx buffers containing incoming data.

Request

NameType
rx vector<RxBuffer>:818

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 tx transmit results.

Request

NameType
tx vector<TxResult>:8188

DelegateRxLease

Transfers a receive wake lease up to the application.

Devices that allow applications to fully deal with a frame after a wake from network traffic may use this method as a "lease baton passing" strategy. Applications that support wake handling hold on to the lease until the rx traffic is fully processed.

Devices must keep track of the number of rx frames sent over NetworkDeviceIfc.CompleteRx and use the latest issued frame number as fuchsia.hardware.network/DelegatedRxLease.hold_until_frame to guarantee processing. Every frame successfully given to CompleteRx should increase the rx frame count. Note that the frame number is 1-based, see hold_until_frame docs for details.

Note that this is a one-way method and flow-control is enforced via the regular rx space -> rx completion flow.

Request

NameType
delegated fuchsia.hardware.network/DelegatedRxLease

PortStatusChanged

Notifies the interface of status changes on port with id.

Port status changes must always be notified through StatusChanged. The interface will not poll ports for status via NetworkPort.GetStatus.

  • request id port identifier.
  • request new_status new port's status.

Request

NameType
id fuchsia.hardware.network/BasePortId
new_status fuchsia.hardware.network/PortStatus

RemovePort

Destroys port with id.

NOTE: Resources associated with the port must not be freed until NetworkPort.Removed is called.

  • request id removed port identifier.

Request

NameType
id fuchsia.hardware.network/BasePortId

NetworkDeviceImpl

Defined in fuchsia.hardware.network.driver/network-device.fidl

GetInfo

Gets information about the device.

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

  • response info device information.

Request

<EMPTY>

Response

NameType
info DeviceImplInfo

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 the "Stopped" state, the Start method will be called once the data path needs to be opened.

  • request iface handle to the device interface.
  • response s initialization status. A value other than ZX_OK will cause the device to unbind.

Request

NameType
iface client_end: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 id until NetworkDeviceImpl.ReleaseVmo is called with the same id.

  • request id identifier used to reference this VMO.
  • request vmo VMO where frame data will be stored.
  • response s vmo registration status. ZX_OK indicates a successful VMO preparation. Any other status value indicates an implementation specific error and causes the client session which owns the VMO to be closed.

Request

NameType
id VmoId
vmo handle<vmo>

Response

NameType
s zx/Status

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.

Buffers enqueued while the device in is the stopped state must be returned with a zero length.

  • request buffers rx space buffers to be filled with network data when it arrives.

Request

NameType
buffers vector<RxSpaceBuffer>:2047

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.

Buffers enqueued while the device in is the stopped state must be returned with an appropriate error. See TxResult.status for specific error codes.

  • request buffers tx buffers to enqueue for sending.

Request

NameType
buffers vector<TxBuffer>:481

ReleaseVmo

Device may dispose of all references to the VMO referenced by id.

No more buffers will be sent with this id.

ReleaseVmo is guaranteed to only be called when the implementation holds no buffers that reference that id.

  • request id VMO identifier.

Request

NameType
id VmoId

Response

<EMPTY>

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 successfully. Until then, the contract guarantees that no other data-path calls will be made to the device (QueueTx, RxAvailable, Stop, or a second call to Start), so implementers can safely assume or assert that this contract is upheld.

  • response s start status. ZX_OK indicates a successful start. ZX_ERR_ALREADY_BOUND indicates that the device has already been successfully started. Any other status value indicates an implementation specific error.

Request

<EMPTY>

Response

NameType
s zx/Status

Stop

Stops the network device.

The device implementation must return all outstanding Tx and Rx buffers upon receiving this call. Any new buffers received in the stopped state must be returned with an appropriate error (tx) or unfulfilled (rx). See NetworkDeviceIfc.CompleteTx and NetworkDeviceIfc.CompleteRx for details.

The device implementation may perform any power saving measures after observing stop.

Request

<EMPTY>

Response

<EMPTY>

NetworkPort

Defined in fuchsia.hardware.network.driver/network-device.fidl

GetInfo

Gets information about the port.

Port information must not change over the port's lifetime.

  • response info port information.

Request

<EMPTY>

Response

NameType
info fuchsia.hardware.network/PortBaseInfo

GetMac

Gets an interface to the MAC addressing layer of the port.

Ports that do not support MAC addressing must return an empty interface. That means the generated-banjo bindings ctx and ops fields must both be null.

  • response mac_ifc mac addressing handle.

Request

<EMPTY>

Response

NameType
mac_ifc client_end:MacAddr?

GetStatus

Gets operational status of the port.

Changes to operational status must be reported via NetworkDeviceIfc.StatusChanged

  • response status snapshot of port's operational status.

Request

<EMPTY>

Response

NameType
status fuchsia.hardware.network/PortStatus

Removed

Notifies this port has been removed from the interface.

Resources associated with the port must only be freed upon receiving the Removed call. Note that Removed will ONLY be called if AddPort has returned and indicated success. If AddPort fails this will not be called, check the return status of AddPort instead.

Request

<EMPTY>

SetActive

Notifies the port that there are sessions interested in it.

An active port has sessions attached to it. Implementations may employ power saving or other strategies on disabled ports. Implementations that do employ such strategies:

  • should not report inbound frames for inactive ports;
  • must return errors for outbound frames destined to inactive ports.

All ports are inactive on creation.

  • request active true if port has sessions attached to it, false otherwise.

Request

NameType
active bool

STRUCTS

BufferMetadata

Defined in fuchsia.hardware.network.driver/network-device.fidl

Metadata associated with a TxBuffer or an RxBuffer.

FieldTypeDescriptionDefault
port fuchsia.hardware.network/BasePortId

Destination or source port identifier for this buffer.

 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 fuchsia.hardware.network/FrameType

Type of frame contained in this buffer, as defined in fuchsia.hardware.network/FrameType.

 No default

BufferRegion

Defined in fuchsia.hardware.network.driver/network-device.fidl

A contiguous memory region in a VMO.

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

FieldTypeDescriptionDefault
vmo VmoId

VMO backing this region.

 No 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

RxBuffer

Defined in fuchsia.hardware.network.driver/network-device.fidl

A buffer containing a single frame received by the device.

FieldTypeDescriptionDefault
meta BufferMetadata

Metadata associated with buffer.

 No default
data vector<RxBufferPart>:4

Fulfilled rx buffer space comprising this frame.

Must have at least one part.

 No default

RxBufferPart

Defined in fuchsia.hardware.network.driver/network-device.fidl

A single contiguous part of an RxBuffer, created from an RxSpaceBuffer.

FieldTypeDescriptionDefault
id BufferId

The buffer identifier informed in the RxSpaceBuffer that originated this RxBuffer.

 No default
offset uint32

Offset in bytes from RxSpaceBuffer's start where inbound data begins.

This is a relative offset within the region defined by the originating space, not an absolute offset in the space's VMO.

 No default
length uint32

The total length in bytes written in the RxSpaceBuffer referenced by id, excluding any offset bytes.

 No default

RxSpaceBuffer

Defined in fuchsia.hardware.network.driver/network-device.fidl

A buffer with allocated space to receive frames in. An RxSpaceBuffer must always be returned as an RxBufferPart within an RxBuffer.

FieldTypeDescriptionDefault
id BufferId

Unique buffer identifier.

 No default
region BufferRegion

VMO region where buffer space is located.

 No default

TxBuffer

Defined in fuchsia.hardware.network.driver/network-device.fidl

A transmit buffer containing a single frame.

FieldTypeDescriptionDefault
id BufferId

Unique buffer identifier.

 No default
data vector<BufferRegion>:4

Regions of VMO holding frame data.

 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 DeviceInfo.tx_tail_length value. The tail bytes are always at the end of the buffer.

 No default

TxResult

Defined in fuchsia.hardware.network.driver/network-device.fidl

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

FieldTypeDescriptionDefault
id BufferId

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

 No default
status zx/Status

The result status to report.

Error results map to their equivalents in fuchsia.hardware.network/TxReturnFlags.

  • 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) or stopped.
  • ZX_ERR_INTERNAL or any other unlisted errors will be reported as a generic fuchsia.hardware.network/TxReturnFlags.TX_RET_ERROR.
 No default

TABLES

DeviceImplInfo

Defined in fuchsia.hardware.network.driver/network-device.fidl

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

OrdinalFieldTypeDescription
device_features uint32

Device features Required.
tx_depth uint16

Maximum depth of tx frames in device's outgoing queue. Required.
rx_depth uint16

Maximum number of rx frames in a device's incoming queue. Required.
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. Required.
max_buffer_parts uint8

Maximum virtual discontiguous buffer parts accepted by the device.

Devices that can't perform scatter-gather operations must set max_buffer_parts to 1.

Must be in the range [1, MAX_BUFFER_PARTS]. Required.
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. Required.
buffer_alignment uint32

Alignment requirement for buffers relative to the start of VMOs.

Must be greater than zero. Required.
min_rx_buffer_length uint32

The minimum rx buffer length for correct operation, in bytes. Required.
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. Required.
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. Required.
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. Required.
rx_accel vector<fuchsia.hardware.network/RxAcceleration>

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. Required.
tx_accel vector<fuchsia.hardware.network/TxAcceleration>

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

Features

Defined in fuchsia.hardware.network.driver/network-mac.fidl

Device features reported by MacAddr.GetFeatures.

OrdinalFieldTypeDescription
multicast_filter_count uint32

The maximum number of multicast filtering entries available on this device.

Implementations must set 0 if multicast filtering is not supported. Values will always be saturated to MAX_MAC_FILTER. Optional, interpreted as zero if absent.
supported_modes SupportedMacFilterMode

The filtering operating modes supported by this device.

Bitfield of possible SupportedMacFilterMode values that can be passed to MacAddr.SetMode.

BITS

SupportedMacFilterMode flexible

Type: uint32

Defined in fuchsia.hardware.network.driver/network-mac.fidl

Device MAC filtering modes supported.

The variants of this type should match fuchsia.hardware.network.MacFilterMode.

NameValueDescription
1

Device accepts only unicast frames addressed to its own unicast address, or multicast frames that are part of the multicast address filter list.
2

Device accepts unicast frames addressed to its own unicast address, or any multicast frames.
4

Device accepts all frames.

CONSTANTS

NameValueTypeDescription
MAC_SIZE 6 uint64

The length of an IEEE 802 MAC Address, in bytes.
MAX_BUFFER_PARTS 4 uint32

Maximum number of disjoint parts a buffer may have.
MAX_MAC_FILTER 64 uint64

The maximum number of multicast MAC addresses set to filter.
MAX_RX_BUFFERS 818 uint32

The maximum number of RxBuffer structs that could be sent in a single FIDL message while staying within the maximum message size enforced by the bindings.

At the time of writing, FIDL messages are limited to 65 KiB. In the current FIDL wire format, the size of an RxBuffer is 80 bytes, and the fixed overhead of the CompleteRx request is 32 bytes (16 for the FIDL message header + 16 for the vector), so we selected the maximum N where 32

  • N * 80 <= 65 KiB.
MAX_RX_SPACE_BUFFERS 2047 uint32

The maximum number of RxSpaceBuffer structs that could be sent in a single FIDL message while staying within the maximum message size enforced by the bindings.

At the time of writing, FIDL messages are limited to 65 KiB. In the current FIDL wire format, the maximum size of an RxSpaceBuffer is 32 bytes, and the fixed overhead of the QueueRxSpace request is 32 bytes (16 for the FIDL message header + 16 for the vector), so we selected the maximum N where 32 + N * 32 <= 65 KiB.
MAX_TX_BUFFERS 481 uint32

The maximum number of TxBuffer structs that could be sent in a single FIDL message while staying within the maximum message size enforced by the bindings.

At the time of writing, FIDL messages are limited to 65 KiB. In the current FIDL wire format, the size of a TxBuffer is 136 bytes, and the fixed overhead of the QueueTx request is 32 bytes (16 for the FIDL message header + 16 for the vector), so we selected the maximum N where 32 + N * 136 <= 65 KiB.
MAX_TX_RESULTS 8188 uint32

The maximum number of TxResult structs that could be sent in a single FIDL message while staying within the maximum message size enforced by the bindings.

At the time of writing, FIDL messages are limited to 65 KiB. In the current FIDL wire format, the size of each TxResult is 8 bytes, and the fixed overhead of the CompleteTx request is 32 bytes (16 for the FIDL message header + 16 for the vector), so we selected the maximum N where 32 + N * 8 <= 65 KiB.
MAX_VMOS 32 uint8

The maximum number of concurrent shared VMOs that may exist.

ALIASES

NameValueDescription
BufferId uint32

Buffer identifier.

Rx space buffers and tx buffers are identified by these when exchanged between interface and implementation.
VmoId uint8

VMO identifier.

VMO identifiers are always in the range [0, MAX_VMOS).

VMO identifiers are reported to devices through NetworkDeviceImpl.PrepareVmo.

SERVICES

Service

Defined in fuchsia.hardware.network.driver/network-device.fidl

NameTypeTransport
network_device_impl fuchsia.hardware.network.driver/NetworkDeviceImpl Driver