// Copyright 2020 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.network;

/// Types of frames.
type FrameType = strict enum : uint8 {
    ETHERNET = 0x01;
    IPV4 = 0x02;
    IPV6 = 0x03;
};

/// Blanket definition for raw frames.
///
/// Devices that do not perform any sort of parsing of outbound traffic should
/// define `FRAME_FEATURES_RAW` in the [`FrameTypeSupport`] entry.
const FRAME_FEATURES_RAW uint32 = 1;

/// Ethernet frame sub-types and features.
type EthernetFeatures = strict bits : uint32 {
    /// Device supports any type of ethernet frame.
    ///
    /// Same as specifying all other flags. Used by devices that do not inspect
    /// or parse outbound traffic.
    RAW = 1;
    /// Device supports EthernetII frames.
    ETHERNET_II = 2;
    /// Device supports 802.1q VLAN additions.
    E_802_1_Q = 4;
    /// Device supports 802.1 q-in-q Multiple VLAN tagging additions.
    ///
    /// Only meaningful if `E_802_1_Q` is also present.
    E_802_1_Q_IN_Q = 8;
    /// Device supports 802.3 LLC + SNAP Ethernet frame format.
    E_802_3_LLC_SNAP = 16;
};

/// Specifies a frame type and features and supported flags associated with that
/// type.
///
/// This is used by clients to read the supported frames on the tx path for a
/// given Network Device.
///
/// Some Network Devices may parse outgoing frames to perform frame
/// transformation or specific hardware support. Each frame type has an
/// associated [`FrameTypeSupport.features`] bits enumeration that lists
/// FrameType-specific features that may or may not be supported. Devices that
/// do not perform parsing are encouraged to just use the [`FRAME_FEATURES_RAW`]
/// bit in `features`, which informs the client that all frame features are
/// allowed.
type FrameTypeSupport = struct {
    /// The frame type this support entry refers to.
    type FrameType;
    /// The frame type-specific features supported.
    features uint32;
    /// The flags supported for the given frame type.
    supported_flags TxFlags;
};

/// Maximum number of chained descriptors that describe a single frame.
const MAX_DESCRIPTOR_CHAIN uint8 = 4;

/// The type of metadata information appended to a frame.
type InfoType = strict enum : uint32 {
    /// No extra information is available.
    NO_INFO = 0x00;
};

/// Available rx acceleration features.
///
/// Features are mapped to the `RX_ACCEL_*` bits in descriptors by the available
/// values reported in [`Info.rx_accel`].
type RxAcceleration = strict enum : uint8 {
    /// Inbound rx frame validated the Ethernet Frame Check Sequence.
    VALIDATED_ETHERNET_FCS = 0;
    /// Inbound rx frame validated the IPv4 checksum.
    VALIDATED_IPV4_CHECKSUM = 1;
    /// Inbound rx frame validated the TCP checksum.
    VALIDATED_TCP_CHECKSUM = 2;
    /// Inbound rx frame validated the UDP checksum.
    VALIDATED_UDP_CHECKSUM = 3;
};

/// Available tx acceleration features.
///
/// Features are mapped to the `TX_ACCEL_*` bits in descriptors by the available
/// values reported in [`Info.tx_accel`].
type TxAcceleration = strict enum : uint8 {
    /// Request that device calculate the Ethernet Frame Check Sequence and
    /// write it in place.
    COMPUTE_ETHERNET_FCS = 0;
    /// Request that the device calculate the IPv4 checksum and write it in
    /// place.
    COMPUTE_IPV4_CHECKSUM = 1;
    /// Request that the device calculate the TCP checksum and write it in
    /// place.
    COMPUTE_TCP_CHECKSUM = 2;
    /// Request that the device calculate the UDP checksum and write it in
    /// place.
    COMPUTE_UDP_CHECKSUM = 3;
    // Future expansions: TCP segmentation acceleration
};

/// Flags set by a Device when handing a buffer to a client on the rx path.
///
/// Set by devices on the `inbound_flags` field of an rx descriptor.
type RxFlags = strict bits : uint32 {
    /// Acceleration flag 0.
    ///
    /// Acceleration flags are mapped to the acceleration features reported by
    /// the [`Device`] in [`Info.rx_accel`]. The n-th feature in `rx_accel` maps
    /// to the `RX_ACCEL_n` `RxFlag`.
    RX_ACCEL_0 = 0x00000001;
    RX_ACCEL_1 = 0x00000002;
    RX_ACCEL_2 = 0x00000004;
    RX_ACCEL_3 = 0x00000008;
    RX_ACCEL_4 = 0x00000010;
    RX_ACCEL_5 = 0x00000020;
    RX_ACCEL_6 = 0x00000040;
    RX_ACCEL_7 = 0x00000080;
    RX_ACCEL_8 = 0x00000100;
    RX_ACCEL_9 = 0x00000200;
    RX_ACCEL_10 = 0x00000400;
    RX_ACCEL_11 = 0x00000800;
    RX_ACCEL_12 = 0x00001000;
    RX_ACCEL_13 = 0x00002000;
    RX_ACCEL_14 = 0x00004000;
    RX_ACCEL_15 = 0x00008000;

    // RESERVED - bits 16 to 28 reserved for future expansions

    /// Device experienced a hardware rx overrun.
    ///
    /// Rx overruns are typically set by hardware controllers when a frame event
    /// was detected but the frame data couldn't be captured. Devices should
    /// clear the controller flag once this is set on an inbound frame, so
    /// future overruns can be detected and reported.
    RX_OVERRUN = 0x20000000;
    /// This bit is set if frame validation is performed (such as by hardware
    /// acceleration features) and fails.
    ///
    /// It's important to note that some devices may simply discard frames for
    /// which validation fails and never notify the client. Rx frames that
    /// failed validation are only transmitted to the client if the
    /// `SessionFlags::REPORT_INVALID_RX` option is selected when creating a
    /// session.
    RX_VALIDATION_ERROR = 0x40000000;
    /// This is an echoed tx frame, created by a tx request.
    ///
    /// Can only be set in sessions that have the `LISTEN_TX` flag.
    RX_ECHOED_TX = 0x80000000;
};

/// Flags set by a Client when handing a buffer to a client on the tx path.
///
/// Set by Clients on the `inbound_flags` field of a tx descriptor.
type TxFlags = strict bits : uint32 {
    /// Acceleration flag 0.
    ///
    /// Acceleration flags are mapped to the acceleration features reported by
    /// the [`Device`] in [`Info.tx_accel`]. The n-th feature in `tx_accel` maps
    /// to the `TX_ACCEL_n` `TxFlag`.
    TX_ACCEL_0 = 0x00000001;
    TX_ACCEL_1 = 0x00000002;
    TX_ACCEL_2 = 0x00000004;
    TX_ACCEL_3 = 0x00000008;
    TX_ACCEL_4 = 0x00000010;
    TX_ACCEL_5 = 0x00000020;
    TX_ACCEL_6 = 0x00000040;
    TX_ACCEL_7 = 0x00000080;
    TX_ACCEL_8 = 0x00000100;
    TX_ACCEL_9 = 0x00000200;
    TX_ACCEL_10 = 0x00000400;
    TX_ACCEL_11 = 0x00000800;
    TX_ACCEL_12 = 0x00001000;
    TX_ACCEL_13 = 0x00002000;
    TX_ACCEL_14 = 0x00004000;
    TX_ACCEL_15 = 0x00008000;
};

/// Flags set by a Device when returning a tx buffer back to a client.
///
/// Set by Devices on the `return_flags` field of a tx descriptor.
type TxReturnFlags = strict bits : uint32 {
    /// Requested operation in `inbound_flags` is not supported; the frame was
    /// not sent.
    ///
    /// Always set in conjunction with `TX_RET_ERROR`.
    TX_RET_NOT_SUPPORTED = 1;
    /// Could not allocate resources to send frame.
    ///
    /// Always set in conjunction with `TX_RET_ERROR`.
    TX_RET_OUT_OF_RESOURCES = 2;
    /// Device is not available (offline or disconnected); the frame was not
    /// sent.
    ///
    /// Always set in conjunction with `TX_RET_ERROR`.
    TX_RET_NOT_AVAILABLE = 4;

    // An error occurred sending this frame.
    TX_RET_ERROR = 0x80000000;
};