54 lines
9.6 KiB
Markdown
54 lines
9.6 KiB
Markdown
---
|
|
name: firmware-lowlevel-psp-development
|
|
description: "创建、修改和验证项目级 PSP 平台配置；有相近板卡 PSP 时受控继承，无参考项目时依据硬件/BSP 事实、应用接口与精确 Media/AIPlugin Release 默认配置逐字段建立。用于 CV181X Media/AI 通道和参数审计、PSP 适配、组包证据及交接；不用于 BSP/驱动、应用业务、公共组件或未经确认的设备/发布操作。"
|
|
---
|
|
|
|
# 固件底层开发_PSP开发
|
|
|
|
把每个硬件项目的 PSP 作为独立、轻量的配置仓库维护。PSP 固定工作区是当前用户的 `~/work/project/EMX2.1/AppTeam/Psp/`；项目目录由用户或团队预先在该根目录下创建。有参考 PSP 时只做最小差异；没有参考 PSP 时从已确认的硬件/BSP、应用接口和精确 Release 基线建立，不把任一 Release 当成完整 PSP。PSP 的唯一身份是完整 Git commit SHA。
|
|
|
|
## 进入流程
|
|
|
|
1. 先读取并遵守统一的[流程文档写法](../firmware-lowlevel-development/references/chinese-process-docs.md)，所有面向人的流程文档使用简体中文和直白表达。
|
|
2. 读取统一入口的[项目所有权契约](../firmware-lowlevel-development/references/ownership-contract.md)、[治理工作流](../firmware-lowlevel-development/references/governance.md)和[风险等级](../firmware-lowlevel-development/references/risk-levels.md)。
|
|
3. 读取 [PSP 主工作流](references/workflow.md)，先形成带来源/hash 的硬件拓扑事实，再确认目标项目目录是固定工作区的直接子目录，并确认是否有参考 PSP、芯片/板卡/系统形态、BSP handoff、差异清单和负责人。目标目录不存在时停止，请用户或团队先创建；不得代为创建目录或初始化仓库。
|
|
4. 首次填充、迁移、提交或更新 PSP 仓库时，读取[项目与 Git 规则](references/project-and-git.md)。首次填充只对预创建的空独立 Git 仓库执行：先在 staging 中适配并审计，验证通过后自动导入并创建本地候选提交，同时保留 `.git`、分支和远端；不再为导入和提交重复询问。已有业务内容的项目转入现有项目更新流程，不得按参考复制覆盖。
|
|
5. 修改 GPIO、BSP 引用、内存/分区结果、Sensor、Media 或 AIPlugin 配置时，读取[配置边界与检查](references/configuration-boundaries.md)。CV181X Media/AI 配置另读[源码与 Release 取值指南](references/cv181x-media-ai-configuration.md)，按每个字段的生效路径、代码行为和实际硬件需求取值。CV18 Sensor 默认按芯片系列使用 skill 内置枚举表；ISP/PQ 由用户更新。PSP 只消费 BSP 和公共组件成果，不越界修改其源码。
|
|
6. 使用 BSP 产物时，读取统一的 [BSP→PSP 交接契约](../firmware-lowlevel-development/references/bsp-psp-handoff.md)，校验用户明确提供的 `psp_handoff.json`；禁止扫描目录选择最新构建。
|
|
7. 需要组包或设备验证时，读取[组包与设备验证](references/packaging-and-device-validation.md)。EMX2.1 的目录和命令按内置固定规则生成本地契约，再做打包准备检查；不用让用户重复提供已经固定的信息。
|
|
8. 需要跨角色交付或返工时，读取 [Etunel 交接](references/etunel-handoff.md)；机器可读文件按[数据契约](references/schemas.md)生成。
|
|
|
|
## PSP 内容边界
|
|
|
|
PSP 仓库可以保存 `psp.json`、项目配置、运行脚本、用户提供的 ISP/PQ/标定参数、必要小型板级资源、精简结果文档和 `metadata/bsp.lock.json`。Skill 不生成或修改 ISP/PQ；保持参考 PSP 的目录和 `psp.json` schema，除非跨层变更已经确认。
|
|
|
|
PSP 仓库不保存固定打包框架、BSP 源码或 IMG、大型模型、公共运行库、烧录包、缓存、原始日志和持续变化的验证记录。HAL、驱动、Bootloader、DTS/DTSI、底层内存实现以及公共 Media/AIPlugin 代码不属于本模块。
|
|
|
|
## 不可绕过的门禁
|
|
|
|
- 新 PSP 优先使用用户明确指定的兼容参考 PSP；没有参考时允许走 `prepare-empty`，但必须独立证明硬件/BSP、应用 `psp.json` schema、Media/AI 精确 Release、运行配置、资源和分区闭包。仅凭 Release 默认值不能形成 candidate；跨平台参考明显不兼容时停止，除非用户知情确认风险。
|
|
- 原理图、规格书、GPIO 表和 BSP handoff 必须先收敛成 `hardware-topology.json`。目标旧配置和参考 PSP（若有）只证明软件现状，不能覆盖硬件资料；资料冲突未解决时停止。
|
|
- 目标 PSP 必须位于当前用户的 `~/work/project/EMX2.1/AppTeam/Psp/<项目名>/`，是该固定根目录的普通直接子目录和独立 Git 仓库。目录缺失、软链接、嵌套仓库或根目录外路径均停止；不运行 `mkdir` 或 `git init` 补齐。
|
|
- 有参考时分别展示修改项和关键继承项；无参考时展示 Release 默认→最终生效值的逐字段差异及每项来源。能由代码、Release、BSP handoff 和硬件资料证明的值不要求用户重复确认；GPIO、Sensor、BSP 固件、Media 或 AIPlugin 有冲突、缺项或多种合理解释时阻止形成 `candidate`。
|
|
- CV181X 的 `sensor_cfg.ini` 中 `name` 必须填写内置 `sensor_list.h` 的 `_SAMPLE_SNS_TYPE_E` 枚举名称；CV184X 必须填写内置 `sensor_cfg.h` 的 `_SNS_TYPE_E` 对应枚举值。规格选型不明确或内置表中无匹配项时停止，不得猜测；只有已证明 SDK 枚举不同才使用显式头文件覆盖。
|
|
- 保留团队统一环境中的绝对路径；检查全部 JSON 和配置/脚本文本。允许公共构建根路径；个人目录和临时目录必须警告，正式交付仅在用户显式批准精确根路径后放行。
|
|
- `psp.json`、BSP handoff、配置接口或依赖基线不匹配时，不通过寻找近似文件、选择最新目录、静默覆盖或降低检查来继续。
|
|
- 需求和适配方案已经确认后，完整差异和打包准备检查通过即自动完成本地导入、`git add`、候选提交、应用工程内既有 `psp` 子模块更新、`./product.py` 和 `./release.py 0`，不再请求执行确认。自动范围不包括创建或更换子模块地址、提交应用仓库、Git 上传、Etunel 交接、`accepted/revoked` tag、`./release.py 1`、设备烧录和发布。
|
|
- 自动步骤出现脏工作区重叠、仓库或 commit 不一致、子模块缺失、脚本/路径变化、检查失败、命令报错、产物不唯一或需要清理重试时立即停止。先保存证据，再请用户确认处理方式；不得自行覆盖、丢弃改动、修改应用框架或改用 `./release.py 1`。
|
|
- 同一阻塞条件没有变化时，不重复发整套问题。只说明缺少的证据、它阻止哪一步，以及由谁补充。
|
|
- 输出警告时按“阻止继续”“需要确认”“暂不影响当前步骤”分组；目标机路径在主机不存在、ISP/PQ 待用户更新等已知情况不得与真实组包错误混在一起。
|
|
- `packaged`、`device_verified`、`app_integrated` 和 `accepted` 必须引用真实证据与同一个完整 PSP commit。人工设备结果标记为 `USER_REPORTED`，未执行项不得写成通过。
|
|
- 完成时按[记录规范](../firmware-lowlevel-development/references/records.md)和[统一交付契约](../firmware-lowlevel-development/references/deliverable-contract.md)报告；没有有效 Etunel 上下文时只生成交接材料，不声称已发送。
|
|
|
|
## 确定性辅助工具
|
|
|
|
- `scripts/psp/psp_project_guard.py`：用 `inspect` 只读校验固定 PSP 根目录、项目路径和独立仓库并区分空仓库/现有项目；首次填充时受控复制到 staging，检查差异白名单与旧项目残留，验证通过后自动导入内容、复核最终目录且证明 Git 分支/远端未改变；不创建目录、不初始化仓库。
|
|
- `scripts/psp/validate_hardware_topology.py`：校验证据文件/hash、存储和每路 Sensor 物理事实，并用显式 `config_expectations` 对照唯一 `sensor_cfg.ini`。
|
|
- `scripts/psp/analyze_psp_delta.py`：同时比较目标 HEAD、目标 worktree、参考 HEAD 和参考 worktree，区分稳定参考、参考未提交改动、目标特有改动和未分类冲突。
|
|
- `scripts/psp/audit_cv181x_media_ai.py`：只读枚举 CV181X 精确 Media/AI Release 的全部 JSON 叶子字段、默认值/hash、源码读取位置线索，核对 SDK/ABI 标识、VPSS 图和 PSP 候选差异；不把代码命中或静态通过当成硬件正确性证明。
|
|
- `scripts/psp/validate_bsp_handoff.py`：校验 BSP handoff、权限证据、精确 imgs 路径和产物 hash。直接运行默认只读；PSP 已确认的适配流程自动在证据和项目身份一致时修复本次输出的 `a+rX` 权限并复核，失败则阻止 candidate。
|
|
- `scripts/psp/validate_psp.py`：校验 PSP 结构、配置语法、路径、脚本、CV18 Sensor 枚举映射和应用/PSP 覆盖关系；根据 `--expected-chip` 自动选择内置 CV181X/CV184X 头文件，通常无需 `--sensor-enum-header`。
|
|
- `scripts/psp/validate_partition_closure.py`：从 `psp.json` 推导完整分区 offset/size，逐项核对 Boot/Default 镜像值，并按 UBI LEB/PEB 与保留块校验 `mkAiData.py` 参数。
|
|
- `scripts/psp/record_packaging_result.py`：用 `contract` 根据 EMX2.1 固定目录和命令生成本地契约；用 `preflight` 在候选提交前和正式组包前检查资源来源、DATA 工具、分区字段、BSP 分区余量与应用脚本；用 `snapshot/record` 证明本轮唯一新增的 `output/<版本>/` 及指定烧录包并记录路径、大小和 hash。工具不执行打包命令。
|
|
- `scripts/psp/render_psp_handoff.py`：把同一 commit 的验证证据汇总为供用户确认或 Etunel Hub 使用的交接文件，并可只读核对远端 commit；不发送消息。
|