此页面由 Cloud Translation API 翻译。

Codelab：定义新的主板配置

此 Codelab 介绍了如何使用 Bazel 构建系统在 Fuchsia 中定义新的主板配置。主板配置对于指定在特定设备上运行 Fuchsia 所需的硬件专用组件、驱动程序和设置至关重要。

前提条件

熟悉 Fuchsia 的软件组装概念。
对 Bazel 构建规则有基本的了解。

什么是板级配置？

Fuchsia 中的主板配置封装了为特定硬件构建系统映像所需的所有必要信息。其中包括：

硬件标识：名称和版本。
代码：板级专用驱动程序和平台功能。
存储布局：分区排列方式。
启动过程：内核实参和设备树信息。
文件系统详细信息：压缩等选项。

主板配置使用 BUILD.bazel 文件（通常位于 //boards 目录中）中的 fuchsia_board_configuration 规则进行定义。

编写板级配置

下面我们通过示例来了解 fuchsia_board_configuration 规则的关键属性。

基本设置

每个主板配置都需要一个名称、主板名称和分区配置。例如：

# //boards/my_awesome_board/BUILD.bazel
load(
    "@rules_fuchsia//fuchsia:assembly.bzl",
    "fuchsia_board_configuration",
)

fuchsia_board_configuration(
    name = "my_awesome_board",  # Target name for the build system
    board_name = "my_awesome_board",  # Identifier used by tools like ffx
    version = "1.2.3.4",  # Version of the board configuration
    partitions_configuration = "//boards/partitions/my_awesome_board",
    # ... more attributes to come
)

分区配置

partitions_configuration 字段指向 fuchsia_partitions_configuration 目标，该目标通常在 //boards/partitions 的子目录中的 BUILD.bazel 文件中定义。此目标定义了主板的分区布局和类型，例如 ZBI、VBMeta 和 FXFS 的位置。

这些映像和分区通常会整理到不同的 ABR slot 中。

例如，在 //boards/partitions/my_awesome_board/BUILD.bazel 中：

load(
    "@rules_fuchsia//fuchsia:assembly.bzl",
    "PARTITION_TYPE",
    "SLOT",
    "fuchsia_bootloader_partition",
    "fuchsia_partition",
    "fuchsia_partitions_configuration",
)

# Standard Fuchsia partitions
fuchsia_partition(
    name = "zircon_a",
    partition_name = "zircon_a",
    slot = SLOT.A,
    type = PARTITION_TYPE.ZBI,
)

fuchsia_partition(
    name = "vbmeta_a",
    partition_name = "vbmeta_a",
    slot = SLOT.A,
    type = PARTITION_TYPE.VBMETA,
)

fuchsia_partition(
    name = "fxfs",
    partition_name = "fvm", # Or "fxfs" depending on board
    type = PARTITION_TYPE.FXFS,
)

# ... (typically define all slots A, B, R for ZBI/VBMeta)

# Board-specific bootloader partition
fuchsia_bootloader_partition(
    name = "my_bootloader",
    image = "//boards/my_awesome_board/firmware:my_awesome_bootloader.img",
    partition_name = "bootloader",

    # The type is used by the board's paver driver to map to a particular
    # partition during Over-the-Air (OTA) updates.
    type = "",
)

# The main configuration, referencing the partition targets
fuchsia_partitions_configuration(
    name = "my_awesome_board",

    # `ffx` compares `hardware_revision` to the fastboot variable `hw-revision`,
    # and refused to flash the device is they do not match. This ensures that
    # the wrong image is not flashed to the wrong board.
    hardware_revision = "my_awesome_board_rev1",
    bootloader_partitions = [
        ":my_bootloader",
    ],
    partitions = [
        ":zircon_a",
        ":vbmeta_a",
        ":fxfs",
        # ... and other partition targets
    ],
)

说明：

fuchsia_partition 定义各个分区（如 ZBI、VBMeta 和 FXFS），并指定其名称、类型和 slot（如果适用）。
fuchsia_bootloader_partition 定义引导加载程序分区，并关联到引导加载程序映像目标。程序集将引导加载程序分区视为“无 slot”。
定义一个描述设备上分区的 fuchsia_partitions_configuration 目标。所有主板都需要此参数。

包含代码：板级专用代码与平台专用代码

您可以通过两种主要方式在板配置中包含代码：

板输入源软件包 (BIB)：适用于与板硬件紧密耦合的代码。
提供的功能：用于从 Fuchsia 平台请求通用功能

板级输入源捆绑包 (BIB)

BIB 用于打包特定于主板的驱动程序、配置和硬件特有的其他文件。这些变量使用 fuchsia_board_input_bundle 规则定义。例如：

# //boards/my_awesome_board/BUILD.bazel
load(
    "@rules_fuchsia//fuchsia:assembly.bzl",
    "fuchsia_board_input_bundle",
)

# BIB for a board-specific compass driver
fuchsia_board_input_bundle(
    name = "my-compass",
    bootfs_driver_packages = [
        "//src/devices/board/drivers/my-compass",
    ],
)

可以使用 board_input_bundles 属性将 BIB 包含在主板配置中。例如：

# //boards/my_awesome_board/BUILD.bazel
fuchsia_board_configuration(
    name = "my_awesome_board",
    board_name = "my_awesome_board",
    version = "1.2.3.4",
    partitions_configuration = "//boards/partitions/my_awesome_board",

    board_input_bundles = [
        ":my-compass",  # Reference the BIB target
    ],

)

最佳实践是为每个可能也在其他主板上找到的硬件逻辑组创建一个 BIB。这样，类似的板就可以共享 BIB。例如 compass、paver、rtc 等。

提供的功能

此属性允许主板声明其支持或需要某些平台级功能。然后，组装系统可以根据这些标志包含必要的平台代码。

此机制可将主板定义与常见平台功能的实现细节分离。主板不再提供代码，而是声明需要代码。例如：

# //boards/my_awesome_board/BUILD.bazel
fuchsia_board_configuration(
    name = "my_awesome_board",
    board_name = "my_awesome_board",
    version = "1.2.3.4",
    partitions_configuration = "//boards/partitions/my_awesome_board",

    provided_features = [
        "fuchsia::driver_runtime",
        "fuchsia::vulkan_support",
    ],

)

在这种情况下，主板表示它具有需要平台提供的运行时驱动程序和 Vulkan 支持的硬件。

设备树

如果您的主板使用设备树，则可以使用 devicetree 属性指定 .dtb 二进制目标。例如：

# In //boards/my_awesome_board/BUILD.bazel
fuchsia_board_configuration(
    name = "my_awesome_board",
    board_name = "my_awesome_board",
    version = "1.2.3.4",
    partitions_configuration = "//boards/partitions/my_awesome_board",

    devicetree = "//boards/my_awesome_board/firmware:board.dtb",

)

文件系统选项

filesystems 属性接受一个字典来配置图片的各个方面，例如 ZBI 压缩。如需查看可用选项的完整列表，请参阅 BoardFilesystemConfig。例如：

# In //boards/my_awesome_board/BUILD.bazel
fuchsia_board_configuration(
    name = "my_awesome_board",
    board_name = "my_awesome_board",
    version = "1.2.3.4",
    partitions_configuration = "//boards/partitions/my_awesome_board",

    filesystems = {
        "zbi": {
            "compression": "zstd.max",
        },
    },

)

您还可以在 filesystems 属性中配置 vbmeta 签名密钥。例如：

# In //boards/my_awesome_board/BUILD.bazel
fuchsia_board_configuration(
    name = "my_awesome_board",
    board_name = "my_awesome_board",
    version = "1.2.3.4",
    partitions_configuration = "//boards/partitions/my_awesome_board",

    filesystems = {
        "vbmeta": {
            "key": "//path/to/my:vbmeta_private_key",
            "key_metadata": "//path/to/my:vbmeta_key_metadata",
        },
    },

)

后处理脚本

如果您的主板在标准组装后需要执行额外的映像处理步骤（例如，创建特定于供应商的启动映像格式），则可以使用 post_processing_script 属性。

定义 fuchsia_post_processing_script 目标。例如：

# In //boards/my_awesome_board/BUILD.bazel
load(
    "@rules_fuchsia//fuchsia:assembly.bzl",
    "fuchsia_post_processing_script",
)

fuchsia_post_processing_script(
    name = "my_post_processing_script",
    post_processing_script_path = "tools/sign_image.sh",
    post_processing_script_args = [
        "-i", "zbi",
        "-o", "zbi.signed",
    ],
    post_processing_script_inputs = {
        "//path/to/keys:private_key": "keys/private_key",
    },
)

在主板配置中引用它。例如：

# In //boards/my_awesome_board/BUILD.bazel
fuchsia_board_configuration(
    name = "my_awesome_board",
    board_name = "my_awesome_board",
    version = "1.2.3.4",
    partitions_configuration = "//boards/partitions/my_awesome_board",

    post_processing_script = ":my_post_processing_script",

)

后续步骤

此 Codelab 介绍了在 Fuchsia 中使用 Bazel 定义新主板配置的基础知识。您已了解如何使用 fuchsia_board_configuration 及相关规则来指定从驱动程序到文件系统选项的所有内容。

如需继续学习，您可以：

探索 //boards 目录中的现有板级配置，重点关注 x64、arm64 和 vim3 等子目录中的 BUILD.bazel 文件。
深入了解 Fuchsia 软件组装概念。