# BSP 项目适配工作流

## 1. 识别模式

本工作流用于在当前用户的 `~/EapilBsp/EMX2.0/EmxRes` 中，从一个已确认参考项目创建新 BSP 配置项目。`EmxRes` 是配置 Overlay；不能假定它是完整 SDK 源码树。

若用户只要求审查已有 BSP，不创建项目，则执行对应的只读检查，不运行复制和最终写入步骤。

## 2. 最低输入与继承

始终需要参考项目名、新项目型号、精确芯片型号、单/双系统形态、验证模式和交付级别。交付级别必须明确为以下之一：

- `config-project`：仅创建 BSP 配置项目；
- `bsp-build-artifacts`：再运行统一构建并交付 imgs 版本目录；
- `flash-package`：要求项目原生流程产生明确的可烧录/升级包；
- `production-package`：要求量产整片包、签名或发布时另行确认对应权限。

用户要求修改某一领域时再要求对应输入：

- GPIO：GPIO List 或原理图；已覆盖 CV18 芯片的 GPIO/PINOUT 设计表由 Skill 内置并自动选择；
- 媒体内存：明确数值和单位；
- 分区：变化的分区名称和目标大小。

未提及的领域完整继承参考项目。用户直接提供的 GPIO List 是目标需求；只提供原理图时，先按 [GPIO 实施计划契约](gpio-plan.md)提取候选差量并让用户确认。

## 3. 只读预检

1. 将 `~` 解析为执行任务的当前用户主目录，确认参考项目是 `EmxRes` 的直接子目录，目标也是新的直接子目录。
2. 检查目标正式目录和同名残留目录；正式目录已存在时停止，不覆盖。
3. 先运行 `scripts/bsp/bsp_preflight.py project`，再只读取报告定位的 `buildEnvConfig.sh`、配置同步脚本和实际配置目录，发现精确芯片、SDK、Flash、架构、单/双系统形态和板卡 build type。
   CV184X 保持单板卡目录；CV181X 必须分别检查 `configs/kernel/` 和 `configs/uboot/`，并以 U-Boot 板级 defconfig 及两侧同名 `cvitek_` defconfig 确定 build type。`CONFIG_ENABLE_FREERTOS=y` 不能单独当作双系统证据。结构不匹配时停止，不自动转换。
4. GPIO 任务按 [内置 GPIO 资料目录](builtin-gpio-pinout.md)从 `buildEnvConfig.sh` 的 `EP_CHIP` 自动选表并查询全部目标信号；将结果保存为输入证据。目录名与 `EP_CHIP` 冲突时以后者为芯片配置事实并报告命名风险，原理图芯片与 `EP_CHIP` 冲突时停止。
5. 按 [调查范围与验证模式](scope-and-validation-modes.md)执行 GPIO/DTS 检查。默认 EmxRes 配置模式不人工搜索 SDK；完整 DTS 审核模式只读取精确解析出的 include 链。
   若用户另行指定精确 CV181X SDK 根目录，可按 [CV181X 分目录与 SDK 只读核对](cv181x-sdk-readonly-review.md)执行文件映射核对；该检查不授予同步或编译权限。
   CV184X 项目可按 [CV184X 板级配置与构建链](cv184x-sdk-readonly-review.md)核对单目录映射、真实 build type、生成配置和补丁副作用；用户未指定 SDK 路径时仅分析 EmxRes 和 tools。
6. 默认要求参考与目标使用相同精确芯片、SDK、Flash 和系统形态。不同芯片或布局转换不是少量适配，要求更接近的参考项目或新的工作包。
7. 只读检查 `EmxRes` Git 状态。参考项目自身包含已修改或未跟踪文件时，列出并要求确认复制当前磁盘状态；其他项目的改动只记录、不阻塞。
8. 扫描软链接。允许保留项目内相对链接；约定的 `imgs` 链接按第 6 节处理；其他指向 `EmxRes` 外部的链接要求确认。
9. 发现凭据、私钥、token 文件或未知大型生成物时停止复制该项并报告，不能静默带入新项目。

## 4. 命名与板卡版本

默认目录名：

```text
<大写芯片型号>-<项目型号>
<大写芯片型号>-<项目型号>_dualos
```

项目型号内部原有连字符可保留。`_dualos` 由明确的双系统形态决定，不能从 `CONFIG_RTOS_ION_SIZE` 单独推断。`_v6.3.3`、`_optimize`、日期、Flash 等额外后缀只有用户明确要求时添加。

板卡 build type 中的 `xxxx` 默认继承参考项目。用户明确改变时，必须一致修改配置目录、板卡 defconfig、DTS 名称和所有实际引用；禁止只重命名单个文件或全局盲替换项目名。

## 5. 一次性实施确认

持久化复制前展示：

- 参考和目标绝对路径；
- 芯片、SDK、Flash、系统形态、布局和板卡版本；
- 最终项目名；
- GPIO、内存、分区差量和继承项；
- 当前 RES/staging 项目内的候选修改文件；SDK 同步映射和构建写入另列，按 [RES、SDK 与表述边界](res-sdk-boundary.md) 说明；
- `imgs` 链接变化；
- 输入证据和 `doc/` 计划；
- 交付级别、调查范围、验证模式及结论上限；
- 完整 GPIO 实施表和所有 `provisional`/`blocked` 项；
- 将执行及不会执行的验证、同步、编译和外部动作。

用户确认后运行本地复制。交付级别需要构建产物时，该确认同时覆盖预检通过后的标准全量编译，不再在编译前重复询问；设备动作、上传和发布仍不在授权范围内。

## 6. 安全复制与 `imgs`

使用：

```bash
python3 scripts/bsp/project_guard.py prepare \
  --reference-project <参考项目> \
  --target-project <新项目>
```

脚本在 `EmxRes` 下创建唯一的 `.<新项目>.bsp-staging-*` 临时目录，保留普通文件权限和软链接，排除 Git 元数据、缓存、明确构建输出和日志，并写出克隆清单。

约定的：

```text
/epbuild/EMX2.0/EmxRes/<参考项目>/imgs
```

只重定向为：

```text
/epbuild/EMX2.0/EmxRes/<新项目>/imgs
```

不跟随或复制镜像内容。新目标不存在时允许悬空，并记录警告。

## 7. 差量实施

1. 先读取目标文件的真实结构、调用语义和构建引用。
2. 只修改经确认字段；未给出的方向、电平、初值、分区属性等继承参考项目。
3. CV18 GPIO 使用 [CV18 GPIO 与 DTS 规则](cv18-gpio-dts.md)。
4. 媒体内存和分区使用 [内存与分区规则](memory-and-partition.md)。
5. 在 `doc/bsp_adaptation/` 建立适配报告、输入证据和验证记录。
6. GPIO 任务保存已确认的 `inputs/gpio_plan.json`，并在写代码前后运行校验器。
7. 不执行与目标差量无关的格式化、重构、warning 清理或版本升级。

## 8. 差异白名单与正式写入

对每个允许修改的文件传入精确相对路径；不要用 `configs/**` 一类宽泛规则：

```bash
python3 scripts/bsp/project_guard.py verify \
  --reference-project <参考项目> \
  --staging-dir <临时目录名> \
  --target-project <新项目> \
  --allow-path <精确相对文件> [--allow-path <另一文件> ...]
```

`doc/bsp_adaptation/` 和约定 `imgs` 链接由工具内建允许。出现白名单外新增、删除、内容或权限变化时停止。

全部必需静态检查通过且 `adaptation_report.md` 已完成后：

```bash
python3 scripts/bsp/project_guard.py finalize \
  --reference-project <参考项目> \
  --staging-dir <临时目录名> \
  --target-project <新项目> \
  --allow-path <精确相对文件> [--allow-path <另一文件> ...]
```

最终化不信任旧的 `project_delta.json`，会用同一参考项目和精确白名单重新执行完整验证，再在同一文件系统原子重命名。失败时保留临时目录供检查；清理临时目录必须再次确认。

## 9. 完成状态

没有执行 SDK 同步和完整编译时，正式状态写为：

```text
本地 BSP 配置项目已创建；尚未同步 SDK，尚未完成编译验证
```

后续同步或编译失败不删除已创建项目，只更新项目内验证证据和真实状态。

任务已要求构建产物时，正式项目静态检查通过后自动进入标准全量编译。预检失败、输出版本冲突、统一脚本缺失、工作区出现重叠改动、命令返回失败或产物检查失败时停止，不自动覆盖、清理或重试；记录证据后请用户决定如何处理。

完整编译成功后先把本次精确 imgs 版本路径按 `a+rX` 处理并复核，确保其他用户和组能够读取、进入该路径；再按分区表验证唯一 `kernel.bin`、`rootfs.bin` 均至少保留 512 KiB 分区余量，最后记录精确 imgs 版本目录和 BSP→PSP 交接 manifest。权限或余量检查未执行、未通过，或者只有 `imgs` 软链接或“最新目录”，都不能作为下游基线。