// 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;

@for_deprecated_c_bindings
type MacAddress = struct {
    octets array<uint8, 6>;
};

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

@for_deprecated_c_bindings
type Info = struct {
    features Features;
    mtu uint32;
    mac MacAddress;
};

@for_deprecated_c_bindings
type Fifos = resource struct {
    // handles for the rx and tx fifo
    rx zx.handle:FIFO;
    tx zx.handle:FIFO;

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

/// 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 SIGNAL_STATUS uint32 = 0x01000000;

type DeviceStatus = strict bits : uint32 {
    ONLINE = 1;
};

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

/// For compatibility with a past revision, allow one extra byte for an optional
/// null-terminator.
const SET_CLIENT_NAME_MAX_LEN uint32 = 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.
@for_deprecated_c_bindings
protocol Device {
    /// Obtain information about device
    GetInfo() -> (struct {
        info Info;
    });

    /// Obtain a pair of fifos for queueing tx and rx operations
    GetFifos() -> (resource struct {
        status zx.status;
        info box<Fifos>;
    });

    /// Set the IO Buffer that will provide the data buffers for tx and rx operations
    SetIOBuffer(resource struct {
        h zx.handle:VMO;
    }) -> (struct {
        status zx.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() -> (struct {
        status zx.status;
    });

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

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

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

    SetClientName(struct {
        name string:SET_CLIENT_NAME_MAX_LEN;
    }) -> (struct {
        status zx.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() -> (struct {
        device_status DeviceStatus;
    });

    SetPromiscuousMode(struct {
        enabled bool;
    }) -> (struct {
        status zx.status;
    });

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

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