PROTOCOLS
Device
Defined in fuchsia.hardware.ethernet/ethernet.fidl
Operation
Packets are transmitted by writing data into the IO buffer and writing a FifoEntry referencing that data (offset + length) into the tx fifo. When the driver is done accessing the data, a FifoEntry with the same cookie value (opaque to the driver) will be readable from the tx fifo.
Packets are received by writing a FifoEntry referencing an available buffer (offset + length) in the IO buffer. When a packet is received, a FifoEntry with the same cookie value (opaque to the driver) will be readable from the rx fifo. The offset field will be the same as was sent. The length field will reflect the actual size of the received packet. The flags field will indicate success or a specific failure condition.
IMPORTANT: The driver will not buffer response messages. It is the client's responsibility to ensure that there is space in the reply side of each fifo for each outstanding tx or rx request. The fifo sizes are returned along with the fifo handles from GetFifos().
See //zircon/system/public/zircon/device/ethernet.h for fifo entry layout and request / response message bits.
ConfigMulticastAddMac
Request
| Name | Type |
|---|---|
addr |
MacAddress
|
Response
| Name | Type |
|---|---|
status |
zx/status
|
ConfigMulticastDeleteMac
Request
| Name | Type |
|---|---|
addr |
MacAddress
|
Response
| Name | Type |
|---|---|
status |
zx/status
|
ConfigMulticastSetPromiscuousMode
Request
| Name | Type |
|---|---|
enabled |
bool
|
Response
| Name | Type |
|---|---|
status |
zx/status
|
ConfigMulticastTestFilter
Request
| Name | Type |
|---|
Response
| Name | Type |
|---|---|
status |
zx/status
|
DumpRegisters
Request
| Name | Type |
|---|
Response
| Name | Type |
|---|---|
status |
zx/status
|
GetFifos
Obtain a pair of fifos for queueing tx and rx operations
Request
| Name | Type |
|---|
Response
| Name | Type |
|---|---|
status |
zx/status
|
info |
Fifos?
|
GetInfo
Obtain information about device
Request
| Name | Type |
|---|
Response
| Name | Type |
|---|---|
info |
Info
|
GetStatus
Obtain the device status bits When these change, the signal SIGNAL_STATUS is asserted on the rx fifo. When these are read, the signal is deasserted.
Request
| Name | Type |
|---|
Response
| Name | Type |
|---|---|
device_status |
DeviceStatus
|
ListenStart
Start listening to the packets that we're transmitting as well as the packets we're receiving.
Request
| Name | Type |
|---|
Response
| Name | Type |
|---|---|
status |
zx/status
|
ListenStop
Stop listening to the packets that we're transmitting.
Request
| Name | Type |
|---|
Response
| Name | Type |
|---|
SetClientName
Request
| Name | Type |
|---|---|
name |
string[16]
|
Response
| Name | Type |
|---|---|
status |
zx/status
|
SetIOBuffer
Set the IO Buffer that will provide the data buffers for tx and rx operations
Request
| Name | Type |
|---|---|
h |
handle<vmo>
|
Response
| Name | Type |
|---|---|
status |
zx/status
|
SetPromiscuousMode
Request
| Name | Type |
|---|---|
enabled |
bool
|
Response
| Name | Type |
|---|---|
status |
zx/status
|
Start
Start transferring packets Start will not succeed (ZX_ERR_BAD_STATE) until the fifos have been obtained and an io buffer vmo has been registered.
Request
| Name | Type |
|---|
Response
| Name | Type |
|---|---|
status |
zx/status
|
Stop
Stop transferring packets
Request
| Name | Type |
|---|
Response
| Name | Type |
|---|
EthernetIfc
Defined in fuchsia.hardware.ethernet/ethernet.fidl
Recv
Request
| Name | Type |
|---|---|
data |
vector<uint8>
|
flags |
uint32
|
Response
| Name | Type |
|---|
Status
Value with bits set from the |ETHERNET_STATUS_*| flags
Request
| Name | Type |
|---|---|
status |
uint32
|
Response
| Name | Type |
|---|
EthernetImpl
Defined in fuchsia.hardware.ethernet/ethernet.fidl
The ethernet midlayer will never call ethermac_protocol methods from multiple threads simultaneously, but it can call send() methods at the same time as non-send methods.
GetBti
Get the BTI handle (needed to pin DMA memory) for this device. This method is only valid on devices that advertise ETHERNET_FEATURE_DMA The caller takes ownership of the BTI handle.
Request
| Name | Type |
|---|
Response
| Name | Type |
|---|---|
bti |
handle<bti>
|
Query
Obtain information about the ethermac device and supported features Safe to call at any time.
Request
| Name | Type |
|---|---|
options |
uint32
|
Response
| Name | Type |
|---|---|
s |
zx/status
|
info |
EthernetInfo
|
QueueTx
Request transmission of the packet in netbuf. The driver takes ownership of the netbuf and must call the completion callback passed in to return it once the enqueue is complete. The callback may be used to return the packet before transmission itself completes, and may called from within the queue_tx() implementation itself.
|QueueTx| may be called at any time after start() is called including from multiple threads simultaneously.
Return status indicates queue state: ZX_OK: Packet has been enqueued. Other: Packet could not be enqueued. Upon a return of ZX_OK, the packet has been enqueued, but no information is returned as to the completion state of the transmission itself.
Request
| Name | Type |
|---|---|
options |
uint32
|
netbuf |
EthernetNetbuf
|
Response
| Name | Type |
|---|---|
status |
zx/status
|
netbuf |
EthernetNetbuf
|
SetParam
Request a settings change for the driver. Return status indicates disposition: ZX_OK: Request has been handled. ZX_ERR_NOT_SUPPORTED: Driver does not support this setting. Other: Error trying to support this request.
|value| and |data| usage are defined for each |param|; see comments above.
set_param() may be called at any time after start() is called including from multiple threads simultaneously.
Request
| Name | Type |
|---|---|
param |
uint32
|
value |
int32
|
data |
vector<uint8>
|
Response
| Name | Type |
|---|---|
s |
zx/status
|
Start
Start ethermac running with ifc_virt Callbacks on ifc may be invoked from now until stop() is called
Request
| Name | Type |
|---|---|
ifc |
EthernetIfc
|
Response
| Name | Type |
|---|---|
s |
zx/status
|
Stop
Shut down a running ethermac Safe to call if the ethermac is already stopped.
Request
| Name | Type |
|---|
Response
| Name | Type |
|---|
STRUCTS
EthDevMetadata
Defined in fuchsia.hardware.ethernet/ethernet.fidl
| Name | Type | Description | Default |
|---|---|---|---|
vid |
uint32
|
No default | |
pid |
uint32
|
No default | |
did |
uint32
|
No default |
EthernetInfo
Defined in fuchsia.hardware.ethernet/ethernet.fidl
| Name | Type | Description | Default |
|---|---|---|---|
features |
uint32
|
No default | |
mtu |
uint32
|
No default | |
mac |
uint8[6]
|
No default | |
reserved0 |
uint8[2]
|
No default | |
netbuf_size |
uint64
|
No default | |
reserved1 |
uint32[2]
|
No default |
EthernetNetbuf
Defined in fuchsia.hardware.ethernet/ethernet.fidl
Note that this struct may have a private section encoded after it. Allocator much call parent device's |Query| to get the correct size.
| Name | Type | Description | Default |
|---|---|---|---|
data |
vector<uint8>
|
Provided by the generic ethernet driver. |
No default |
phys |
zx/paddr
|
Only used if ETHERNET_FEATURE_DMA is available. |
No default |
reserved |
uint16
|
No default | |
flags |
uint32
|
No default |
Fifos
Defined in fuchsia.hardware.ethernet/ethernet.fidl
| Name | Type | Description | Default |
|---|---|---|---|
rx |
handle<fifo>
|
No default | |
tx |
handle<fifo>
|
No default | |
rx_depth |
uint32
|
No default | |
tx_depth |
uint32
|
No default |
Info
Defined in fuchsia.hardware.ethernet/ethernet.fidl
| Name | Type | Description | Default |
|---|---|---|---|
features |
Features
|
No default | |
mtu |
uint32
|
No default | |
mac |
MacAddress
|
No default |
MacAddress
Defined in fuchsia.hardware.ethernet/ethernet.fidl
| Name | Type | Description | Default |
|---|---|---|---|
octets |
uint8[6]
|
No default |
ENUMS
EthernetFeature
Type: uint32
Defined in fuchsia.hardware.ethernet/ethernet.fidl
The ethernet interface supports both synchronous and asynchronous transmissions using the proto->queue_tx() and ifc->complete_tx() methods.
Receive operations are supported with the ifc->recv() interface.
The FEATURE_WLAN flag indicates a device that supports wlan operations.
The FEATURE_SYNTH flag indicates a device that is not backed by hardware.
The FEATURE_DMA flag indicates that the device can copy the buffer data using DMA and will ensure that physical addresses are provided in netbufs.
| Name | Value | Description |
|---|---|---|
WLAN |
1 |
|
SYNTH |
2 |
|
DMA |
4 |
BITS
DeviceStatus
Type: uint32
Defined in fuchsia.hardware.ethernet/ethernet.fidl
| Name | Value | Description |
|---|---|---|
| ONLINE | 1 |
Features
Type: uint32
Defined in fuchsia.hardware.ethernet/ethernet.fidl
Features distinguishes between NICs with different features.
| Name | Value | Description |
|---|---|---|
| WLAN | 1 | |
| SYNTHETIC | 2 | |
| LOOPBACK | 4 |
CONSTANTS
| Name | Value | Type | Description |
|---|---|---|---|
| ETHERNET_MULTICAST_FILTER_OVERFLOW |
-1
|
int32 |
|
| ETHERNET_SETPARAM_DUMP_REGS |
4
|
uint32 |
|
| ETHERNET_SETPARAM_MULTICAST_FILTER |
3
|
uint32 |
|value| is number of addresses, or ETHERNET_MULTICAST_FILTER_OVERFLOW for "too many to count." |data| is |value|*6 bytes of MAC addresses. Caller retains ownership. If |value| is _OVERFLOW, |data| is ignored. |
| ETHERNET_SETPARAM_MULTICAST_PROMISC |
2
|
uint32 |
|value| is bool. |data| is unused. |
| ETHERNET_SETPARAM_PROMISC |
1
|
uint32 |
SETPARAM_ values identify the parameter to set. Each call to set_param() takes an int32_t |value| and uint8_t* |data| which have meaning specific to the parameter being set. |value| is bool. |data| is unused. |
| ETHERNET_STATUS_ONLINE |
1
|
uint32 |
|
| ETHERNET_TX_OPT_MORE |
1
|
uint32 |
Indicates that additional data is available to be sent after this call finishes. Allows an ethernet driver to batch tx to hardware if possible. |
| ETH_FRAME_MAX_HDR_SIZE |
18
|
uint32 |
|
| ETH_FRAME_MAX_SIZE |
1518
|
uint32 |
|
| ETH_MAC_SIZE |
6
|
uint32 |
|
| ETH_MTU_SIZE |
1500
|
uint32 |
|
| MAX_CLIENT_NAME_LEN |
15
|
uint32 |
Max client name length |
| SET_CLIENT_NAME_MAX_LEN |
16
|
uint32 |
For compatibility with a past revision, allow one extra byte for an optional null-terminator. |
| SIGNAL_STATUS |
16777216
|
uint32 |
Signal that is asserted on the RX fifo whenever the Device has a status change. This is ZX_USER_SIGNAL_0. |