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 zircon.ethernet;
6
7using zx;
8
9struct MacAddress {
10    array<uint8>:6 octets;
11};
12
13// Info.features bits
14const uint32 INFO_FEATURE_WLAN = 0x00000001;
15const uint32 INFO_FEATURE_SYNTH = 0x00000002;
16const uint32 INFO_FEATURE_LOOPBACK = 0x00000004;
17
18struct Info {
19    uint32 features;
20    uint32 mtu;
21    MacAddress mac;
22};
23
24struct Fifos {
25    // handles for the rx and tx fifo
26    handle<fifo> rx;
27    handle<fifo> tx;
28
29    // maximum number of items in rx and tx fifo
30    uint32 rx_depth;
31    uint32 tx_depth;
32};
33
34// device_status bits
35const uint32 DEVICE_STATUS_ONLINE = 0x00000001;
36
37// zircon/device/ethernet.h
38[Layout = "Simple"]
39interface Device {
40    // Obtain information about device
41    1: GetInfo() -> (Info info);
42
43    // Obtain a pair of fifos for queueing tx and rx operations
44    2: GetFifos() -> (zx.status status, Fifos? info);
45
46    // Set the IO Buffer that will provide the data buffers for tx and rx operations
47    3: SetIOBuffer(handle<vmo> h) -> (zx.status status);
48
49    // Start transferring packets
50    // Start will not succeed (ZX_ERR_BAD_STATE) until the fifos have been
51    // obtained and an io buffer vmo has been registered.
52    4: Start() -> (zx.status status);
53
54    // Stop transferring packets
55    5: Stop() -> ();
56
57    // Start listening to the packets that we're transmitting
58    // as well as the packets we're receiving.
59    6: ListenStart() -> (zx.status status);
60
61    // Stop listening to the packets that we're transmitting.
62    7: ListenStop() -> ();
63
64    // `#define DEVICE_NAME_LEN 16`
65    8: SetClientName(string:16 name) -> (zx.status status);
66
67    // Obtain the device status bits
68    // When these change, ZX_USER_SIGNAL_0 is asserted on the rx fifo.
69    // When these are read, the signal is deasserted.
70    9: GetStatus() -> (uint32 device_status);
71
72    10: SetPromiscuousMode(bool enabled) -> (zx.status status);
73
74    // TODO(tamird): do we need to support this?
75    // 11: ConfigMulticast(eth_multicast_config_t) -> (zx.status status);
76};
77
78// Operation
79//
80// Packets are transmitted by writing data into the io_vmo and writing
81// an FifoEntry referencing that data (offset + length) into the tx fifo.
82// When the driver is done accessing the data, a FifoEntry with the same
83// cookie value (opaque to the driver) will be readable from the tx fifo.
84//
85// Packets are received by writing a FifoEntry referencing an available
86// buffer (offset + length) in the io vmo.  When a packet is received,
87// a FifoEntry with the same cookie value (opaque to the driver) will be
88// readable from the rx fifo.  The offset field will be the same as was
89// sent.  The length field will reflect the actual size of the received
90// packet.  The flags field will indicate success or a specific failure
91// condition.
92//
93// IMPORTANT: The driver *will not* buffer response messages.  It is the
94// client's responsibility to ensure that there is space in the reply side
95// of each fifo for each outstanding tx or rx request.  The fifo sizes
96// are returned along with the fifo handles from GetFifos().
97
98// flags values for request messages
99// - none -
100
101// flags values for response messages
102const uint32 FIFO_RX_OK = 0x00000001; // packet received okay
103const uint32 FIFO_TX_OK = 0x00000001; // packet transmitted okay
104const uint32 FIFO_INVALID = 0x00000002; // offset+length not within io_vmo bounds
105const uint32 FIFO_RX_TX = 0x00000004; // received our own tx packet (when Listen enabled)
106
107struct FifoEntry {
108    // offset from start of io vmo to packet data
109    uint32 offset;
110
111    // length of packet data to tx or rx
112    uint16 length;
113
114    // FIFO_* flags as above
115    uint16 flags;
116
117    // opaque cookie
118    uint64 cookie;
119};
120