blob: 422cac1611f89e49c29db22e069c8dfab638bd2e [file] [log] [blame]
// 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.
/// The maximum number of status samples that can be buffered by a
/// [`StatusWatcher`].
const MAX_STATUS_BUFFER uint32 = 50;
/// The maximum number of ports attached to a device at a given time.
const MAX_PORTS uint8 = 32;
/// The base identifier of a port within a device. Always less than
/// [`MAX_PORTS`].
alias base_port_id = uint8;
/// A device port identifier.
type PortId = struct {
/// The base identifier for the port.
/// Generally identifies a port instance in hardware.
base base_port_id;
/// An implementation-defined identifier that is guaranteed to change on
/// every instantiation of the identified port.
salt uint8;
/// Network device class.
/// *Note*: Device implementers are encouraged to propose additions to this
/// enumeration to avoid using ill-fitting variants if there's not a good match
/// available.
// TODO( Rename to PortClass once we can easily soft
// transition through aliasing to prevent source breakages.
// TODO( Make this a flexible enum once HLCPP flexible
// enums don't break chromium.
type DeviceClass = strict enum : uint16 {
// TODO( Transition this variant out of zero per
// recommendation in
// once this is
// a flexible enum.
WLAN = 2;
PPP = 3;
WLAN_AP = 5;
/// Network port class.
alias PortClass = DeviceClass;
/// Port status bits, reported in [`PortStatus.flags`].
type StatusFlags = strict bits : uint32 {
/// Port is online, i.e., data path is open and any ongoing sessions may
/// send and receive frames.
ONLINE = 0x01;
/// Dynamic port information.
type PortStatus = table {
/// Port status flags.
1: flags StatusFlags;
/// 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: mtu uint32;
/// 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() -> (struct {
port_status PortStatus;
/// Logical port information.
type PortInfo = table {
/// Port's identifier. Required.
1: id PortId;
/// Port's class. Required.
2: class PortClass;
/// 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: rx_types vector<FrameType>:MAX_FRAME_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: tx_types vector<FrameTypeSupport>:MAX_FRAME_TYPES;
/// A logical port belonging to a [`Device`].
protocol Port {
/// Obtain information about port.
/// - response `info` port information.
GetInfo() -> (struct {
info PortInfo;
/// Obtain the operating port status.
/// - response `status` snapshot of port's current status.
GetStatus() -> (struct {
status PortStatus;
/// 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(resource struct {
watcher server_end:StatusWatcher;
buffer uint32;
/// 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(resource struct {
mac server_end:MacAddressing;
/// Connects to the [`Device`] this port belongs to.
/// + request `device` grants access to the parent device.
GetDevice(resource struct {
device server_end:Device;
/// Establishes a new connection to this port.
/// + request `port` the server end for the new connection.
Clone(resource struct {
port server_end:Port;