本程式碼研究室會逐步說明如何使用 Bazel 建構系統，在 Fuchsia 中定義新的開發板設定。主機板設定對於指定在特定裝置上執行 Fuchsia 所需的硬體專屬元件、驅動程式和設定至關重要。
必要條件
- 熟悉 Fuchsia 的軟體組裝概念。
- 對 Bazel 建構規則有基本瞭解。
什麼是看板設定？
Fuchsia 的主機板設定會封裝所有必要資訊，以便為特定硬體建構系統映像檔。包括：
- 硬體識別：名稱和版本。
- 程式碼：主機板專屬驅動程式和平台功能。
- 儲存空間配置：分區的排列方式。
- 啟動程序：核心引數和裝置樹狀結構資訊。
- 檔案系統詳細資料：壓縮等選項。
主機板設定是使用 BUILD.bazel 檔案中的 fuchsia_board_configuration 規則定義，通常位於 //boards 目錄中。
編寫主面板設定
接著來看看 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 插槽。
例如，在 //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，並指定名稱、類型和適用於這些分割區的插槽。fuchsia_bootloader_partition會定義系統啟動載入程式分割區，並連結至系統啟動載入程式映像檔目標。組裝程序會將開機載入程式分區視為「未分槽」。- 定義描述裝置上分割區的
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", )
後續步驟
本程式碼研究室涵蓋了在 Fuchsia 中使用 Bazel 定義新開發板設定的基本知識。您已瞭解如何使用 fuchsia_board_configuration 和相關規則，指定從驅動程式到檔案系統選項的所有項目。
如要繼續學習，請參閱下列文章：
- 在
//boards目錄中探索現有的開發板設定，並留意x64、arm64和vim3等子目錄中的BUILD.bazel檔案。 - 進一步瞭解 Fuchsia 軟體組裝概念。