8.3 KiB
构建、Git、imgs 与 PSP 交接证据
项目内证据目录
新项目必须包含：
doc/bsp_adaptation/
├── adaptation_report.md
├── inputs/
├── validation/
├── handoff/
│ └── psp_handoff.json
└── status.json
adaptation_report.md 至少记录参考与目标、芯片/SDK/Flash/系统形态、交付级别、调查范围、验证模式、用户确认、输入依据、修改文件、旧值与新值、继承项、GPIO/DTS 冲突处理、内存/分区检查、未执行验证、风险和真实状态。
小型 GPIO List、内存或分区需求原样复制到 inputs/。大型或敏感原理图、芯片手册和工程资料默认不重复复制，只记录受控路径、版本、适用型号和 SHA-256。禁止保存密钥、token、证书内容或许可证凭据。
CSV 只有从原理图提取或重新映射 Pinmux 时才作为派生审核证据写入 inputs/；它不是唯一事实源。
开发改动与构建写入
按 RES、SDK 与表述边界 将当前 RES 项目的开发改动、SDK 只读核对映射和原生构建实际写入分开记录。构建授权覆盖标准工具已说明的配置同步及生成物写入，不授权额外编辑 SDK、替换 SDK 软链接或备份后恢复 SDK 配置。SDK 中出现差异时，先确定是否影响本次同步；不要把调查结果直接变成 SDK 修复方案。
本地 Git
EmxRes 已有 Git worktree 只用于只读状态、参考项目脏文件发现和差异证据。不得执行 git init、add、commit、stash、清理、分支切换、历史改写或 push。
项目创建本身不需要远端 Git。根仓库其他项目的改动不阻塞；与参考或目标重叠的已有改动必须先确认。
项目创建阶段
仅创建 config-project 或只读审查时不执行：
ep_kernel.sh；ep_uboot.sh；EPSYNCSDKConfig.sh；EMX2_BuildSDKTool。
这些脚本会将配置复制或 rsync 到项目外 SDK，有的还会改变脚本权限或访问远端。仅创建配置项目时只完成目录、配置回读、DTS/GPIO 静态一致性、精确差异白名单和文档检查。任务要求 bsp-build-artifacts 或更高交付级别时，静态检查完成后按下一节自动执行标准全量编译。
统一编译
需求和实施方案已经确认、任务需要构建产物时，标准流程自动执行：
cd ~/EapilBsp/EMX2.0/EmxRes
source tools/script_completion.sh
EMX2_BuildSDKTool <项目名> <YYYYMMDD_N> all
YYYYMMDD 使用 Asia/Shanghai 当前日期；未指定时选择尚不存在的最小正整数序号。默认全量 all，只有用户明确要求时使用组件构建。
先运行：
python3 <BSP Skill>/scripts/bsp/bsp_preflight.py build \
--project <项目名> \
--version <YYYYMMDD_N>
passed=true 是构建的必要条件。执行前把工具返回的精确工作目录、完整命令、项目与 SDK 路径、构建范围、最终 imgs 版本路径、工作区状态、配置同步副作用，以及统一脚本中的远端 git fetch origin 写入记录。不得从 EmxRes 的父目录启动，也不得依赖登录 Shell 的偶然当前目录。
CV184X 的补丁检查和失败诊断交给原生构建脚本；Skill 不单独检查补丁完整性，也不进入 SDK 仓库。预检仅查看本轮精确构建脚本是否仍可能自动调用 --applypatch --force；若有则停止，交构建脚本所有者改为失败即退出，禁止用静默替换脚本、跳过补丁检查或注入拦截命令来继续。安全脚本就绪后直接执行统一编译，按实际退出码和日志报告结果；CV181X 不套用 CV184X 的补丁逻辑。
下列情况不自动处理：预检失败、统一脚本或路径与固定规则不符、输出版本已存在、参考或目标出现新的重叠改动、需要直接运行同步脚本、需要组件构建、需要改变构建参数、需要修改统一脚本，或者构建失败后需要清理和重试。此时停止并向用户说明异常、影响和可选处理方式。
不得修改、注入或静默绕过统一构建脚本的远端检查。本地免远端模式属于独立工具优化任务。
输出冲突与权限
输出目录通常为：
/epbuild/EMX2.0/EmxRes/<项目名>/imgs/<构建版本>
已存在时默认停止并建议下一序号。绝不自动向“强制删除并继续”回答 yes；覆盖需要针对精确绝对路径的独立确认。
构建前记录新项目内同步脚本权限；统一脚本临时 chmod 777 后，构建结束恢复已记录的原权限并写入报告。只恢复新项目内的已知文件，不改 SDK 或其他项目权限。
编译命令成功后，record_build_handoff.py 必须在生成交接文件前自动处理本次精确 imgs 版本路径：
- 从
--output-root到本次<项目名>/imgs/<构建版本>的路径节点都补齐a+rx，保证所有用户都能读取并进入目录； - 本次版本目录内递归执行等价于
a+rX的受控处理：目录补齐a+rx，普通文件补齐a+r，只有原本带执行位的文件才补齐a+x； - 不跟随软链接，不改软链接目标，不处理其他项目或其他构建版本，也不使用
chmod -R 777； - 不使用
sudo。当前用户无法修改权限、路径节点不是普通目录、输出包含特殊文件或复核仍不满足要求时立即停止，不能生成build_passed； - 将处理前后模式、变更数量和复核结果写入
validation/output_permissions_<构建版本>.json，并同时写入 PSP 交接 manifest。
构建证据与状态
成功必须同时满足：
- 命令退出码为零；
- 日志到达正常完成阶段；
- 输出目录存在且含非空固件文件；
- 本次精确 imgs 版本路径已经通过
a+rX权限处理与复核； - 当前项目实际生效的分区表可唯一确定，或已显式指定
configs/内精确文件； - 最终 imgs 中唯一
kernel.bin和rootfs.bin相对各自最小对应分区均保留至少 512 KiB（524288 字节）； - 文件名、大小和 SHA-256 清单写入
validation/； - 构建后项目源码差异仍通过白名单。
满足以上条件后运行：
python3 <BSP Skill>/scripts/bsp/record_build_handoff.py \
--project <项目名> \
--build-version <YYYYMMDD_N> \
--build-exit-code 0 \
--completion-marker-seen \
--risk <仍存在的硬件风险>
python3 <BSP Skill>/scripts/bsp/project_guard.py audit-final \
--target-project <项目名>
自动发现多个 partition*.xml 时，上述记录命令必须追加：
--partition-table configs/<实际生效路径>/partition_spinand.xml
该参数只接受当前 BSP 项目 configs/ 内的文件。检查失败时脚本不会生成 build_passed handoff。
记录脚本生成或更新：
validation/artifact_manifest_<构建版本>.sha256；validation/image_partition_margin_<构建版本>.json；validation/output_permissions_<构建版本>.json；handoff/psp_handoff.json；status.json。
psp_handoff.json 遵循统一入口的 BSP→PSP 交接契约。audit-final 必须在这些文档写入后执行；它使用 prepare 时冻结的参考清单，而不是假定参考项目从未变化。
成功时保存简明摘要、输出路径权限证据、kernel/rootfs 分区余量证据、固件哈希清单和精确 imgs 版本路径；失败时保存完整日志、阶段和关键错误。后续同步或编译失败不删除已经通过静态门禁的正式项目，只更新状态。不得只记录 imgs 软链接、父目录或“latest”；交付和 PSP 依赖必须绑定具体构建版本目录。
没有同步和编译时写：
本地 BSP 配置项目已创建；尚未同步 SDK，尚未完成编译验证
本地编译成功也不能替代板上 GPIO、电平、时序、外设或负责人验收。
最终回复
完成构建时必须显式输出：项目路径、精确 imgs 版本路径、a+rX 权限复核结果及证据路径、kernel/rootfs 的镜像大小、最小对应分区大小和实际余量、余量证据路径、交接 manifest 路径、产物清单/hash 路径、audit-final 结果，以及硬件/负责人/发布状态。没有生成交接 manifest 时不能声称已完成 PSP 交接。