fuchsia.hardware.usb.endpoint

添加了：HEAD

PROTOCOLS

端点

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

端点接口。 与端点关联的预注册 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（即不能跨越不连续的物理页面或多个缓冲区区域）。

客户端负责缓存管理并确保缓存一致性。以下说明涉及之前通过 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_ids。返回

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

请求

名称类型
vmo_ids vector<VmoInfo>:64

响应

名称类型
vmos vector<VmoHandle>:64

UnregisterVmos

取消注册与 vmo_ids 对应的 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/Status>: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（即不能跨越不连续的物理页面或多个缓冲区区域）。

完成资源

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

完成

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

请求已完成。
status zx/Status

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

  • 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（即不能跨越不连续的物理页面或多个缓冲区区域）。

IsochronousEndpointInfo

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

同步端点信息

序数字段类型说明
lead_time uint64

以转机次数表示的提前时间。
supports_scatter_gather bool

如果端点控制器支持多页 / 多 TRB 散布-收集链，则为 true。 如果为 false，则每个请求必须包含一个完全位于单个物理连续内存范围内的 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 严格

在 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 句柄的向量。