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 |
No default |
info_type |
uint32
|
Type of data in |
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 A large value (close to |
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 |
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 |
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.
|
No default |
tx_accel |
vector<uint8>
|
Available tx acceleration flags for this device, as defined in
fuchsia.hardware.network/TxAcceleration.
|
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 |
No default |
total_length |
uint64
|
The total length of bytes written in the RxSpaceBuffer
referenced by |
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 |
---|---|---|---|
id |
uint32
|
The buffer identifier informed in the TxBuffer that originated
this |
No default |
status |
zx/status
|
The result status to report.
|
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 |
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 |