繫結程式庫規範

Fuchsia 命名空間和範圍

Fuchsia 樹狀結構 (fuchsia.git) 中定義的所有繫結程式庫都必須遵守下列命名空間規則：

  • 如果繫結程式庫用於內部測試，且已從 SDK 排除，則頂層命名空間必須是 test
  • 否則頂層命名空間必須為 fuchsia。這表示繫結程式庫是開放原始碼 Fuchsia 專案的一部分。

繫結程式庫範圍

繫結程式庫應以下列其中一種方式設定範圍：

  • 供應商平台
  • 硬體功能
  • 已淘汰的 Banjo 通訊協定

供應商平台

由供應商平台範圍限定的繫結程式庫會定義與供應商硬體相關聯的屬性。舉例來說，Amlogic 等供應商會維護自己的產品 ID (PID) 資料庫。

整體來說，繫結程式庫的命名空間應採用以下格式：

fuchsia.<vendor>.platform

透過命名空間巢狀結構，可依特定硬體或功能進一步縮減繫結程式庫的範圍。舉例來說，Amlogic 硬體的繫結程式庫高層級命名空間為 fuchsia.amlogic.platform。

如果我們想要 Amlogic Meson 系列的繫結程式庫，可以在 fuchsia.amlogic.platform.meson 命名空間中定義。如果我們想要適用於 Amlogic 硬體的繫結程式庫 (具備顯示功能)，可以在 fuchsia.amlogic.platform.display 命名空間中定義。

硬體功能

繫結程式庫 (以硬體功能為範圍) 包含與該功能相關的屬性。命名空間應採用以下格式：

fuchsia.<hardware function>

這些繫結程式庫屬於高階通用程式庫，因此，任何供應商平台繫結程式庫都可以擴充這些屬性。

硬體功能命名空間可透過巢狀結構劃分為更具體的繫結程式庫。舉例來說，fuchsia.usb 繫結程式庫包含 USB 裝置的高階屬性。如要定義 USB 大量儲存裝置專屬的屬性，可以在 fuchsia.usb.massstorage 繫結程式庫中定義這些屬性。

已淘汰的 Banjo 通訊協定

由 Banjo 通訊協定範圍限定的繫結程式庫包含代表實作通訊協定的裝置的屬性。這些程式庫是因舊版程式碼而建立，應逐步淘汰，改用以硬體功能為範圍的程式庫。

命名

命名空間元件

名稱的每個元件都必須是小寫，且符合規則運算式 [a-z][a-z0-9]*。

屬性鍵和值

屬性鍵和值最好採用全大寫蛇形命名法。這項功能可提升語言繫結中產生的常數可讀性。

舉例來說，假設有下列繫結程式庫

library fuchsia.input;

enum DEVICE_CATEGORY {
  KEYBOARD,
  MOUSE,
};

系統會產生下列常數：

C++

// WARNING: This file is machine generated by bindc.

#ifndef BIND_FUCHSIA_INPUT_BINDLIB_
#define BIND_FUCHSIA_INPUT_BINDLIB_

#include <string>

namespace bind_fuchsia_input {

static const std::string DEVICE_CATEGORY = "fuchsia.input.DEVICE_CATEGORY";
static const std::string DEVICE_CATEGORY_KEYBOARD = "fuchsia.input.DEVICE_CATEGORY.KEYBOARD";
static const std::string DEVICE_CATEGORY_MOUSE = "fuchsia.input.DEVICE_CATEGORY.MOUSE";

}  // namespace bind_fuchsia_input

#endif  // BIND_FUCHSIA_INPUT_BINDLIB_

荒漠油廠

// WARNING: This file is machine generated by bindc.

pub const DEVICE_CATEGORY: &str = "fuchsia.example.library.DeviceCategory";
pub const DEVICE_CATEGORY_KEYBOARD: &str =
    "fuchsia.input.DEVICE_CATEGORY.KEYBOARD";
pub const DEVICE_CATEGORY_MOUSE: &str =
    "fuchsia.input.DEVICE_CATEGORY.MOUSE";

類型

建議使用列舉型別，而非字串，做為繫結集

對於值數量有限且靜態已知的屬性，建議使用列舉型別。舉例來說，fuchsia.hardware.gpio.FUNCTION 屬性更適合做為列舉型別，因為每個開發板的功能集都是靜態已知的。

如果可能需要將新值新增至屬性，使用列舉可能仍較合適。您可以從新的繫結程式庫擴充屬性，藉此調整屬性值。

如果屬性值範圍廣泛且彈性，建議使用字串類型。例如 ACPI HID 值，這是用來識別裝置製造商和供應商製造的特定裝置的字串 (例如「PRP0001」)。

外部登錄檔請使用整數值

整數值更適合代表由知名登錄機構從外部維護的數字值屬性，例如 PCI ID 登錄中的供應商 ID，以及 USB 登錄中的類別代碼。

避免在舊版繫結程式庫中新增屬性

舊版屬性定義於 fuchsia 繫結程式庫和 binding_priv.h。由於這些屬性已淘汰，且正逐步停用，請盡量避免在其中新增任何屬性。

擴充屬性

繫結程式庫應只擴充命名空間中較高層級的其他繫結程式庫，或硬體功能範圍內的程式庫屬性。

如果繫結程式庫的範圍是硬體功能，則應只從命名空間中較高的繫結程式庫擴充。舉例來說， fuchsia.usb.audio 繫結程式庫只能擴充 fuchsia.usb 和 fuchsia 繫結程式庫的屬性。

廠商平台繫結程式庫可以從任何硬體功能繫結程式庫擴充。

從舊版資源擴展

舊版紫紅色繫結程式庫位於最高層級。所有繫結程式庫都可以從中擴充。不過，由於這些屬性已淘汰，我們應避免擴充屬性，並改為導入新屬性。