// Copyright 2018 The Fuchsia Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.

library fuchsia.hardware.ethernet;

using zx;

[ForDeprecatedCBindings]
struct MacAddress {
    array<uint8>:6 octets;
};

/// Features distinguishes between NICs with different features.
bits Features : uint32 {
    WLAN = 0x01;
    SYNTHETIC = 0x02;
    LOOPBACK = 0x04;
};

[ForDeprecatedCBindings]
struct Info {
    Features features;
    uint32 mtu;
    MacAddress mac;
};

[ForDeprecatedCBindings]
resource struct Fifos {
    // handles for the rx and tx fifo
    zx.handle:FIFO rx;
    zx.handle:FIFO tx;

    // maximum number of items in rx and tx fifo
    uint32 rx_depth;
    uint32 tx_depth;
};

/// Signal that is asserted on the RX fifo whenever the Device has a status
/// change.  This is ZX_USER_SIGNAL_0.
// TODO(teisenbe/kulakowski): find a better way to represent this
const uint32 SIGNAL_STATUS = 0x01000000;

bits DeviceStatus : uint32 {
    ONLINE = 1;
};

/// Max client name length
const uint32 MAX_CLIENT_NAME_LEN = 15;

/// For compatibility with a past revision, allow one extra byte for an optional
/// null-terminator.
const uint32 SET_CLIENT_NAME_MAX_LEN = 16;

/// 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.
[ForDeprecatedCBindings]
protocol Device {
    /// Obtain information about device
    GetInfo() -> (Info info);

    /// Obtain a pair of fifos for queueing tx and rx operations
    GetFifos() -> (zx.status status, Fifos? info);

    /// Set the IO Buffer that will provide the data buffers for tx and rx operations
    SetIOBuffer(zx.handle:VMO h) -> (zx.status status);

    /// 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.
    Start() -> (zx.status status);

    /// Stop transferring packets
    Stop() -> ();

    /// Start listening to the packets that we're transmitting
    /// as well as the packets we're receiving.
    ListenStart() -> (zx.status status);

    /// Stop listening to the packets that we're transmitting.
    ListenStop() -> ();

    SetClientName(string:SET_CLIENT_NAME_MAX_LEN name) -> (zx.status status);

    /// 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.
    GetStatus() -> (DeviceStatus device_status);

    SetPromiscuousMode(bool enabled) -> (zx.status status);

    ConfigMulticastAddMac(MacAddress addr) -> (zx.status status);
    ConfigMulticastDeleteMac(MacAddress addr) -> (zx.status status);
    ConfigMulticastSetPromiscuousMode(bool enabled) -> (zx.status status);

    // TODO(teisenbe): We should probably remove these?  They are only used for testing.
    ConfigMulticastTestFilter() -> (zx.status status);
    DumpRegisters() -> (zx.status status);
};