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

/// The maximum number of status samples that can be buffered by a [`StatusWatcher`].
const uint32 MAX_STATUS_BUFFER = 50;

/// The maximum number of ports attached to a device at a given time.
const uint8 MAX_PORTS = 32;

/// The identifier of a port within a device. Always less than [`MAX_PORTS`].
alias port_id = uint8;

/// Network device class.
// TODO(https://fxbug.dev/76232): Rename to PortClass once we can easily soft transition through
// aliasing to prevent source breakages.
enum DeviceClass : uint16 {
    UNKNOWN = 0x00;
    ETHERNET = 0x01;
    WLAN = 0x02;
    PPP = 0x03;
    BRIDGE = 0x04;
    // TODO(https://fxbug.dev/77697): Add WLAN_AP here and make this enum flexible so we don't break
    // chromium.
};

/// Network port class.
alias PortClass = DeviceClass;

/// Port status bits, reported in [`PortStatus.flags`].
bits StatusFlags : uint32 {
    /// Port is online, i.e., data path is open and any ongoing sessions may send and receive
    /// frames.
    ONLINE = 0x01;
};

/// Dynamic port information.
table PortStatus {
    /// Port status flags.
    1: StatusFlags flags;
    /// Maximum transmit unit for this port, in bytes.
    ///
    /// The reported MTU is the size of an entire frame, including any header and trailer bytes for
    /// whatever protocols this port supports.
    2: uint32 mtu;
};

/// Provides a way to receive updates on port status changes.
protocol StatusWatcher {
    /// `WatchStatus` blocks until the port's status has changed.
    ///
    /// The first call to `WatchStatus` returns immediately with the current port status, subsequent
    /// calls complete when the port status differs from the last one that was returned through this
    /// `StatusWatcher`.
    ///
    /// If `StatusWatcher` was created with a buffer value larger than 1, `WatchStatus` may return a
    /// queued status change, depending on how many status changed happened since the last call to
    /// `WatchStatus`.
    ///
    /// - response `device_status` the most recent port status.
    WatchStatus() -> (PortStatus port_status);
};

/// Logical port information.
table PortInfo {
    /// Port's identifier. Required.
    1: port_id id;
    /// Port's class. Required.
    2: PortClass class;
    /// Supported rx frame types on this port. Required.
    ///
    /// Clients may open sessions subscribing to a subset of `rx_types` frame types on this port.
    3: vector<FrameType>:MAX_FRAME_TYPES rx_types;
    /// Supported tx frame types on this port. Required.
    ///
    /// Frames destined to this port whose frame type is not in `tx_types` are returned with an
    /// error.
    ///
    /// Some network devices may need to perform partial frame parsing and serialization and, for
    /// that reason, `tx_types` is a vector of [`FrameTypeSupport`] which includes specific features
    /// per frame type. For example, a device that supports Ethernet frames but needs to convert the
    /// Ethernet header may only support standard Ethernet II frames, and not any "raw" Ethernet
    /// frame.
    4: vector<FrameTypeSupport>:MAX_FRAME_TYPES tx_types;
};

/// A logical port belonging to a [`Device`].
protocol Port {
    /// Obtain information about port.
    ///
    /// - response `info` port information.
    GetInfo() -> (PortInfo info);
    /// Obtain the operating port status.
    ///
    /// - response `status` snapshot of port's current status.
    GetStatus() -> (PortStatus status);
    /// Connects to a [`StatusWatcher`] to observe port status changes.
    ///
    /// + request `watcher` handle to the status watcher.
    /// + request `buffer` the number of status changes that the client requests to be stored by
    /// `StatusWatcher`. Values are capped at [`MAX_STATUS_BUFFER`]. A value of 0 or 1 causes the
    /// `StatusWatcher` to not keep any buffers on status changed. Clients that need to observe all
    /// changes to status (as opposed to only the current state) are encouraged to set a buffer
    /// value larger than 1, so that all edges can be observed. If `StatusWatcher`'s internal queue
    /// is filled and new status changes occur, the oldest samples will be dropped to make room for
    /// new ones.
    GetStatusWatcher(request<StatusWatcher> watcher, uint32 buffer);
    /// Connects to a [`MacAddressing`] associated with the port.
    ///
    /// + request `mac` mac handle. Closed with `ZX_ERR_NOT_SUPPORTED` if this port does not support
    /// mac addressing.
    GetMac(request<MacAddressing> mac);
};