Driver 執行階段 API 指南

本頁包含 Fuchsia 在驅動程式庫執行階段中定義 C API 時遵循的一套原則和規則。相較於其他 API，Fuchsia 對這些 API 更有意識，因為 API 是驅動程式庫 ABI 的重要部分。

命名

• API 應遵循 <subject>_<verb>[_<object>] 的 Zircon 系統呼叫命名慣例。
  • 在 fdf_dispatcher_get_options 的 API 範例中，主詞是 dispatcher、動詞為 get，物件為 options。
  • 不過，並非所有 API 都有物件。在某些情況下，物件可能是副詞 (例如 fdf_channel_wait_async)。
  • 嵌入環境 API 的僅供測試和 API 參照全域單例模式物件。
• API 的開頭須為 fdf_ 前置字串。
  • 僅供測試用的 API 必須以 fdf_testing_ 前置字串開頭。
  • 適用於嵌入環境的 API 必須以 fdf_env_ 前置字串開頭。
• 輸出參數的開頭必須是 out_ 前置字串。

執行緒

• API 應指出在留言區塊中是否遭到封鎖。
• 封鎖 API 必須驗證是否在驅動程式庫執行階段分派器 (已指定 FDF_DISPATCHER_OPTION_ALLOW_SYNC_CALLS 選項) 中叫用。
  • 不過，zx_futex_wait 和 zx_futex_requeue 是例外狀況，因為它們不能在驅動程式庫外部的狀態上進行封鎖，避免在驅動程式庫程式作者無法控制的情況下發生死結風險。
• API 必須為執行緒安全。
  • 雖然這些函式可能會在錯誤的調派程式情境中呼叫時傳回錯誤，但不應以未定義的方式採取行動。
• 用於回呼的 API 應在已同步處理² 驅動程式庫執行階段調度程式中提供同步取消語意¹。
  • 非同步取消應導致呼叫回呼，可能因為錯誤狀態表示向前進度已強制執行，而未符合觸發回呼的一般條件。
  • API 不應根據註冊回呼的調度工具類型以外的任何類型，提供有條件的同步或非同步取消機制。

物品

• 建立物件的 API 必須具備對應的 API 才能刪除這些物件。
• 傳回建立物件的 API 應傳回物件的不透明指標，而不是描述物件的內部結構。
• 建立物件的 API 應採用 uint32_t options 參數，並搭配可擴充的位元旗標以提升擴充性。

參數

• API 應透過指標擷取所有非原始參數。
• 如果 API 使用的用戶端分配參數時間超過函式呼叫本身，則必須執行下列操作：
  • 取得物件的完整擁有權，以及物件參照的任何其他物件 (也就是說，也包含在相同的配置中)。
  • 提供可將物件傳回呼叫端的機制 (例如回呼參數)。
  • 提供取消機制，以便在一般傳回物件之前主動將物件傳回呼叫端。
  • 提供一種機制，讓用戶端使用單一配置，在物件後方內嵌其他用戶端專屬結構定義。
• 不應假設字串為空值，也不應包含「靜態」生命週期。
• 回呼參數應使用 typedef 轉換為新類型。
• 回呼參數應該嵌入 struct 中，確保這些參數可以儲存在單一分配位置中。

其他

• API 應包含註解區塊，說明其用途、參數、輸出，以及可能的錯誤。
  • 範例為選填，但建議使用。
  • 註解區塊必須使用 Markdown 語法，這種語法有助於產生網頁式說明文件。
• API 必須是「記憶體不足」；也就是說，執行階段分配的記憶體必須由執行階段釋放，用戶端分配的記憶體必須釋出。
  • 這項規則是例外情況。
• 如果叫用不當，API 應優先傳回錯誤，而非斷言 (例如，在含有無效參數的調派程式上)。
• 僅供測試專用的 API 只能在測試環境中使用。
• 環境專用 API 只能提供給驅動程式庫的執行環境使用，而非驅動程式庫本身。