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，且該 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_ids 的控制代碼。 如果 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，且該 VMO 完全位於單一實體連續記憶體範圍內 (也就是說，不得跨越不連續的實體頁面或多個緩衝區)。

完成 resource

定義於 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，且該 VMO 完全位於單一實體連續記憶體範圍內 (也就是說，不得跨越不連續的實體頁面或多個緩衝區)。

IsochronousEndpointInfo

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

等時端點資訊

序數欄位類型說明
lead_time uint64

以轉乘次數表示的前置時間。
supports_scatter_gather bool

如果端點控制器支援多頁面 / 多 TRB 散佈收集鏈結，則為 True。 如果為 false，則每項要求都必須包含單一 VMO，且該 VMO 完全位於單一實體連續記憶體範圍內 (也就是說，不得跨越不連續的實體頁面或多個緩衝區)。

VmoHandle resource

定義於 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 大小。

工會

EndpointInfo 彈性

定義於 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 控制代碼向量。