Skip to content

Translation pending. This page is currently available in Chinese.

实例化构建与运行(instances/ 与 tools/a20)

1.0 的 平台决策 已将 LoongArch32/PPC64LE 退出支持。当前 instances/ 只登记活跃目标;旧 PPC64LE 清单归档在已退役平台的实例清单与文档已删除,LoongArch32 的历史运行记录见平台文档。Makefile 和 tools/a20 都会拒绝这两个目标,并指向干净的 v0.18 checkout 作为历史复现基线。功能与性能实例的证据要求见1.0 验收。

A20OS 的构建、运行与冒烟测试配置统一由 instances/ 下的 TOML 清单声明。每份清单指定架构、板卡、ABI、内核选项、根文件系统、网络、GUI 与测试期望。

  • 未写的字段沿用 Makefile 默认值;能力范围可用 tools/a20 trim <实例> 查询。
  • 架构、板卡、ABI、SMP、NOMMU 和驱动组件配置在构建前校验;失败会指出具体字段。
  • 修改清单或注册表后运行 make check-manifests,修改工具后运行 make check-a20-tests。

解析、注册表与构建接线的维护约束见 工具技术参考。

快速上手

tools/a20 list                            # 列出所有实例(名称、架构、可用动作、状态)
tools/a20 list --arch riscv64 armv7m      # 只看这些架构
tools/a20 list --action test              # 只看能跑冒烟的实例
tools/a20 show vf2-physical                # 这个实例支持什么、要多少资源、会碰什么
tools/a20 trim qemu-riscv64               # 这个实例按什么剪裁计划构建(profile/能力/内存预算)
tools/a20 run qemu-riscv64                # 构建并在 QEMU 启动(文本模式)
tools/a20 run xfce-x86_64                 # 图形桌面实例(apk world,含 virtio-gpu + 声卡)
tools/a20 run xfce-aarch64                # aarch64 桌面(SMP 竞态未决,暂为单 CPU)
tools/a20 run xfce-riscv64                # riscv64 桌面(xfce-loongarch64 同理)
tools/a20 run minecraft-x86_64 -- GUI_MEDIA=build/minecraft/1.21.11  # Minecraft 桌面
tools/a20 run minecraft-aarch64 -- GUI_MEDIA=build/minecraft/1.21.11-aarch64  # 其他架构同理
tools/a20 debug qemu-riscv64              # -O0 -g 构建 + QEMU GDB stub(:1234)
tools/a20 test smoke-riscv64              # 跑一个冒烟测试实例
tools/a20 flash stm32f103-xuanwu          # 构建固件并经 OpenOCD 烧录开发板
tools/a20 console vf2-physical           # 接开发板串口,按 [target] 做上板检查
tools/a20 deploy  vf2-physical           # 烧录 + 写启动介质 + 上板验证,一条命令走完
tools/a20 package vbox-iso-x86_64         # 构建并组装发布产物(ISO/UEFI 镜像/SD 卡/发布件)
tools/a20 resources                     # 查看实例运行所依据的宿主资源预算
tools/a20 build qemu-riscv64 -- -j8       # 只构建;`--` 后参数透传给 make
tools/a20 show-vars qemu-riscv64-smp4     # 查看实例推导出的 make 变量
tools/a20 check                           # 校验全部实例(CI 门禁同款)
tools/a20 check-registry                  # 校验驱动组件注册表并与 Makefile 交叉比对
tools/a20 check-trim                      # 校验剪裁注册表(components/trim.toml)与生成的 trim.mk
tools/a20 check-flash-backends            # 校验烧录后端注册表并与 makefile 交叉比对

实例参数既可以是 instances/ 下的名字(qemu-riscv64),也可以是任意 TOML 文件路径。--dry-run 打印将执行的 make/QEMU 命令而不执行。

run / debug / test 在启动 guest 前会做宿主资源预检,不足则**等待**而不是硬启动,见下文。

需要 Python ≥ 3.11(只用标准库,无第三方依赖)。

Tab 补全

eval "$(tools/a20 completion)"    # bash;当次会话生效

要长期生效就把这行放进 ~/.bashrc;zsh 先执行 autoload -U +X bashcompinit && bashcompinit 再 eval 同样可用。注册的补全入口是 a20、tools/a20 与 ./tools/a20 三种写法,别的写法(绝对路径、自定义别名)用 complete -F _a20_completions <词> 追加。

补全内容包括:子命令、实例名(instances/*.toml 的 stem,run/build/test 等实例参数位)、每个子命令自己的选项,以及 list --arch / boards --arch / check --require-arch(架构取自实例清单)、list --action、ledger --format 的参数值。候选来自 a20 自身的 argparse 树,新增子命令或选项无需改补全脚本。check 的清单路径位与 -- 之后的 make 参数位不做候选,回退到文件名补全。

实例文件参考

最小实例只有两个字段:

name = "qemu-riscv64"        # 可选;默认取文件名主干
arch = "riscv64"             # 必填

完整示例:

# 下面这份清单把**所有**字段集中在一处便于查阅,但一份实例不可能同时用上全部:
# 被注释掉的行属于互斥组合,另起一份实例即可启用,详见本节末尾的"互斥组合"。
# 直接复制整段可以通过 `a20 check`。
name = "qemu-riscv64-gui"
description = "RISC-V 64 GUI desktop in QEMU with virtio-gpu"
arch = "riscv64"
board = "qemu-virt-riscv64"  # 可选;默认 qemu-virt-<arch>(armv7m 默认 stm32f103)
abi = "both"                 # linux | native | both

[kernel]
profile = "full"             # full | benchmark | mcu(mcu 按 [profile.mcu].arches 或 .boards 选择)
opt = "-O3"
user_opt = "-O3"
bringup = false              # true = 只编译内核,不组文件系统镜像
nommu = false                # 仅 riscv64/riscv32/aarch64/arm32/armv7m
driver_deployment = "generic"  # generic(.a20drv 可加载)| embedded(静态链接)
ubsan = true
swap = false
werror = true
cooperative_boot = false
storage_read_only = false
external_root = false
ramfs_user = false           # 支持范围见 components/trim.toml 的 ramfs-user 矩阵
ramfs_media = false          # 需要 ramfs_user=true;嵌入已有 videoplay/audioplay
ramfs_distro = false         # 需要 ramfs_user=true、rootfs.world;只接管具名 A20OS GPT 发行版分区
virtio_console_profile = "throughput" # 默认;compact 减少队列与缓冲区内存
# virtio_console_rx_slots = 2         # 可单独覆盖预设,必须为 1~16 的 2 次幂
# virtio_console_tx_slots = 2
# virtio_console_buffer_size = 512    # 64~4096 的 2 次幂,单位 B
# virtio_console_ring_size = 512      # 128~65536 的 2 次幂,单位 B

[log]                        # 使用入口见 ../kernel/logging/README.md
enabled = true               # false = 不编译日志核心/写入器/日志环,仅保留最小启动控制台
level = "info"               # debug | info | warn | err
console = true               # 是否镜像到串口/fbcon
persistent = true             # L2 JSONL 写入
mode = "auto"                 # auto | partition | rootfs | ram | esp
partition_mb = 64             # 专用 "A20OS log" GPT 分区大小;0 = 不建
max_bytes = 8388608           # 单次启动 JSONL 上限
session = true                # L3 会话日志(支持的 world)
loader = true                 # L0 UEFI ESP 面包屑(x86_64/aarch64)
boot_report = false          # 是否编译 Boot Report;true 可保留按需读取
report = "off"                # off | error | always,通用屏幕诊断(默认关闭)
report_window_ms = 10000       # 0..120000;观察窗口,不阻塞启动
report_settle_ms = 500         # 0..10000;发现错误后继续收集
report_max_records = 48        # 0..48;0 只显示摘要
report_context = true         # false 仅选择警告和错误
porting_report = false        # 编译启动阶段/驱动检查台账
porting_records = 128         # 16..1024;台账保留容量
metrics = true                # 编译 perf 窗口和锁统计;false 裁掉实现/存储
trace = false                 # 编译事件轨迹;与普通日志独立
trace_records = 128           # 每 CPU 16..1024 条,总事件容量不超过 4096
trace_mask = 63               # boot=1 driver=2 IRQ=4 I/O=8 sched=16 user=32
trace_boot = false            # 时钟就绪后立即采集;需要 trace=true

[machine]
console = "serial"           # cli-x86_64 默认 virtio:带背压的批量 TTY;其余保持 serial
smp = 1                      # >1 仅限已验证 QEMU 平台,否则需 allow_unverified_smp
memory = "1G"                # QEMU -m 参数格式
allow_unverified_smp = false
extra_qemu = ["-device", "riscv-iommu-pci,bus=pcie.0"]  # 追加的 QEMU 参数
gpu_3d = false               # true = 选 virgl-capable virtio-gpu(GPU_3D=1)
display_mode = "text"        # text = -nographic;gui = 真实显示 + GUI 设备集

[gui]
enabled = false              # true = virtio-gpu GUI 启动
display = "gtk"              # QEMU -display
audio_driver = "pa"          # QEMU audiodev 后端
audio_device = "hda"         # hda | virtio

[net]
# 宿主端口转发。不写这一段 = 完全不转发(默认值,见下)
hostfwd = ["tcp::5555-:5555", "udp::5555-:5555"]
# 网卡 MAC。不写 = QEMU 内置默认 52:54:00:12:34:56——单实例没问题,但两个
# 实例共处一条 L2 段(如集群双实例演示)会 ARP 撞车,必须各自显式声明。
mac = "52:54:00:12:34:01"
# 整段 QEMU -netdev 规格,替换默认的 SLIRP user 后端。必须带 id=net(默认
# 网卡固定以 -device ...,netdev=net 挂接)。与 hostfwd 互斥——hostfwd 只
# 存在于被替换掉的 user 后端上,组合会被 a20 check 拒绝。
# 不写 = -netdev user,id=net[,hostfwd...],全部既有实例走这条路。
backend = "socket,id=net,udp=127.0.0.1:44122,localaddr=127.0.0.1:44121"
# guest 侧静态 IPv4,经 -append 以 a20.dhcp=0 / a20.ip / a20.netmask /
# a20.gateway 注入内核(kernel/net/control/net_config.c 解析)。设置 guest_ip 后
# Makefile 自动关 DHCP,netmask/gateway 可选;只在有 QEMU -append 通路的
# 架构上有意义。用法见 docs/zh/cluster/02-udp-demo.md。
guest_ip = "10.0.3.2"
guest_netmask = "255.255.255.0"

[rootfs]
size_mb = 128                # FAT32 根盘大小
ext4_size_mb = 128
# world = "base"               # packages/world/<name>.world 必须存在;设置后走 apk 镜像流程
# world_size_mb = 4096         # world 镜像大小(→ PKG_SIZE_MB),第二个 ext4 槽只能用它定尺寸
# alpine = true                # world 组装是否引入 Alpine 上游仓库(→ PKG_ALPINE)
drivers = ["virtio-net", "hda"]   # 运行时驱动子集,见下文"组件注册表"

[test]                       # 冒烟测试实例(a20 test)
timeout = "20s"              # 默认 20s
input_delay = 8              # 注入命令前等待秒数,默认 8
commands = ["syscall_smoke", "poweroff"]  # 启动后经串口注入的命令
expect = ["SYSCALL_SMOKE: PASS"]          # 日志中必须全部出现的子串
# require_clean_exit = true              # 额外要求在时限内自然退出且 QEMU 状态为 0

# [stm32]                      # 仅 arch = "armv7m":STM32 板级变体
# flash_kb = 512               # → STM32_FLASH_KB
# ram_kb = 64                  # → STM32_RAM_KB
# xuanwu = true                # 普中玄武板(STM32F103ZET6)
# qemu = true                  # 面向 QEMU stm32vldiscovery 的构建(a20 run 可用)
# bt_name = "KasaneTeto"       # 蓝牙参数(格式约束由 Makefile 校验)
# bt_pin = "2233"
# bt_baud = 38400
# wifi_ssid = "..."            # 可选;留空表示不内置 Wi-Fi 配置
# wifi_password = "..."

# [flash]                      # a20 flash:烧录开发板;tool 必须是已注册后端(见下)
# tool = "openocd"              # components/flash-backends.toml 里的后端名
# interface = "interface/cmsis-dap.cfg"
# transport = "swd"
# adapter_khz = 1000
# serial = ""                  # 可选:CMSIS-DAP 探针序列号(多探针时区分)

[package]                    # a20 package:构建后组装发布产物
kind = "release"             # grub-iso | uefi-image | fit-sdcard | release
# variant = "..."              # uefi-image: default|text;fit-sdcard: minimal|sdcard(kind = release 时无意义)
kernel_out = "kernel-rv"     # 仅 release:产物文件名(缺省按架构惯例)
disk_out = "disk.img"        # 仅 release

[target]                    # a20 console / a20 deploy:串口那头的物理板
serial = "/dev/ttyUSB0"      # 必填;控制台设备节点
baud = 115200
reset = "openocd -f interface/cmsis-dap.cfg -c 'init' -c 'reset run'"  # 复位命令(shlex 拆成 argv,不走 shell)
boot_wait = 4               # 复位后等待注入命令的秒数
boot_timeout = "90s"        # 等 console_check / expect 的上限
console_check = ["[FDT] RAM range", "System ready"]   # 内核真的起来了的证据
commands = ["cat /etc/os-release", "poweroff"]        # 注入命令
expect = ["A20OS", "poweroff"]                        # 必须出现的子串
boot_media = ["build/vf2-firmware/a20os-sd.img"]     # 要写进板子的镜像
media_device = "/dev/sda"     # 写到哪里;不写就不写启动介质
log = ".kernel-build/console/board.log"   # 仓库相对路径

字段到 make 变量的映射

实例字段 make 变量
arch / board / abi ARCH / BOARD / ABI
kernel.profile / opt / user_opt PROFILE / OPT / USER_OPT
kernel.bringup / nommu BRINGUP / NOMMU
kernel.driver_deployment DRIVER_DEPLOYMENT
kernel.virtio_console_profile VIRTIO_CONSOLE_PROFILE(throughput / compact)
kernel.virtio_console_rx_slots / virtio_console_tx_slots VIRTIO_CONSOLE_RX_SLOTS / VIRTIO_CONSOLE_TX_SLOTS
kernel.virtio_console_buffer_size / virtio_console_ring_size VIRTIO_CONSOLE_BUFFER_SIZE / VIRTIO_CONSOLE_RING_SIZE
log.enabled / console / persistent / session / loader LOG_ENABLED / LOG_CONSOLE / LOG_PERSISTENT / LOG_SESSION / LOG_LOADER
log.level / mode / partition_mb / max_bytes LOG_LEVEL / LOG_MODE / LOG_PARTITION_MB / LOG_MAX_BYTES

log.level 必须是 debug|info|warn|err,log.mode 必须是auto|partition|rootfs|ram;partition_mb 为 0 表示不建专用分区,max_bytes 限制单次启动的 JSONL 大小。运行期可用内核命令行a20.log.* 覆盖 level/console/persistent/mode/max_bytes。 | kernel.ubsan / werror | CONFIG_UBSAN / KERNEL_WERROR | | kernel.swap | CONFIG_SWAP(y/n) | | kernel.cooperative_boot / storage_read_only / external_root / ramfs_user | COOPERATIVE_BOOT / STORAGE_READ_ONLY / EXTERNAL_ROOT / RAMFS_USER | | kernel.ramfs_media | RAMFS_MEDIA;仅增加现有播放器,不承诺具体板型的显示/音频硬件可用 | | kernel.ramfs_distro | RAMFS_DISTRO;保留内嵌恢复用户态,挂载唯一有效的 A20OS distro GPT Linux 分区,再由现有 init 交给 apk world | | machine.smp / memory / allow_unverified_smp | NR_CPUS / QEMU_MEMORY / ALLOW_UNVERIFIED_SMP | | gui.display / audio_driver / audio_device | QEMU_GUI_DISPLAY / QEMU_GUI_AUDIO_DRIVER / QEMU_GUI_AUDIO_DEVICE | | net.hostfwd | NET_HOSTFWD(逗号连接) | | net.mac / net.backend | NET_MAC(设备 mac=)/ NET_BACKEND(整段 -netdev 规格) | | net.guest_ip / guest_netmask / guest_gateway | NET_GUEST_IP / NET_GUEST_NETMASK / NET_GUEST_GATEWAY(→ -append 的 a20.* bootargs) | | rootfs.size_mb / ext4_size_mb | FAT32_IMAGE_MB / EXT4_IMAGE_MB | | rootfs.world / world_size_mb / alpine | PKG_WORLD / PKG_SIZE_MB / PKG_ALPINE | | rootfs.drivers | DRIVER_SELECTION(自动补 .a20drv 后缀) | | test.timeout / input_delay | SMOKE_TIMEOUT / SMOKE_INPUT_DELAY | | stm32.* | STM32_FLASH_KB / STM32_RAM_KB / STM32_XUANWU / STM32_QEMU / STM32_BT_* / STM32_WIFI_* | | flash.interface / transport / adapter_khz / serial | OpenOCD:STM32_OPENOCD_INTERFACE / STM32_OPENOCD_TRANSPORT / STM32_OPENOCD_ADAPTER_KHZ / STM32_CMSIS_DAP_SERIAL;esptool 的 serial → ESPTOOL_PORT | | target.serial / boot_media / media_device | TARGET_SERIAL / TARGET_BOOT_MEDIA / TARGET_MEDIA_DEVICE |

kernel.virtio_console_* 是驱动构建配置:throughput 默认保持吞吐配置,compact 将当前 x86_64 批量 TTY 的 DMA 分配从 200 KiB 降至 16 KiB。预设、覆盖参数、Make 用法及完整内存预算见 Virtio-console 内存配置。

gui.enabled、test.commands、test.expect、test.require_clean_exit、flash.tool、package.* 由 a20 自己消费,不产生 make 变量;machine.gpu_3d → GPU_3D、machine.display_mode → DISPLAY_MODE、machine.extra_qemu → EXTRA_QEMU。

machine.accel 可显式选择 tcg 或 kvm。使用 accel = "tcg" 时,可设置 tcg_tb_size_mb = 128 固定 TCG 翻译缓存预算(1..4096 MiB),生成单个 -accel tcg,tb-size=128 参数;不设置时保留 QEMU 默认值。该字段只配置宿主模拟器,不改变 guest 内存或内核定时器。重复生命周期的验收实例使用有界缓存,避免缓存整体清理的单次工作量随 QEMU 默认的大缓存增长。

extra_qemu 是 argv 数组,每个元素对应一个参数。例如 extra_qemu = ["-append", "driver.runtime_test=1 driver.amdvi_requester_test=1"] 将整段内核命令行作为一个参数传递。按 TOML 规则写字符串即可,无须额外添加 shell 引号;空格、引号和 $ 均作为参数内容保留,不作为 shell/Make 表达式求值。

[target] 的其余字段(baud、reset、boot_wait、boot_timeout、console_check、commands、expect、log)只供 a20 控制台动作读取,不导出 make 变量。用 a20 show 查看串口、复位、命令与匹配条件,不能从 show-vars 的 make 变量列表推断它们是否配置。接线约束见 实例解析参考。

list 的"可用动作"列不是分类标签,而是逐条镜像对应命令里已经存在的拒绝条件(a20_instance.applicable_actions)。所以它不会承诺一个随后被拒绝的动作:stm32f103 只有 build,因为它的 [stm32] qemu 没设;deploy 在 boot_media 缺 media_device 时不出现,因为 cmd_deploy 会拒绝。加一个命令就要在这里补上它的条件,这正是这一列的用途。

--action 可以给多个,此时取交集(--action console deploy = 同时支持两者的实例)。想看某个动作的全部目标,优先用它,而不是在 45 行里用眼睛找。

各动作的适用条件

动作 说明
build 所有架构;bringup 或 armv7m 实例自动选 kernel-only,设了 rootfs.world 走 image-world,其余 dev-build
run 有通用 QEMU 路径的架构;armv7m 需 [stm32] qemu = true(走 stm32vldiscovery);rootfs.world 实例走 run-world/run-world-gui(world 镜像作第二块盘,distro 模式)
debug 通用 QEMU 架构;-O0 -g + GDB stub
test 通用 QEMU 架构 + [test].expect 必填
flash 需要 [flash].tool 指向已注册后端,且实例的 board 与 flash 几何在后端允许范围内;先构建再烧录
console 需要 [target] 段:接串口、可选复位、等 console_check、注入 commands、断言 expect、落盘 transcript
deploy 需要 [target],并且**有东西可以放到板子上**:要么 boot_media + media_device 配对,要么 [handoff].commands(无块驱动的板走这条路)。有 [flash] 则先烧录,然后写启动介质或准备 handoff;M0Sense 上传 UF2 应用,最后同 console 验证。--auto-handoff 可自动完成支持板型的 U-Boot RAM 装载
prepare 根据板型构建固定版本的启动固件或取得恢复资产。只准备宿主文件,不连接或烧写板卡
package 需要 [package].kind:grub-iso(x86_64,variant vbox(默认)/ rescue-usb)、grub-disk(x86_64 可直接启动的 GRUB 磁盘)、uefi-disk(x86_64 可直接启动的 BOOTX64.EFI 磁盘)、uefi-image(board=virtualbox-aarch64,variant default/text)、fit-sdcard(board=visionfive2,variant minimal/sdcard)、release(riscv64/loongarch64)、kernel-bundle(内核交接目录或 MCU 探针)、board-sdcard(板级完整 SD 镜像,具体固件依赖见平台页)

VisionFive 2 的 SD 卡编排(firmware 预检、extra 分区来源)保留在 tools/mk/targets-build.mk 的 vf2-* 目标里。实例提供经过校验的板卡身份与统一入口,编排逻辑不复制进 Python。使用前先按 platforms/visionfive2-boot.md 跑一次 make vf2-firmware。

校验规则(选摘)

  • smp > 1 只允许在已验证的 QEMU virt 平台(riscv64/aarch64/loongarch64/x86_64),否则必须显式 allow_unverified_smp = true。
  • gui.enabled 与 kernel.bringup 互斥;[test] 与 GUI 互斥。
  • nommu、swap、ramfs_user 有架构白名单(出处是 components/trim.toml 的 capability 矩阵;此前 Makefile 只会在构建期把这些请求静默 force-off,现在 a20 check 直接拒绝);kernel.profile 必须与架构一致——mcu 只用于 MCU 级架构,而 MCU 级架构上的其他 profile 会被 Makefile 强制成 mcu,写错都会在编译前被拒绝。driver_deployment 是取值枚举(generic | embedded)。
  • run/debug/test 仅支持活跃且有对应运行路径的架构;armv7m 走 tools/mk/stm32.mk。LoongArch32/PPC64LE 在当前注册表中会被明确拒绝;归档实例只用于历史追溯。

互斥组合

上面的完整示例为了查阅方便把字段都摆在一起,但一份实例不会同时用上全部。以下组合互斥,校验会在编译前拒绝,所以示例里对应的行是注释掉的:

组合 原因
rootfs.world ↔ [test] world 镜像走 run-world 启动(init chroot 进去),a20 test 这条路径不驱动它
gui.enabled ↔ kernel.bringup bringup 只编译内核,没有根文件系统可显示
[test] ↔ gui.enabled 冒烟判定读串口日志,GUI 实例没有可断言的串口会话
[stm32] ↔ 非 armv7m 架构 STM32 段只对 arch = "armv7m" 有意义
[flash] ↔ 非 STM32 板 tool = "openocd" 这个后端只覆盖 stm32f103 系列板
package.variant ↔ package.kind = "release" release 按架构约定命名产物,没有 variant 概念

a20 show:选命令之前先看这一屏

show-vars 回答"make 会看到什么";show 回答"我能不能跑、要花多少、会碰到什么"。在 45 个实例里挑一个时先问的就是这三个问题:

$ tools/a20 show vf2-physical
vf2-physical  [riscv64]  VisionFive 2 with a physical serial target for a20 console/deploy
  actions     build, run, debug, package, console, deploy
  board       visionfive2
  needs       mem 2048 MiB, 1 vCPU, disk 2048 MiB
  host ports  none (nothing to connect to)
  console     /dev/ttyUSB0 at 115200 baud
  boot media  build/vf2-firmware/a20os-sd.img -> /dev/sda
  expects     A20OS, SMC: System ready, poweroff
  manifest    .../instances/vf2-physical.toml

needs 走的是启动前门控用的同一个 requirement_for,所以这里看到的数字就是真跑起来时被检查的数字;actions 与 list 的能力列同源。boot media 指向 (unset!) 表示 manifest 写了 boot_media 却没给 media_device,deploy 会被拒绝。

退出码

脚本和 CI 会按退出码分支,所以它是契约而不是实现细节:

码 含义
0 成功
1 a20 拒绝执行,或实例没通过自己声明的检查
2 命令行用法错误
3 被委派的工具失败(make / QEMU / OpenOCD / 辅助脚本)
124 超时

被委派工具的退出码**不会**原样透传:make 对"目标不存在"返回 2,若原样透传,它就与 a20 自己的用法错误撞在一起,无法区分。

诊断信息一律走 stderr,报告本身走 stdout。于是 a20 check > 清单.txt 拿到的是通过清单,失败在 2>错误.txt,CI 里可以分开处理。

物理目标与上板验证([target])

板级支持范围、默认实例和部署方法由 docs/zh/platforms/ 中对应的单平台页面说明;文档范围见 平台文档约定。console / deploy 支持 --serial DEVICE 覆盖串口;deploy 支持--media-device DEVICE 覆盖目的盘、--no-console 将介质准备与上板验证分开、--no-build 复用已构建产物(带烧录后端时还需 --no-flash)。deploy ls2k0300 --stage-mount DIRECTORY --no-console 将校验后的 ELF 放到显式指定的已挂载 FAT 卷;deploy m0sense-bl702-probe --uf2-mount DIRECTORY --no-console 上传原厂 UF2 应用,未指定卷时自动识别。--interactive 在同一串口连接转发人工输入,供操作 U-Boot,同时记录日志并检查启动断言; Ctrl-] 退出,等待仍受 target.boot_timeout 限制,不能与 --no-console 合用。

其余所有段描述的要么是构建,要么是 QEMU 里的 guest。[target] 描述的是串口线那头那块板:控制台在哪、怎么让它重启、它的启动日志必须出现什么才算真的起来。这个段存在,就意味着这是一个物理目标;所以没有 kind 字段可以跟它自相矛盾。

tools/a20 console vf2-physical    # 只接串口做上板检查
tools/a20 deploy  vf2-physical    # 烧录 + 写启动介质 + 上板验证

deploy 的每一步都对应一个既有机制,而不是新写一套:烧录走「烧录后端注册表」一节,写启动介质走 make 的 target-write-media,最后一步与 console 完全相同。

console 的执行顺序是:复位(可选)→ 等 console_check → 等 boot_wait → 注入 commands → 等 expect。每一处等待都有上限:板子没起来、或者起来了但不回话,会在一个具名的阶段上结束,而不是把终端挂住。

串口前提

tools/a20 console / deploy 只需 Python 标准库,无需安装 pyserial。串口设备必须可访问,所选波特率必须受宿主平台支持;不支持时命令会报告可用波特率。串口传输与平台编码的实现说明见 串口技术参考。

安全边界

  • reset 按命令参数执行,不经 shell;清单中不能使用管道或 ; 连接多条命令。
  • target-write-media 在 dd 之前检查块设备、整盘及子分区的挂载/交换使用状态与容量;lsblk 检查失败即停止。只接受一份完整镜像,避免多份镜像连续从偏移零写入互相覆盖。目的盘身份仍须人工核对,工具不会判断哪支盘是你想写的盘。
  • target.log 必须是仓库相对路径,否则控制台日志会带上某一台机器的绝对路径,正是「产物账本」一节要消灭的那类东西。
  • 设了 commands 就必须设 expect:没有断言的上板检查只可能空洞通过。

固件装载内核与自动交接([handoff])

没有内核块驱动时,仍可由固件通过 SD FAT、USB 或网络载入内核;A20OS 启动后的块设备能力需另行验证。board-sdcard 生成板级 SD 镜像;固件、DTB 和启动脚本的组成由平台打包器决定。其中 board=quartz64-zero 可选择 package.variant="video":prepare 与 package 共同使用独立的 firmware-video,manifest 也记录该固件来源。其他板型不接受此 variant。quartz64-zero-media 已提供该配置;其显示前提和音频限制见对应 platform 文档。prepare 取得固件依赖,package 生成可写介质。完整操作由对应单平台页面说明。

tools/a20 prepare pine-a64
tools/a20 package pine-a64
tools/a20 deploy pine-a64 --no-build --no-console --media-device /dev/disk/by-id/实际读卡器
# 移卡到目标板,先连接串口,再上电;卡内脚本自动启动。
tools/a20 console pine-a64 --serial /dev/serial/by-id/实际串口

kernel-bundle 只生成交接目录。通用 Image 包含 kernel.bin、kernel.elf、uboot.cmd、manifest.json 与操作说明;LS2K0300 使用核对过的 ELF 和独立装载器,M0Sense 使用独立 RV32 M-mode UF2 探针。打包器从 ELF PT_LOAD 读取地址范围;Image 包核对镜像头覆盖含 BSS 的内存占用。 Lichee Pi Zero 使用 ARM32 uImage/bootm,分别检查载荷暂存区和实际内核装载区,不将 bootm 暂存地址当作 ELF 入口。[handoff].commands 描述载入命令;包内 uboot.cmd 包含核对后的实际地址。

SD 实例默认通过卡内配置启动。支持 --auto-handoff 的平台可从正在运行的 U-Boot 重新载入:

tools/a20 console pine-a64 --auto-handoff --serial /dev/serial/by-id/实际串口
# LS2K0300 的 FAT USB 路径:先在宿主暂存,再移到板子。
tools/a20 deploy ls2k0300 --stage-mount /media/用户名/实际FAT卷 --no-console
tools/a20 console ls2k0300 --auto-handoff --transfer usb --serial /dev/serial/by-id/实际串口

--auto-handoff 独占同一串口,停止倒计时,逐条验证装载回应、传输长度与 CRC,再执行启动并检查内核标记。Image/uImage 交接还核对实例与包的身份、DTB 与内核/BSS 分离; LS2K0300 依据完整 DDR/LMB 信息选择 ELF 暂存地址。自动路径不写固件、不执行 saveenv;不支持的固件命令、缺少文件或校验失败会停止。[handoff].prompt_timeout、command_timeout 可设正的时间值(如 30s);内核等待使用 [target] 的超时。

较老固件可用 --interactive 在同一窗口人工粘贴包内命令;不能与 --auto-handoff 合用。--no-console 只准备产物,稍后先连接串口再上电。DTB 必须匹配板型并位于独立 RAM; Nano TFTP 路径会先复制固件控制 DTB,避免直接使用固件 malloc 区的地址。 M0Sense 仅 USB 时加 --no-console,依据蓝灯心跳人工确认;有外部 UART 时部署器先监听,再上传 UF2,捕获 loader 重启后的首次探针标记。USB 复制成功本身不算内核验收。

边角但必要的开关

这些开关平时用不上,但缺了会卡住某类具体场景。

--dry-run:什么都不碰

prepare / run / debug / test / console / deploy / flash / package 都接受 --dry-run。它的含义是**一个字节都不写出去**:不构建、不启动 QEMU、不开串口、不烧录、不写启动介质,只打印将要执行的命令。

tools/a20 console vf2-physical --dry-run   # 只打印,不会往在线板子注入命令

这一点对 console / deploy 尤其重要:它们默认会**真的**往串口那头的板子写命令。所以这两个命令的 --dry-run 必须在任何字节离开进程之前就返回。

资源等待的开关

tools/a20 run qemu-riscv64 --no-wait              # 资源不足立刻失败(CI 用)
tools/a20 run qemu-riscv64 --wait-timeout 120     # 最多等 120 秒

--no-wait 适合 CI:排队等资源会让 job 挂到超时,而 CI 想要的恰恰是"立刻说清楚缺什么,然后失败"。

上板:分开"烧"和"复位"

tools/a20 deploy vf2-physical --no-flash   # 不烧 flash,只写介质 + 上板验证
tools/a20 console vf2-physical --no-reset  # 不复位,直接接当前已启动的板子

--no-flash 让你在只改了根文件系统、没动内核时省掉一次烧录。--no-reset 让你在已经手动起好的板子上做验证,不去碰别人的启动状态。

a20 check --require-arch

默认校验 instances/ 下的全部实例。改动只影响部分架构时,用它缩小范围:

tools/a20 check --require-arch riscv64 aarch64

a20 regen-drivers

components/drivers.toml 是驱动注册表的手工来源,components/drivers.mk 是它的生成物。改了 TOML 必须重新生成,否则 make check-component-registry 报 stale。

tools/a20 regen-drivers --dry-run   # 只说会不会改,不写
tools/a20 regen-drivers             # 写

同一实例不会被并发跑两遍

同一实例已有 a20 test 运行时,再次启动会在构建前失败。并发保护的实现契约见 工具技术参考。

获取锁失败时报 InstanceBusy(退出码 1)并指出锁在哪,而不是静默排队等一个自己不知道存在的进程。

诊断输出只给尾部

会话失败时打印日志的**最后 80 行**而不是全文。一次 console 的日志轻易上万行,而有用信息通常在末尾:panic、assert、启动失败原因都在那里。

查看 QEMU 命令行

需要检查实际启动参数时,使用与目标实例相同的构建变量运行 make _qemu_argv:

make ARCH=riscv64 BOARD=qemu-virt-riscv64 ABI=both BRINGUP=0 _qemu_argv

该命令只查询、不构建。不要加 -n,否则得到的是打印命令而不是 QEMU 参数。参数生成与执行的分工见 工具技术参考。

产物账本(a20 ledger)

tools/a20 ledger <instance> 报告这个实例**实际**产出了什么:build 目录、源码版本(head + 分支 + dirty)、实例解析出的 make 变量,以及每个产物的 size 与 sha256。

$ tools/a20 ledger qemu-riscv64
instance : qemu-riscv64
arch     : riscv64   board: qemu-virt-riscv64   abi: both
build    : .kernel-build/riscv64-qemu-virt-riscv64-both-dev
git      : 47192790cb81 on embedded/instance-manager

role                   size  sha256                                                           path
kernel-elf          4.0 MiB  9c52b54a0b45bbe0ef58d71def3315be1e598e8c315900e8e08113600ae393e9  .kernel-build/.../kernel.elf
rootfs-fat32      128.0 MiB  c14b40170fc1a9dceaafafd84fa10b5c8dac1011e8f1b412d1f9f37cc162b127  .kernel-build/.../fat32.img
rootfs-ext4       128.0 MiB  2c0c24e196957a8c682026c7cd4eb5f2324efb483b57407c5216c044bc8e32a9  .kernel-build/.../ext4.img

带 world 的实例多报一行 world 镜像,未构建的产物照样显式列出:

$ tools/a20 ledger xfce-riscv64
role                   size  sha256                                                           path
world-xfce          4.0 GiB  a7beeb021edc4fcced047a515751aec27f0e20c6adc45f7e25f07817ee0d1f63  build/images/xfce-riscv64.img

not built yet:
  .kernel-build/.../kernel.elf
  .kernel-build/.../fat32.img

三种格式:--format table(人读,默认)、json(机器读)、markdown(可直接贴进平台文档的表格块);--out FILE 写文件。路径一律仓库相对:正是绝对路径让旧的板级验收记录不可移植。未构建的产物显式列出,退出码非 0,不假装齐全。

账本直接计算当前产物的大小和 SHA-256;更换配置或重新构建后应重新生成,不在平台文档中维护手抄的镜像摘要。

产物路径向 make 查询而不是在 Python 里重算 BUILD_DIR:那个名字把 ARCH、BOARD、ABI、BRINGUP、NOMMU、SMP 数、驱动部署等十几个开关都编码了进去。

宿主端口转发

默认不做任何端口转发。宿主端口是一种会被争用的共享资源,而此前 NET_HOSTFWD 默认 hostfwd=tcp/udp::5555-:5555,于是**每一次** QEMU 启动都会占用宿主 5555,包括那几十个只用串口、从不接受入站连接的冒烟门禁。结果是任何时刻只能跑一个实例,落败的那个以 QEMU 的一句 "could not set up host forwarding rule" 收场,指向端口而不是指向真正的争用。

现在转发由实例显式声明:

[net]
hostfwd = ["tcp::5555-:5555"]   # 固定端口
hostfwd = ["tcp::0-:8080"]     # 端口 0 = 由系统分配
hostfwd = []                    # 显式不要转发(等价于不写)

a20 run / debug / test 在启动前会打印本实例占用的端口,所以"连哪个端口"是实例的属性、看得见的,而不是靠猜。

为什么默认不是随机端口

QEMU 确实接受 hostfwd=tcp::0-... 并正常启动,但它**不会在任何输出里报告自己拿到了哪个端口**。随机端口因此意味着"你无从知道该连哪里",除非 a20 额外拉一条 QMP 控制通道去查询,而那意味着为一个更差的可用性付出真实的复杂度。固定端口可写进文档、可被脚本引用、每次都一样。

多实例并行的正确做法是**声明不同的端口**(可被 review),而不是让端口变成不可复现的随机数。

端口也是一项会被等待的资源

声明的端口在启动前检查是否可用。端口被占用时,默认等待释放;--no-wait 使检查立即失败,--wait-timeout 限制等待时长。端口探测机制见 工具技术参考。

tools/a20 ports                    # 谁占了哪些端口、现在空不空、跨实例是否冲突
tools/a20 ports qemu-riscv64       # 只看一个
tools/a20 run qemu-riscv64         # 启动前打印本实例的端口

a20 ports 会把跨实例的端口冲突作为提示列出(不判失败:如果你从不让它们同时跑,共用一个端口是完全合理的选择),并给出改用端口 0 的建议。

[net].backend 声明的端口同样纳入预检:listen=addr:port 按 TCP、localaddr=addr:port 按 UDP 各自实测 bind 探测(协议探错会把"UDP 端口与某个 TCP 监听者同号"误判为冲突,永远等下去);connect= 是客户端,不占宿主端口。

宿主资源预检

run / debug / test 是 a20 唯一几种失败方式不是非零退出码、而是"把宿主机搞死"的动作:QEMU 在可用内存不足时申请 4 GiB,结果由 OOM killer 决定谁死,而被杀的通常不是你在调试的那个进程。所以这三个动作在启动 guest 前先做预检,资源不足时等待到释放,而不是硬上。

tools/a20 resources 打印当前预算:

memory available : 25672 MiB (+1024 MiB reserved per run)
cpu              : 16 online, load 5.3
guest slots      : 4 free of 4 (0 running)
disk free        : 42944 MiB (floor 2048 MiB per run)
wait timeout     : forever

需求从实例自身字段推导:guest 内存取 machine.memory(缺省 1G,与 Makefile 的 QEMU_MEMORY 一致),vCPU 取 machine.smp,磁盘取 [rootfs] 声明的各镜像大小之和。

两个测量点容易做错,代码里都标了原因:

  • 可用内存必须取 MemAvailable,不能取 free。free 不算可回收的 page cache,所以在一台其实很空闲的机器上它常常只有几百 MiB(本机就是 365 MiB,而 MemAvailable 是 25 GiB)。用 free 的门禁会永远等下去。
  • 空闲的 vCPU 不出现在 load average 里。所以 load 单独无法判断"另一个 guest 是否已经占住了这台机器想要的 CPU",并发数因此单独统计(扫 /proc 数 qemu-system-*,不用 pgrep)。

不足时等待,而不是失败

资源不足默认**等待到释放**,不是报错退出。这是有意的选择:一个把 8 个 guest 排着队跑 CI 的工程师,遇到"第 9 个暂时没内存"时想要的不是一条红字,而是"等第 7 个跑完"。默认等待上限因此是 0(无限)。

等待期间必须能回答三个问题,所以每次播报都带齐:

  • 缺什么(哪一项资源不足)
  • 为什么不足(当前的实测值 vs 需要值)
  • 怎么解除(可执行的 remedy,例如关掉哪个进程、释放哪个实例)
a20: waiting to run qemu-riscv64 -- host resources are short
      have/want: mem 10000000 MiB, 1 vCPU, disk 0 MiB
      blocked:   memory: need 10000000 MiB, available 12859 MiB
      to proceed: free memory (stop a guest or a build) and retry
      press Ctrl-C to give up

只在**缺项集合**变化时播报新增项,另有 30 秒心跳,因此一次等待十分钟不会刷出六百行。解除后立刻继续,不要求重新敲命令。

--no-wait 改为立即失败,--wait-timeout SEC 限定等待时长。预算可用环境变量覆盖,CI 机器余量不同不必改代码:

变量 默认 含义
A20_RESERVE_MEM_MB 1024 每次运行额外预留(覆盖构建本身与宿主自身)
A20_MAX_CONCURRENT CPU 数 / 4 同时允许的 guest 数
A20_WAIT_TIMEOUT 0(无限) 等待上限秒数
A20_MIN_DISK_MB 2048 磁盘需求的下限

等待期间只在缺项种类变化时播报,另有 30 秒心跳,因此长时间等待不会每 5 秒刷一行。

冒烟测试实例

带 [test] 段的实例就是一个冒烟测试。a20 test 先构建并启动该实例,等待 input_delay 秒后经串口注入 commands,在 timeout 内等待退出或终止超时会话。bringup = true 只构建内核,其他实例构建开发镜像;额外的 QEMU 参数由 machine.extra_qemu 声明。参数生成契约见 工具技术参考。

默认保留旧的标记判定:日志中 expect 的全部子串都出现即 PASS,超时杀掉但日志已齐也算 PASS。需要验证完整启动和关机的实例应设置 [test].require_clean_exit = true,此时还要求 QEMU 在时限内自然退出且状态为 0,打印标记后卡死或异常退出均失败。smoke-quickstart 使用此严格模式。失败打印日志末尾 80 行;日志保存在.kernel-build/smoke/<实例名>.log。

把旧冒烟迁移成实例只需三步:

  1. 把 $(MAKE) ARCH=... ABI=... BRINGUP=... 一行翻译成实例的顶层/[kernel] 字段;
  2. 把 printf 注入的命令写进 test.commands,把 grep -q 的模式写进 test.expect(注意:expect 是**子串**匹配,不是正则),超时差异写进 test.timeout;
  3. 额外的 -device 参数写进 machine.extra_qemu(QEMU 参数顺序无关);然后把 make 目标改成一行包装:smoke-foo: ; tools/a20 test smoke-foo。

已迁移的参考样例:instances/smoke-riscv64.toml(纯 expect)、instances/smoke-abi-linux.toml(commands + expect)、instances/smoke-iommu-discovery.toml(extra_qemu)、instances/smoke-gpu3d-riscv64.toml(gpu_3d + display_mode = "gui":文本模式不挂 virtio-gpu,做 GPU 门禁必须切到 gui)。

组件注册表(components/drivers.toml)

可加载驱动(.a20drv 包)的单一事实来源。每个条目:

[[driver]]
name = "virtio-net"          # 包名 = <name>.a20drv
source = "kernel/drvmod/examples/virtio_net.c"  # 必须存在的源文件
arches = ["riscv64", "x86_64", "aarch64", "loongarch64"]
early_arches = ["riscv64"]   # 可选:嵌入内核 root ramfs 的架构(启动盘驱动)
description = "virtio network device"

实例用 [rootfs].drivers 按名字选择进入 /lib/drivers 的运行时驱动子集;a20 在编译前校验:名字必须存在、必须支持实例架构、不能是该架构的 early 驱动(early 驱动始终嵌入内核镜像,无需也不能再选)。选定后通过 DRIVER_SELECTION 传给 make;不写该字段则按 tools/mk/driver-modules.mk 的默认全集打包。

make check-component-registry(= tools/a20 check-registry)校验两件事:注册表自身(重名、未知架构、early ⊆ arches、early 必须配 generic 部署、源文件存在),以及生成物 components/drivers.mk 是否与 components/drivers.toml 一致。改完 TOML 要跑 tools/a20 regen-drivers(make regen-driver-fragment)重新生成,否则这一门禁会报 stale。

烧录后端注册表(components/flash-backends.toml)

a20 flash 用哪个烧录器由这里决定,而不是写在 Python 里:

[[backend]]
name = "openocd"
description = "OpenOCD over CMSIS-DAP/SWD with STM32F1x target scripts"
boards = ["stm32f103"]      # 允许的 board
flash_kb = 512              # 该配方所针对的 flash 几何
ram_kb = 64
make_target = "flash-xuanwu-openocd"   # 配方住在 make 里,不在 Python 里

boards + flash_kb/ram_kb 是**安全契约,不是说明文档**:实例的 board 或 flash 几何落在允许范围外时,a20 check 就直接拒绝,编译根本不会开始。用错几何去擦除不是编译错误那种可回退的失误。一段 512 KiB 的擦除脚本打到 64 KiB 的片子上,会从片子末尾跑出去。

几何必须进 key,因为一个 board 名会承载多种 flash 尺寸:board = "stm32f103" 既指 64 KiB 的 C8,也指 512 KiB 的 ZET6("xuanwu")变体,由 [stm32].xuanwu 区分。只按 board 判断会让 64 KiB 的实例和 512 KiB 的实例走同一道门,而这正是这个注册表要防的那个 bug。

新增烧录方式只需两步,Python 不用改:加一条 [[backend]],再写对应的 make 目标。

make check-flash-backend-registry(= tools/a20 check-flash-backends)同样两层:注册表自身(重名、board 必须真有 kernel/arch/<arch>/boards/<board>/board.c、make_target 必须是 makefile 里真实存在的规则),以及每个 make_target 必须在 a20 实际能派发的目标集合里;两边任何一边漂移都会 FAIL,而不是等到烧录烧到一半才发现。

剪裁注册表(components/trim.toml)

内核剪裁的**策略**数据来源:每个构建 profile 策展的源码清单、每个可选能力的架构矩阵、每个架构的固定特性宏。这三个清单过去同时活在 Makefile 和 a20_instance.py 里,靠手工保持一致;现在只有这一份:

[profile.mcu]                # MCU 级构建 profile
arches = ["armv7m"]          # 整架构强制选择
boards = ["riscv32/esp32-c3", "riscv32/qemu-virt-riscv32-mcu"] # 仅这些板选择 MCU;其他 RV32 保持完整档位
opt = "-Os"
cppflags = ["-DCONFIG_MCU", "-DCONFIG_KLOG_BUF_SIZE=256"]
nommu = true                 # profile 隐含 NOMMU=1
bringup = true               # ……以及 BRINGUP=1(kernel-only)
sources = [ "kernel/arch/armv7m/boards/stm32f103/mcu_main.c", "kernel/core/panic.c", … ]  # 策展源码白名单

[capability.swap]            # 能力矩阵:架构白名单 + 可选 board 排除
arches = ["riscv64", "loongarch64", "aarch64", "x86_64", "arm32"]

[arch-cppflags]              # 每架构无条件 -D 特性宏
x86_64 = ["-DCONFIG_IOPORT", "-DCONFIG_AHCI", "-DCONFIG_PCI_MMIO_BASE_LEGACY"]

消费路径有两条:Makefile 读 make regen-trim-fragment 生成的 components/trim.mk(NOMMU_SUPPORTED_ARCHES、SWAP_SUPPORTED_ARCHES 等矩阵与 mcu 源码列表都出自它),tools/a20 校验实例时直接读 TOML——同一份数据喂两边,实例校验和构建不可能各说各话。make check-trim-registry(= tools/a20 check-trim)做三件事:注册表自身自洽(必备条目存在、源码文件真实存在、board 排除项真实存在)、生成的 fragment 没有过期、每个发射的变量都有 makefile 在读(没有消费者的策略条目是死配置)。

想知道一个实例按什么剪裁计划构建,用 tools/a20 trim <实例>:profile 是谁、哪些能力开/关/被 force-off 及其理由、flash/RAM 预算从哪来。a20 show 也带一行摘要。策略的**逻辑**(force-off 顺序、$(error))仍在 Makefile;这份文件只搬走了**数据**。板级事实(引脚、时钟)继续留在 kernel/arch/<arch>/boards/<board>/,链接兼容桩(kernel/mcu/mcu_stubs.c)是代码,都不属于这里。

CI 门禁

目标 作用
make check-manifests 下面四个门禁的聚合入口(CI 的 toolchain-gates job 调它)
make check-instances 校验 instances/ 全部实例(schema + 语义 + 驱动选择)
make check-instance-matrix 校验每个 SUPPORTED_HOSTED_ARCHES 成员至少有一个有效实例,矩阵与实例目录不漂移
make check-component-registry 校验驱动注册表并与 Makefile 构建清单交叉比对
make check-flash-backend-registry 校验烧录后端注册表,并交叉比对每个 make_target 在 makefile 中存在、且 a20 确实能派发到它
make check-a20-tests a20 工具自身的单元测试(stdlib unittest,见 tools/tests/test_a20.py)

宿主侧门禁(不启动 guest)

这几条不是 make 目标,但同样是"不能失败的检查不构成验证"这条规则的执行者。用法与边界见 graphics/host-tools.md。

脚本 作用 需要 root
tools/check-drm-abi.sh 每个 DRM ioctl 号与结构体布局对 Linux UAPI 逐条比对,漂移时 exit 1 否
tools/build-virglrenderer.sh check 报告宿主 QEMU、两版 virglrenderer、/dev/dri/renderD128 是否真的可访问 否
tools/build-virglrenderer.sh build 构建宿主 virglrenderer ≥ 0.11 到 tools/virgl/install(Makefile 自动拾取) 是
tools/cli/a20_resource.py 不直接调用:tools/a20 run/debug/test 在启动前采样宿主 RAM/负载/磁盘,放不下就**等待**(A20_PREFLIGHT=0 跳过)。tools/a20 check 会校验它与 Makefile 默认值的副本未漂移。原 a20_preflight.py 已合并进本文件 否

build/package/flash 不启动 guest,因此不受 preflight 约束。

apk world 镜像实例(用包管理组装用户态)

物理 PC 可复用相同 world:package.kind="uefi-disk"、package.variant="world"将原生 EFI 启动器与 ext4 world 封装到同一 GPT 盘,要求kernel.ramfs_user=true、kernel.ramfs_distro=true 和 rootfs.world。该路径保留 RAM 恢复环境,只自动挂载唯一有效的 A20OS distro Linux-data 分区,不依赖 QEMU 的第二块裸 ext4 盘。build 构建内核与 world,package 生成完整介质;具体硬件、写盘和验收步骤见 华为 CT5100。

与宿主 Linux 做性能对比可用 benchmark-x86_64:其 benchmark world 通过 apk 安装 sysbench、stress-ng 和 OpenSSL。相同二进制的 KVM / Linux 对照运行方法与基线测量协议参见 instances/benchmark-x86_64.toml。

[rootfs].world 设置后,实例的构建与启动切换到 apk 流程(详见 packaging/overview.md):build 等价于 make image-world(打包 → 建本地仓库 → 按 world 清单组镜像),run 等价于 run-world / run-world-gui,world 镜像作为第二块盘挂载,含 /usr/lib/a20/init 标记的镜像会被 init chroot 接管(distro 模式)。

例如用 apk 安装完整 XFCE 桌面的实例(instances/xfce-riscv64.toml):

name = "xfce-riscv64"
arch = "riscv64"

[machine]
memory = "2G"

[gui]
enabled = true

[rootfs]
world = "xfce"        # packages/world/xfce.world:labwc + xfce4-* + 字体 + 输入法……
world_size_mb = 4096

tools/a20 run xfce-riscv64 一条命令完成组镜像与 GUI 启动。首次组装需从 Alpine 镜像站拉取上游包(之后走 build/cache/apk 缓存);alpine = false 可做纯本地仓库组合。x86_64 变体 xfce-x86_64 使用同一个 xfce world(Wayland/labwc),并在带 /dev/kvm 的宿主机上自动启用 KVM 加速。注意 world 与 bringup、[test] 互斥,且仅支持 hosted 架构。

run 会完成内核、软件包和 world 镜像构建,无需预先执行 tools/a20 build。每次运行都会重新生成 world 镜像,前一轮写入的数据不会保留。world 镜像为无日志 ext4,QEMU 被终止后呈脏状态属于预期;此类实例不做启动前 fsck。维护镜像接线时见 工具技术参考。

纯命令行(无 [gui])的同类实例见 instances/cli-<arch>.toml:world 为 cli(Alpine 上游 zsh + GNU coreutils/findutils/grep/sed/gawk + git/vim/tmux/htop/curl/python3),overlay 的 stage-2 init 直接把串口交给 zsh,是 QEMU 上的日常命令行环境。注意 server world 并不是同一回事——它是刻意的"最小服务器形态"(busybox ash + dropbear + chrony),不以交互体验为目标。

与旧 make 目标的对照

旧的逐架构目标全部保留为薄包装,行为不变:

旧命令 等价的新命令
make run-riscv64 tools/a20 run qemu-riscv64
make run-riscv64 BRINGUP=1 tools/a20 run qemu-riscv64-bringup
make run-nommu-riscv64 tools/a20 run qemu-riscv64-nommu
make debug-arm64 tools/a20 debug qemu-aarch64
make smoke-riscv64 tools/a20 test smoke-riscv64
make stm32f103-bringup / stm32f103-xuanwu tools/a20 build stm32f103 / stm32f103-xuanwu
make run-stm32f103-qemu tools/a20 run stm32f103-qemu
make flash-stm32f103-xuanwu tools/a20 flash stm32f103-xuanwu
make vbox-iso-x86_64 tools/a20 package vbox-iso-x86_64
make x86_64-uefi-disk / pc-rescue-disk tools/a20 package vbox-x86_64 / vbox-disk-x86_64
make vbox-image-aarch64 / vbox-text-image-aarch64 tools/a20 package vbox-aarch64 / vbox-aarch64-text
make vf2-minimal / vf2-sdcard tools/a20 package vf2-minimal / vf2-sdcard
make release-rv / release-la tools/a20 package release-riscv64 / release-loongarch64

注意:薄包装**不转发**命令行变量覆盖(如 make run-riscv64 QEMU_MEMORY=2G)。需要临时覆盖时,要么改实例文件,要么用通用的 make ARCH=... run(该变量驱动入口仍然保留)。

新增一个实例

  1. 在 instances/ 新建 <名字>.toml,必填只有 arch;
  2. 跑 tools/a20 check <名字> 通过校验;
  3. 用 tools/a20 show-vars <名字> 确认推导出的变量符合预期,用 tools/a20 trim <名字> 确认剪裁计划(profile、能力开关、内存预算)符合预期;
  4. tools/a20 run <名字> 实际启动验证。

如果新实例覆盖了一个此前没有的架构,记得 make check-instance-matrix 会随之更新覆盖关系;新增驱动组件时同步更新 components/drivers.toml 并跑 make check-component-registry。要为实例开启/关闭某项能力而架构矩阵不允许时,改的是 components/trim.toml 的 capability 条目(并重新生成 fragment),不是实例或 Makefile。

移植检查、可裁剪的性能/锁统计、事件轨迹及 tools/a20 diagnose/compare-evidence 见 设备测试与性能分析。