PROTOCOLS
Device
Defined in fuchsia.hardware.network/device.fidl
A Network Device.
GetInfo
Obtain information about device
Request
Name | Type |
---|
Response
Name | Type |
---|---|
info |
Info
|
GetStatus
Obtain the operating device status.
Request
Name | Type |
---|
Response
Name | Type |
---|---|
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
Name | Type |
---|---|
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
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 that may be capable of MAC address filtering.
GetDevice
Connects to the Device implementation, giving access to data-plane features.
Request
Name | Type |
---|---|
device |
request<Device>
|
GetMacAddressing
Connects to the MacAddressing implementation, giving access to
MAC filtering control. DeviceInstance
s that do not support MacAddressing
will have the
request immediately closed.
Request
Name | Type |
---|---|
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
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.
Request
Name | Type |
---|
Response
Name | Type |
---|---|
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
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 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
Name | Type |
---|---|
mode |
MacFilterMode
|
Response
Name | Type |
---|---|
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.
The session will be 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.
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
Name | Type |
---|
SetPaused
Pauses or unpauses reception of frames on this session.
Request
Name | Type |
---|---|
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
Name | Type |
---|
Response
Name | Type |
---|---|
device_status |
Status
|
STRUCTS
Device_OpenSession_Response
Defined in fuchsia.hardware.network/device.fidl
Name | Type | Description | Default |
---|---|---|---|
session |
Session
|
No default | |
fifos |
Fifos
|
No default |
Fifos
Defined in fuchsia.hardware.network/session.fidl
Data-plane FIFOs.
Name | 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 |
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.
Name | 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 |
Info
Defined in fuchsia.hardware.network/device.fidl
Network device information.
Name | Type | Description | Default |
---|---|---|---|
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 |
uint16
|
Maximum number of items in rx FIFO (per session).
|
No default |
tx_depth |
uint16
|
Maximum number of items in tx FIFO (per session).
|
No default |
buffer_alignment |
uint32
|
Alignment requirement for buffers in the data VMO. All buffers in the data VMO must be
aligned to |
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 required for device. |
No default |
min_tx_buffer_length |
uint32
|
The minimum tx buffer length required for the device. This value accounts only for tx payload length, Clients must zero pad outgoing frames to meet the required minimum length. |
No default |
min_tx_buffer_head |
uint16
|
The number of bytes the device requests be free as |
No default |
min_tx_buffer_tail |
uint16
|
The amount of bytes the device requests be free as |
No default |
rx_types |
vector<FrameType>[4]
|
Supported rx frame types on this device. Clients may open sessions subscribing to a subset of |
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 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. |
No default |
tx_accel |
vector<TxAcceleration>[16]
|
Available tx acceleration flags for this device. |
No default |
SessionInfo
Defined in fuchsia.hardware.network/session.fidl
Session configuration.
Name | Type | Description | Default |
---|---|---|---|
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 |
No default |
descriptor_version |
uint8
|
Requested descriptor version. If the network device does not support the requested
descriptor version, Device.OpenSession will fail with
|
No default |
descriptor_length |
uint8
|
Descriptor length, in 64-bit words. The length of each descriptor in the |
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, |
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.
Name | Value | Description |
---|---|---|
UNKNOWN |
0 |
|
ETHERNET |
1 |
|
WLAN |
2 |
|
PPP |
3 |
|
BRIDGE |
4 |
FrameType
Type: uint8
Defined in fuchsia.hardware.network/frames.fidl
Types of frames.
Name | Value | Description |
---|---|---|
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.
Name | Value | Description |
---|---|---|
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.
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
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.
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
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.
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
Status
Defined in fuchsia.hardware.network/device.fidl
Dynamic device information.
Ordinal | Name | Type | Description |
---|---|---|---|
1 | flags |
StatusFlags
|
Device status flags. |
2 | mtu |
uint32
|
Maximum transmit unit for this device, in bytes. The reported |
UNIONS
Device_OpenSession_Result
Defined in fuchsia.hardware.network/device.fidl
Name | Type | Description |
---|---|---|
response |
Device_OpenSession_Response
|
|
err |
zx/status
|
BITS
EthernetFeatures
Type: uint32
Defined in fuchsia.hardware.network/frames.fidl
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_3_LLC_SNAP | 16 | Device supports 802.3 LLC + SNAP Ethernet frame format. |
RxFlags
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.
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_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 |
RX_ECHOED_TX | 2147483648 | This is an echoed tx frame, created by a tx request. Can only be set in sessions that have
the |
SessionFlags
Type: uint16
Defined in fuchsia.hardware.network/session.fidl
Additional session options.
Name | Value | Description |
---|---|---|
PRIMARY | 1 | Sessions marked with the
|
LISTEN_TX | 2 |
|
REPORT_INVALID_RX | 4 | Sessions marked with |
StatusFlags
Type: uint32
Defined in fuchsia.hardware.network/device.fidl
Device status bits, reported in Info.
Name | Value | Description |
---|---|---|
ONLINE | 1 | Device is online, i.e., data path is open and any ongoing sessions may send and receive frames. |
TxFlags
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.
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_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
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.
Name | Value | Description |
---|---|---|
TX_RET_NOT_SUPPORTED | 1 | Requested operation in |
TX_RET_OUT_OF_RESOURCES | 2 | Could not allocate resources to send frame.
Always set in conjunction with |
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 | 2147483648 |
CONSTANTS
Name | Value | Type | Description |
---|---|---|---|
FRAME_FEATURES_RAW |
1
|
uint32 |
Blanket definition for raw frames. Devices that do not perform any sort of parsing of outbound
traffic should define |
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
( |
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. |