RFC-0054：參數屬性

「編寫自行記錄 API 的可能性」

摘要

我們可以將屬性套用至 FIDL 的各種元素，但不能套用至參數。為接受參數屬性，建議您擴充文法。

與其他 RFC 的關係

這個 RFC 已由以下機構取代：

• RFC-0050：語法翻新

提振精神

為更多語言元素提供屬性，可提高語言一致性 也有助於日後推出更多功能關於 API 的任何相關資訊 若是類型系統中無法編碼的，則改在屬性中編碼。 任何無法在類型系統中編碼的事實，都可以擷取更多 結構，簡化各後端的延遲驗證。這些 屬性在程式碼檢查方面相當實用，而產生器也能 產生更好的程式碼，或將其傳播到 目標語言。有助於對目標進行靜態和/或動態分析 語言。此外，屬性是建立原型的好方法 或是修正類型系統

這項功能的驅動案例是檢查處理事件是否外洩， 免費錯誤後再使用

核心 ABI (例如系統呼叫) 也會以 FIDL 格式表示， 帳號代碼的擁有權不清楚。使用者需要在 a task_kill syscall 嗎？但不從說明文件中明確得知。其他 Syscall 的說明文件非常清楚，但只能手動檢查：

[Transport = "Syscall"]
protocol handle {
    /// Close a handle.
    /// Rights: None.
    handle_close(handle handle) -> (status status);

    /// Close a number of handles.
    /// Rights: None.
    handle_close_many(vector<handle> handles) -> (status status);

    /// Duplicate a handle.
    /// Rights: handle must have ZX_RIGHT_DUPLICATE.
    handle_duplicate(handle handle, rights rights) -> (status status, handle out);

    /// Replace a handle.
    /// Rights: None.
    handle_replace(handle handle, rights rights) -> (status status, handle out);
};

啟用參數屬性後，可將註解替換為 屬性。這些屬性就像註解一樣容易閱讀，有助於 產生器，以便產生可使用靜態和動態檢查檢查功能的程式碼 分析工具，例如這個。kazoo 工具 為 C 及 C++ 繫結產生相應的註解，讓 Clang 靜態分析工具 處理濫用錯誤。

此原型已在 Fuchsia 中發現一些錯誤，

設計

本提案將參數屬性新增至 FIDL 來源語言。這些 屬性應該在 JSON IR 中，類似於其他 屬性。我們可能需要更新格式設定工具。不會影響線路 格式。語言繫結只會在引入特定字詞時 可以變更系統產生的程式碼，但不會受到這次程式碼影響的註解 直接提案

我們的提案只會變更一項 FIDL 產生規則 文法：

- parameter = type-constructor , IDENTIFIER ;
+ parameter = ( attribute-list ) , type-constructor , IDENTIFIER ;

我們必須診斷三條斜線文件或文件屬性 參數。

執行策略

這項變更具有回溯相容性，無須進行遷移。有很多 說明文件。這項提案 會變更剖析器，並在 IR 中新增資訊。一項可能變更 當新的參數屬性出現 。

人體工學

這麼做有望讓 FIDL API 更容易理解並相互繫結 進行靜態和動態分析但複雜作業的成本 溫度較低。如要查看潛在參數屬性的範例，請參閱下一節。 編輯器支援功能可能也需要小幅更新。

說明文件和範例

文法說明文件和語言參考資料需要小幅更新，三 然後加入一些樣式規範，瞭解如何在特定情況下換行 參數屬性這點不必特別重要，因為屬性 先前在樣式指南中提及的所有元素。

如需示例，請參閱動機一節。

回溯相容性

本提案保有 FIDL 來源和線路 ABI 的相容性。 之後才引入的特定屬性可能會導致 ABI 連線 不相容情形需要這些屬性才能通過 RFC 程序 。

成效

未來屬性可能會對成效產生明顯影響。更多資訊 可能有助於最佳化目標語言的最佳化工具。

安全性

具體特徵可以協助減少 提供動態分析工具

測試

將以 fidlc 編寫測試，確保剖析正確且容易進行診斷 才能進行編譯系統也會測試產生的 JSON IR。為了 我們必須導入至少一個適用的屬性 參數。發電機一開始不會有任何接觸，因此不會 需要額外測試

缺點、替代方案和未知

實作成本相對較低。

RFC-0044 是可能的替代方案。接受提案 在語言中導入一些不一致的情況，做為描述文字的一種方式 參數可讓使用者在寫入參數屬性時 而不是此外，RFC-0044 也具有效能成本，因此某些通訊協定，例如 syscall 請盡量少用到完全不要使用

既有藝術品和參考資料

Protobuf 有 開啟選項 訊息，其行為與參數屬性類似。FIDL 某些語言元素 (例如成員和通訊協定) 已有屬性，