Struct UsbFunctionProxy 

pub struct UsbFunctionProxy { /* private fields */ }

Implementations

impl UsbFunctionProxy

pub fn new(channel: AsyncChannel) -> Self

Create a new Proxy for fuchsia.hardware.usb.function/UsbFunction.

pub fn take_event_stream(&self) -> UsbFunctionEventStream

Get a Stream of events from the remote end of the protocol.

Panics

Panics if the event stream was already taken.

pub fn connect_to_endpoint( &self, ep_addr: u8, ep: ServerEnd<EndpointMarker>, ) -> QueryResponseFut<UsbFunctionConnectToEndpointResult, DefaultFuchsiaResourceDialect>

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.

pub fn configure( &self, configuration: &[u8], iface: ClientEnd<UsbFunctionInterfaceMarker>, ) -> QueryResponseFut<UsbFunctionConfigureResult, DefaultFuchsiaResourceDialect>

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.

pub fn deconfigure( &self, ) -> QueryResponseFut<UsbFunctionDeconfigureResult, DefaultFuchsiaResourceDialect>

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.

pub fn alloc_resources( &self, interface_count: u8, endpoints: Vec<EndpointResource>, strings: &[String], ) -> QueryResponseFut<UsbFunctionAllocResourcesResult, DefaultFuchsiaResourceDialect>

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.

pub fn endpoint_set_stall( &self, endpoint_address: u8, ) -> QueryResponseFut<UsbFunctionEndpointSetStallResult, DefaultFuchsiaResourceDialect>

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

pub fn endpoint_clear_stall( &self, endpoint_address: u8, ) -> QueryResponseFut<UsbFunctionEndpointClearStallResult, DefaultFuchsiaResourceDialect>

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

pub fn configure_endpoint( &self, endpoint_address: u8, endpoint_configuration: &EndpointConfiguration, ) -> QueryResponseFut<UsbFunctionConfigureEndpointResult, DefaultFuchsiaResourceDialect>

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.

pub fn disable_endpoint( &self, endpoint_address: u8, ) -> QueryResponseFut<UsbFunctionDisableEndpointResult, DefaultFuchsiaResourceDialect>

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

Trait Implementations

impl Clone for UsbFunctionProxy

fn clone(&self) -> UsbFunctionProxy

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for UsbFunctionProxy

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

Formats the value using the given formatter.

impl Proxy for UsbFunctionProxy

type Protocol = UsbFunctionMarker

The protocol which this Proxy controls.

fn from_channel(inner: AsyncChannel) -> Self

Create a proxy over the given channel.

fn into_channel(self) -> Result<AsyncChannel, Self>

Attempt to convert the proxy back into a channel.

fn as_channel(&self) -> &AsyncChannel

Get a reference to the proxy’s underlying channel.

fn into_client_end(self) -> Result<ClientEnd<Self::Protocol>, Self>

Attempt to convert the proxy back into a client end.

fn is_closed(&self) -> bool

Returns true if the proxy has received the PEER_CLOSED signal.

fn on_closed(&self) -> OnSignals<'_, Unowned<'_, NullableHandle>>

Returns a future that completes when the proxy receives the PEER_CLOSED signal.

impl UsbFunctionProxyInterface for UsbFunctionProxy

type ConnectToEndpointResponseFut = QueryResponseFut<Result<(), i32>>

type ConfigureResponseFut = QueryResponseFut<Result<(), i32>>

type DeconfigureResponseFut = QueryResponseFut<Result<(), i32>>

type AllocResourcesResponseFut = QueryResponseFut<Result<(Vec<u8>, Vec<u8>, Vec<u8>), i32>>

type EndpointSetStallResponseFut = QueryResponseFut<Result<(), i32>>

type EndpointClearStallResponseFut = QueryResponseFut<Result<(), i32>>

type ConfigureEndpointResponseFut = QueryResponseFut<Result<(), i32>>

type DisableEndpointResponseFut = QueryResponseFut<Result<(), i32>>

fn connect_to_endpoint( &self, ep_addr: u8, ep: ServerEnd<EndpointMarker>, ) -> Self::ConnectToEndpointResponseFut

fn configure( &self, configuration: &[u8], iface: ClientEnd<UsbFunctionInterfaceMarker>, ) -> Self::ConfigureResponseFut

fn deconfigure(&self) -> Self::DeconfigureResponseFut

fn alloc_resources( &self, interface_count: u8, endpoints: Vec<EndpointResource>, strings: &[String], ) -> Self::AllocResourcesResponseFut

fn endpoint_set_stall( &self, endpoint_address: u8, ) -> Self::EndpointSetStallResponseFut

fn endpoint_clear_stall( &self, endpoint_address: u8, ) -> Self::EndpointClearStallResponseFut

fn configure_endpoint( &self, endpoint_address: u8, endpoint_configuration: &EndpointConfiguration, ) -> Self::ConfigureEndpointResponseFut

fn disable_endpoint( &self, endpoint_address: u8, ) -> Self::DisableEndpointResponseFut