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
) 可能無法
取得處理常式引數這些函式會以目前的
上傳資料集之後,您可以運用 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
主題。