49 lines
8.0 KiB
Markdown
49 lines
8.0 KiB
Markdown
---
|
|
name: firmware-lowlevel-psp-development
|
|
description: "基于相近板卡 PSP 创建、修改和验证项目级平台配置，锁定 BSP 固件、Media 与 AIPlugin 依赖，并通过固定打包环境形成可交给应用层的精确 Git 基线。用于 PSP 配置适配、组包证据、人工设备验证和 Etunel 交接；不用于 BSP/DTS/驱动实现、应用业务、公共组件开发或未经确认的烧录、上传与发布。"
|
|
---
|
|
|
|
# 固件底层开发_PSP开发
|
|
|
|
把每个硬件项目的 PSP 作为独立、轻量的配置仓库维护。PSP 固定工作区是当前用户的 `~/work/project/EMX2.1/AppTeam/Psp/`；项目目录由用户或团队预先在该根目录下创建。以用户指定的相近板卡 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)，确认目标项目目录是固定工作区的直接子目录，并确认参考 PSP、芯片/板卡/系统形态、BSP handoff、差异清单和负责人。目标目录不存在时停止，请用户或团队先创建；不得代为创建目录或初始化仓库。
|
|
4. 首次填充、迁移、提交或更新 PSP 仓库时，读取[项目与 Git 规则](references/project-and-git.md)。首次填充只对预创建的空独立 Git 仓库执行：先在 staging 中适配并审计，验证通过后自动导入并创建本地候选提交，同时保留 `.git`、分支和远端；不再为导入和提交重复询问。已有业务内容的项目转入现有项目更新流程，不得按参考复制覆盖。
|
|
5. 修改 GPIO、BSP 引用、内存/分区结果、Sensor、Media 或 AIPlugin 配置时，读取[配置边界与检查](references/configuration-boundaries.md)。CV18 Sensor 默认按芯片系列使用 skill 内置枚举表，把规格书选型自动映射为配置名称或数值；无需临时查找 SDK 头文件。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；先核对芯片系列、系统形态、存储介质、Sensor、GPIO、媒体和 AIPlugin 能力。明显不兼容时停止，除非用户知情确认跨平台参考。
|
|
- 目标 PSP 必须位于当前用户的 `~/work/project/EMX2.1/AppTeam/Psp/<项目名>/`，是该固定根目录的普通直接子目录和独立 Git 仓库。目录缺失、软链接、嵌套仓库或根目录外路径均停止；不运行 `mkdir` 或 `git init` 补齐。
|
|
- 默认继承参考 PSP，但必须分别展示修改项和关键继承项。能由参考兼容性、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_bsp_handoff.py`：校验 BSP handoff、精确 imgs 路径和产物 hash。
|
|
- `scripts/psp/validate_psp.py`：校验 PSP 结构、配置语法、路径、脚本、CV18 Sensor 枚举映射和应用/PSP 覆盖关系；根据 `--expected-chip` 自动选择内置 CV181X/CV184X 头文件，通常无需 `--sensor-enum-header`。
|
|
- `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；不发送消息。
|