87 lines
9.1 KiB
Markdown
87 lines
9.1 KiB
Markdown
# PSP 配置边界与检查
|
||
|
||
## PSP 可以维护
|
||
|
||
- 参考 PSP 已有的 `psp.json` 字段和目录布局；
|
||
- `configs/`、`param/`、`scripts/` 和项目实际采用的等价目录；
|
||
- 应用可见的 IO/GPIO 语义、LED/按键/IRCUT/PWM/PTZ 等运行配置；
|
||
- Sensor、Media 和 AIPlugin 的项目级配置与 profile；
|
||
- BSP IMG 的绝对路径引用、最终内存/分区摘要和依赖锁定；
|
||
- 用户提供的 ISP/PQ、标定参数、Logo 等必要的小型平台资源；
|
||
- 精简结果文档和 sidecar metadata。
|
||
|
||
固定打包框架、BSP IMG、大型模型、公共运行库、构建缓存、烧录包及持续变化的日志/验证记录不进入 PSP 仓库。
|
||
|
||
## 不取得的所有权
|
||
|
||
PSP 不直接修改 BSP 的 `cvi_board_init.c`、DTS/DTSI、驱动、Bootloader、分区表或内存实现。CV181X 的 `memmap.py/ION_SIZE`，以及 CV184X board defconfig 中的 `CONFIG_ION_SIZE`、`CONFIG_RTOS_ION_SIZE` 由 BSP 工作流根据用户明确的媒体内存需求修改。SigmaStar 等未提供规则的平台由用户手工处理，并保留警告。
|
||
|
||
PSP 可以保存和核对最终值。Media/AIPlugin 需求要求改变 BSP 时，生成需求清单，经 Etunel Hub 路由 BSP；接收新的 BSP handoff 后再更新 PSP。
|
||
|
||
PSP 也不修改 Media/AIPlugin 公共源码、训练/转换模型、ISP/PQ 配置或伪造兼容版本；缺少上游成果时交 Hub 路由。
|
||
|
||
## GPIO 一致性
|
||
|
||
交叉核对 BSP handoff/Pinmux 结果与 PSP 中实际存在的 GPIO 配置，包括但不限于：
|
||
|
||
- `configs/bsp.json`；
|
||
- `scripts/pinmux.sh`；
|
||
- `configs/ptz/motorGpio.json`；
|
||
- 其他包含 GPIO 编号和应用语义的配置。
|
||
|
||
发现 GPIO 被 BSP、DTS/DTSI 或其他设备树模块占用时，停止 PSP 验收并提出 BSP 变更请求。没有对应 GPIO 时明确记录“无此 GPIO”，不伪造编号。PSP 只修改自己的运行语义，不越界释放 Kernel IO。
|
||
|
||
## CV18 Sensor 配置基线
|
||
|
||
CV18 系列以 PSP 内唯一的 `sensor_cfg.ini` 为主要 Sensor 配置。文件可能位于参考 PSP 的 `configs/media/sensor/`、`configs/media/isp/` 或等价目录；保持参考布局，不为统一目录而搬移。存在多个同名候选、没有候选、软链接或无法确认当前生效文件时停止。
|
||
|
||
先从原理图或 GPIO list 确认 Sensor 型号、数量、I2C bus/address、MIPI device/lane、P/N swap、MCLK、reset/power GPIO 等实际字段，再用规格书中的 Sensor 类型锁定枚举标识符。不得只凭相近命名、参考板旧值或枚举数字猜选型。每个 `[sensor]`、`[sensor2]` 等实际启用 section 都要分别给出规格书选定的枚举名称和依据。
|
||
|
||
Sensor 拓扑变更的依赖闭包至少包含：唯一 `sensor_cfg.ini`、Media profile/config/param、ISP/PQ 文件引用和 hash、AIPlugin 通道/输入配置、pinmux/reset/power/MCLK/PWM 脚本，以及与通道数有关的资源拷贝映射。只改 `sensor_cfg.ini` 不算闭环；不适用项也要写明原因。
|
||
|
||
Skill 已内置本流程确认的两份枚举基线，运行时不得再到 SDK 目录或附件目录中搜索“最新”或相近文件：
|
||
|
||
- [CV181X `sensor_list.h`](sensor-enums/cv181x/sensor_list.h)，用于 `_SAMPLE_SNS_TYPE_E`；
|
||
- [CV184X `sensor_cfg.h`](sensor-enums/cv184x/sensor_cfg.h)，用于 `_SNS_TYPE_E`。
|
||
|
||
`validate_psp.py` 根据 `--expected-chip` 自动选择对应内置文件并在结果中记录内置路径和 SHA-256。若规格书 Sensor 在内置表中不存在，或项目资料明确证明目标 Media SDK 使用不同枚举版本，停止自动适配并报告基线差异；不得退回目录扫描或猜测近似枚举。此时可在用户提供精确新头文件后用 `--sensor-enum-header` 显式覆盖并记录 `source=override`，随后应按独立 skill 更新流程评审是否替换内置基线。
|
||
|
||
配置规则如下：
|
||
|
||
- CV181X（CV1810、CV1811C、CV1815JA 等）：读取 `sensor_list.h` 中 `typedef enum _SAMPLE_SNS_TYPE_E`，`sensor_cfg.ini` 的 `name` 填枚举名称，例如 `SMS_SC4336P_MIPI_4M_30FPS_10BIT`，不能填枚举序号或自行换算值。
|
||
- CV184X（CV1841CP、CV1842CP、CV1842HP、CV1843HP 等）：读取 `sensor_cfg.h` 中 `typedef enum _SNS_TYPE_E`，先按规格确定枚举名称，再把该枚举的显式整数值写入 `sensor_cfg.ini` 的 `name`；建议保持头文件中的十六进制表达形式。结果同时记录枚举名称和值，不能只记录一个无来源数字。
|
||
|
||
调用 `validate_psp.py` 时无需提供头文件路径；只需为每个实际 Sensor section 根据规格选型生成 `--expected-sensor sensor=ENUM_NAME`、`--expected-sensor sensor2=ENUM_NAME`。工具会自动选取内置头文件，记录 `sensor_cfg.ini` 与枚举表 hash，并按芯片系列验证名称或数值表示；枚举不存在、数值不可解析、section 缺少规格期望或配置不一致均阻止 candidate。`--sensor-enum-header` 仅用于上述已确认的版本差异覆盖，不是日常必需输入。
|
||
|
||
## ISP/PQ 用户边界
|
||
|
||
ISP 和 PQ 文件由用户更新，Skill 不生成、不选择、不修改，也不把参考值自动声明为适配完成。若参考 PSP 已包含这些文件，保留其目录和内容，把状态记录为 `USER_OWNED/PENDING`；用户提供更新后记录精确文件/hash 和 `USER_REPORTED` 确认。ISP/PQ 未更新不阻止完成 PSP 的其他静态检查，但相关设备检查保持未执行或风险项，不能据此声称图像效果已经通过。
|
||
|
||
ISP/PQ 清单必须同时证明配置中的实际引用、文件存在性和 SHA-256。缺文件、引用旧文件、目录里有文件但没有任何生效引用，均不能标为已更新；Sensor 型号、数量、lane 或 ISP profile 变化后，旧确认自动失效。
|
||
|
||
## Media 与 AIPlugin
|
||
|
||
CV181X 的新项目或 Media/AI 变更先读[源码与 Release 取值指南](cv181x-media-ai-configuration.md)，并用 `audit_cv181x_media_ai.py` 按精确 Release/profile 枚举全部字段、默认值、代码读取线索、最终 PSP 差异和 VPSS 通道图。`source_hits_hint_only` 不是语义证明；每个拟修改字段仍要从代码、当前 SDK 枚举/范围、产品需求或硬件事实确认。没有参考 PSP 时不得把 Release 配置直接当成完整 PSP，也不能因为字段目录存在就认为系统可运行。
|
||
|
||
至少核对：Media 版本、Sensor 型号/数量/总线、用户负责的 ISP/PQ 状态、AIPlugin 版本、AIPlugin profile 的 SDK、模型平台和运行库目录。版本冲突默认阻塞；只有有实际负责人确认的兼容例外才能继续，并写入最终结果。
|
||
|
||
未声明的参考配置可以继承，但必须把关键继承项列给用户确认。Media 或 AIPlugin 未提供差异不等于自动禁用，也不等于其真实兼容。
|
||
|
||
Media 的运行库或驱动列表为空时默认阻塞。只有存在 `metadata/media-runtime-exception.json`，明确替代来源、目标路径、文件/hash、适用 Media 版本、原因、负责人和确认时间，并在当前应用工程验证替代来源真实存在，才能按例外继续。空列表不能只靠口头说明或“系统里已有”放行。
|
||
|
||
BSP build 变化的依赖闭包至少包含：`psp.json` 全部 BSP/IMG 资源路径、`metadata/bsp.lock.json`、驱动/模块资源映射、Boot/Default、旧 build ID/旧路径残留。分区变化的依赖闭包至少包含：`psp.json` 分区顺序/大小/file、Boot/Default 的 offset/size/mtdparts/内嵌 partition JSON、所有 MTD 索引、DATA 工具映射、`release.py` 的 `mkAiData.py` 参数和最终分区 CSV/摘要。
|
||
|
||
## `psp.json` 和绝对路径
|
||
|
||
应用打包代码已依赖参考 `psp.json`，因此默认保持文件名、层级和字段。新增 BSP lock、允许覆盖和治理信息使用 `metadata/` sidecar；变更 `psp.json` schema、文件名、目录、启动调用或应用可见 GPIO 语义时，先通过 Etunel 取得技术负责人和应用层确认。
|
||
|
||
应用层与底层共用 BSP 环境，所以保留 `psp.json` 的绝对路径。路径检查覆盖 PSP 中所有 JSON，以及 `.ini`、`.cfg`、`.conf`、`.sh`、`.py` 文本，不能只检查 `psp.json`。允许团队公共构建根；`/home/<用户>`、`/tmp`、`/var/tmp` 等个人/临时路径必须警告，正式交付默认失败。只有用户确认的共享根或本轮验证根才能通过重复的 `--allowed-absolute-root <精确绝对路径>` 放行，放行记录必须进入验证结果。外部构建输入不存在时失败，其他配置/脚本路径不存在时至少警告；不得自动寻找名称相近或日期更新的替代物。
|
||
|
||
## 同名配置覆盖
|
||
|
||
现有打包顺序允许 PSP 后复制并覆盖应用配置，但不能静默覆盖。比较应用 `orgConfigs` 与 PSP `configs`、应用 `orgParam` 与 PSP `param` 等真实映射，输出相对路径、双方 hash 和最终生效方。
|
||
|
||
默认保留应用工程中的 `orgConfigs`、`orgParam`，并从 PSP 候选内容中移除重复的同名文件。这样不会让参考 PSP 在组包时意外覆盖应用配置，也不需要用户逐个确认“继续保留应用值”。
|
||
|
||
只有硬件适配确实要求 PSP 成为最终生效方时，才向用户展示双方路径、hash、差异和影响，并在确认后把精确路径写入 `metadata/allowed-overrides.json`。不要为绕过门禁添加通配符；schema 见[数据契约](schemas.md)。
|