Zircon 系統介面評分量表

Zircon 系統介面是以 libzircon.so vDSO API 介面表示。

介面中的函式名稱必須以 zx_ 開頭 和預先處理器巨集的名稱開頭必須為 ZX_。定義為 介面部分名稱的開頭須為 zx_,結尾則須為 _t

介面中的所有函式都必須使用 Markdown 文件 /docs/zircon/syscalls/ 中的檔案,並 來自 /docs/zircon/syscalls.md 。

函式名稱

函式的名稱必須完全由小寫英文字母組成, 並符合下列文法:

zx_<noun>_<verb>{_<direct-object>}

例如:

zx_handle_close, zx_channel_write, zx_object_signal_peer

一般來說,名詞是核心物件類型,但也可以是其他名詞,例如 clockticks,沒有對應的核心物件。其他 函式會使用更多抽象名詞,例如 systemstatus

名詞和動詞不得包含底線 (以免造成混淆 文法)。名詞和動詞應各為一個英文單字,而非縮寫 (或 如果沒有合適的字詞或字詞太長,可以使用縮寫。

直接物件可以包含底線。

有些函式會執行複合作業。在這種情況下,函式可能是 透過串連元件作業名稱來命名

有些函式會針對多種類型的核心物件進行運算, 是更為抽象的物件類型例如,名詞為 object 的函式 對大多數核心物件和函式執行運算,而名詞 task 會在 工作、程序和執行緒。

類型

使用 zx_status_t 表示成功和失敗。

使用固定大小的整數類型。函式不得使用 shortintunsigned long (或類似類型)。請改用 int16_t 等類型。 int32_tuint64_t

針對緩衝區長度、元素大小和元素計數,請使用 size_t

在呼叫端位址空間中,使用 void* 做為指標,以便前往任意類型。使用 zx_vaddr_t / zx_paddr_t

使用 zx_time_t 指定逾時時間,必須使用絕對期限, 系統的單調時脈時間基數 (以奈秒為單位)。在下列情況下, 絕對期限並不合理 (例如計時器空間), zx_duration_t 表示以奈秒為單位的時間長度,沒有特定要求 時間上限。

參數

接收器

大多數函式都是根據控點執行,而這是對核心的參照 符合函式名稱中 noun 的類型物件。這個帳號代碼是 這類函式的第一個引數稱為接收器。

使用接收器的名稱 handle

物件建立函式 (例如 zx_channel_createzx_event_create) 可能無法 取得處理常式引數這些函式會以目前的 上傳資料集之後,您可以運用 AutoML 自動完成部分資料準備工作

選項參數

函式通常包含 options 參數,以允許影響標記的標記 並在作業中保留空間,以便日後新增其他標記 API 修訂版本

使用類型 uint32_t 和名稱 options 做為 options 參數。

存在時,options 參數必須是緊接在 或整體第一個引數 (如果函式沒有 接收器。

並非所有函式都需要 options 參數。

個別選項值必須定義為投放 將數字常值轉換為 uint32_t。選項必須是位元旗標 結合使用位元 | 運算子。

帳號代碼

當函式以參數的形式指定時,函式必須 一律消耗或不使用處理常式,但以下情況除外:

  • 如果函式使用 options 參數,則函式可能具有 非預設的選項,避免在各種錯誤情況下使用控制代碼。

  • 如果函式沒有使用 options 參數,函式可能會避免 會耗用控制代碼 (如果傳回 ZX_ERR_SHOULD_WAIT 或何時傳回)。

包含資料、計數/大小和/或實際資料的緩衝區

一律伴隨陣列或大小,以及數量或大小 (類型為 size_t) 的緩衝區。 包括字串如果緩衝區是由函式寫入,則函式必須 有一個 out 參數,會傳回寫入資料的計數或大小。

針對讀寫作業,緩衝區的指標會 後面接著緩衝區數量或大小,如果簡短讀取或寫入 可能會提供失敗參數的實際計數或大小:

zx_status_t zx_socket_write(zx_handle_t handle, uint32_t options,
                            const void* buffer, size_t size, size_t* actual);

如果有多個緩衝區,畫面上會顯示緩衝區、長度和傳出參數 以一致的順序交錯例如,請參閱 zx_channel_read

zx_status_t zx_channel_read(zx_handle_t handle, uint32_t options,
                            void* bytes, zx_handle_t* handles,
                            uint32_t num_bytes, uint32_t num_handles,
                            uint32_t* actual_bytes, uint32_t* actual_handles);

輸出內容

外參數是由函式寫入的純量值。舉例來說 透過寫入 uint32_t 來傳回 CPU 數量的函式已無 參數。如果函式會填入用戶端提供的緩衝區,緩衝區 不是結尾參數。

結束參數一律位於參數清單的結尾。

結尾參數也必須為 in 參數。例如,如果函式 具有 out 參數,而該參數會傳回寫入到 緩衝區,函式也不得使用該參數來接收 呼叫端的緩衝區長度。

傳回類型

絕大多數的函式都有傳回類型 zx_status_t, 成功時為 ZX_OK,失敗時則為 ZX_ERR_...

請勿透過 zx_status_t 傳回其他值,例如使用 正值範圍內請改用 out 參數。

其他傳回類型可能會用於無法失敗的函式。例如: zx_thread_exit 絕對不會離開執行緒,且傳回類型為 void。 同樣地,zx_clock_get_monotonic 無法取得目前時間,且 zx_time_t 的傳回類型。

函式專屬規則

zx_object_get_property 與 zx_object_get_info

有兩種類似的機制可用來公開物件相關資料: 《zx_object_get_property》和《zx_object_get_info》。偏好以公開方式提供資料 zx_object_get_property 表示 (a) 可使用屬性設定屬性 zx_object_set_property 或 (b) 屬性存在於多種類型中 如需儲存大量結構化物件 建議使用 Cloud Bigtable若是其他情況,建議您在 具有屬性的物件類型的 zx_object_get_info 主題。