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

  • response info device information.

Request

<EMPTY>

Response

NameType
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

NameType
id port_id
port request<Port>

GetPortWatcher

Connects a PortWatcher to this device.

  • request watcher server end of watcher channel.

Request

NameType
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

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 exposed on devfs.

GetDevice

Connects to the Device implementation.

  • request device device handle.

Request

NameType
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

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.

  • response address device's unicast MAC address.

Request

<EMPTY>

Response

NameType
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

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

NameType
mode MacFilterMode

Response

NameType
status zx/status

Port

Defined in fuchsia.hardware.network/port.fidl

A logical port belonging to a Device.

GetInfo

Obtain information about port.

  • response info port information.

Request

<EMPTY>

Response

NameType
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

NameType
mac request<MacAddressing>

GetStatus

Obtain the operating port status.

  • response status snapshot of port's current status.

Request

<EMPTY>

Response

NameType
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

NameType
watcher request<StatusWatcher>
buffer uint32

PortWatcher

Defined in fuchsia.hardware.network/device.fidl

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

NameType
event DevicePortEvent

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

NameType
port port_id
rx_frames vector<FrameType>[4]

Response

NameType
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

NameType
port port_id

Response

NameType
result Session_Detach_Result

StatusWatcher

Defined in fuchsia.hardware.network/port.fidl

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

NameType
port_status PortStatus

STRUCTS

Device_OpenSession_Response resource

Defined in fuchsia.hardware.network/device.fidl

FieldTypeDescriptionDefault
session Session No default
fifos Fifos No default

Empty

Defined in fuchsia.hardware.network/device.fidl

<EMPTY>

Fifos resource

Defined in fuchsia.hardware.network/session.fidl

Data-plane FIFOs.

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

FieldTypeDescriptionDefault
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

Defined in fuchsia.hardware.network/session.fidl

<EMPTY>

Session_Detach_Response

Defined in fuchsia.hardware.network/session.fidl

<EMPTY>

ENUMS

DeviceClass strict

Type: uint16

Defined in fuchsia.hardware.network/port.fidl

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.

NameValueDescription
VIRTUAL 0
ETHERNET 1
WLAN 2
PPP 3
BRIDGE 4
WLAN_AP 5

FrameType strict

Type: uint8

Defined in fuchsia.hardware.network/frames.fidl

Types of frames.

NameValueDescription
ETHERNET 1
IPV4 2
IPV6 3

InfoType strict

Type: uint32

Defined in fuchsia.hardware.network/frames.fidl

The type of metadata information appended to a frame.

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

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 strict

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 strict

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

DeviceInfo

Defined in fuchsia.hardware.network/device.fidl

Network device information.

OrdinalFieldTypeDescription
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

Defined in fuchsia.hardware.network/port.fidl

Logical port information.

OrdinalFieldTypeDescription
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

Defined in fuchsia.hardware.network/port.fidl

Dynamic port information.

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

SessionInfo resource

Defined in fuchsia.hardware.network/session.fidl

Session configuration.

OrdinalFieldTypeDescription
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

Defined in fuchsia.hardware.network/device.fidl

Port creation and destruction events.

Ordinal
VariantTypeDescription
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

Defined in fuchsia.hardware.network/device.fidl

Ordinal
VariantTypeDescription
1 response Device_OpenSession_Response
2 err zx/status

Session_Attach_Result strict

Defined in fuchsia.hardware.network/session.fidl

Ordinal
VariantTypeDescription
1 response Session_Attach_Response
2 err zx/status

Session_Detach_Result strict

Defined in fuchsia.hardware.network/session.fidl

Ordinal
VariantTypeDescription
1 response Session_Detach_Response
2 err zx/status

BITS

EthernetFeatures strict

Type: uint32

Defined in fuchsia.hardware.network/frames.fidl

Ethernet frame sub-types and features.

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 strict

Type: uint32

Defined in fuchsia.hardware.network/frames.fidl

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.

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 strict

Type: uint16

Defined in fuchsia.hardware.network/session.fidl

Additional session options.

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

StatusFlags strict

Type: uint32

Defined in fuchsia.hardware.network/port.fidl

Port status bits, reported in PortStatus.flags.

NameValueDescription
ONLINE 1

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

TxFlags strict

Type: uint32

Defined in fuchsia.hardware.network/frames.fidl

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.

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 strict

Type: uint32

Defined in fuchsia.hardware.network/frames.fidl

Flags set by a Device when returning a tx buffer back to a client.

Set by Devices on the return_flags field of a tx descriptor.

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_PORTS 32 uint8

The maximum number of ports attached to a device at a given time.

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.

TYPE ALIASES

NameValueDescription
PortClass fuchsia.hardware.network/DeviceClass

Network port class.

port_id uint8

The identifier of a port within a device. Always less than MAX_PORTS.