Enum UsbFunctionRequest 

pub enum UsbFunctionRequest {
    ConnectToEndpoint {
        ep_addr: u8,
        ep: ServerEnd<EndpointMarker>,
        responder: UsbFunctionConnectToEndpointResponder,
    },
    Configure {
        configuration: Vec<u8>,
        iface: ClientEnd<UsbFunctionInterfaceMarker>,
        responder: UsbFunctionConfigureResponder,
    },
    Deconfigure {
        responder: UsbFunctionDeconfigureResponder,
    },
    AllocResources {
        interface_count: u8,
        endpoints: Vec<EndpointResource>,
        strings: Vec<String>,
        responder: UsbFunctionAllocResourcesResponder,
    },
    EndpointSetStall {
        endpoint_address: u8,
        responder: UsbFunctionEndpointSetStallResponder,
    },
    EndpointClearStall {
        endpoint_address: u8,
        responder: UsbFunctionEndpointClearStallResponder,
    },
    ConfigureEndpoint {
        endpoint_address: u8,
        endpoint_configuration: EndpointConfiguration,
        responder: UsbFunctionConfigureEndpointResponder,
    },
    DisableEndpoint {
        endpoint_address: u8,
        responder: UsbFunctionDisableEndpointResponder,
    },
}

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.

Variants

ConnectToEndpoint

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.

Fields

ep_addr: u8

ep: ServerEnd<EndpointMarker>

responder: UsbFunctionConnectToEndpointResponder

Configure

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.

Fields

configuration: Vec<u8>

iface: ClientEnd<UsbFunctionInterfaceMarker>

responder: UsbFunctionConfigureResponder

Deconfigure

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.

Fields

responder: UsbFunctionDeconfigureResponder

AllocResources

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.

Fields

interface_count: u8

endpoints: Vec<EndpointResource>

strings: Vec<String>

responder: UsbFunctionAllocResourcesResponder

EndpointSetStall

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).

Fields

endpoint_address: u8

responder: UsbFunctionEndpointSetStallResponder

EndpointClearStall

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).

Fields

endpoint_address: u8

responder: UsbFunctionEndpointClearStallResponder

ConfigureEndpoint

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.

Fields

endpoint_address: u8

endpoint_configuration: EndpointConfiguration

responder: UsbFunctionConfigureEndpointResponder

DisableEndpoint

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).

Fields

endpoint_address: u8

responder: UsbFunctionDisableEndpointResponder

Implementations

impl UsbFunctionRequest

pub fn into_connect_to_endpoint( self, ) -> Option<(u8, ServerEnd<EndpointMarker>, UsbFunctionConnectToEndpointResponder)>

pub fn into_configure( self, ) -> Option<(Vec<u8>, ClientEnd<UsbFunctionInterfaceMarker>, UsbFunctionConfigureResponder)>

pub fn into_deconfigure(self) -> Option<UsbFunctionDeconfigureResponder>

pub fn into_alloc_resources( self, ) -> Option<(u8, Vec<EndpointResource>, Vec<String>, UsbFunctionAllocResourcesResponder)>

pub fn into_endpoint_set_stall( self, ) -> Option<(u8, UsbFunctionEndpointSetStallResponder)>

pub fn into_endpoint_clear_stall( self, ) -> Option<(u8, UsbFunctionEndpointClearStallResponder)>

pub fn into_configure_endpoint( self, ) -> Option<(u8, EndpointConfiguration, UsbFunctionConfigureEndpointResponder)>

pub fn into_disable_endpoint( self, ) -> Option<(u8, UsbFunctionDisableEndpointResponder)>

pub fn method_name(&self) -> &'static str

Name of the method defined in FIDL

Trait Implementations

impl Debug for UsbFunctionRequest

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.