fuchsia.hardware.usb.endpoint

Added: HEAD

协议

端点

在 fuchsia.hardware.usb.endpoint/endpoint.fidl 中定义

端点接口。 与端点关联的预注册 VMO 与端点的生命周期相关联。当端点关闭时，所有未完成的已注册 VMO 都会取消注册，对这些 VMO 句柄的引用会被丢弃，并且系统会调用 DisableEndpoint 的所有必要操作。

CancelAll

取消所有请求。返回

  • ZX_ERR_IO_NOT_PRESENT：如果设备未运行、已断开连接或处于非活动状态。
  • ZX_ERR_IO：如果因请求失败而导致取消失败。

请求

<EMPTY>

响应

名称类型
payload Endpoint_CancelAll_Result

GetInfo

获取端点信息

请求

<EMPTY>

响应

名称类型
payload Endpoint_GetInfo_Result

OnCompletion

在完成时调用，以向设备驱动程序通知完成事件。 请注意，如果已看到超过 MAX_COMPLETIONS_PER_EVENT 个 defer_completion == true 的成功请求，则当看到 defer_completion == false（或发生故障）时，驱动程序可能会多次调用 OnCompletion，以将所有看到的请求返回给客户端。

响应

名称类型
completion vector<Completion>:64

QueueRequests

将请求提交到队列。从第 0 个请求开始处理。提交请求向量可实现预缓冲。在 supports_scatter_gather 为 false 的端点上，每个请求都必须由单个 VMO 组成，该 VMO 完全位于单个物理连续内存范围内（即不能跨非连续物理页面或多个缓冲区区域）。

客户端负责缓存管理并确保缓存一致性。以下说明涉及之前通过 RegisterVmos 注册的 VMO。必须遵循以下规则：

  1. 写入 VMO 支持的缓冲区后，调用方必须先使用 ZX_CACHE_FLUSH_DATA 调用 zx_cache_flush，然后才能调用 QueueRequests，从而使硬件对缓冲区进行 DMA 处理。这样可以避免 DMA 读取过时的缓冲区数据，并避免硬件和 CPU 之间发生并发争用以更新相同的地址。

  2. 在从 VMO 支持的缓冲区读取数据之前，调用方必须在硬件通过 DMA 写入缓冲区内容后，使用 ZX_CACHE_FLUSH_DATA | ZX_CACHE_FLUSH_INVALIDATE 调用 zx_cache_flush。这意味着缓存不脏（请参阅上文中的第 1 点），并确保任何后续 CPU 读取操作都会从 RAM 中提取之前由 DMA 写入的数据。

不遵守这些规则会导致交换损坏和/或过时的数据。 如果 VMO 未进行虚拟映射（不常见），则应使用 zx_vmo_op_range 代替 zx_cache_flush。如果使用的是 usb::FidlRequest 类型，则其中包含这些操作的辅助函数。

请求可能会被预先缓冲。换句话说，对于缓冲区中尚不存在/尚未准备好的数据，请求可能会排队。使用请求的 USB 端点服务器不关心缓冲区中的数据是否准备就绪，并且始终会按计划处理请求。提交请求的 USB 端点客户端负责确保数据按计划准备就绪（同时考虑上述缓存管理）。

  • “按计划”的定义因端点和控制器而异。通常，这将通过 GetInfo 返回的 lead_time 参数进行传达。

请求

名称类型
req vector<fuchsia.hardware.usb.request/Request>:64

RegisterVmos

注册 VMO 并将其固定到 vmo_id。返回

  • vmo：已成功注册的 vmo_id 的句柄。 已注册的 VMO ID 将无法注册。

请求

名称类型
vmo_ids vector<VmoInfo>:64

响应

名称类型
vmos vector<VmoHandle>:64

UnregisterVmos

取消注册与 vmo_id 对应的 VMO。返回

  • failed_vmo_ids：未能取消注册的 vmo_id。
  • errors：与上述 failed_vmo_ids 一一对应的错误值。

请求

名称类型
vmo_ids vector<fuchsia.hardware.usb.request/VmoId>:64

响应

名称类型
failed_vmo_ids vector<fuchsia.hardware.usb.request/VmoId>:64
errors vector<zx/Result>:64

STRUCTS

Endpoint_CancelAll_Response

在 fuchsia.hardware.usb.endpoint/endpoint.fidl 中定义

<EMPTY>

Endpoint_GetInfo_Response

在 fuchsia.hardware.usb.endpoint/endpoint.fidl 中定义

字段类型说明默认
info EndpointInfo 无默认应用

TABLES

BulkEndpointInfo

在 fuchsia.hardware.usb.endpoint/endpoint.fidl 中定义

批量端点信息

序数字段类型说明
supports_scatter_gather bool

如果端点控制器支持多页 / 多 TRB 分散-收集链，则为 true。 如果为 false，则每个请求必须由单个 VMO 组成，该 VMO 完全位于单个物理连续内存范围内（即不能跨越非连续物理页面或多个缓冲区区域）。

补全资源

在 fuchsia.hardware.usb.endpoint/endpoint.fidl 中定义

完成

序数字段类型说明
request fuchsia.hardware.usb.request/Request

请求已完成。
status zx/Result

完成状态。常见的返回状态代码包括：

  • ZX_OK：成功。
  • ZX_ERR_NOT_SUPPORTED：请求的操作或功能不受支持（例如，请求要求在 supports_scatter_gather 为 false 的端点上进行分散-收集，例如跨越不连续的物理页面或多个缓冲区区域）。
  • ZX_ERR_IO_NOT_PRESENT：设备不再存在（例如，物理断开连接或关机）。收到此消息后，调用方应终止传输循环，而无需重新排队。
  • ZX_ERR_INVALID_ARGS：请求参数无效。
  • ZX_ERR_BAD_STATE：驱动程序处于无效状态。
  • ZX_ERR_IO_REFUSED：设备或控制器拒绝或停止了传输（例如，端点被主机 SET_FEATURE(ENDPOINT_HALT) 停止/暂停，或硬件传输中止）。一旦停止条件清除，缓冲区可能会重新排队/回收。
  • ZX_ERR_CANCELED：传输已被客户端软件明确取消（例如通过 CancelAll）。
  • ZX_ERR_NO_MEMORY：内存分配失败。
  • ZX_ERR_INTERNAL：内部驱动程序错误。
  • ZX_ERR_IO_MISSED_DEADLINE：传输未在截止时间前完成。
  • ZX_ERR_IO：一般 I/O 错误。
  • ZX_ERR_IO_INVALID：I/O 操作无效。
transfer_size uint64

已成功转移的字节数。
wake_lease handle<eventpair>

如果此完成操作使系统退出挂起状态，则唤醒租约。

ControlEndpointInfo

在 fuchsia.hardware.usb.endpoint/endpoint.fidl 中定义

控制端点信息

序数字段类型说明

InterruptEndpointInfo

在 fuchsia.hardware.usb.endpoint/endpoint.fidl 中定义

中断端点信息

序数字段类型说明
supports_scatter_gather bool

如果端点控制器支持多页 / 多 TRB 分散-收集链，则为 true。 如果为 false，则每个请求必须由单个 VMO 组成，该 VMO 完全位于单个物理连续内存范围内（即不能跨越非连续物理页面或多个缓冲区区域）。

IsochronousEndpointInfo

在 fuchsia.hardware.usb.endpoint/endpoint.fidl 中定义

等时端点信息

序数字段类型说明
lead_time uint64

以换乘次数表示的提前时间。
supports_scatter_gather bool

如果端点控制器支持多页 / 多 TRB 分散-收集链，则为 true。 如果为 false，则每个请求必须由单个 VMO 组成，该 VMO 完全位于单个物理连续内存范围内（即不能跨越非连续物理页面或多个缓冲区区域）。

VmoHandle 资源

在 fuchsia.hardware.usb.endpoint/endpoint.fidl 中定义

为已注册的 VMO 返回的 VMO 句柄。仅用作 UnregisterVmos() 的返回值，用于将 VMO 句柄与其注册到的 VmoId 相关联。

序数字段类型说明
id fuchsia.hardware.usb.request/VmoId

与已注册 VMO 对应的 ID，由 RegisterVmos() 通过 VmoInfo 传入。
vmo handle<vmo>

VMO 的句柄。

VmoInfo

在 fuchsia.hardware.usb.endpoint/endpoint.fidl 中定义

用于注册 VMO 的 VMO 信息。仅用于 RegisterVmos()，以传达要注册 VMO 的 ID 及其大小。

序数字段类型说明
id fuchsia.hardware.usb.request/VmoId

与要注册的 VMO 对应的 ID。
size uint64

要注册的 VMO 的大小。

UNIONS

EndpointInfo 灵活

在 fuchsia.hardware.usb.endpoint/endpoint.fidl 中定义

端点信息

序数变体类型说明
bulk BulkEndpointInfo

批量端点信息
control ControlEndpointInfo

控制端点信息
isochronous IsochronousEndpointInfo

等时端点信息
interrupt InterruptEndpointInfo

中断端点信息

Endpoint_CancelAll_Result strict

在 fuchsia.hardware.usb.endpoint/endpoint.fidl 中定义

序数变体类型说明
response Endpoint_CancelAll_Response
err zx/Status

Endpoint_GetInfo_Result strict

在 fuchsia.hardware.usb.endpoint/endpoint.fidl 中定义

序数变体类型说明
response Endpoint_GetInfo_Response
err zx/Status

常量

名称值类型说明
MAX_COMPLETIONS_PER_EVENT 64 uint32

限制在单个 OnCompletion 事件中传送的完成次数，以避免超出 Zircon 通道消息大小限制（ZX_CHANNEL_MAX_MSG_BYTES = 64KB），即使使用分散-收集缓冲区链也是如此。
REQUEST_MAX 64 uint32

对 QueueRequests() 的一次调用中的请求数量限制。
VMO_VECTOR_MAX 64 uint32

对一次调用 RegisterVmos() 或 UnregisterVmos() 的 VMO 数量的限制。 受 Zircon 通道句柄限制 (ZX_CHANNEL_MAX_MSG_HANDLES = 64) 的约束，因为 RegisterVmos() 会返回 VMO 句柄的向量。