fuchsia.hardware.usb.endpoint

新增：HEAD

通訊協定

端點

定義於 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

在完成時呼叫，通知裝置驅動程式庫完成事件。請注意，如果 defer_completion == true 的成功要求數量超過 MAX_COMPLETIONS_PER_EVENT，當 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_ids。傳回

  • 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 1:1 對應的錯誤值。

要求

名稱類型
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()，將 ID 傳送至要註冊的 VMO 及其大小。

序數欄位類型說明
id fuchsia.hardware.usb.request/VmoId

要註冊的 VMO 對應 ID。
size uint64

要註冊的 VMO 大小。

UNIONS

EndpointInfo flexible

定義於 fuchsia.hardware.usb.endpoint/endpoint.fidl

端點資訊

序數Variant類型說明
bulk BulkEndpointInfo

大量端點資訊
control ControlEndpointInfo

控制端點資訊
isochronous IsochronousEndpointInfo

等時端點資訊
interrupt InterruptEndpointInfo

中斷端點資訊

Endpoint_CancelAll_Result strict

定義於 fuchsia.hardware.usb.endpoint/endpoint.fidl

序數Variant類型說明
response Endpoint_CancelAll_Response
err zx/Status

Endpoint_GetInfo_Result strict

定義於 fuchsia.hardware.usb.endpoint/endpoint.fidl

序數Variant類型說明
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 控制代碼的向量。