应用请求进入 Recovery 模式

这个 sample 演示的重点不是“单独构建 boot”，而是“应用如何进入 boot 的 recovery mode”：

应用正常启动
应用调用 uboot_recovery_request(UBOOT_RECOVERY_MODE_SOFT)
应用调用系统侧 sys_reboot(SYS_REBOOT_SOFT)
boot_s 识别 soft req
boot_s 进入 recovery mode

为了让 recovery 进入结果有一个可直接观察、可重复验证的出口，本样例当前让 boot recovery 同时打开了 ADB shell、ADB sync 和 RAW 访问能力。也就是说， BOOT_ADB 是这个 sample 的验证手段，不是这个 sample 想表达的主题。

如果你要的是“纯 boot 工程，只编 recovery boot”，请改用 samples/subsys/uboot/recovery_basic。本样例是 app sample，用来展示 app 侧如何请求进入 boot recovery mode。

本样例不依赖 OTA，也不会生成或烧录 partab.bin、ota.tar、ota.txz 或 easyflash_reset.bin。

关键配置

本样例通过 public boot 开关请求 recovery-only 能力：

CONFIG_BOOT_ADB=y
CONFIG_BOOT_ADB_SHELL=y
CONFIG_BOOT_ADB_SYNC=y

src/shell_cfg_user.h 是 sample 本地的 letter-shell overlay，供 boot recovery shell 复用。

构建

./build.sh -C -S samples/subsys/uboot/app_enter_boot_recovery -DBOARD=arcs_evb

构建完成后只需要关注：

build/arcs.bin：主固件，烧录到 0x0

手动烧录

guardian 会按照 sample.yaml 里的 images 顺序烧录。

如果手工使用 cskburn，只需要烧主 bin：

./tools/burn/cskburn -C arcs -s /dev/ttyACM0 -b 3000000 --erase-all
./tools/burn/cskburn -C arcs -s /dev/ttyACM0 -b 3000000 --verify-all \
    0x0 build/arcs.bin

预期日志

应用阶段会打印：

APP enter boot recovery sample running
APP requested boot recovery mode, rebooting

进入 recovery 后会打印：

boot reason: soft req
boot adb: start reason=soft req

正常应用阶段 adb devices 必须保持为空；只有进入 recovery 后才允许枚举 ADB 设备。

BOOT_ADB recovery bench

仓库内可重复执行的 bench 入口：

bash samples/subsys/uboot/app_enter_boot_recovery/verify_boot_adb_shell.sh --board arcs_evb

如果只想先检查 host 侧合同、build truth 和 marker 文档是否一致，而不触发 build、burn 或板级动作，可执行：

bash samples/subsys/uboot/app_enter_boot_recovery/verify_boot_adb_shell.sh --preflight-only

--preflight-only 只做前置合同检查，不触发 build、burn 或板级动作；但仍会把 preflight.txt、recovery_contract.txt、adb_devices_baseline.txt 等诊断证据持久化到 .cache/boot_adb_shell_bench/latest/。

脚本会把最近一次执行的证据持久化到 .cache/boot_adb_shell_bench/latest/，重点看这些文件：

context.txt / preflight.txt：worktree 路径、解析出的 build_arcs_base、 boot cache、串口/工具前置条件
recovery_contract.txt：src/main.c、verify_boot_adb_shell.sh 与 README 的 app-to-boot recovery 合同检查结果
build_truth.txt：build/boot/app.config、build/boot/.config 与 build/boot/CMakeCache.txt 的 truth check 结果
serial_normal.txt / serial_recovery_wait.txt / serial_recovery.txt：应用阶段、等待 recovery 枚举期间、以及 recovery 后的串口日志
adb_devices_baseline.txt / adb_devices_normal.txt / adb_devices_recovery.txt：baseline、应用阶段、recovery 枚举结果
adb_push_file.txt / adb_pull_file.txt / adb_push_sync.txt / adb_push_sync_stale.txt：相对文件路径 push/pull 与相对路径 adb push --sync 证据（仅覆盖默认根 /SD:/adb/）
adb_push_raw_sdraw.txt / adb_pull_raw_sdraw.txt： /RAW/SDRAW/0/1000 的 push/pull 闭环证据
adb_unlock.txt / adb_status_after_unlock.txt / adb_push_raw_flash_fastpath.txt / adb_push_raw_nand_fastpath.txt： /RAW/FLASH/40000/10000 与 /RAW/NAND/40000/10000 的对齐 fast-path push 证据
result.txt：完整跑通时生成的通过项摘要

实板执行流程

运行 bench；脚本会先做 preflight，再调用：

bash ./build.sh -C -S samples/subsys/uboot/app_enter_boot_recovery -DBOARD=arcs_evb

build 完成后，脚本会复制并校验 build/boot/app.config、build/boot/.config 与 build/boot/CMakeCache.txt，确认 boot image 真正打开了：
- CONFIG_BOOT_ADB_SHELL=y
- CONFIG_BOOT_ADB_SYNC=y
- CONFIG_ADB_SHELL=y
- CONFIG_ADB_SYNC=y
- CONFIG_ADB_PUSH_PULL_DEFAULT_ROOT="/SD:/adb/"
脚本随后使用仓库自带 ./tools/burn/cskburn -C arcs 只烧录 arcs.bin。
应用阶段必须先看到：
- APP enter boot recovery sample running
- APP requested boot recovery mode, rebooting
bench 会在 serial_normal.txt 中等待这组 marker，并在这个阶段持续确认 adb devices 仍然为空。
recovery 阶段验收内容：
- adb devices 恰好出现 1 个设备
- quoted one-shot adb shell "root;listenai;upgrade status"，也就是 shell 里的 upgrade status，在 unlock 前保持 exit，错误口令后仍保持 exit；执行 upgrade enter 后切换为 enter
- 文件路径 flow：相对路径 adb push / adb pull / adb push --sync 通过默认根 /SD:/adb/ 落到设备端；绝对路径和 /RAW/... 不属于 stale-sync freshness 合同
- SDRAW flow：adb push / adb pull 必须与 host 侧 4KB payload checksum 一致
- FLASH/NAND flow：bench 使用 64KB 对齐 payload，分别 adb push 到 /RAW/FLASH/40000/10000 与 /RAW/NAND/40000/10000；这两条路径用于验证 boot raw flash fast-path push，可和 upgrade enter transcript 一起作为真板证据