| // 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`]. |
| @available(added=HEAD) |
| const MAX_STATUS_BUFFER uint32 = 50; |
| |
| /// The maximum number of ports attached to a device at a given time. |
| @available(added=HEAD) |
| const MAX_PORTS uint8 = 32; |
| |
| /// The base identifier of a port within a device. Always less than |
| /// [`MAX_PORTS`]. |
| @available(added=HEAD) |
| alias BasePortId = uint8; |
| |
| /// A device port identifier. |
| @available(added=HEAD) |
| type PortId = struct { |
| /// The base identifier for the port. |
| /// |
| /// Generally identifies a port instance in hardware. |
| base BasePortId; |
| /// 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(https://fxbug.dev/42156114): Rename to PortClass once we can easily soft |
| // transition through aliasing to prevent source breakages. |
| // TODO(https://fxbug.dev/42157740): Make this a flexible enum once HLCPP flexible |
| // enums don't break chromium. |
| type DeviceClass = strict enum : uint16 { |
| // TODO(https://fxbug.dev/42157740): Transition this variant out of zero per |
| // recommendation in |
| // https://fuchsia.dev/fuchsia-src/concepts/api/fidl#enum once this is |
| // a flexible enum. |
| VIRTUAL = 0; |
| ETHERNET = 1; |
| WLAN = 2; |
| PPP = 3; |
| BRIDGE = 4; |
| WLAN_AP = 5; |
| }; |
| |
| /// Network port class. |
| @available(added=HEAD) |
| alias PortClass = DeviceClass; |
| |
| /// Port status bits, reported in [`PortStatus.flags`]. |
| @available(added=HEAD) |
| 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. |
| @available(added=HEAD) |
| 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. |
| @available(added=HEAD) |
| closed 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. |
| strict WatchStatus() -> (struct { |
| port_status PortStatus; |
| }); |
| }; |
| |
| /// Port base info. |
| @available(added=HEAD) |
| type PortBaseInfo = table { |
| /// Port's class. Required. |
| 1: port_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. |
| 2: 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. |
| 3: tx_types vector<FrameTypeSupport>:MAX_FRAME_TYPES; |
| }; |
| |
| /// Logical port information. |
| @available(added=HEAD) |
| type PortInfo = table { |
| /// Port's identifier. Required. |
| 1: id PortId; |
| // Port base info. Required. |
| 2: base_info PortBaseInfo; |
| }; |
| |
| /// A logical port belonging to a [`Device`]. |
| @available(added=HEAD) |
| closed protocol Port { |
| /// Obtain information about port. |
| /// |
| /// - response `info` port information. |
| strict GetInfo() -> (struct { |
| info PortInfo; |
| }); |
| /// Obtain the operating port status. |
| /// |
| /// - response `status` snapshot of port's current status. |
| strict 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. |
| strict 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. |
| strict GetMac(resource struct { |
| mac server_end:MacAddressing; |
| }); |
| /// Connects to the [`Device`] this port belongs to. |
| /// |
| /// + request `device` grants access to the parent device. |
| strict GetDevice(resource struct { |
| device server_end:Device; |
| }); |
| /// Establishes a new connection to this port. |
| /// |
| /// + request `port` the server end for the new connection. |
| strict Clone(resource struct { |
| port server_end:Port; |
| }); |
| /// Retrieves a snapshot of traffic counters on this port. |
| strict GetCounters() -> (table { |
| /// The total number of ingress frames on this port. |
| 1: rx_frames uint64; |
| /// The total number of ingress bytes on this port. |
| 2: rx_bytes uint64; |
| /// The total number of egress frames on this port. |
| 3: tx_frames uint64; |
| /// The total number of egress bytes on this port. |
| 4: tx_bytes uint64; |
| }); |
| /// Grants access to [`Diagnostics`] for this port. |
| /// |
| /// + request `diagnostics` grants access to diagnostics information. |
| strict GetDiagnostics(resource struct { |
| diagnostics server_end:Diagnostics; |
| }); |
| }; |