// 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
/// [`fuchsia.hardware.network/Device.OpenSession`] call are the data plane. Lifetime of the session
/// is controlled by a `Session` protocol handle. Sessions are always created in a paused state.
///
/// The session will be 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 [`fuchsia.hardware.network/SessionInfo.descriptor_count`].
///    - Descriptor chains larger than [`fuchsia.hardware.network/MAX_DESCRIPTOR_CHAIN`].
///    - rx buffers smaller than [`fuchsia.hardware.network/Info.min_rx_buffer_length`].
///    - tx buffers smaller than [`fuchsia.hardware.network/Info.min_tx_buffer_length`].
///    - tx buffers not respecting [`fuchsia.hardware.network/Info.min_tx_buffer_head`] or
///    [`fuchsia.hardware.network/Info.min_tx_buffer_tail`].
protocol Session {
    /// Pauses or unpauses reception of frames on this session.
    SetPaused(bool paused);
    /// 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 {
    /// 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_TX` sessions will 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;
    /// 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 struct SessionInfo {
    /// VMO containing the descriptors. 16-bit indices transmitted over the FIFOs index a descriptor
    /// in this VMO (byte offset = descriptor_length * 8 * index).
    zx.handle:VMO descriptors;
    /// VMO containing frame data. Descriptors contain byte-offsets that are used to index
    /// arbitrary regions in `data`.
    zx.handle:VMO data;
    /// Requested descriptor version. If the network device does not support the requested
    /// descriptor version, [`fuchsia.hardware.network/Device.OpenSession`] will fail with
    /// `ZX_ERR_NOT_SUPPORTED`.
    uint8 descriptor_version;
    /// Descriptor length, in 64-bit words. 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.
    uint8 descriptor_length;
    /// Total number of descriptors that can be used by this session. Descriptor indices transferred
    /// through either the rx or tx FIFO must be in the range [0, `descriptor_count`).
    uint16 descriptor_count;
    /// Extra options.
    SessionFlags options;
    /// List of frame types the client is subscribing to.
    vector<FrameType>:MAX_FRAME_TYPES rx_frames;
};