新增 Zircon 系統呼叫 (或新增 Zircon 物件類型)

本文件是新增 Zircon 系統呼叫的簡短指南。目標對象是核心開發人員或任何新增系統呼叫的使用者。

請注意，本指南只涵蓋新增系統呼叫/物件的機制。這不是樣式指南或評分標準，也不會提供任何建議，說明如何判斷 API 是否足夠穩定或成熟，可成為系統介面的一部分。

由於系統會持續變更，因此本指南可能會過時。很抱歉，如果您在按照本指南操作時發現錯誤或遺漏，請嘗試更新。感謝您！

總覽

您可以透過多種方式設定變更，以新增新的 Zircon 系統呼叫 (或物件)。本指南將說明一種方法，其中包含四個 CL：Stub、實作、額外和註解。

我們將遵循「重寫歷史記錄」方法。Zircon 系統呼叫 (目前) 不會遵循平台版本，因此我們會讓系統呼叫看起來像是一直存在。為此，我們需要更新部分 SDK 記錄檔，以便凍結 API 級別。

空白 CL：從 HEAD 的空白開始

在這個 CL 中，您將定義系統呼叫，並提供簡單傳回 ZX_ERR_NOT_SUPPORTED 的簡化函式實作。請務必在這個 Stub CL 中加入核心測試，驗證呼叫端不會當機，且新呼叫會如預期傳回錯誤。

建構系統和 FIDL 編譯器會自動產生部分標準程式碼。為充分利用這項功能，建議您養成在變更 FIDL 檔案後，執行預設建構作業 fx build 和 fx check-goldens 的習慣。

為說明這項功能，我們來看看Stub CL，它同時新增了新的 Zircon 物件 (counter) 和新的系統呼叫 (zx_counter_create)。

空白 CL 有四個部分。

1. 使用 FIDL 定義系統呼叫

接著，請在現有的 .fidl 檔案中定義新的系統呼叫，或視需要新增檔案。請務必新增註解 @available(added=HEAD) 註解，指出在 HEAD 中新增了新的系統呼叫 (或物件，如果新增了新的 Zircon 物件)。

在較少見的新增 Zircon 物件情況下，您需要採取一些額外步驟。

a. 向 FIDL 編譯器說明新的物件類型。FIDL 工具鍊會將物件類型的知識納入其中。這不是最理想的做法，但可避免產生循環依附性。您必須更新部分 FIDL 工具鍊，才能瞭解新的物件類型。具體來說，請更新：

b. 請按照未更新 fidlc 金標準時收到的建構錯誤訊息中提供的指示，更新 fidlc 金標準。

c. 將新物件類型新增至 zircon/types.h。

d. 更新 //sdk/history/*/zx.api_summary.json 檔案。這些是公用 zx FIDL 程式庫的內容，與系統呼叫程式庫共用 zx_common.fidl。

e. 視需要擴充 docsgen。

2. 在核心中實作系統呼叫

請在 zircon/kernel/lib/syscalls/ 中的某處實作系統呼叫，前置字元應為 sys_，而非 zx_。目前，實作項目應只傳回 ZX_ERR_NOT_SUPPORTED。

3. 新增 lib/zx C++ 包裝函式

新增或擴充現有的 lib/zx 包裝函式，為新的系統呼叫提供 C++ API。請務必將 ZX_AVAILABLE_SINCE(HEAD) 註解套用至新的 C++ 方法 (或類別，如果是新的 Zircon 物件)。雖然系統一開始就會顯示系統呼叫本身，但 C++ 包裝函式是在 HEAD 中新增的。

4. 新增核心測試

新增核心測試，驗證 Stub 是否傳回正確的錯誤值 (且不會導致系統當機)。在這個測試中使用新的 lib/zx 包裝函式，即可確保它也能正常運作。

當您取得要建構並通過 CQ 的存根資料後，請將其發布。接著，請前往實作 CL。

實作 CL：填入輔助程式

現在，您可以將 Stub 實作項目替換為實際項目，並新增實際測試和實際文件。建構、通過 CQ，然後將其發布。

額外 CL：新增其餘內容

有了 C/C++ 繫結的有效實作項目後，您就可以新增 Rust 繫結，並更新 (fidl_codec (由 fidlcat 使用)： - display_handle.cc 中的 ShortObjTypeName - printer.cc 中的 PrettyPrinter::DisplayObjType

上述「額外」清單可能不完整，因此不妨查看其他系統呼叫，看看是否還有其他需要更新的項目 (工具？其他語言的繫結？)。將額外 CL 放置到專案中，然後繼續執行最後一個步驟。

註解 CL：將 HEAD 變更為 NEXT

實作和額外項目已完成，請返回並將 @available 和 ZX_AVAILABLE_SINCE 註解中新增的值從 HEAD 變更為 NEXT，以便在下一個穩定的 API 級別中提供系統呼叫。