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

fuchsia.hardware.network

PROTOCOLS

Device

Defined in fuchsia.hardware.network/device.fidl

A Network Device.

GetInfo

Obtain information about device

Request

NameType

Response

NameType
info Info

GetStatus

Obtain the operating device status.

Request

NameType

Response

NameType
device_status Status

GetStatusWatcher

Connects to a StatusWatcher to observe device status changes.

buffer is the number of status changes that the client requests to be stored by StatusWatcher, limited to MAX_STATUS_BUFFER. A value of 0 or 1 will cause 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

NameType
watcher request<StatusWatcher>
buffer uint32

OpenSession

Opens a new session with the network device. session_name is used only as a debug label. session_info contains the necessary information to setup the session's data exchange.

Request

NameType
session_name string[64]
session_info SessionInfo

Response

NameType
result Device_OpenSession_Result

DeviceInstance

Defined in fuchsia.hardware.network/instance.fidl

An instance of a network device that may be capable of MAC address filtering.

GetDevice

Connects to the Device implementation, giving access to data-plane features.

Request

NameType
device request<Device>

GetMacAddressing

Connects to the MacAddressing implementation, giving access to MAC filtering control. DeviceInstances that do not support MacAddressing will have the request immediately closed.

Request

NameType
mac request<MacAddressing>

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.

Returns ZX_ERR_INVALID_ARGS if the provided address is not a multicast address.

Request

NameType
address fuchsia.net/MacAddress

Response

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

Request

NameType

Response

NameType
address fuchsia.net/MacAddress

RemoveMulticastAddress

Removes multicast address from the list of multicast groups.

Returns ZX_ERR_INVALID_ARGS if the provided address is not a multicast address.

Request

NameType
address fuchsia.net/MacAddress

Response

NameType
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 will be 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 will succeed 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

NameType
mode MacFilterMode

Response

NameType
status zx/status

Session

Defined in fuchsia.hardware.network/session.fidl

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 are always created in a paused state.

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

NameType

SetPaused

Pauses or unpauses reception of frames on this session.

Request

NameType
paused bool

StatusWatcher

Defined in fuchsia.hardware.network/device.fidl

Provides a way to receive updates on device status changes.

WatchStatus

WatchStatus will block until the device's status has changed. The first call to WatchStatus will always return immediately with the current device status, subsequent calls will only complete when the device 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.

Request

NameType

Response

NameType
device_status Status

STRUCTS

Device_OpenSession_Response

Defined in fuchsia.hardware.network/device.fidl

NameTypeDescriptionDefault
session Session No default
fifos Fifos No default

Fifos

Defined in fuchsia.hardware.network/session.fidl

Data-plane FIFOs.

NameTypeDescriptionDefault
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

Defined in fuchsia.hardware.network/frames.fidl

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 will inform the client that all frame features are allowed.

NameTypeDescriptionDefault
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

Info

Defined in fuchsia.hardware.network/device.fidl

Network device information.

NameTypeDescriptionDefault
class DeviceClass

Device's class, defined in DeviceClass.

No default
min_descriptor_length uint8

Minimum descriptor length, in 64-bit words. Expresses 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.

No default
descriptor_version uint8

Accepted descriptor version.

No default
rx_depth uint32

Maximum number of items in Rx FIFO (per session). rx_depth is calculated based on the size of the actual backing hardware rx queue.

No default
tx_depth uint32

Maximum number of items in Tx FIFO (per session). tx_depth is calculated based on the size of the actual backing hardware tx queue.

No default
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.

No default
max_buffer_length uint32

Maximum supported length of buffers in the data VMO, in bytes.

No default
min_rx_buffer_length uint32

The minimum RX buffer length for correct operation, in bytes.

No default
min_tx_buffer_head uint16

The number of bytes the device requests be free as head space in a Tx buffer. Devices may choose to reject Tx buffers that do not satisfy this constraint.

No default
min_tx_buffer_tail uint16

The amount of bytes the device requests be free as tail space in a Tx buffer. Devices may choose to reject Tx buffers that to not satisfy this constraint.

No default
rx_types vector<FrameType>[4]

Supported Rx frame types on this device.

Clients may open sessions subscribing to a subset of rx_types frame types on this device. Clients will only receive the frame types they are subscribed to in this session

No default
tx_types vector<FrameTypeSupport>[4]

Supported Tx frame types on this device.

A client is free to send any frame type on an open session, as long as the frame type is part of tx_types. 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 EthernetII frames, and not any "raw" Ethernet frame.

No default
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.

No default
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 [fuchsia.hardware.network/TxAcceleration]. Position n of tx_accel conveys the meaning of the TX_ACCEL_n flag.

No default

SessionInfo

Defined in fuchsia.hardware.network/session.fidl

Session configuration.

NameTypeDescriptionDefault
descriptors handle<vmo>

VMO containing the descriptors. 16-bit indices transmitted over the FIFOs index a descriptor in this VMO (byte offset = descriptor_length * 8 * index).

No default
data handle<vmo>

VMO containing frame data. Descriptors contain byte-offsets that are used to index arbitrary regions in data.

No default
descriptor_version uint8

Requested descriptor version. If the network device does not support the requested descriptor version, Device.OpenSession will fail with ZX_ERR_NOT_SUPPORTED.

No default
descriptor_length uint8

Descriptor length, in 64-bit words. 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.

No default
descriptor_count uint16

Total number of descriptors that can be used by this session. Descriptor indices transferred through either the Rx or Tx FIFO must be in the range [0, descriptor_count).

No default
options SessionFlags

Extra options.

No default
rx_frames vector<FrameType>[4]

List of frame types the client is subscribing to.

No default

ENUMS

DeviceClass

Type: uint16

Defined in fuchsia.hardware.network/device.fidl

Network device class. The network device's class is part of its Info reporting and can be used by tools that enumerate network devices to present human-readable types, so it is easier for a user to identify the listed devices. The Info.class value does not imply any kind of capabilities or behavior.

NameValueDescription
UNKNOWN 0
ETHERNET 1
WLAN 2
PPP 3
BRIDGE 4

FrameType

Type: uint8

Defined in fuchsia.hardware.network/frames.fidl

Types of frames.

NameValueDescription
ETHERNET 1
IPV4 2
IPV6 3

InfoType

Type: uint32

Defined in fuchsia.hardware.network/frames.fidl

The type of metadata information appended to a frame, included in the descriptors VMO.

NameValueDescription
NO_INFO 0

No extra information is available.

MacFilterMode

Type: uint32

Defined in fuchsia.hardware.network/mac.fidl

The address filtering mode supported by MAC devices.

NameValueDescription
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

Type: uint8

Defined in fuchsia.hardware.network/frames.fidl

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

NameValueDescription
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

Type: uint8

Defined in fuchsia.hardware.network/frames.fidl

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

NameValueDescription
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

Status

Defined in fuchsia.hardware.network/device.fidl

Dynamic device information.

OrdinalNameTypeDescription
1 flags StatusFlags

Device status flags.

2 mtu uint32

Maximum transmit unit for this device, in bytes. The reported MTU is the size of an ENTIRE frame, including any header and trailer bytes for whatever protocol the FrameTypes of this device support.

UNIONS

Device_OpenSession_Result

Defined in fuchsia.hardware.network/device.fidl

NameTypeDescription
response Device_OpenSession_Response
err zx/status

BITS

EthernetFeatures

Type: uint32

NameValueDescription
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

Type: uint32

NameValueDescription
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

Type: uint16

NameValueDescription
PRIMARY 1

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_TX sessions will 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

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

Type: uint32

NameValueDescription
ONLINE 1

Device is online, i.e., data path is open and any ongoing sessions may send and receive frames.

TxFlags

Type: uint32

NameValueDescription
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

Type: uint32

NameValueDescription
TX_RET_NOT_SUPPORTED 1

Requested operation in inbound_flags is not supported; the frame was not sent. Always set in conjunction with TX_RET_ERROR.

TX_RET_OUT_OF_RESOURCES 2

Could not allocate resources to send frame. Always set in conjunction with TX_RET_ERROR.

TX_RET_NOT_AVAILABLE 4

Device is not available (offline or disconnected); the frame was not sent. Always set in conjunction with TX_RET_ERROR.

TX_RET_ERROR 2147483648

CONSTANTS

NameValueTypeDescription
FRAME_FEATURES_RAW 1 uint32

Blanket definition for raw frames. Devices that do not perform any sort of parsing of outbound traffic should define FRAME_FEATURES_RAW in the FrameTypeSupport entry.

MAX_ACCEL_FLAGS 16 uint32

Maximum number of acceleration flags. Each descriptor has 16 bits of space for acceleration flags (RxFlags and TxFlags) thus the maximum number of reported accelerations is 16. Each descriptor reports which accelerations were applied (RxFlags) or are requested (TxFlags) by mapping indexes in the vector of supported accelerations (Info.rx_accel and (Info.tx_accel) to bits in the respective acceleration flags bitfield.

MAX_DESCRIPTOR_CHAIN 4 uint8

Maximum number of chained descriptors that describe a single frame.

MAX_FRAME_TYPES 4 uint32

Maximum numbers of supported frame types for Rx or Tx.

MAX_SESSION_NAME 64 uint32

Maximum length of session label.

MAX_STATUS_BUFFER 50 uint32

The maximum number of status samples that can be buffered by a StatusWatcher.