fuchsia.hardware.usb.dci

PROTOCOLS

UsbDci

Defined in fuchsia.hardware.usb.dci/usb-dci.fidl

Protocol implemented by the USB Device Controller Interface (DCI) hardware driver.

Used by the USB peripheral controller driver (usb-peripheral) to control the hardware controller's state and configure physical endpoints.

AllocEndpoint

Request the DCI driver to allocate a physical endpoint.

This is used by the peripheral manager to dynamically allocate a physical endpoint matching the requested direction, endpoint_type, and max_packet_size specified in EndpointAllocationRequest. This method must only be called if GetHardwareInfo reported supports_dynamic_ep_sizing as true.

The allocation is atomic. If the DCI driver cannot satisfy the request, it returns an error and no hardware state is modified.

Closing the UsbDci channel automatically frees all endpoints allocated through it.

• error:
  • ZX_ERR_IO_NOT_PRESENT if the DCI controller is not ready to take allocation requests (for example, in controller drivers that update hardware registers during allocation, if underlying hardware conditions such as power, clocks, reset, or MMIO accessibility prevent register access).
  • ZX_ERR_NO_RESOURCES if no physical endpoints matching the request are available.
  • ZX_ERR_NOT_SUPPORTED if the DCI driver does not support dynamic endpoint allocation.

Request

Name	Type
payload	EndpointAllocationRequest

Response

Name	Type
payload	UsbDci_AllocEndpoint_Result

CancelAll

Cancel all pending transactions for the given endpoint.

All cancelled transactions are completed with ZX_ERR_CANCELED.

Must only be called for active/configured endpoints. Calling this when there are no pending transfers is a no-op.

This method replies after hardware FIFOs are flushed and all requests are cancelled.

• error:
  • ZX_ERR_INVALID_ARGS if the endpoint address is invalid.

Request

Name	Type
ep_address	uint8

Response

Name	Type
payload	UsbDci_CancelAll_Result

ConfigureEndpoint

Configure an endpoint with the given configuration parameters.

See usb20 9.6.6 (Standard Endpoint Descriptor).

Typically called in response to host SET_CONFIGURATION or SET_INTERFACE control requests routed via Control.

Calling this for an already configured endpoint reconfigures it.

This method replies after hardware registers for the physical endpoint (direction, type, packet size) have been updated and the endpoint is enabled.

• error:
  • ZX_ERR_INVALID_ARGS if the endpoint address or type is invalid (e.g. EP0).
  • ZX_ERR_NOT_SUPPORTED if the endpoint type (e.g. Isochronous) is not supported.
  • ZX_ERR_NO_RESOURCES if there are insufficient hardware resources (e.g. TX FIFO space).
  • ZX_ERR_IO_NOT_PRESENT if the controller is powered off.
  • ZX_ERR_BAD_STATE if the controller is stopped or interface is not bound.

Request

Name	Type
ep_descriptor	fuchsia.hardware.usb.descriptor/UsbEndpointDescriptor
ss_comp_descriptor	fuchsia.hardware.usb.descriptor/UsbSsEpCompDescriptor

Response

Name	Type
payload	UsbDci_ConfigureEndpoint_Result

ConnectToEndpoint

Connect to an endpoint.

Must only be called after SetInterface has successfully bound a callback interface. Typically called before StartController to prepare endpoints for configuration, or during operation when new interfaces/endpoints are configured.

If the client closes its end of the ep channel, the DCI server must automatically release and unbind the physical endpoint, abort any pending transfers without sending completion events, and allow subsequent ConnectToEndpoint calls to succeed.

• error:
  • ZX_ERR_NOT_FOUND if endpoint address does not exist on the controller.
  • ZX_ERR_ALREADY_BOUND if the endpoint is already connected to another active channel.
  • ZX_ERR_BAD_STATE if called before SetInterface.

Request

Name	Type
ep_addr	uint8
ep	server_end:fuchsia.hardware.usb.endpoint/Endpoint

Response

Name	Type
payload	UsbDci_ConnectToEndpoint_Result

DisableEndpoint

Disable the given endpoint.

Must only be called for endpoints that have been previously configured. Calling this when the endpoint is already disabled is a no-op.

This method replies after hardware has disabled the endpoint and rejected any further host tokens on it. All pending transfers on the endpoint are cancelled, sending completion events with ZX_ERR_CANCELED.

• error:
  • ZX_ERR_INVALID_ARGS if the endpoint address is invalid.
  • ZX_ERR_BAD_STATE if the controller is stopped.

Request

Name	Type
ep_address	uint8

Response

Name	Type
payload	UsbDci_DisableEndpoint_Result

EndpointClearStall

Clear stall condition for the given endpoint.

See usb20 8.5.3.4 (Stall Handshakes) / 9.4.5 (Clear Feature).

Must only be called for endpoints that have been configured via ConfigureEndpoint and have not been disabled. Calling this on an endpoint that is not stalled is a no-op.

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.

This method replies after the hardware stall is cleared and the data toggle is reset.

• error:
  • ZX_ERR_INVALID_ARGS if the endpoint address is invalid or not active.
  • ZX_ERR_BAD_STATE if the controller is stopped.

Request

Name	Type
ep_address	uint8

Response

Name	Type
payload	UsbDci_EndpointClearStall_Result

EndpointSetStall

Set stall condition (HALT feature) for the given endpoint.

See usb20 8.5.3.4 (Stall Handshakes).

Must only be called for endpoints that have been configured via ConfigureEndpoint and have not been disabled. Calling this on an already stalled endpoint is a no-op.

This method replies after hardware has been configured to return STALL handshakes. All pending transfers on the endpoint are cancelled, sending completion events with ZX_ERR_CANCELED. Note that setting stall does not modify the endpoint's data toggle bit.

• error:
  • ZX_ERR_INVALID_ARGS if the endpoint address is invalid or not active.
  • ZX_ERR_NOT_SUPPORTED if stall is not supported for this endpoint.
  • ZX_ERR_BAD_STATE if the controller is stopped.

Request

Name	Type
ep_address	uint8

Response

Name	Type
payload	UsbDci_EndpointSetStall_Result

FreeEndpoint

Free a previously dynamically allocated endpoint.

Release the physical endpoint back to the DCI driver's pool. The endpoint must be disabled via DisableEndpoint before calling this method.

• error:
  • ZX_ERR_IO_NOT_PRESENT if the DCI controller is not ready or accessible to process deallocation requests.
  • ZX_ERR_NOT_FOUND if the endpoint was not dynamically allocated.
  • ZX_ERR_BAD_STATE if the endpoint is still active or enabled.

Request

Name	Type
ep_address	uint8

Response

Name	Type
payload	UsbDci_FreeEndpoint_Result

GetHardwareInfo

Query the DCI driver for hardware-specific endpoint limits.

This method retrieves the static endpoint configuration and capabilities of the DCI controller. It is typically called once by the peripheral manager during startup.

• error:
  • ZX_ERR_IO_NOT_PRESENT if the DCI controller is not ready or accessible to handle hardware queries (for example, if underlying hardware conditions such as power, clock or reset states prevent safe register access).
  • ZX_ERR_NOT_SUPPORTED if the DCI driver does not support hardware queries (legacy drivers).

Request

<EMPTY>

Response

Name	Type
payload	UsbDci_GetHardwareInfo_Result

SetInterface

Bind to the callback interface (UsbDciInterface) implemented by usb-peripheral.

The controller uses this channel to dispatch control transfers and connection events.

Must be called before StartController.

If the client closes its end of the interface channel, the DCI server must automatically stop the controller if it is running (performing soft disconnect from host if connected), disable all endpoints, and abort any pending requests, sending completion events with ZX_ERR_CANCELED.

The DCI driver may call methods on UsbDciInterface at any point after StartController is called, up until StopController completes. It does not call UsbDciInterface methods synchronously while handling a UsbDci request.

• error:
  • ZX_ERR_INVALID_ARGS if the interface handle is invalid.
  • ZX_ERR_ALREADY_BOUND if a callback interface is already bound.
  • ZX_ERR_BAD_STATE if called while the controller is already running.

Request

Name	Type
interface	client_end:UsbDciInterface

Response

Name	Type
payload	UsbDci_SetInterface_Result

StartController

Start running in peripheral mode.

Connect the device to the USB host. Called by usb-peripheral once all function drivers have bound to their interfaces and are ready to receive host traffic.

Must only be called after SetInterface has successfully bound a callback interface.

Calling this when the controller is already running is a no-op and returns ZX_OK.

This method replies after hardware registers are initialized and the physical D+ pull-up is asserted. It does not wait for bus enumeration or configuration from the host to complete.

After this replies successfully, the controller may begin calling SetConnected and SetSpeed on the bound UsbDciInterface as physical bus state changes.

• error:
  • ZX_ERR_BAD_STATE if called before SetInterface has bound a callback.
  • ZX_ERR_IO if hardware initialization fails due to a hardware error.
  • ZX_ERR_IO_NOT_PRESENT if the controller hardware is not present or powered off.

Request

<EMPTY>

Response

Name	Type
payload	UsbDci_StartController_Result

StopController

Stop running in peripheral mode.

Disconnect the device from the host (soft disconnect). Must only be called after SetInterface has successfully bound a callback interface.

Calling this when the controller is already stopped is a no-op and returns ZX_OK.

This method replies after physical disconnection has been completed (the pull-up is deasserted) and endpoints are disabled in hardware.

This triggers an asynchronous UsbDciInterface::SetConnected(false) event.

• error:
  • ZX_ERR_IO if the hardware fails to stop or reset.

Request

<EMPTY>

Response

Name	Type
payload	UsbDci_StopController_Result

UsbDciInterface

Defined in fuchsia.hardware.usb.dci/usb-dci.fidl

Interface for parent (typically DCI driver) to call into its child (currently usb-peripheral driver). Use UsbDci.SetInterface to bind the client end in the parent driver.

Control

Dispatch a control transaction (EP0 SETUP transfer).

See usb20 8.5.3 (Control Transfers) and 9.6 (Standard Device Requests).

Only called by DCI while the controller is running, after a SETUP packet is received on EP0.

This method replies after the peripheral controller or the target function driver has processed the request.

To comply with USB 2.0 Section 9.2.6 (Request Processing Timing), the peripheral driver must process and reply to requests without a data stage (and SET_ADDRESS) within 50 ms. For requests with a data stage, it must reply (beginning the data stage) within 500 ms. Both drivers must process these requests within these limits to prevent host-side timeouts and enumeration failures.

• error:
  • ZX_ERR_NOT_SUPPORTED if the request is not recognized.
  • ZX_ERR_BAD_STATE if called while the controller is stopped or interface is not bound. Note: For any error returned by this method, the DCI driver stalls EP0 with a STALL handshake to signal the failure to the USB host.

Request

Name	Type
setup	fuchsia.hardware.usb.descriptor/UsbSetup
write	vector<uint8>:65508

Response

Name	Type
payload	UsbDciInterface_Control_Result

SetConnected

Inform driver of current port connection state (physical cable plug in/out).

Called by DCI while the controller is running, when a physical connection change is detected.

If is_connected is false, it transitions usb-peripheral to an unconfigured state. This results in DisableEndpoint and CancelAll calls to UsbDci from the peripheral driver.

• error:
  • Any error status indicates the peripheral driver failed to process the event. The DCI driver typically logs these errors but takes no further action.

Request

Name	Type
is_connected	bool

Response

Name	Type
payload	UsbDciInterface_SetConnected_Result

SetSpeed

Inform driver of current bus speed negotiated with the host.

Called by DCI while the controller is running, after physical connection is established (SetConnected(true)), before routing control requests.

Record the speed to be used during subsequent descriptor validation and endpoint resource allocation.

• error:
  • Any error status indicates the peripheral driver failed to process the event. The DCI driver typically logs these errors but takes no further action.

Request

Name	Type
speed	fuchsia.hardware.usb.descriptor/UsbSpeed

Response

Name	Type
payload	UsbDciInterface_SetSpeed_Result

STRUCTS

UsbDciInterface_Control_Response

Defined in fuchsia.hardware.usb.dci/usb-dci.fidl

Field	Type	Description	Default
read	vector<uint8>:65508		No default

UsbDciInterface_SetConnected_Response

Defined in fuchsia.hardware.usb.dci/usb-dci.fidl

<EMPTY>

UsbDciInterface_SetSpeed_Response

Defined in fuchsia.hardware.usb.dci/usb-dci.fidl

<EMPTY>

UsbDci_AllocEndpoint_Response

Defined in fuchsia.hardware.usb.dci/usb-dci.fidl

Field	Type	Description	Default
ep_address	uint8		No default

UsbDci_CancelAll_Response

Defined in fuchsia.hardware.usb.dci/usb-dci.fidl

<EMPTY>

UsbDci_ConfigureEndpoint_Response

Defined in fuchsia.hardware.usb.dci/usb-dci.fidl

<EMPTY>

UsbDci_ConnectToEndpoint_Response

Defined in fuchsia.hardware.usb.dci/usb-dci.fidl

<EMPTY>

UsbDci_DisableEndpoint_Response

Defined in fuchsia.hardware.usb.dci/usb-dci.fidl

<EMPTY>

UsbDci_EndpointClearStall_Response

Defined in fuchsia.hardware.usb.dci/usb-dci.fidl

<EMPTY>

UsbDci_EndpointSetStall_Response

Defined in fuchsia.hardware.usb.dci/usb-dci.fidl

<EMPTY>

UsbDci_FreeEndpoint_Response

Defined in fuchsia.hardware.usb.dci/usb-dci.fidl

<EMPTY>

UsbDci_GetHardwareInfo_Response

Defined in fuchsia.hardware.usb.dci/usb-dci.fidl

Field	Type	Description	Default
info	DciHardwareInfo		No default

UsbDci_SetInterface_Response

Defined in fuchsia.hardware.usb.dci/usb-dci.fidl

<EMPTY>

UsbDci_StartController_Response

Defined in fuchsia.hardware.usb.dci/usb-dci.fidl

<EMPTY>

UsbDci_StopController_Response

Defined in fuchsia.hardware.usb.dci/usb-dci.fidl

<EMPTY>

TABLES

DciHardwareInfo

Defined in fuchsia.hardware.usb.dci/usb-dci.fidl

Overall hardware capability summary of the DCI controller.

Ordinal	Field	Type	Description
1	endpoints	vector<EndpointInfo>:32	List of physical endpoint capabilities supported by the controller. Required if supports_dynamic_ep_sizing is false.
2	supports_dynamic_ep_sizing	bool	If true, usb-peripheral must use UsbDci.AllocEndpoint. Optional. Interpreted as false if absent.

EndpointAllocationRequest

Defined in fuchsia.hardware.usb.dci/usb-dci.fidl

Request parameters when dynamically allocating a physical endpoint from the DCI driver.

Ordinal	Field	Type	Description
1	direction	fuchsia.hardware.usb.descriptor/EndpointDirection	The required direction of the endpoint (IN or OUT). Required.
2	endpoint_type	fuchsia.hardware.usb.descriptor/EndpointType	The transfer type required for this endpoint (BULK, CONTROL, ISOCHRONOUS, or INTERRUPT). Required.
3	max_packet_size	uint16	The maximum packet size required by this endpoint in bytes. Required.

EndpointInfo

Defined in fuchsia.hardware.usb.dci/usb-dci.fidl

Static configuration and supported types for a physical endpoint.

Ordinal	Field	Type	Description
1	ep_address	uint8	The endpoint address, as defined in USB 2.0 specification section 9.6.6. e.g., 0x81 (IN 1), 0x02 (OUT 2). Required.
2	supported_types	vector<SupportedEndpointInfo>:4	The transfer types supported by this physical endpoint, along with any type-specific hardware limits. Required.

SupportedEndpointInfo

Defined in fuchsia.hardware.usb.dci/usb-dci.fidl

Hardware capability and limit information for a specific endpoint transfer type.

Ordinal	Field	Type	Description
1	endpoint_type	fuchsia.hardware.usb.descriptor/EndpointType	The transfer type supported (BULK, CONTROL, ISOCHRONOUS, or INTERRUPT). Required.
2	max_packet_size_limit	uint16	The maximum packet size supported for this transfer type in bytes. Required.
3	min_lead_time	uint64	For isochronous endpoints: minimum lead time required in number of transfers. Optional even when endpoint_type is ISOCHRONOUS. Interpreted as 0 (no additional lead time required) if absent.

UNIONS

UsbDciInterface_Control_Result strict

Defined in fuchsia.hardware.usb.dci/usb-dci.fidl

Ordinal	Variant	Type	Description
1	response	UsbDciInterface_Control_Response
2	err	zx/Status
3	framework_err	internal

UsbDciInterface_SetConnected_Result strict

Defined in fuchsia.hardware.usb.dci/usb-dci.fidl

Ordinal	Variant	Type	Description
1	response	UsbDciInterface_SetConnected_Response
2	err	zx/Status
3	framework_err	internal

UsbDciInterface_SetSpeed_Result strict

Defined in fuchsia.hardware.usb.dci/usb-dci.fidl

Ordinal	Variant	Type	Description
1	response	UsbDciInterface_SetSpeed_Response
2	err	zx/Status
3	framework_err	internal

UsbDci_AllocEndpoint_Result strict

Defined in fuchsia.hardware.usb.dci/usb-dci.fidl

Ordinal	Variant	Type	Description
1	response	UsbDci_AllocEndpoint_Response
2	err	zx/Status
3	framework_err	internal

UsbDci_CancelAll_Result strict

Defined in fuchsia.hardware.usb.dci/usb-dci.fidl

Ordinal	Variant	Type	Description
1	response	UsbDci_CancelAll_Response
2	err	zx/Status
3	framework_err	internal

UsbDci_ConfigureEndpoint_Result strict

Defined in fuchsia.hardware.usb.dci/usb-dci.fidl

Ordinal	Variant	Type	Description
1	response	UsbDci_ConfigureEndpoint_Response
2	err	zx/Status
3	framework_err	internal

UsbDci_ConnectToEndpoint_Result strict

Defined in fuchsia.hardware.usb.dci/usb-dci.fidl

Ordinal	Variant	Type	Description
1	response	UsbDci_ConnectToEndpoint_Response
2	err	zx/Status
3	framework_err	internal

UsbDci_DisableEndpoint_Result strict

Defined in fuchsia.hardware.usb.dci/usb-dci.fidl

Ordinal	Variant	Type	Description
1	response	UsbDci_DisableEndpoint_Response
2	err	zx/Status
3	framework_err	internal

UsbDci_EndpointClearStall_Result strict

Defined in fuchsia.hardware.usb.dci/usb-dci.fidl

Ordinal	Variant	Type	Description
1	response	UsbDci_EndpointClearStall_Response
2	err	zx/Status
3	framework_err	internal

UsbDci_EndpointSetStall_Result strict

Defined in fuchsia.hardware.usb.dci/usb-dci.fidl

Ordinal	Variant	Type	Description
1	response	UsbDci_EndpointSetStall_Response
2	err	zx/Status
3	framework_err	internal

UsbDci_FreeEndpoint_Result strict

Defined in fuchsia.hardware.usb.dci/usb-dci.fidl

Ordinal	Variant	Type	Description
1	response	UsbDci_FreeEndpoint_Response
2	err	zx/Status
3	framework_err	internal

UsbDci_GetHardwareInfo_Result strict

Defined in fuchsia.hardware.usb.dci/usb-dci.fidl

Ordinal	Variant	Type	Description
1	response	UsbDci_GetHardwareInfo_Response
2	err	zx/Status
3	framework_err	internal

UsbDci_SetInterface_Result strict

Defined in fuchsia.hardware.usb.dci/usb-dci.fidl

Ordinal	Variant	Type	Description
1	response	UsbDci_SetInterface_Response
2	err	zx/Status
3	framework_err	internal

UsbDci_StartController_Result strict

Defined in fuchsia.hardware.usb.dci/usb-dci.fidl

Ordinal	Variant	Type	Description
1	response	UsbDci_StartController_Response
2	err	zx/Status
3	framework_err	internal

UsbDci_StopController_Result strict

Defined in fuchsia.hardware.usb.dci/usb-dci.fidl

Ordinal	Variant	Type	Description
1	response	UsbDci_StopController_Response
2	err	zx/Status
3	framework_err	internal

CONSTANTS

Name	Value	Type	Description
MAX_CONTROL_REQUEST_LEN	65508	uint64
MAX_ENDPOINTS	32	uint32
MAX_SUPPORTED_TYPES	4	uint32

SERVICES

UsbDciService

Defined in fuchsia.hardware.usb.dci/usb-dci.fidl

Name	Type	Transport
device	fuchsia.hardware.usb.dci/UsbDci	Channel