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
通常,名詞是核心物件類型,但也可以是其他名詞,例如沒有對應核心物件的 clock
或 ticks
。其他函式則會使用較抽象的名詞,例如 system
或 status
。
名詞和動詞不得包含底線 (避免文法錯誤造成混淆)。名詞和動詞應為英文單字,但如果沒有適當字詞或字詞太長,則可使用縮寫 (或縮寫)。
直接物件可以包含底線。
部分函式會執行複合作業。在這類情況下,可透過串連元件作業名稱,為函式命名。
某些函式會在核心物件類型上運作,在此情況下,名詞是較抽象的物件類型。例如,含有名詞 object
的函式可在大多數核心物件和函式上執行,帶有名詞 task
的函式會在工作、程序和執行緒上運作。
類型
使用 zx_status_t
表示成功和失敗。
使用固定大小的整數類型。函式不得使用 short
、int
或 unsigned long
(或類似類型)。請改用 int16_t
、int32_t
和 uint64_t
等類型。
使用 size_t
做為緩衝區長度、元素大小和元素數量。
使用 void*
可以指向呼叫端位址空間中的任意類型指標。針對可能在其他位址空間中的位址,請使用 zx_vaddr_t
/ zx_paddr_t
。
針對逾時使用 zx_time_t
,這類值必須以系統單音時鐘時間集的絕對期限表示 (以奈秒表示)。如果使用絕對期限並不合理 (例如計時器倒帶),請使用 zx_duration_t
以沒有特定時間範圍的奈秒表示時間長度。
參數
接收器
絕大多數的函式都會對控制代碼執行操作,而控制代碼是類型中與函式名稱內 noun 相符的核心物件參照。這個帳號代碼是這類函式的第一個引數,稱為接收器。
請使用接收端的名稱 handle
。
物件建立函式 (例如 zx_channel_create
、zx_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_property
和 zx_object_get_info
。如果 (a) 可使用 zx_object_set_property
設定屬性,或 (b) 屬性跨多種物件類型,則偏好透過 zx_object_get_property
公開資料。如果不是的話,建議您針對含有該屬性的物件類型,在一般 zx_object_get_info
主題中加入資料。