blob: da716dd7c510d30b1656986a4ef1698a4d061fb4 [file] [log] [blame]
// 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.
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.
/// Inbound traffic is dispatched to all open sessions. Devices typically
/// operate with a single primary session, see [`SessionFlags.PRIMARY`]. Each
/// additional open session to the same device causes data copy overhead on the
/// device's data path.
/// 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 `rx_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(struct {
port PortId;
rx_frames vector<FrameType>:MAX_FRAME_TYPES;
}) -> (struct {}) 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(struct {
port PortId;
}) -> (struct {}) 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`.
/// Additional session options.
type SessionFlags = strict bits : 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.
/// Data-plane FIFOs.
type Fifos = resource struct {
/// Handle for the rx FIFO.
/// Clients must write 16-bit descriptor indexes to this FIFO to be able to
/// receive frames.
rx zx.handle:FIFO;
/// Handle for the tx FIFO.
/// Clients write 16-bit descriptor indexes to this FIFO to enqueue outgoing
/// frames.
tx zx.handle:FIFO;
/// Session configuration.
type SessionInfo = resource table {
/// 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: descriptors zx.handle:VMO;
/// VMO containing frame data. Required.
/// Descriptors contain byte-offsets that are used to index arbitrary
/// regions in `data`.
2: data zx.handle:VMO;
/// Requested descriptor version. Required.
/// If the network device does not support the requested descriptor version,
/// [`Device.OpenSession`] fails with `ZX_ERR_NOT_SUPPORTED`.
3: descriptor_version uint8;
/// 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: descriptor_length uint8;
/// 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: descriptor_count uint16;
/// Extra options. Interpreted as empty bitmask if absent.
6: options SessionFlags;