# ARCS 人脸示例配套升级与验证

## 范围

更新 `samples/algorithms/face_detect` 和 `demos/arcs/face_detect`。
两者使用 ARCS `lsface.arcs.0.0.0009.0.1008`，384 维特征、12 B 结果头和 2956 B 单条结果。
SDK 统一接收入口检查当前结果 ABI；示例分别处理引擎错误，摄像头 demo 的按键操作使用受保护的结果快照。
VenusA SDK 示例的资源和预编译 AP 不在本轮升级范围内。

## 配套资源

| 镜像 | Flash 偏移 | 大小 |
|---|---:|---:|
| AP | 0x000000 | 318184 B |
| 检测 | 0x100000 | 448056 B |
| 对齐 | 0x170000 | 557304 B |
| 活体 | 0x200000 | 957528 B |
| 特征 | 0x300000 | 1936808 B |
| CP | 0x800000 | 按实际构建读取 |

新版活体模型不能放进原 0x200000..0x2C0000 的空间，因此特征模型起点后移到 0x300000。
每个示例的 `res/manifest.json` 固定 AP/模型 SHA256、大小、地址和容量。
AP SHA256 为 `79297e6bb34d4cbe290aee3341e57640ff78cb4aa29ccd9fac9e3f8ce98e7713`。
`example.cmake` 在每次编译/打包时执行资源校验；合并脚本也调用同一个检查器。
结果类型的编译期断言与 manifest 保持一致，SDK ABI 后续变化时不能沿用这些 AP 二进制。

AP 直接在 Flash 0 启动，CP 入口为 0x30800000。AP/CP 各占 8 MiB PSRAM，
CP PSRAM 基址 0x28800000；IPC 基址 0x2004E000，LSF 共享区基址 0x20048000。
AP 算法池为 768 KiB，模型保持 XIP。

SDK 可独立使用已发布的配套二进制。维护者在集成 PDK 仓库中重建 AP 的命令为：

```powershell
$faceAPConfig = (Resolve-Path apps/remote-ap/sdk-face-arcs.conf).Path
./build.ps1 -S apps/remote-ap -B build/sdk-arcs-face-ap -DBOARD=arcs_evb "-DCONFIG_FILES=$faceAPConfig"
```

发布新的 AP/引擎时，须核对生成的 `.config`、链接地址及资源契约，再同步两个示例的
`res/ap.bin`、配套模型和 manifest；不要将 rust-face-detect-demo 的紧凑布局 AP 直接复制过来。

## 2026-10-10 实板结果

设备为当前 `arcs_evb`，COM6 / CH343 / `5AB9015836`，此前读取芯片 ID 为 `6b3bc01b1758c9bd`。
以下命令均从集成仓库根目录执行：

```powershell
./build.ps1 -S arcs-sdk/samples/algorithms/face_detect -B build/sdk-face-sample -DBOARD=arcs_evb
./build.ps1 -S arcs-sdk/demos/arcs/face_detect -B build/sdk-face-camera -DBOARD=arcs_evb
```

两项构建和整包资源检查通过。SDK 单独使用时将源码路径去掉 `arcs-sdk/` 前缀。
基础示例整包为 8677832 B；摄像头示例整包为 8800138 B。
每个整包包含布局填充；实板分段写入并以 `cskburn --verify-all` 逐段读回验证，未执行整片擦除。

| 自动检查 | 结果 | 证据（集成仓库根目录） |
|---|---|---|
| 基础静态图示例，25 秒 | 23 次有效结果；检测到人脸、活体通过、有效特征为 384 维；无 ABI/引擎错误 | build/sdk-face-static-hardware |
| 摄像头 demo，30 秒 | 相机 320×240 启动成功，结果计数达到 100；无 ABI/引擎错误 | build/sdk-face-camera-hardware |
| 主机 ABI/边界检查 | 当前布局、旧格式、截断、非法索引/数量、特征上界及错误包，ASan/UBSan 通过 | build/sdk-fd-validation-checks |
| 资源校验 | 两套正确资源通过；等长 AP 字节损坏被拒绝；手动合并与自动整包一致 | pack_example.py / merge_bins.py |

静态 CP 烧录读回 MD5 为 `9704e815ef394ee337b29034a651728d`；摄像头 CP 为 `18e635bbbcaabd0f34c4d2e50b7fa922`。
最终板上保留摄像头 SDK demo。原 CUP2 320 固件快照位于 `build/face-arcs-optimized-320-device.bin`。

测试前后对 0xF80000..0x1000000 的 524288 B 数据区逐字节比对一致，SHA256：
`e51b25df8693c26bd38dfb668e8e943c016d1342bcd4ae719743af3454bae7ab`。
备份分别为 `build/sdk-arcs-examples-data-before.bin` 与 `build/sdk-arcs-examples-data-after.bin`；
比对报告 `build/sdk-arcs-examples-persistence.json`。原 CUP2 ID 1 数据未被修改。

## 自动验证入口与边界

SDK 内提供 `tools/verify_example.py`，需要 pyserial，默认 921600 波特率。
在烧录/复位后立即运行，明确选择实际端口：

```powershell
python arcs-sdk/components/acomp/fd/tools/verify_example.py --port COM6 --kind static --seconds 25 --output build/sdk-face-static-hardware
python arcs-sdk/components/acomp/fd/tools/verify_example.py --port COM6 --kind camera --seconds 30 --output build/sdk-face-camera-hardware
```

脚本检查真实结果进度与错误，保存 `device.log` / `report.json`，失败返回非零。
上述自动结果不代表 LCD 外观、触摸/实体按键、真人注册/比对准确率、假体效果或长期稳定性已验收。
摄像头 demo 仍按原业务通过实体按键注册/比对，注册特征为 RAM 临时数据。