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

using zx;

/// Represents a session with a Network device.
///
/// A session has a data plane and a control plane. The `Session` protocol represents the control
/// plane of the session and the FIFOs and VMOs exchanged during the [`Device.OpenSession`] call are
/// the data plane. Lifetime of the session is controlled by a `Session` protocol handle.
///
/// Sessions must attach to ports of interest to start receiving and sending data. Sessions are
/// always created with no ports attached.
///
/// If a port is destroyed from the underlying device, it is automatically detached from the
/// session.
///
/// The session is closed with an error epitaph if an invalid buffer descriptor is sent over either
/// the tx or rx FIFOs. Invalid descriptors include:
///    - Descriptor index larger than [`SessionInfo.descriptor_count`].
///    - Descriptor chains larger than [`MAX_DESCRIPTOR_CHAIN`].
///    - rx buffers smaller than [`Info.min_rx_buffer_length`].
///    - tx buffers smaller than [`Info.min_tx_buffer_length`].
///    - tx buffers not respecting [`Info.min_tx_buffer_head`] or [`Info.min_tx_buffer_tail`].
protocol Session {
    /// Attaches the session to `port`.
    ///
    /// Once attached, the session starts to receive the subscribed frames over the data FIFOs and
    /// it may send frames destined to the specified `port`.
    ///
    /// + request `port` port to subscribe to.
    /// + request `fx_frames` Frame types of interest on the port.
    /// * error `ZX_ERR_NOT_FOUND` if `port` is not valid.
    /// * error `ZX_ERR_INVALID_ARGS` if `rx_frames` is not a subset of the port's supported frames.
    /// * error `ZX_ERR_ALREADY_BOUND` if `port` is already attached.
    Attach(port_id port, vector<FrameType>:MAX_FRAME_TYPES rx_frames) -> () error zx.status;
    /// Detaches the session from `port`.
    ///
    /// Once detached, the session stops receiving frames from `port`. Frames sent to a detached
    /// port may be returned with an error. It is not necessary to call `Detach` on ports that are
    /// removed from the device, doing so causes `ZX_ERR_NOT_FOUND` to be returned.
    ///
    /// + request `port` port to subscribe to.
    /// * error `ZX_ERR_NOT_FOUND` if the session is not currently attached to the port.
    Detach(port_id port) -> () error zx.status;
    /// Cleanly closes a session.
    ///
    /// This will cause the session to send a `ZX_ERR_CANCELLED` epitaph and proceed to close the
    /// Session channel. Clients may only assume that they own all the buffers that are currently
    /// owned by the session (sent over either the rx or tx FIFOs) once the epitaph is received.
    /// Closing the rx or tx FIFO is equivalent to calling `Close`.
    Close();
};

/// Additional session options.
bits SessionFlags : uint16 {
    /// Attach as primary session.
    ///
    /// Sessions marked with the `PRIMARY` bit get the following different treatment:
    /// - If no PRIMARY sessions are attached, the device will *not* serve rx frames to non-PRIMARY
    ///   sessions.
    /// - If there's only one PRIMARY session active, it may get a zero-copy data path from the
    ///   the backing hardware, if the underlying implementation supports it.
    PRIMARY = 0x0001;
    /// Listen for outgoing frames.
    ///
    /// `LISTEN_TX` sessions receive any outgoing frames (from all sessions) on its rx path. Can be
    /// used for snooping traffic. Sessions marked with `LISTEN_TX` may also send frames, but they
    /// should keep in mind that they'll ALWAYS receive those frames back on their rx path (no
    /// origin session filtering is performed).
    LISTEN_TX = 0x0002;
    /// Receive invalid rx frames.
    ///
    /// Sessions marked with `REPORT_INVALID_RX` are interested in receiving frames that were
    /// rejected by internal device checks or payload validation performed by hardware. Due to the
    /// nature of some hardware platforms, sessions marked with `REPORT_INVALID_RX` may still not
    /// receive frames that fail validation if the hardware implementation simply drops the frame
    /// and doesn't expose it to the software stack. Sessions NOT marked with `REPORT_INVALID_RX`,
    /// in contrast, will NEVER receive an rx frame with the `RX_VALIDATION_ERROR` flag set.
    REPORT_INVALID_RX = 0x0004;
};

/// Data-plane FIFOs.
resource struct Fifos {
    /// Handle for the rx FIFO.
    ///
    /// Clients must write 16-bit descriptor indexes to this FIFO to be able to receive
    /// frames.
    zx.handle:FIFO rx;
    /// Handle for the tx FIFO.
    ///
    /// Clients write 16-bit descriptor indexes to this FIFO to enqueue outgoing frames.
    zx.handle:FIFO tx;
};

/// Session configuration.
resource table SessionInfo {
    /// VMO containing the descriptors. Required.
    ///
    /// 16-bit indices transmitted over the FIFOs index a descriptor in this VMO (byte offset =
    /// descriptor_length * 8 * index).
    1: zx.handle:VMO descriptors;
    /// VMO containing frame data. Required.
    ///
    /// Descriptors contain byte-offsets that are used to index arbitrary regions in `data`.
    2: zx.handle:VMO data;
    /// Requested descriptor version. Required.
    ///
    /// If the network device does not support the requested descriptor version,
    /// [`Device.OpenSession`] fails with `ZX_ERR_NOT_SUPPORTED`.
    3: uint8 descriptor_version;
    /// Descriptor length, in 64-bit words. Required.
    ///
    /// The length of each descriptor in the `descriptors` VMO. This is used as a multiplier to find
    /// byte offsets in `descriptors` given a descriptor index passed through the rx or tx FIFOs.
    4: uint8 descriptor_length;
    /// Total number of descriptors that can be used by this session. Required.
    ///
    /// Descriptor indices transferred through either the rx or tx FIFO must be in the range [0,
    /// `descriptor_count`).
    5: uint16 descriptor_count;
    /// Extra options. Interpreted as empty bitmask if absent.
    6: SessionFlags options;
};