blob: 930bdbdd6a29b078895270534ad736d5da26c176 [file]
// Copyright 2023 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.
@available(added=HEAD)
library fuchsia.hardware.usb.function;
using zx;
using fuchsia.hardware.usb.endpoint;
using fuchsia.hardware.usb.descriptor;
const MAX_STRING_LEN uint32 = 126;
const MAX_STRINGS uint32 = 255;
const MAX_ENDPOINTS uint32 = 255;
const MAX_INTERFACES uint32 = 32;
/// Maximum length of a configuration descriptor block (32 KiB).
///
/// Note: While the USB specification allows configuration descriptors up to 65,535 bytes (64 KiB),
/// this limit is set to 32,768 bytes (32 KiB) to leave ample headroom (32 KiB) for future FIDL
/// protocol evolution (new struct fields, handles, or message headers) within Zircon's 64 KiB
/// channel message limit (`ZX_CHANNEL_MAX_MSG_BYTES`, 65,536 bytes).
const MAX_DESCRIPTOR_LEN uint32 = 32768;
/// Protocol for configuring a USB function.
///
/// This protocol is implemented by the USB peripheral controller (protocol server) and called by
/// the USB function driver (protocol client).
///
/// Closing the `UsbFunction` channel automatically deconfigures the function and closes the `iface`
/// ([`UsbFunctionInterface`]) channel.
@discoverable
closed protocol UsbFunction {
/// Connect to an allocated endpoint.
///
/// This must be called after the endpoint has been allocated via [`AllocResources`]. If the
/// endpoint channel was not provided during `AllocResources`, this method must be called to
/// establish the endpoint channel before any data transfers can occur on the endpoint.
///
/// If the endpoint channels were not provided in `AllocResources` and this is never called, the
/// protocol client cannot communicate with the endpoint (no channel is established). This does
/// not prevent control-plane callbacks (like `SetConfigured`) from being made.
///
/// The endpoint connection persists across `Configure` and `Deconfigure` calls. If the protocol
/// server closes the connection (server end closes), it indicates that the endpoint is no
/// longer available (e.g. device disconnected or function removed). The protocol client should
/// clean up by closing its client end of the channel, cancelling any pending I/O operations,
/// and stopping any tasks using the endpoint. The protocol client is not required to call
/// `DisableEndpoint` or `Deconfigure` in this case (and such calls may fail if the interface is
/// being torn down).
///
/// * error:
/// * `ZX_ERR_NOT_FOUND` if endpoint address does not exist (e.g. not allocated).
/// * `ZX_ERR_ALREADY_BOUND` if the endpoint is already bound to an active channel. To
/// connect a new channel, the existing channel must be closed first. Note that channel
/// closure detection is asynchronous; if the protocol client closes the existing channel
/// and immediately calls `ConnectToEndpoint`, it may still fail with
/// `ZX_ERR_ALREADY_BOUND` if the protocol server has not yet processed the closure.
strict ConnectToEndpoint(resource struct {
ep_addr uint8;
ep server_end:fuchsia.hardware.usb.endpoint.Endpoint;
}) -> () error zx.Status;
/// Configure the function with the given descriptors.
///
/// **Ordering**: This must be called after `AllocResources` has been called to allocate all
/// interfaces, endpoints, and strings referenced in the descriptors. Calling this when already
/// configured returns `ZX_ERR_ALREADY_BOUND`.
///
/// This binds the [`UsbFunctionInterface`] callback channel (where the protocol client acts as
/// the server).
///
/// `configuration` is a vector of concatenated USB descriptors in standard USB wire format
/// (Interface -> Endpoint -> Class/Vendor descriptors). A raw byte vector is used to allow
/// arbitrary class-specific and vendor-specific descriptors that cannot be statically defined
/// in FIDL.
///
/// This byte vector is expected to contain one or more interface descriptors following the
/// USB specification.
///
/// This descriptor block is cached by the peripheral controller and sent *as-is* to the host in
/// response to standard host `GET_DESCRIPTOR` (Configuration) requests.
///
/// **Structure and Validation**:
/// - Must begin with an Interface or Interface Association descriptor.
/// - Standard descriptors (Interface, Endpoint) embedded in the vector must follow the standard
/// USB specification descriptor layouts.
/// - All interface numbers and endpoint addresses must match the resources allocated in
/// [`AllocResources`].
/// - The peripheral controller parses this vector linearly using descriptor length fields.
/// Mismatched resource IDs or malformed layouts return `ZX_ERR_INVALID_ARGS`.
///
/// `iface` is the client end of [`UsbFunctionInterface`] which the protocol server uses to send
/// events to the protocol client.
///
/// The function remains configured until `Deconfigure` is called or the `iface` channel is
/// closed. If `iface` is closed, the function is automatically deconfigured, which stops the
/// peripheral controller and disconnects the device from the host.
///
/// * error:
/// * `ZX_ERR_INVALID_ARGS` if the configuration is invalid or references unallocated
/// resources.
/// * `ZX_ERR_ALREADY_BOUND` if the function interface is already bound.
/// * `ZX_ERR_NO_MEMORY` if the protocol server fails to allocate memory to store the
/// descriptors.
/// * `ZX_ERR_BAD_STATE` if the peripheral device is stopping or tearing down.
strict Configure(resource struct {
configuration vector<uint8>:MAX_DESCRIPTOR_LEN;
iface client_end:UsbFunctionInterface;
}) -> () error zx.Status;
/// Deconfigure the function.
///
/// **Ordering**: Can be called at any time. If the function is not configured, it trivially
/// succeeds.
///
/// This is the opposite of `Configure`. The protocol server disables all physical endpoints
/// for this function, clears its stored descriptors, and unbinds the `iface` channel. If the
/// function was active, the peripheral controller may trigger a USB re-enumeration to reflect
/// the updated function configuration.
///
/// This does *not* close the endpoint channels (they remain connected and can be reused if the
/// function is re-configured).
///
/// * error:
/// * `ZX_ERR_UNAVAILABLE` if a deconfiguration is already in progress.
strict Deconfigure() -> () error zx.Status;
/// Allocate resources for the function.
///
/// This method is atomic. If any resource allocation fails, all allocations made during this
/// call are rolled back.
///
/// This must be called during driver initialization before `Configure`. Calling this after the
/// function has been configured returns `ZX_ERR_BAD_STATE`.
///
/// `interface_count` informs how many interfaces to create. `interface_nums` returns a vector
/// of length `interface_count` containing the allocated interface numbers.
///
/// `endpoints` is a vector of endpoints to allocate. The direction and endpoint server end are
/// provided. The protocol client can optionally provide endpoint channels in `endpoints`
/// to connect them immediately. If an endpoint channel is not provided, the protocol client
/// must call [`ConnectToEndpoint`] later to use it. `endpoint_addrs` returns a vector of the
/// same size containing the allocated endpoint addresses, where element `i` corresponds 1:1
/// to element `i` of `endpoints`. All endpoint channels provided here or connected later via
/// [`ConnectToEndpoint`] persist across [`Configure`] and [`Deconfigure`] calls.
///
/// `strings` is a vector of strings to allocate. `string_indices` returns a vector of the
/// same size containing the allocated string indices, where element `i` corresponds 1:1 to
/// element `i` of `strings`.
///
/// Returns the interface ids, endpoint ids, and string ids that were allocated. On error, no
/// resources are allocated.
///
/// The allocated resource numbers and addresses remain allocated for the lifetime of the
/// connection to `UsbFunction`. They are *not* freed on `Deconfigure`.
///
/// * error:
/// * `ZX_ERR_BAD_STATE` if the function has already been configured.
/// * `ZX_ERR_NO_RESOURCES` if any resource namespace numbers are exhausted.
/// * `ZX_ERR_INVALID_ARGS` if the endpoint configuration contains invalid arguments.
strict AllocResources(resource struct {
interface_count uint8;
endpoints vector<@generated_name("EndpointResource") resource struct {
direction fuchsia.hardware.usb.descriptor.EndpointDirection;
endpoint server_end:fuchsia.hardware.usb.endpoint.Endpoint;
/// Information about the endpoint (e.g. Bulk, Interrupt).
ep_info fuchsia.hardware.usb.endpoint.EndpointInfo;
/// The maximum packet size the endpoint supports.
max_packet_size uint32;
}>:MAX_ENDPOINTS;
strings vector<string:MAX_STRING_LEN>:MAX_STRINGS;
}) -> (struct {
interface_nums vector<uint8>:MAX_INTERFACES;
endpoint_addrs vector<uint8>:MAX_ENDPOINTS;
string_indices vector<uint8>:MAX_STRINGS;
}) error zx.Status;
/// Stall the endpoint.
///
/// The endpoint must have been allocated and configured.
///
/// This method returns after the hardware confirms the stall condition is active. All pending
/// transfers queued on the endpoint are cancelled and completed with `ZX_ERR_IO_REFUSED` via
/// `OnCompletion`. While the endpoint is stalled, any new requests submitted via
/// `QueueRequests` must immediately fail and complete with `ZX_ERR_IO_REFUSED`.
///
/// * error:
/// * `ZX_ERR_BAD_STATE` if the function is not configured.
/// * `ZX_ERR_IO_NOT_PRESENT` if the device is not running, disconnected, or inactive.
/// * `ZX_ERR_NOT_FOUND` if the endpoint address does not exist (not allocated).
strict EndpointSetStall(struct {
endpoint_address uint8;
}) -> () error zx.Status;
/// Clear the endpoint's stalled state.
///
/// The endpoint must have been allocated and configured.
///
/// This method returns after the hardware confirms the stall has been cleared. As required by
/// USB 2.0 Section 9.4.5, clearing the halt feature also resets the endpoint's data toggle bit
/// to `DATA0` in hardware. The client must resubmit any cancelled transfers once the endpoint
/// is cleared. Any requests queued *after* this method returns are processed normally.
///
/// * error:
/// * `ZX_ERR_BAD_STATE` if the function is not configured.
/// * `ZX_ERR_IO_NOT_PRESENT` if the device is not running, disconnected, or inactive.
/// * `ZX_ERR_NOT_FOUND` if the endpoint address does not exist (not allocated).
strict EndpointClearStall(struct {
endpoint_address uint8;
}) -> () error zx.Status;
/// Configure and enable an endpoint with the given configuration.
///
/// Called by the function driver in response to `SetConfigured` (when `configured == true`) or
/// `SetInterface` requests to enable physical transfers on the endpoint. Calling this before
/// the function has been configured via `Configure` returns `ZX_ERR_BAD_STATE`. Clients should
/// wait for the `SetConfigured` or `SetInterface` request before configuring endpoints to
/// ensure the host is ready.
///
/// The endpoint must have been allocated via `AllocResources`.
///
/// Returns only after the physical endpoint has been configured by the DCI driver.
///
/// See USB 2.0 Specification Section 9.6.6 (Endpoint Descriptor) for details on the standard
/// endpoint configuration fields mapped in `EndpointConfiguration`.
///
/// * error:
/// * `ZX_ERR_BAD_STATE` if the function is not configured.
/// * `ZX_ERR_IO_NOT_PRESENT` if the device is not running, disconnected, or inactive.
/// * `ZX_ERR_NOT_FOUND` if the endpoint address does not exist (not allocated).
/// * `ZX_ERR_INVALID_ARGS` if the configuration is invalid.
strict ConfigureEndpoint(struct {
endpoint_address uint8;
endpoint_configuration EndpointConfiguration;
}) -> () error zx.Status;
/// Disable an endpoint.
///
/// Called by the function driver in response to `SetConfigured` (when `configured == false`)
/// or `SetInterface` requests to disable physical transfers on the endpoint. Calling this when
/// the endpoint is already disabled is a no-op and returns `ZX_OK`. If called before the
/// function has been configured via `Configure`, it also trivially succeeds (`ZX_OK`), as the
/// endpoint is already unconfigured and disabled.
///
/// The endpoint must have been allocated via `AllocResources`.
///
/// Returns only after the physical endpoint has been disabled by the DCI driver.
///
/// * error:
/// * `ZX_ERR_IO_NOT_PRESENT` if the device is not running, disconnected, or inactive.
/// * `ZX_ERR_NOT_FOUND` if the endpoint address does not exist (not allocated).
strict DisableEndpoint(struct {
endpoint_address uint8;
}) -> () error zx.Status;
};
/// Protocol offered to [`UsbFunction`] instances to handle host-initiated
/// requests.
///
/// This protocol is implemented by the USB function driver (protocol server)
/// and called by the USB peripheral controller (protocol client).
open protocol UsbFunctionInterface {
/// Callback for handling EP0 class/vendor-specific control requests targeting the interface(s)
/// owned by this function.
///
/// This is called when the host sends a control request to the device. The protocol server (of
/// [`UsbFunctionInterface`]) should process the request and return the result.
///
/// The host expects a response within a strict timeout period defined by the USB specification
/// Section 9.2.6 (50ms for requests without data, and 500ms for read data stages). Because of
/// these hardware-enforced limits, the implementation must reply as quickly as possible and
/// avoid blocking the dispatcher.
///
/// `setup` is the control request metadata (setup packet). `write` contains the raw bytes sent
/// by the host in the Data Stage of a host-to-device (OUT) control transfer. It is empty for
/// device-to-host (IN) transfers. `read` in the response payload contains the raw bytes
/// returned to the host in the Data Stage of a device-to-host (IN) control transfer. It must
/// be empty for host-to-device (OUT) transfers.
///
/// Any error returned by this method (including `ZX_ERR_NOT_SUPPORTED`) causes the
/// peripheral controller to stall Endpoint 0, signaling a "Request Error" to the host.
///
/// * error:
/// * `ZX_ERR_NOT_SUPPORTED` if the request is not supported by the protocol server.
/// * `ZX_ERR_INVALID_ARGS` if the setup packet or data is invalid.
/// * `ZX_ERR_IO_NOT_PRESENT` if the device was disconnected while processing the request.
flexible Control(struct {
setup fuchsia.hardware.usb.descriptor.UsbSetup;
write vector<uint8>:MAX;
}) -> (struct {
read vector<uint8>:MAX;
}) error zx.Status;
/// Inform the protocol server (of [`UsbFunctionInterface`]) when the USB device configured
/// state changes.
///
/// Called with `configured == true` in response to a `SET_CONFIGURATION` control request that
/// selects a configuration that contains this function. In this case, the protocol server
/// should use [`UsbFunction.ConfigureEndpoint`] to configure its endpoints.
///
/// Per USB 2.0 Specification Section 9.4.7, receiving a `SET_CONFIGURATION` request when the
/// function is already configured is valid and should reset/re-initialize the function state
/// rather than returning an error.
///
/// Called with `configured == false` when configuration is disabled or USB is disconnected.
/// The protocol server should then use [`UsbFunction.DisableEndpoint`] to disable its
/// endpoints.
///
/// The protocol server must perform all endpoint configuration/disabling and wait for those
/// calls to complete before replying to this method. This ensures that the protocol client can
/// report success/failure back to the host (by ACK'ing or STALL'ing the `SET_CONFIGURATION`
/// request).
///
/// Any error returned by this method causes the peripheral controller to stall Control
/// Endpoint 0, signaling a failure to the host (rejecting the `SET_CONFIGURATION` request).
///
/// * error:
/// * `ZX_ERR_BAD_STATE` if the device or function is in an uninitialized state where
/// configuration transitions are invalid (excluding re-configuring an active state).
/// * `ZX_ERR_INVALID_ARGS` if the speed or configuration parameters are invalid.
/// * `ZX_ERR_NOT_SUPPORTED` if the requested speed or configuration is unsupported.
/// * `ZX_ERR_NO_RESOURCES` if endpoint allocation or hardware configuration fails.
flexible SetConfigured(struct {
configured bool;
speed fuchsia.hardware.usb.descriptor.UsbSpeed;
}) -> () error zx.Status;
/// Called to set an alternate setting for an interface due to a `SET_INTERFACE` control
/// request.
///
/// The protocol server (of [`UsbFunctionInterface`]) must use [`UsbFunction.ConfigureEndpoint`]
/// and [`UsbFunction.DisableEndpoint`] to configure or disable the interface's endpoints as
/// appropriate for the new alternate setting.
///
/// Depending on the alternate setting definition, this transition may require configuring new
/// endpoints (via `ConfigureEndpoint`), disabling existing endpoints (via `DisableEndpoint`),
/// or doing both. If an alternate setting does not use any endpoints, no endpoint
/// configuration calls are required.
///
/// The protocol server must perform all endpoint configuration/disabling and wait for those
/// calls to complete before replying to this method. This ensures that the protocol client can
/// report success/failure back to the host (by ACK'ing or STALL'ing the `SET_INTERFACE`
/// request).
///
/// Any error returned by this method causes the peripheral controller to stall Control
/// Endpoint 0, signaling a failure to the host (rejecting the `SET_INTERFACE` request).
///
/// * error:
/// * `ZX_ERR_NOT_SUPPORTED` if the alternate setting is not supported.
/// * `ZX_ERR_INVALID_ARGS` if the interface or alt_setting is invalid.
/// * Other errors if the function driver fails to configure or disable endpoints for the
/// new setting.
flexible SetInterface(struct {
interface uint8;
alt_setting uint8;
}) -> () error zx.Status;
};
/// Endpoint configuration given to [`UsbFunction.ConfigureEndpoint`].
type EndpointConfiguration = table {
1: descriptor @generated_name("EndpointDescriptor") struct {
bm_attributes uint8;
/// The endpoint's max packet size.
///
/// Note: This is expressed in host-endianness, as opposed to the wire descriptors that are
/// always little-endian.
w_max_packet_size uint16;
b_interval uint8;
};
2: super_speed_companion @generated_name("SuperSpeedEndpointCompanionDescriptor") struct {
b_max_burst uint8;
bm_attributes uint8;
/// The endpoint's max super-speed maximum bytes per interval.
///
/// Note: This is expressed in host-endianness, as opposed to the wire descriptors that are
/// always little-endian.
w_bytes_per_interval uint16;
};
};
service UsbFunctionService {
device client_end:UsbFunction;
};