120 lines
13 KiB
Markdown
120 lines
13 KiB
Markdown
# PSP 主工作流
|
||
|
||
## 1. 输入和事实基线
|
||
|
||
开始前从项目和安全只读检查中确认：
|
||
|
||
- 目标应用项目路径、新项目名称，以及固定根目录 `~/work/project/EMX2.1/AppTeam/Psp/` 下由用户或团队预创建的同名 PSP 项目目录；
|
||
- 用户指定的相近板卡 PSP 路径或精确 commit；没有时记录“无参考”，不索取不存在的项目；
|
||
- 芯片、硬件 revision、单/双系统、存储介质和目标 BSP build type；
|
||
- BSP `doc/bsp_adaptation/handoff/psp_handoff.json`；
|
||
- 相对参考 PSP 的已知 GPIO、内存/分区、Media、Sensor 和 AIPlugin 差异，以及由用户更新的 ISP/PQ 状态；
|
||
- CV18 项目的 Sensor 规格选型和原理图/GPIO list；枚举表由 skill 按芯片系列从内置基线自动选择，不要求用户另行提供头文件；
|
||
- PSP、应用集成、设备验证和批准负责人；
|
||
- 禁止修改的目录及可用的 Git/Etunel 上下文。
|
||
- 用户指定的 EMX2.1 应用工程绝对路径；工程已有固定 `scripts/product.py`、`scripts/release.py` 和 `output/` 约定时，Skill 自行读取，不再向用户追问命令。
|
||
|
||
先把原理图、规格书、GPIO 表和已经确认的 BSP 事实收敛为仓库外 `hardware-topology.json`，运行 `validate_hardware_topology.py`。它至少记录芯片、系统形态、存储类型/容量、每路 Sensor 型号、I2C bus/address、MIPI device、lane 数、枚举名、证据源路径/hash，以及对 `sensor_cfg.ini` 的显式字段期望。器件型号未给出时只能按用户允许的范围记录容量，不猜型号。目标旧配置和参考 PSP 属于待核对的软件现状，不能作为覆盖硬件资料的证据；任何未解决冲突都阻止适配。
|
||
|
||
缺失可从仓库发现的事实时先调查，不要求用户重复。是否有参考 PSP、负责人决定或跨平台风险属于用户决定，不能推断；用户明确没有参考时启用下述“无参考”分支。同一缺项连续出现时只更新缺项列表，不重复完整问卷，也不在没有新输入时反复生成同一结论。
|
||
|
||
把 `~` 展开为运行 skill 的当前用户目录，并记录规范化后的绝对 PSP 根路径。目标项目必须是该根目录的普通直接子目录和独立 Git 仓库；保留已有分支、远端和仓库配置。目标目录不存在时停止并请用户或团队创建，禁止由 skill 建目录、运行 `git init` 或替用户配置远端。预创建目录已有业务内容时视为现有 PSP，只走基于 Git 差异的更新流程，禁止再次从参考 PSP 整体导入。
|
||
|
||
## 2. 参考兼容性
|
||
|
||
无参考 PSP 时本节兼容性和四视图报告标记为 `N/A（无参考）`，不得伪造一个参考。先锁定精确 Media/AI Release 版本/profile、硬件事实、BSP handoff 和应用打包接口，依[CV181X Media/AI 取值指南](cv181x-media-ai-configuration.md)生成全字段默认目录和生效配置差异。即使 Release 与源码完全相同，Media/AI 的 SDK、ABI、通道、模型、驱动与最终 PSP 值仍须单独验证。
|
||
|
||
比较参考和目标的芯片系列、板卡形态、单/双系统、存储介质、Sensor 数量/型号、GPIO/Pinmux 结构、媒体能力和 AIPlugin 能力。列出：
|
||
|
||
- 可直接继承；
|
||
- 需要修改；
|
||
- 无法确认；
|
||
- 明显不兼容。
|
||
|
||
明显不兼容时默认停止。用户明确接受跨平台参考风险后仍须把每个未验证项留在结果中。
|
||
|
||
参考或目标是 Git 仓库时运行 `analyze_psp_delta.py`，固定四个视图：目标 HEAD、目标 worktree、参考 HEAD、参考 worktree。后续差异必须归入“匹配参考稳定 HEAD”“匹配参考未提交 worktree”“目标特有”“未分类冲突”；不能把参考仓库的脏文件冒充其 commit 内容。未分类项必须逐项解决，工具报告和两个完整 commit 一并进入外部证据。
|
||
|
||
## 3. 受控适配
|
||
|
||
对于尚无业务内容的预创建项目仓库，有参考时按[项目与 Git 规则](project-and-git.md)在同一固定根目录的唯一 staging 中复制参考 PSP，排除参考仓库身份、构建输出、缓存、日志、临时文件、本机生成物和旧的应用侧 `psp.lock.json`。无参考时使用 `psp_project_guard.py prepare-empty` 建立空 staging，依据应用接口、BSP handoff、硬件拓扑和精确 Release 默认值逐项建立业务文件；工具不会生成 `psp.json`、分区、Sensor、GPIO 或 PQ，缺少这些依据时只能保持 partial/blocked。最终仅把已验证业务内容导入目标，目标自身 `.git` 不进入 staging、也不被替换。
|
||
|
||
对于已有业务内容的目标项目，先证明它是固定根目录下的预期独立仓库，记录 HEAD、分支、远端和工作区状态；只修改任务明确授权的文件，并以修改前 commit/worktree 为差异基线。不得为了套用参考项目而清空、覆盖或重新初始化目标。
|
||
|
||
只修改确认的目标差异。无参考时“修改”指相对选定 Release 默认/应用接口新建或改变的字段，不是相对另一个板卡。适配后生成两张清单：
|
||
|
||
1. 修改项：文件、关键字段、旧值、新值、依据和影响；
|
||
2. 继承项：GPIO、Sensor、BSP、Media、AIPlugin 等关键配置及确认状态。
|
||
|
||
扫描旧项目名、旧芯片/板卡、旧 BSP build ID、旧绝对路径、旧 Sensor、旧 SDK/Media/AIPlugin 版本、脚本硬编码及“临时修改/记得修改”等残留。每个命中必须归类为已替换、确认继承或无法判断；无法判断项阻止 accepted。
|
||
|
||
## 4. 先处理 BSP 阻塞
|
||
|
||
使用 `validate_bsp_handoff.py` 校验精确 BSP 输入、生产者的权限证据和当前路径权限，并把稳定摘要写入 `metadata/bsp.lock.json`；不要修改 BSP handoff。调用 `validate_psp.py` 时必须显式提供目标 PSP 项目名，以及期望的 BSP 项目、芯片、SDK、build type 和单/双系统形态；项目身份和权限证据一致但当前输出权限不足时，自动只补齐本次 imgs 路径的 `a+rX` 并复核。任一身份缺失或不一致、权限证据缺失或无权修复都阻止 candidate。关键 IMG 缺失或 hash 不一致时同样阻止 candidate。
|
||
|
||
如果 BSP handoff 缺失、镜像 hash 不符或 kernel/rootfs 的 512 KiB 余量检查失败，只报告这一组 BSP 问题和精确失败值，先交 BSP 处理。不要同时要求用户补 Sensor、ISP/PQ 或应用打包信息。能从现有 BSP 产物重新生成的证据应先做只读检查，再只申请一次明确的 BSP 操作确认。
|
||
|
||
按[配置边界与检查](configuration-boundaries.md)核对 GPIO、内存/分区、Sensor、Media、AIPlugin 及应用覆盖关系。CV18 根据规格书确定枚举名称后调用 `validate_psp.py --expected-sensor sensor=ENUM_NAME`，工具根据芯片自动使用内置枚举表：CV181X 验证配置中的枚举名称，CV184X 验证该名称对应的枚举数值。无需搜索或传入 SDK 头文件；只有已确认的枚举版本差异才显式覆盖。ISP/PQ 仅记录用户负责的状态，不由 Skill 修改。`psp.json` 保持参考格式；新增治理数据写入 sidecar metadata，避免未经协调改变应用打包接口。
|
||
|
||
任何分区变化必须运行 `validate_partition_closure.py`，从 `psp.json` 推导几何并核对 PSP 内实际生效的 Boot/Default 和应用 `release.py`。任何 Sensor、BSP build、Media/AIPlugin 变化都按配置依赖闭包逐项检查，不能只改最显眼的一个文件后进入 candidate。
|
||
|
||
## 5. 静态验证和打包准备检查
|
||
|
||
最低静态检查包括：
|
||
|
||
- 受控复制和差异白名单；
|
||
- PSP 目录、JSON/INI 和 shell 语法；
|
||
- 文本编码、软链接和不可访问路径；运行时目录软链接不跟随扫描，但必须由资源映射和打包检查单独证明；
|
||
- 旧项目残留；
|
||
- BSP handoff、路径、大小和 hash；
|
||
- GPIO、Media、Sensor 枚举映射、AIPlugin、SDK 和模型引用的一致性，以及 ISP/PQ 的用户负责状态；
|
||
- 硬件拓扑证据、四视图差异分类（无参考时为 N/A 并附 Release→生效值目录）、配置依赖闭包和分区闭包；
|
||
- 应用与 PSP 的同名配置覆盖清单；
|
||
- 未决、警告和批准例外。
|
||
|
||
在导入目标 PSP 和创建候选提交前，还要读取用户指定应用工程的固定打包入口，并运行：
|
||
|
||
1. `record_packaging_result.py contract`，根据 `<应用工程>/psp`、`scripts/`、`output/` 和目标芯片生成仓库外的本地契约；
|
||
2. `record_packaging_result.py preflight --psp-source <staging>`，提前核对 `EmxResToProduct` 的每个资源来源、重复目标、`data.file`、DATA 组包工具映射、`mkAiData.py` 参数、PSP 分区与 BSP `bsp.lock.json`；
|
||
3. 只读检查 `product.py` 依赖的 Media、AIPlugin、公共运行库和驱动配置。空数组、缺目录或脚本只打印错误但仍返回 0 的情况必须列为阻塞；PSP Skill 不自行修改应用脚本。
|
||
|
||
打包准备检查不执行 `product.py` 或 `release.py`。它失败时先在 staging 修正 PSP；问题属于应用框架、BSP 或公共组件时只给出文件、字段和影响，由对应所有者处理。不要先提交一个已知无法组包的候选版本。
|
||
|
||
警告分三组输出：阻止继续、需要用户确认、暂不影响当前步骤。ISP/PQ 的 `USER_OWNED/PENDING`、目标机运行路径在当前主机不可见等已知状态，单独列出，不计入静态错误总数。
|
||
|
||
## 6. 自动提交候选版本
|
||
|
||
需求和适配方案已经确认后，先输出完整差异、继承清单、静态验证、打包准备检查、风险、commit message，以及下一阶段的精确路径和命令。所有检查通过后直接完成本地导入、`git add` 和候选提交，不再询问是否提交。提交前后核对工作区内容一致，完整 SHA 是唯一 PSP 身份。
|
||
|
||
Git 身份未配置、工作区有非本任务改动、暂存区包含白名单外文件、验证结果在提交前发生变化或提交失败时停止。不要替用户配置 Git 身份、丢弃改动或改写历史；说明异常后请用户决定。`./release.py 1`、Git 上传、Etunel 发送、tag、设备和发布不在自动范围内。
|
||
|
||
## 7. 组包和设备/应用验证
|
||
|
||
候选提交创建后，自动把应用工程中已经登记且仓库身份一致的 `psp` 子模块更新到该完整 commit；不自动新建子模块、不更换 URL，也不提交应用仓库。随后用同一工具以 `--formal` 再做一次打包准备检查，确认 commit 和工作区未变。在 `<应用工程>/scripts` 自动运行 `./product.py`；退出码和日志都没有错误后，自动运行默认增量的 `./release.py 0`。按[组包与设备验证](packaging-and-device-validation.md)证明本轮唯一新增的 `output/<版本>/`，再记录项目规则明确指定的唯一烧录包。
|
||
|
||
子模块不存在、URL 或仓库身份不一致、父仓库的 `.gitmodules`/`psp` 已有重叠改动、`product.py` 报错、`release.py 0` 报错或产物检查失败时停止并请用户决定。需要 clean rebuild 时也停止，展示原因和 `./release.py 1` 精确命令，取得确认后才执行。
|
||
|
||
达到 packaged 后可以经 Etunel 提供给应用层，人工设备验证与应用集成并行：
|
||
|
||
```text
|
||
candidate -> packaged -> device_verified
|
||
-> app_integrated
|
||
同一 commit 两项均通过 -> accepted
|
||
```
|
||
|
||
配置、脚本、小型资源或依赖变化使受影响证据失效；纯文档变化经差异证明和负责人确认后可以复用技术证据。
|
||
|
||
## 8. 交接和返工
|
||
|
||
按 [Etunel 交接](etunel-handoff.md)把 packaged candidate 提供给 Hub。应用问题必须携带 PSP commit、应用 commit、BSP build、复现步骤、期望/实际、日志和阻塞影响，经 Hub 创建新的底层任务。
|
||
|
||
无参考项目时渲染交接用 `render_psp_handoff.py --no-reference`，并附精确 Release/profile/hash 和逐字段审计报告；不可把 Release 目录或其他板卡虚构成参考 PSP。
|
||
|
||
职责内问题形成新 candidate commit；跨 BSP、应用、硬件或公共组件的问题只提交证据和归属建议，由 Hub 路由。不得 force-push 已供打包、设备或应用验证的 commit。
|
||
|
||
## 9. 完成状态
|
||
|
||
输出真实阶段，并同时给出中文解释：候选版本（`candidate`）、已组包（`packaged`）、设备验证通过（`device_verified`）、应用集成通过（`app_integrated`）、已验收（`accepted`）、部分完成（`partial`）或已阻塞（`blocked`）。完整成果引用 PSP 仓库/commit、BSP lock、静态检查、烧录包绝对路径/hash、人工设备反馈、应用集成、Etunel 交接、未执行项和剩余风险。
|
||
|
||
accepted 仅表示 PSP 可作为正式应用集成基线，不代表整机测试、所有硬件行为、媒体/算法效果或产品发布已经通过。
|