sdk/fidl/fuchsia.hardware.network/device.fidl

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

/// Maximum numbers of supported frame types for rx or tx.
// NOTE(brunodalbo) 4 seems a sensible number for maximum number of frame types supported by a
// single device. Most common use cases are going to use 1 or 2 types (1 if device operates at L2, 2
// if at L3).
const uint32 MAX_FRAME_TYPES = 4;

/// Maximum length of session label.
const uint32 MAX_SESSION_NAME = 64;

/// Maximum number of acceleration flags.
///
/// Each descriptor has 16 bits of space for acceleration flags ([`RxFlags`] and [`TxFlags`]) thus
/// the maximum number of reported accelerations is 16. Each descriptor reports which accelerations
/// were applied (`RxFlags`) or are requested (`TxFlags`) by mapping indexes in the vector of
/// supported accelerations ([`Info.rx_accel`] and ([`Info.tx_accel`]) to bits in the respective
/// acceleration flags bitfield.
const uint32 MAX_ACCEL_FLAGS = 16;

/// Network device information.
table DeviceInfo {
    /// Minimum descriptor length, in 64-bit words. Required.
    ///
    /// The minimum length that each buffer descriptor must have for correct operation with this
    /// device. Devices that support extra frame metadata inform larger minimum descriptor lengths
    /// that reflect the minimum space needed to be able to store frame metadata.
    1: uint8 min_descriptor_length;
    /// Accepted descriptor version. Required.
    2: uint8 descriptor_version;
    /// Maximum number of items in rx FIFO (per session). Required.
    ///
    /// `rx_depth` is calculated based on the size of the actual backing hardware rx queue.
    3: uint16 rx_depth;
    /// Maximum number of items in tx FIFO (per session). Required.
    ///
    /// `tx_depth` is calculated based on the size of the actual backing hardware tx queue.
    4: uint16 tx_depth;
    /// Alignment requirement for buffers in the data VMO.
    ///
    /// All buffers in the data VMO *must* be aligned to `buffer_alignment` relative to the start of
    /// the VMO. `buffer_alignment == 0` is never reported. Required.
    5: uint32 buffer_alignment;
    /// Maximum supported length of buffers in the data VMO, in bytes. Required.
    6: uint32 max_buffer_length;
    /// The minimum rx buffer length required for device. Required.
    7: uint32 min_rx_buffer_length;
    /// The minimum tx buffer length required for the device. Required.
    ///
    /// This value accounts only for tx payload length, `min_tx_buffer_head` and
    /// `min_tx_buffer_tail` are not part of this value.
    ///
    /// Clients must zero pad outgoing frames to meet the required minimum length.
    8: uint32 min_tx_buffer_length;
    /// The number of bytes the device requests be free as `head` space in a tx buffer. Required.
    9: uint16 min_tx_buffer_head;
    /// The amount of bytes the device requests be free as `tail` space in a tx buffer. Required.
    10: uint16 min_tx_buffer_tail;
    /// Maximum descriptor chain length accepted by the device. Required.
    11: uint8 max_buffer_parts;
    /// Available rx acceleration flags for this device.
    ///
    /// `rx_accel` maps the `RX_ACCEL_*` flags in the frame descriptors with semantic acceleration
    /// features described by [`RxAcceleration`]. Position `n` of `rx_accel` conveys the meaning of
    /// the `RX_ACCEL_n` flag.
    ///
    /// Interpreted as empty if not provided.
    12: vector<RxAcceleration>:MAX_ACCEL_FLAGS rx_accel;
    /// Available tx acceleration flags for this device.
    ///
    /// `tx_accel` maps the `TX_ACCEL_*` flags in the frame descriptors with semantic acceleration
    /// features described by [`TxAcceleration`]. Position `n` of `tx_accel` conveys the meaning of
    /// the `TX_ACCEL_n` flag.
    ///
    /// Interpreted as empty if not provided.
    13: vector<TxAcceleration>:MAX_ACCEL_FLAGS tx_accel;
};

/// A Network Device.
protocol Device {
    /// Obtain information about device
    ///
    /// - response `info` device information.
    GetInfo() -> (DeviceInfo info);
    /// Opens a new session with the network device.
    ///
    /// + request `session_name` is used as a debugging label attached to this session.
    /// + request `session_info` contains the necessary information to setup the session's data
    /// exchange.
    /// - response `session` a handle to control the session.
    /// - response `fifos` data-plane FIFOs attached to the session.
    /// * error `ZX_ERR_NOT_SUPPORTED` if `session_info` contains not supported frame types or
    /// descriptors set up.
    /// * error `ZX_ERR_INVALID_ARGS` if `session_info` is missing fields or contains invalid
    /// information.
    OpenSession(string:MAX_SESSION_NAME session_name, SessionInfo session_info) -> (Session session, Fifos fifos) error zx.status;
    /// Connects to a port the given `id`.
    ///
    /// + request `id` port to connect to.
    /// + request `port` server end of port channel.
    ///
    /// `port` is closed with a `ZX_ERR_NOT_FOUND` epitaph if no port with `id` exists.
    GetPort(port_id id, request<Port> port);
    /// Connects a [`PortWatcher`] to this device.
    ///
    /// + request `watcher` server end of watcher channel.
    GetPortWatcher(request<PortWatcher> watcher);
};

/// Provides iteration over and updates for ports attached to a device.
protocol PortWatcher {
    /// Get the next port event.
    ///
    /// The first N calls return [`DevicePortEvent.existing`] where N is the number of ports present
    /// on the device at the time of the watcher's creation. The next call returns
    /// [`DevicePortEvent.idle`] to indicate the end of existing ports. Subsequent calls block until
    /// a port is added ([`DevicePortEvent.added`]) or removed ([`DevicePortEvent.removed`]).
    ///
    /// The server closes the `PortWatcher` channel with `ZX_ERR_CANCELED` if the number of unread
    /// events reaches a server-selected limit that is at least two times [`MAX_PORTS`]. Clients are
    /// encouraged to maintain a hanging call to `Watch` at all times to avoid triggering this
    /// condition.
    ///
    /// - response `event` next port event.
    Watch() -> (DevicePortEvent event);
};

struct Empty {
};

/// Port creation and destruction events.
// TODO(https://fxbug.dev/66767): `PortEvent` is probably a better name here, but it causes rust
// binding errors.
union DevicePortEvent {
    /// Port existed when watcher was created.
    1: port_id existing;
    /// New port was added to device.
    2: port_id added;
    /// Port was removed from the device.
    3: port_id removed;
    /// Exhausted list of existing ports.
    4: Empty idle;
};