sdk/fidl/fuchsia.hardware.uwb/vendor.fidl

// Copyright 2025 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.uwb;

// FiRa UWB UCI Generic Specification Version 3.0.0 Section 4.4.2 and Section
// 4.5.2: The size of the command and data packet header (message type, packet
// boundary flag, gid, oid, payload length, etc).
//
// FiRa UWB UCI Generic Specification Version 3.0.0 Section 2.2: The maximum
// payload size of UCI control packet is 255 octets.
//
// FiRa UWB UCI Generic Specification Version 3.0.0 Section 8.6: The maximum
// payload size of UCI data packet is specified by the UWB Subsystem in the
// Device Capability Parameters as a two byte value (65536).
//
// The MAX_PACKET_SIZE chosen here represents the maximum packet size of
// a single UCI packet (control or data).
//
// HEADER_SIZE (4) + MAX_DATA_PAYLOAD_SIZE (65536)
const MAX_PACKET_SIZE uint32 = 65540;

type Packet = table {
    1: data vector<byte>:MAX_PACKET_SIZE;
};

/// The full packet sent between the controller and the host, including
/// packet headers.
///
/// Note: if the host or controller performed packet segmentation, the bytes
/// represented here won't be reassembled and will be in segmented form. See
/// FiRa UWB UCI Generic Specification Version 3.0.0 Section 4.4 for more
/// information on segmentation and reassembly.
type SnoopPacket = flexible union {
    1: to_controller_data Packet;
    2: from_controller_data Packet;
    3: command Packet;
    4: response Packet;
    5: notification Packet;
};

/// The Snoop protocol is an output-only channel for monitoring UCI traffic. The
/// snoop channel contains messages that are sent from the Host to the
/// Controller (e.g. control packets, data packets). The snoop channel also
/// contains responses sent from the Controller to the Host (e.g. response
/// packets, notification packets, data packets).
@discoverable
open protocol Snoop {
    /// A hanging-get method that returns when packets have been transmitted or
    /// received. The server is allowed to drop packets if the client takes too
    /// long to call WatchPacket().
    WatchPacket() -> (table {
        1: packets vector<SnoopPacket>:MAX;
        /// The number of outbound packets dropped since the last response to
        /// WatchPacket(). These packets are excluded from `packets`. This is
        /// only non-zero when WatchPacket() is slow to poll.
        2: dropped_sent uint32;
        /// The number of inbound packets dropped since the last response to
        /// WatchPacket(). These packets are excluded from `packets`. This is
        /// only non-zero when WatchPacket() is slow to poll.
        3: dropped_received uint32;
    });
};

/// The UCI protocol is the way the UWB HAL interfaces with the vendor chip via
/// the Driver.
@discoverable
open protocol Uci {
    /// Send serialized UCI packets to the UWB Controller via the Driver. The
    /// UWB HAL or driver aren't responsible for performing any packet
    /// segmentation or reassembly. Bytes will be sent to the UWB Controller as
    /// is.
    ///
    /// NOTE: The UWB spec requires the host to wait for a response to a sent
    /// command before sending another (FiRa UWB UCI Generic Specification
    /// Version 3.0.0 Section 4.3.1). This method can be called multiple times
    /// to queue up data to be sent to the UWB Controller (e.g. when sending a
    /// segmented packet). However, it's the Host's responsibility to ensure
    /// only a single command is sent.
    flexible Send(table {
        1: packets vector<Packet>:MAX;
    }) -> ();

    /// Perform vendor specific session initialization for a given session id.
    ///
    /// Session initialization is done via the Session Init UCI command
    /// (FiRa UWB UCI Generic Specification Version 3.0.0 Section 7.2.1). This
    /// command is normally sent by the upper layers of the stack via Send(...).
    /// However, some Controllers may require vendor specific configuration
    /// during session initialization. This command instructs the Driver to
    /// perform that vendor specific initialization, inserting the necessary
    /// bytes into the UCI data stream.
    flexible SessionInit(table {
        1: session_id uint32;
    }) -> ();

    /// Watch for UCI packets from the UWB Controller. The UWB HAL or driver
    /// isn't responsible for performing any packet segmentation or
    /// reassembly. Bytes will be sent to the UWB Host as is.
    flexible WatchReceive() -> (table {
        1: packets vector<Packet>:MAX;
    });
};

/// The Vendor service is served by the Driver of a particular vendor's
/// Controller.
service Vendor {
    uci client_end:Uci;
    snoop client_end:Snoop;
};