RFC-0054：參數屬性

「有機會編寫自我記錄的 API」

摘要

我們已可將屬性套用至 FIDL 的各種元素，但無法套用至參數。本提案旨在擴充文法，以接受參數屬性。

與其他 RFC 的關係

這項 RFC 已由下列項目取代：

• RFC-0050：語法修訂

提振精神

在更多語言元素上加入屬性，可提高語言一致性，並為日後推出更多功能奠定基礎。無法在型別系統中編碼的 API 相關事實，都可以改為在屬性中編碼。任何無法在型別系統中編碼的事實，都可以在屬性中以更多結構擷取，簡化各種後端的後續驗證。這些屬性可用於 Lint，產生器也能利用這項資訊產生更優質的程式碼，或將這項資訊傳播至目標語言的屬性。這有助於對目標語言進行靜態和/或動態分析。此外，屬性也是原型設計的絕佳方式，可擴充或改良型別系統。

這項功能的主要用途是檢查控制代碼洩漏、重複釋放和釋放後使用錯誤。

核心 ABI (即系統呼叫) 也以 FIDL 格式表示，且控點擁有權通常不明確。使用者是否應在 task_kill 系統呼叫後呼叫 handle_close？說明文件並未清楚說明這點。其他系統呼叫的說明文件非常清楚，但只能手動檢查：

[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 程序。

效能

日後屬性可能會對成效產生良好影響。API 的相關資訊可能對目標語言的最佳化工具有所幫助。

安全性

特定屬性有助於目標語言的靜態和動態分析工具，因此可能提升安全性。

測試

系統會為 fidlc 編寫測試，確保剖析正確無誤，並針對編譯失敗提供合理的診斷資訊。系統也會測試產生的 JSON IR。如要進行測試，我們至少需要導入一個適用於參數的屬性。由於一開始不會觸及產生器，因此不需要額外測試。

缺點、替代方案和未知事項

導入成本相對較低。

RFC-0044 可能是替代方案。接受這項提案會導致語言出現不一致的情況，因為其中一種描述參數的方式可讓使用者編寫參數屬性，另一種則無法。此外，RFC-0044 有效能成本，因此部分通訊協定 (例如系統呼叫) 應盡量少用或完全不用。

既有技術和參考資料

Protobuf 訊息有選項，行為與參數屬性有些類似。FIDL 已經在部分語言元素 (例如成員和通訊協定) 上具有屬性。