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_tint32_tuint64_t 等類型。

使用 size_t 做為緩衝區長度、元素大小和元素數量。

使用 void* 可以指向呼叫端位址空間中的任意類型指標。針對可能在其他位址空間中的位址,請使用 zx_vaddr_t / zx_paddr_t

針對逾時使用 zx_time_t,這類值必須以系統單音時鐘時間集的絕對期限表示 (以奈秒表示)。如果使用絕對期限並不合理 (例如計時器倒帶),請使用 zx_duration_t 以沒有特定時間範圍的奈秒表示時間長度。

參數

接收器

絕大多數的函式都會對控制代碼執行操作,而控制代碼是類型中與函式名稱內 noun 相符的核心物件參照。這個帳號代碼是這類函式的第一個引數,稱為接收器。

請使用接收端的名稱 handle

物件建立函式 (例如 zx_channel_createzx_event_create) 可能無法使用處理引數。這些函式會在目前的程序上間接運作。

選項參數

函式通常包含 options 參數,可用於影響作業的標記,並納入在日後 API 修訂版本中加入其他標記的空間。

針對 options 參數使用 uint32_t 類型和 options 名稱。

如果有,options 參數必須是接收方控點之後的第一個引數,如果函式沒有接收器,則必須是整體的第一個引數。

所有函式都不需要使用 options 參數。

個別選項值必須定義為將數字常值轉換為 uint32_t 的預先處理器巨集。選項必須是可以使用位元 | 運算子合併的位元標記。

帳號代碼

當函式將控制代碼指定為參數時,該函式必須一律使用控制代碼或一律不取用,但以下例外狀況如下:

  • 如果函式使用 options 參數,該函式可能會有非預設選項,以避免在各種錯誤情況下使用帳號代碼。

  • 如果函式沒有使用 options 參數,則函式傳回 ZX_ERR_SHOULD_WAIT 時,可能會避免使用控點。

含有資料、計數/大小及/或實際數據的緩衝區

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

如果是讀取和寫入樣式作業,緩衝區的指標後面會加上緩衝區數量或大小,如果可以進行短的讀取或寫入,傳出參數會提供成功時的實際計數或大小:

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 參數。舉例來說,如果函式具有傳出參數,而該參數會傳回已寫入緩衝區的位元組數,那麼函式不得也使用該參數,從呼叫端接收緩衝區的長度。

傳回類型

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

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

其他傳回類型可用於無法失敗的函式。舉例來說,zx_thread_exit 絕不會結束執行緒,而且傳回類型為無效。同樣地,zx_clock_get_monotonic 無法取得目前時間,且傳回類型為 zx_time_t

函式專屬規則

zx_object_get_property 與 zx_object_get_info

有兩個類似的物件公開資料機制:zx_object_get_propertyzx_object_get_info。如果 (a) 可使用 zx_object_set_property 設定屬性,或 (b) 屬性跨多種物件類型,則偏好透過 zx_object_get_property 公開資料。如果不是的話,建議您針對含有該屬性的物件類型,在一般 zx_object_get_info 主題中加入資料。