1// Copyright 2018 The Fuchsia Authors. All rights reserved.
2// Use of this source code is governed by a BSD-style license that can be
3// found in the LICENSE file.
4
5library fuchsia.hardware.ethernet;
6
7using zx;
8
9struct MacAddress {
10    array<uint8>:6 octets;
11};
12
13const uint32 DEFAULT_BUFFER_SIZE = 2048; // bytes
14/// When writing payload to a tx buffer, clients of a Device must skip this many bytes
15/// so that lower-layer drivers can fill in additional headers in that space.
16const uint32 MAC_HDR_MAX_SIZE    = 64;   // bytes, the closest power of 2 larger than 44, which is
17                                         // DataFrameHeader::max_size(36) + LlcHeader::max_size(8)
18
19// Info.features bits
20const uint32 INFO_FEATURE_WLAN = 0x00000001;
21const uint32 INFO_FEATURE_SYNTH = 0x00000002;
22const uint32 INFO_FEATURE_LOOPBACK = 0x00000004;
23
24struct Info {
25    uint32 features;
26    uint32 mtu;
27    MacAddress mac;
28};
29
30struct Fifos {
31    // handles for the rx and tx fifo
32    handle<fifo> rx;
33    handle<fifo> tx;
34
35    // maximum number of items in rx and tx fifo
36    uint32 rx_depth;
37    uint32 tx_depth;
38};
39
40// Signal that is asserted on the RX fifo whenever the Device has a status
41// change.  This is ZX_USER_SIGNAL_0.
42// TODO(teisenbe/kulakowski): find a better way to represent this
43const uint32 SIGNAL_STATUS = 0x01000000;
44
45// device_status bits
46const uint32 DEVICE_STATUS_ONLINE = 0x00000001;
47
48// Max client name length
49const uint32 MAX_CLIENT_NAME_LEN = 15;
50
51// For compatibility with a past revision, allow one extra byte for an optional
52// null-terminator.
53const uint32 SET_CLIENT_NAME_MAX_LEN = 16;
54
55// zircon/device/ethernet.h
56[Layout = "Simple"]
57interface Device {
58    // Obtain information about device
59    1: GetInfo() -> (Info info);
60
61    // Obtain a pair of fifos for queueing tx and rx operations
62    2: GetFifos() -> (zx.status status, Fifos? info);
63
64    // Set the IO Buffer that will provide the data buffers for tx and rx operations
65    3: SetIOBuffer(handle<vmo> h) -> (zx.status status);
66
67    // Start transferring packets
68    // Start will not succeed (ZX_ERR_BAD_STATE) until the fifos have been
69    // obtained and an io buffer vmo has been registered.
70    4: Start() -> (zx.status status);
71
72    // Stop transferring packets
73    5: Stop() -> ();
74
75    // Start listening to the packets that we're transmitting
76    // as well as the packets we're receiving.
77    6: ListenStart() -> (zx.status status);
78
79    // Stop listening to the packets that we're transmitting.
80    7: ListenStop() -> ();
81
82    8: SetClientName(string:SET_CLIENT_NAME_MAX_LEN name) -> (zx.status status);
83
84    // Obtain the device status bits
85    // When these change, the signal SIGNAL_STATUS is asserted on the rx fifo.
86    // When these are read, the signal is deasserted.
87    9: GetStatus() -> (uint32 device_status);
88
89    10: SetPromiscuousMode(bool enabled) -> (zx.status status);
90
91    11: ConfigMulticastAddMac(MacAddress addr) -> (zx.status status);
92    12: ConfigMulticastDeleteMac(MacAddress addr) -> (zx.status status);
93    13: ConfigMulticastSetPromiscuousMode(bool enabled) -> (zx.status status);
94
95    // TODO(teisenbe): We should probably remove these?  They are only used for testing.
96    14: ConfigMulticastTestFilter() -> (zx.status status);
97    15: DumpRegisters() -> (zx.status status);
98};
99
100// Operation
101//
102// Packets are transmitted by writing data into the io_vmo and writing
103// an FifoEntry referencing that data (offset + length) into the tx fifo.
104// When the driver is done accessing the data, a FifoEntry with the same
105// cookie value (opaque to the driver) will be readable from the tx fifo.
106//
107// Packets are received by writing a FifoEntry referencing an available
108// buffer (offset + length) in the io vmo.  When a packet is received,
109// a FifoEntry with the same cookie value (opaque to the driver) will be
110// readable from the rx fifo.  The offset field will be the same as was
111// sent.  The length field will reflect the actual size of the received
112// packet.  The flags field will indicate success or a specific failure
113// condition.
114//
115// IMPORTANT: The driver *will not* buffer response messages.  It is the
116// client's responsibility to ensure that there is space in the reply side
117// of each fifo for each outstanding tx or rx request.  The fifo sizes
118// are returned along with the fifo handles from GetFifos().
119
120// flags values for request messages
121// - none -
122
123// flags values for response messages
124const uint16 FIFO_RX_OK   = 0x00000001; // packet received okay
125const uint16 FIFO_TX_OK   = 0x00000001; // packet transmitted okay
126const uint16 FIFO_INVALID = 0x00000002; // offset+length not within io_vmo bounds
127const uint16 FIFO_RX_TX   = 0x00000004; // received our own tx packet (when Listen enabled)
128
129struct FifoEntry {
130    // offset from start of io vmo to packet data
131    uint32 offset;
132
133    // length of packet data to tx or rx
134    uint16 length;
135
136    // FIFO_* flags as above
137    uint16 flags;
138
139    // opaque cookie
140    uint64 cookie;
141};
142