fuchsia.hardware.network

A Network Device.

GetInfo

Obtain information about device

response info device information.

Request

<EMPTY>

Response

Name	Type
`info`	`DeviceInfo`

GetPort

Connects to a port the given id.

request id port to connect to.
request port server end of port channel.

port is closed with a ZX_ERR_NOT_FOUND epitaph if no port with id exists.

Request

Name	Type
`id`	`port_id`
`port`	`request<Port>`

GetPortWatcher

Connects a PortWatcher to this device.

request watcher server end of watcher channel.

Request

Name	Type
`watcher`	`request<PortWatcher>`

OpenSession

Opens a new session with the network device.

request session_name is used as a debugging label attached to this session.
request session_info contains the necessary information to setup the session's data exchange.

response session a handle to control the session.
response fifos data-plane FIFOs attached to the session.

error ZX_ERR_NOT_SUPPORTED if session_info contains not supported frame types or descriptors set up.
error ZX_ERR_INVALID_ARGS if session_info is missing fields or contains invalid information.

Request

Name	Type
`session_name`	`string[64]`
`session_info`	`SessionInfo`

Response

Name	Type
`result`	`Device_OpenSession_Result`

DeviceInstance

Defined in fuchsia.hardware.network/instance.fidl

An instance of a network device exposed on devfs.

GetDevice

Connects to the Device implementation.

request device device handle.

Request

Name	Type
`device`	`request<Device>`

MacAddressing

Defined in fuchsia.hardware.network/mac.fidl

AddMulticastAddress

Adds multicast address to the list of multicast groups.

The list of multicast addresses kept is untouched by calls to SetMode. If the device's mode is not MULTICAST_FILTER, the list of multicast addresses is ignored.

request address multicast address to add to the list.

response status ZX_ERR_INVALID_ARGS if address is not a multicast address.

Request

Name	Type
`address`	`fuchsia.net/MacAddress`

Response

Name	Type
`status`	`zx/status`

GetUnicastAddress

Gets the Device's current unicast MAC address.

Implementers of this API do not need to return a uniquely identifiable MAC; the unicast address returned is the one that is currently in use to filter unicast frames, or that identifies the device on a link it's currently on. Users of this API must not rely on the stability or uniqueness of the returned value to identify or disambiguate device instances.

response address device's unicast MAC address.

Request

<EMPTY>

Response

Name	Type
`address`	`fuchsia.net/MacAddress`

RemoveMulticastAddress

Removes multicast address from the list of multicast groups.

request address multicast address to remove from the list.

response status ZX_ERR_INVALID_ARGS if address is not a multicast address.

Request

Name	Type
`address`	`fuchsia.net/MacAddress`

Response

Name	Type
`status`	`zx/status`

SetMode

Sets requested operating mode of this device to mode.

The requested mode is attached to the current client connection to the device. Because multiple clients can be attached to the same device at once, the mode with the least restrictions is the one actively put into effect into the underlying device implementation.

If the device does not support the requested mode, but supports a mode that is more open than the requested one, SetMode succeeds regardless. Otherwise, if the device only supports more restrictive modes than the one requested, SetMode returns ZX_ERR_NOT_SUPPORTED.

Clients must be aware that the resource being accessed is shared, and that the device may be effectively operating at a more open level than the one that was requested (although never at one more restrictive).

request mode request mode to attach to.

response status ZX_ERR_NOT_SUPPORTED it the device only supports mode more restrictive than the one requested.

Request

Name	Type
`mode`	`MacFilterMode`

Response

Name	Type
`status`	`zx/status`

Port

A logical port belonging to a Device.

GetInfo

Obtain information about port.

response info port information.

Request

<EMPTY>

Response

Name	Type
`info`	`PortInfo`

GetMac

Connects to a MacAddressing associated with the port.

request mac mac handle. Closed with ZX_ERR_NOT_SUPPORTED if this port does not support mac addressing.

Request

Name	Type
`mac`	`request<MacAddressing>`

GetStatus

Obtain the operating port status.

response status snapshot of port's current status.

Request

<EMPTY>

Response

Name	Type
`status`	`PortStatus`

GetStatusWatcher

Connects to a StatusWatcher to observe port status changes.

request watcher handle to the status watcher.
request buffer the number of status changes that the client requests to be stored by StatusWatcher. Values are capped at MAX_STATUS_BUFFER. A value of 0 or 1 causes the StatusWatcher to not keep any buffers on status changed. Clients that need to observe all changes to status (as opposed to only the current state) are encouraged to set a buffer value larger than 1, so that all edges can be observed. If StatusWatcher's internal queue is filled and new status changes occur, the oldest samples will be dropped to make room for new ones.

Request

Name	Type
`watcher`	`request<StatusWatcher>`
`buffer`	`uint32`

PortWatcher

Provides iteration over and updates for ports attached to a device.

Watch

Get the next port event.

The first N calls return DevicePortEvent.existing where N is the number of ports present on the device at the time of the watcher's creation. The next call returns DevicePortEvent.idle to indicate the end of existing ports. Subsequent calls block until a port is added (DevicePortEvent.added) or removed (DevicePortEvent.removed).

The server closes the PortWatcher channel with ZX_ERR_CANCELED if the number of unread events reaches a server-selected limit that is at least two times MAX_PORTS. Clients are encouraged to maintain a hanging call to Watch at all times to avoid triggering this condition.

response event next port event.

Request

<EMPTY>

Response

Name	Type
`event`	`DevicePortEvent`

Session

Represents a session with a Network device.

A session has a data plane and a control plane. The Session protocol represents the control plane of the session and the FIFOs and VMOs exchanged during the Device.OpenSession call are the data plane. Lifetime of the session is controlled by a Session protocol handle.

Sessions must attach to ports of interest to start receiving and sending data. Sessions are always created with no ports attached.

If a port is destroyed from the underlying device, it is automatically detached from the session.

Inbound traffic is dispatched to all open sessions. Devices typically operate with a single primary session, see SessionFlags.PRIMARY. Each additional open session to the same device causes data copy overhead on the device's data path.

The session is closed with an error epitaph if an invalid buffer descriptor is sent over either the tx or rx FIFOs. Invalid descriptors include: - Descriptor index larger than SessionInfo.descriptor_count. - Descriptor chains larger than MAX_DESCRIPTOR_CHAIN. - rx buffers smaller than Info.min_rx_buffer_length. - tx buffers smaller than Info.min_tx_buffer_length. - tx buffers not respecting Info.min_tx_buffer_head or Info.min_tx_buffer_tail.

Attach

Attaches the session to port.

Once attached, the session starts to receive the subscribed frames over the data FIFOs and it may send frames destined to the specified port.

request port port to subscribe to.
request rx_frames Frame types of interest on the port.

error ZX_ERR_NOT_FOUND if port is not valid.
error ZX_ERR_INVALID_ARGS if rx_frames is not a subset of the port's supported frames.
error ZX_ERR_ALREADY_BOUND if port is already attached.

Request

Name	Type
`port`	`port_id`
`rx_frames`	`vector<FrameType>[4]`

Response

Name	Type
`result`	`Session_Attach_Result`

Close

Cleanly closes a session.

This will cause the session to send a ZX_ERR_CANCELLED epitaph and proceed to close the Session channel. Clients may only assume that they own all the buffers that are currently owned by the session (sent over either the rx or tx FIFOs) once the epitaph is received. Closing the rx or tx FIFO is equivalent to calling Close.

Request

<EMPTY>

Detach

Detaches the session from port.

Once detached, the session stops receiving frames from port. Frames sent to a detached port may be returned with an error. It is not necessary to call Detach on ports that are removed from the device, doing so causes ZX_ERR_NOT_FOUND to be returned.

request port port to subscribe to.

error ZX_ERR_NOT_FOUND if the session is not currently attached to the port.

Request

Name	Type
`port`	`port_id`

Response

Name	Type
`result`	`Session_Detach_Result`

StatusWatcher

Provides a way to receive updates on port status changes.

WatchStatus

WatchStatus blocks until the port's status has changed.

The first call to WatchStatus returns immediately with the current port status, subsequent calls complete when the port status differs from the last one that was returned through this StatusWatcher.

If StatusWatcher was created with a buffer value larger than 1, WatchStatus may return a queued status change, depending on how many status changed happened since the last call to WatchStatus.

response device_status the most recent port status.

Request

<EMPTY>

Response

Name	Type
`port_status`	`PortStatus`

STRUCTS

Device_OpenSession_Response resource

Field	Type	Description	Default
`session`	`Session`		No default
`fifos`	`Fifos`		No default

Empty

<EMPTY>

Fifos resource

Data-plane FIFOs.

Field Type Description Default

Field	Type	Description	Default
`rx`	`handle<fifo>`	Handle for the rx FIFO. Clients must write 16-bit descriptor indexes to this FIFO to be able to receive frames.	No default
`tx`	`handle<fifo>`	Handle for the tx FIFO. Clients write 16-bit descriptor indexes to this FIFO to enqueue outgoing frames.	No default

rx

handle<fifo>

Handle for the rx FIFO.

Clients must write 16-bit descriptor indexes to this FIFO to be able to receive frames.

No default

tx

handle<fifo>

Handle for the tx FIFO.

Clients write 16-bit descriptor indexes to this FIFO to enqueue outgoing frames.

No default

FrameTypeSupport

Specifies a frame type and features and supported flags associated with that type.

This is used by clients to read the supported frames on the tx path for a given Network Device.

Some Network Devices may parse outgoing frames to perform frame transformation or specific hardware support. Each frame type has an associated FrameTypeSupport.features bits enumeration that lists FrameType-specific features that may or may not be supported. Devices that do not perform parsing are encouraged to just use the FRAME_FEATURES_RAW bit in features, which informs the client that all frame features are allowed.

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

Session_Attach_Response

<EMPTY>

Session_Detach_Response

<EMPTY>

ENUMS

DeviceClass strict

Type: uint16

Network device class.

Note: Device implementers are encouraged to propose additions to this enumeration to avoid using ill-fitting variants if there's not a good match available.

Name	Value	Description
`VIRTUAL`	`0`
`ETHERNET`	`1`
`WLAN`	`2`
`PPP`	`3`
`BRIDGE`	`4`
`WLAN_AP`	`5`

FrameType strict

Type: uint8

Types of frames.

Name	Value	Description
`ETHERNET`	`1`
`IPV4`	`2`
`IPV6`	`3`

InfoType strict

Type: uint32

The type of metadata information appended to a frame.

Name	Value	Description
`NO_INFO`	`0`	No extra information is available.

MacFilterMode strict

Type: uint32

Defined in fuchsia.hardware.network/mac.fidl

The address filtering mode supported by MAC devices.

Name	Value	Description
`MULTICAST_FILTER`	`0`	Device accepts only unicast frames addressed to its own unicast address, or multicast frames that are part of the multicast address filter list.
`MULTICAST_PROMISCUOUS`	`1`	Device accepts unicast frames addressed to its own unicast address, or any multicast frames.
`PROMISCUOUS`	`2`	Device accepts all frames.

RxAcceleration strict

Type: uint8

Available rx acceleration features.

Features are mapped to the RX_ACCEL_* bits in descriptors by the available values reported in Info.rx_accel.

Name	Value	Description
`VALIDATED_ETHERNET_FCS`	`0`	Inbound rx frame validated the Ethernet Frame Check Sequence.
`VALIDATED_IPV4_CHECKSUM`	`1`	Inbound rx frame validated the IPv4 checksum.
`VALIDATED_TCP_CHECKSUM`	`2`	Inbound rx frame validated the TCP checksum.
`VALIDATED_UDP_CHECKSUM`	`3`	Inbound rx frame validated the UDP checksum.

TxAcceleration strict

Type: uint8

Available tx acceleration features.

Features are mapped to the TX_ACCEL_* bits in descriptors by the available values reported in Info.tx_accel.

Name	Value	Description
`COMPUTE_ETHERNET_FCS`	`0`	Request that device calculate the Ethernet Frame Check Sequence and write it in place.
`COMPUTE_IPV4_CHECKSUM`	`1`	Request that the device calculate the IPv4 checksum and write it in place.
`COMPUTE_TCP_CHECKSUM`	`2`	Request that the device calculate the TCP checksum and write it in place.
`COMPUTE_UDP_CHECKSUM`	`3`	Request that the device calculate the UDP checksum and write it in place.

TABLES

DeviceInfo

Network device information.

Ordinal	Field	Type	Description
1	`min_descriptor_length`	`uint8`	Minimum descriptor length, in 64-bit words. Required. The minimum length that each buffer descriptor must have for correct operation with this device. Devices that support extra frame metadata inform larger minimum descriptor lengths that reflect the minimum space needed to be able to store frame metadata.
2	`descriptor_version`	`uint8`	Accepted descriptor version. Required.
3	`rx_depth`	`uint16`	Maximum number of items in rx FIFO (per session). Required. `rx_depth` is calculated based on the size of the actual backing hardware rx queue.
4	`tx_depth`	`uint16`	Maximum number of items in tx FIFO (per session). Required. `tx_depth` is calculated based on the size of the actual backing hardware tx queue.
5	`buffer_alignment`	`uint32`	Alignment requirement for buffers in the data VMO. All buffers in the data VMO must be aligned to `buffer_alignment` relative to the start of the VMO. `buffer_alignment == 0` is never reported. Required.
6	`max_buffer_length`	`uint32`	Maximum supported length of buffers in the data VMO, in bytes. Required.
7	`min_rx_buffer_length`	`uint32`	The minimum rx buffer length required for device. Required.
8	`min_tx_buffer_length`	`uint32`	The minimum tx buffer length required for the device. Required. This value accounts only for tx payload length, `min_tx_buffer_head` and `min_tx_buffer_tail` are not part of this value. Clients must zero pad outgoing frames to meet the required minimum length.
9	`min_tx_buffer_head`	`uint16`	The number of bytes the device requests be free as `head` space in a tx buffer. Required.
10	`min_tx_buffer_tail`	`uint16`	The amount of bytes the device requests be free as `tail` space in a tx buffer. Required.
11	`max_buffer_parts`	`uint8`	Maximum descriptor chain length accepted by the device. Required.
12	`rx_accel`	`vector<RxAcceleration>[16]`	Available rx acceleration flags for this device. `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. Interpreted as empty if not provided.
13	`tx_accel`	`vector<TxAcceleration>[16]`	Available tx acceleration flags for this device. `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. Interpreted as empty if not provided.

PortInfo

Logical port information.

Ordinal	Field	Type	Description
1	`id`	`port_id`	Port's identifier. Required.
2	`class`	`PortClass`	Port's class. Required.
3	`rx_types`	`vector<FrameType>[4]`	Supported rx frame types on this port. Required. Clients may open sessions subscribing to a subset of `rx_types` frame types on this port.
4	`tx_types`	`vector<FrameTypeSupport>[4]`	Supported tx frame types on this port. Required. Frames destined to this port whose frame type is not in `tx_types` are returned with an error. Some network devices may need to perform partial frame parsing and serialization and, for that reason, `tx_types` is a vector of FrameTypeSupport which includes specific features per frame type. For example, a device that supports Ethernet frames but needs to convert the Ethernet header may only support standard Ethernet II frames, and not any "raw" Ethernet frame.

PortStatus

Dynamic port information.

Ordinal Field Type Description

Ordinal	Field	Type	Description
1	`flags`	`StatusFlags`	Port status flags.
2	`mtu`	`uint32`	Maximum transmit unit for this port, in bytes. The reported MTU is the size of an entire frame, including any header and trailer bytes for whatever protocols this port supports.

flags

StatusFlags

Port status flags.

mtu

uint32

Maximum transmit unit for this port, in bytes.

The reported MTU is the size of an entire frame, including any header and trailer bytes for whatever protocols this port supports.

SessionInfo resource

Session configuration.

Ordinal	Field	Type	Description
1	`descriptors`	`handle<vmo>`	VMO containing the descriptors. Required. 16-bit indices transmitted over the FIFOs index a descriptor in this VMO (byte offset = descriptor_length * 8 * index).
2	`data`	`handle<vmo>`	VMO containing frame data. Required. Descriptors contain byte-offsets that are used to index arbitrary regions in `data`.
3	`descriptor_version`	`uint8`	Requested descriptor version. Required. If the network device does not support the requested descriptor version, Device.OpenSession fails with `ZX_ERR_NOT_SUPPORTED`.
4	`descriptor_length`	`uint8`	Descriptor length, in 64-bit words. Required. The length of each descriptor in the `descriptors` VMO. This is used as a multiplier to find byte offsets in `descriptors` given a descriptor index passed through the rx or tx FIFOs.
5	`descriptor_count`	`uint16`	Total number of descriptors that can be used by this session. Required. Descriptor indices transferred through either the rx or tx FIFO must be in the range [0, `descriptor_count`).
6	`options`	`SessionFlags`	Extra options. Interpreted as empty bitmask if absent.

UNIONS

DevicePortEvent strict

Port creation and destruction events.

Ordinal
Variant	Type	Description
1	`existing`	`port_id`	Port existed when watcher was created.
2	`added`	`port_id`	New port was added to device.
3	`removed`	`port_id`	Port was removed from the device.
4	`idle`	`Empty`	Exhausted list of existing ports.

Device_OpenSession_Result strict resource

Ordinal
Variant	Type	Description
1	`response`	`Device_OpenSession_Response`
2	`err`	`zx/status`

Session_Attach_Result strict

Ordinal
Variant	Type	Description
1	`response`	`Session_Attach_Response`
2	`err`	`zx/status`

Session_Detach_Result strict

Ordinal
Variant	Type	Description
1	`response`	`Session_Detach_Response`
2	`err`	`zx/status`

BITS

EthernetFeatures strict

Type: uint32

Ethernet frame sub-types and features.

Name	Value	Description
RAW	1	Device supports any type of ethernet frame. Same as specifying all other flags. Used by devices that do not inspect or parse outbound traffic.
ETHERNET_II	2	Device supports EthernetII frames.
E_802_1_Q	4	Device supports 802.1q VLAN additions.
E_802_1_Q_IN_Q	8	Device supports 802.1 q-in-q Multiple VLAN tagging additions. Only meaningful if `E_802_1_Q` is also present.
E_802_3_LLC_SNAP	16	Device supports 802.3 LLC + SNAP Ethernet frame format.

RxFlags strict

Type: uint32

Flags set by a Device when handing a buffer to a client on the rx path.

Set by devices on the inbound_flags field of an rx descriptor.

Name	Value	Description
RX_ACCEL_0	1	Acceleration flag 0. Acceleration flags are mapped to the acceleration features reported by the Device in Info.rx_accel. The n-th feature in `rx_accel` maps to the `RX_ACCEL_n` `RxFlag`.
RX_ACCEL_1	2
RX_ACCEL_2	4
RX_ACCEL_3	8
RX_ACCEL_4	16
RX_ACCEL_5	32
RX_ACCEL_6	64
RX_ACCEL_7	128
RX_ACCEL_8	256
RX_ACCEL_9	512
RX_ACCEL_10	1024
RX_ACCEL_11	2048
RX_ACCEL_12	4096
RX_ACCEL_13	8192
RX_ACCEL_14	16384
RX_ACCEL_15	32768
RX_OVERRUN	536870912	Device experienced a hardware rx overrun. Rx overruns are typically set by hardware controllers when a frame event was detected but the frame data couldn't be captured. Devices should clear the controller flag once this is set on an inbound frame, so future overruns can be detected and reported.
RX_VALIDATION_ERROR	1073741824	This bit is set if frame validation is performed (such as by hardware acceleration features) and fails. It's important to note that some devices may simply discard frames for which validation fails and never notify the client. Rx frames that failed validation are only transmitted to the client if the `SessionFlags::REPORT_INVALID_RX` option is selected when creating a session.
RX_ECHOED_TX	2147483648	This is an echoed tx frame, created by a tx request. Can only be set in sessions that have the `LISTEN_TX` flag.

SessionFlags strict

Type: uint16

Additional session options.

Name Value Description

PRIMARY

Name	Value	Description
PRIMARY	1	Attach as primary session. Sessions marked with the `PRIMARY` bit get the following different treatment: If no PRIMARY sessions are attached, the device will not serve rx frames to non-PRIMARY sessions. If there's only one PRIMARY session active, it may get a zero-copy data path from the the backing hardware, if the underlying implementation supports it.
LISTEN_TX	2	Listen for outgoing frames. `LISTEN_TX` sessions receive any outgoing frames (from all sessions) on its rx path. Can be used for snooping traffic. Sessions marked with `LISTEN_TX` may also send frames, but they should keep in mind that they'll ALWAYS receive those frames back on their rx path (no origin session filtering is performed).
REPORT_INVALID_RX	4	Receive invalid rx frames. Sessions marked with `REPORT_INVALID_RX` are interested in receiving frames that were rejected by internal device checks or payload validation performed by hardware. Due to the nature of some hardware platforms, sessions marked with `REPORT_INVALID_RX` may still not receive frames that fail validation if the hardware implementation simply drops the frame and doesn't expose it to the software stack. Sessions NOT marked with `REPORT_INVALID_RX`, in contrast, will NEVER receive an rx frame with the `RX_VALIDATION_ERROR` flag set.

Attach as primary session.

Sessions marked with the PRIMARY bit get the following different treatment:

If no PRIMARY sessions are attached, the device will not serve rx frames to non-PRIMARY sessions.
If there's only one PRIMARY session active, it may get a zero-copy data path from the the backing hardware, if the underlying implementation supports it.

LISTEN_TX

Listen for outgoing frames.

LISTEN_TX sessions receive any outgoing frames (from all sessions) on its rx path. Can be used for snooping traffic. Sessions marked with LISTEN_TX may also send frames, but they should keep in mind that they'll ALWAYS receive those frames back on their rx path (no origin session filtering is performed).

REPORT_INVALID_RX

Receive invalid rx frames.

Sessions marked with REPORT_INVALID_RX are interested in receiving frames that were rejected by internal device checks or payload validation performed by hardware. Due to the nature of some hardware platforms, sessions marked with REPORT_INVALID_RX may still not receive frames that fail validation if the hardware implementation simply drops the frame and doesn't expose it to the software stack. Sessions NOT marked with REPORT_INVALID_RX, in contrast, will NEVER receive an rx frame with the RX_VALIDATION_ERROR flag set.

StatusFlags strict

Type: uint32

Port status bits, reported in PortStatus.flags.

Name	Value	Description
ONLINE	1	Port is online, i.e., data path is open and any ongoing sessions may send and receive frames.

TxFlags strict

Type: uint32

Flags set by a Client when handing a buffer to a client on the tx path.

Set by Clients on the inbound_flags field of a tx descriptor.

Name	Value	Description
TX_ACCEL_0	1	Acceleration flag 0. Acceleration flags are mapped to the acceleration features reported by the Device in Info.tx_accel. The n-th feature in `tx_accel` maps to the `TX_ACCEL_n` `TxFlag`.
TX_ACCEL_1	2
TX_ACCEL_2	4
TX_ACCEL_3	8
TX_ACCEL_4	16
TX_ACCEL_5	32
TX_ACCEL_6	64
TX_ACCEL_7	128
TX_ACCEL_8	256
TX_ACCEL_9	512
TX_ACCEL_10	1024
TX_ACCEL_11	2048
TX_ACCEL_12	4096
TX_ACCEL_13	8192
TX_ACCEL_14	16384
TX_ACCEL_15	32768

TxReturnFlags strict

Type: uint32