tangfahong/firmware-lowlevel-development

0 Fork 0

Files

T

tangfahong 1641fac631 feat: strengthen BSP and PSP validation and handoff

2026-09-24 11:52:22 +08:00

8.2 KiB

Raw Blame History

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 实施计划契约提取候选差量并让用户确认。

3. 只读预检

将 ~ 解析为执行任务的当前用户主目录，确认参考项目是 EmxRes 的直接子目录，目标也是新的直接子目录。
检查目标正式目录和同名残留目录；正式目录已存在时停止，不覆盖。
先运行 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 不能单独当作双系统证据。结构不匹配时停止，不自动转换。
GPIO 任务按内置 GPIO 资料目录从 buildEnvConfig.sh 的 EP_CHIP 自动选表并查询全部目标信号；将结果保存为输入证据。目录名与 EP_CHIP 冲突时以后者为芯片配置事实并报告命名风险，原理图芯片与 EP_CHIP 冲突时停止。
按调查范围与验证模式执行 GPIO/DTS 检查。默认 EmxRes 配置模式不人工搜索 SDK；完整 DTS 审核模式只读取精确解析出的 include 链。若用户另行指定精确 CV181X SDK 根目录，可按 CV181X 分目录与 SDK 只读核对执行文件映射核对；该检查不授予同步或编译权限。 CV184X 项目可按 CV184X 板级配置与构建链核对单目录映射、真实 build type、生成配置和补丁副作用；用户未指定 SDK 路径时仅分析 EmxRes 和 tools。
默认要求参考与目标使用相同精确芯片、SDK、Flash 和系统形态。不同芯片或布局转换不是少量适配，要求更接近的参考项目或新的工作包。
只读检查 EmxRes Git 状态。参考项目自身包含已修改或未跟踪文件时，列出并要求确认复制当前磁盘状态；其他项目的改动只记录、不阻塞。
扫描软链接。允许保留项目内相对链接；约定的 imgs 链接按第 6 节处理；其他指向 EmxRes 外部的链接要求确认。
发现凭据、私钥、token 文件或未知大型生成物时停止复制该项并报告，不能静默带入新项目。

4. 命名与板卡版本

默认目录名：

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

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

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

5. 一次性实施确认

持久化复制前展示：

参考和目标绝对路径；
芯片、SDK、Flash、系统形态、布局和板卡版本；
最终项目名；
GPIO、内存、分区差量和继承项；
候选修改文件；
imgs 链接变化；
输入证据和 doc/ 计划；
交付级别、调查范围、验证模式及结论上限；
完整 GPIO 实施表和所有 provisional/blocked 项；
将执行及不会执行的验证、同步、编译和外部动作。

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

6. 安全复制与 `imgs`

使用：

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

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

约定的：

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

只重定向为：

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

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

7. 差量实施

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

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

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

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

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

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

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

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

9. 完成状态

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

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

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

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

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

8.2 KiB Raw Blame History Unescape Escape