此页面由 Cloud Translation API 翻译。

绑定库准则

Fuchsia 命名空间和范围

在 Fuchsia 树 (fuchsia.git) 中定义的所有绑定库都必须遵守命名空间的以下规则：

如果绑定库用于内部测试并从 SDK 中排除，则必须对顶级命名空间进行测试
否则，顶级命名空间必须为 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_

Rust

// 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 绑定库中的属性。

供应商平台绑定库可以从任何硬件功能绑定库进行扩展。

在旧版媒体资源的基础上进行扩展

旧版 fuchsia 绑定库位于最高级别。所有绑定库都可以通过其扩展。不过，由于这些属性已废弃，因此我们应避免扩展这些属性，而应改为引入新属性。