fuchsia.hardware.usb.endpoint

PROTOCOLS

Endpoint

Defined in fuchsia.hardware.usb.endpoint/endpoint.fidl

Endpoint Interface. Pre-registered VMOs associated with the Endpoint are tied to the lifetime of the Endpoint. When the Endpoint is closed, all outstanding registered VMOs are unregistered, references to their handles dropped and any necessary actions for DisableEndpoint will be called.

CancelAll

Cancels all requests. Returns

• ZX_ERR_IO_NOT_PRESENT: If device is not running, disconnected, or inactive.
• ZX_ERR_IO: If cancel failed due to an unsuccessful request.

Request

<EMPTY>

Response

Name	Type
payload	Endpoint_CancelAll_Result

GetInfo

Gets endpoint information

Request

<EMPTY>

Response

Name	Type
payload	Endpoint_GetInfo_Result

OnCompletion

Called on a completion to notify the device driver of an completion event. Note that if more than REQUEST_MAX successful requests with defer_completion == true have been seen, driver may call OnCompletion multiple times when defer_completion == false is seen (or failure happens) to return all seen requests to the client.

Response

Name	Type
completion	vector<Completion>:300

QueueRequests

Submit Requests to queue. Processed starting with the 0th Request. Submitting a vector of Requests allows for pre-buffering.

Clients are responsible for cache management and ensuring cache coherency. The explanation to follow concerns VMOs that have been previously registered via RegisterVmos. The following rules must be followed:

1. After writing to VMO-backed buffers, the caller must call zx_cache_flush with ZX_CACHE_FLUSH_DATA before invoking QueueRequests, causing the hardware to DMA-process the buffer. This avoids both stale buffer data being DMA-read, and a concurrent race between the hardware and CPU to update the same addresses.

2. Before reading from VMO-backed buffers, the caller must call zx_cache_flush with ZX_CACHE_FLUSH_DATA | ZX_CACHE_FLUSH_INVALIDATE after the buffer contents have been DMA-written by the hardware. This implies a non-dirty cache (see #1 above) and ensures any subsequent CPU-reads fetch the previously DMA-written data from RAM.

Failing to adhere to these rules will result in the exchange of corrupted and/or stale data. If the VMO is not virtually mapped (uncommon), zx_vmo_op_range should be used in lieu of zx_cache_flush. If the usb::FidlRequest types are in use, they contain helpers for these operations.

Requests may be pre-buffered. In other words, requests may be queued for data that is not present/ready in the buffer yet. The USB Endpoint Server consuming requests does not care if the data in the buffer is ready or not and will always process requests on schedule. It is the responsibility of the USB Endpoint Client that submits requests to ensure that data is ready on schedule (taking into consideration cache management above).

• Definition of "on schedule" varies for different endpoints and controllers. In general, this will be communicated by the lead_time parameter returned by GetInfo.

Request

Name	Type
req	vector<fuchsia.hardware.usb.request/Request>:300

RegisterVmos

Registers and pins VMOs to the vmo_ids. Returns

• vmo: Handles to successfully registered vmo_ids. VMO IDs that are already are registered to will fail.

Request

Name	Type
vmo_ids	vector<VmoInfo>:300

Response

Name	Type
vmos	vector<VmoHandle>:300

UnregisterVmos

Unregisters the VMOs corresponding to the vmo_ids. Returns

• failed_vmo_ids: vmo_ids that failed to unregister.
• errors: Error values that correspond 1:1 to failed_vmo_ids above.

Request

Name	Type
vmo_ids	vector<fuchsia.hardware.usb.request/VmoId>:300

Response

Name	Type
failed_vmo_ids	vector<fuchsia.hardware.usb.request/VmoId>:300
errors	vector<zx/Status>:300

STRUCTS

Endpoint_CancelAll_Response

Defined in fuchsia.hardware.usb.endpoint/endpoint.fidl

<EMPTY>

Endpoint_GetInfo_Response

Defined in fuchsia.hardware.usb.endpoint/endpoint.fidl

Field	Type	Description	Default
info	EndpointInfo		No default

TABLES

BulkEndpointInfo

Defined in fuchsia.hardware.usb.endpoint/endpoint.fidl

Bulk Endpoint Information

Ordinal	Field	Type	Description

Completion resource

Defined in fuchsia.hardware.usb.endpoint/endpoint.fidl

Completion

Ordinal	Field	Type	Description
1	request	fuchsia.hardware.usb.request/Request	Request completed.
2	status	zx/Status	Completion status.
3	transfer_size	uint64	Bytes successfully transferred.
4	wake_lease	handle<eventpair>	Wake lease if this completion took the system out of suspend.

ControlEndpointInfo

Defined in fuchsia.hardware.usb.endpoint/endpoint.fidl

Control Endpoint Information

Ordinal	Field	Type	Description

InterruptEndpointInfo

Defined in fuchsia.hardware.usb.endpoint/endpoint.fidl

Interrupt Endpoint Information

Ordinal	Field	Type	Description

IsochronousEndpointInfo

Defined in fuchsia.hardware.usb.endpoint/endpoint.fidl

Isochronous Endpoint Information

Ordinal	Field	Type	Description
1	lead_time	uint64	Lead time described in number of transfers.

VmoHandle resource

Defined in fuchsia.hardware.usb.endpoint/endpoint.fidl

VMO handle returned for registered VMOs. Only used as a return value for UnregisterVmos() to associate a VMO handle with the VmoId it was registered to.

Ordinal	Field	Type	Description
1	id	fuchsia.hardware.usb.request/VmoId	ID corresponding to the registered VMO as passed in by RegisterVmos() through VmoInfo.
2	vmo	handle<vmo>	Handle to VMO.

VmoInfo

Defined in fuchsia.hardware.usb.endpoint/endpoint.fidl

VMO information for registering VMOs. Only used for RegisterVmos() to convey the ID to register a VMO to and its size.

Ordinal	Field	Type	Description
1	id	fuchsia.hardware.usb.request/VmoId	ID corresponding to the VMO to be registered.
2	size	uint64	Size of VMO to register.

UNIONS

EndpointInfo flexible

Defined in fuchsia.hardware.usb.endpoint/endpoint.fidl

Endpoint Information

Ordinal	Variant	Type	Description
1	bulk	BulkEndpointInfo	Bulk endpoint information
2	control	ControlEndpointInfo	Control endpoint information
3	isochronous	IsochronousEndpointInfo	Isochronous endpoint information
4	interrupt	InterruptEndpointInfo	Interrupt endpoint information

Endpoint_CancelAll_Result strict

Defined in fuchsia.hardware.usb.endpoint/endpoint.fidl

Ordinal	Variant	Type	Description
1	response	Endpoint_CancelAll_Response
2	err	zx/Status

Endpoint_GetInfo_Result strict

Defined in fuchsia.hardware.usb.endpoint/endpoint.fidl

Ordinal	Variant	Type	Description
1	response	Endpoint_GetInfo_Response
2	err	zx/Status

CONSTANTS

Name	Value	Type	Description
REQUEST_MAX	300	uint32	Arbitrary limit on the number of Requests in one call to QueueRequest().
VMO_VECTOR_MAX	300	uint32	Arbitrary limit on the number of VMOs in one call to RegisterVmos() or UnregisterVmos().