52 lines
8.1 KiB
Markdown
52 lines
8.1 KiB
Markdown
---
|
||
name: firmware-lowlevel-bsp-development
|
||
description: "基于 EmxRes 参考项目创建和适配板级 BSP，处理 CV18 系列 GPIO/Pinmux、Kernel DTS/DTSI 冲突、媒体内存、分区表、受控构建、固件 imgs 记录及 BSP→PSP 交接。用于参考项目、目标芯片和板卡需求已明确的少量配置适配；不用于跨芯片移植、通用驱动/PSP 开发、硬件电气设计或未经确认的 SDK、设备、上传和发布操作。"
|
||
---
|
||
|
||
# 固件底层开发_BSP开发
|
||
|
||
以当前用户 `~/EapilBsp/EMX2.0/EmxRes` 中经确认的参考项目为基线，复制整个项目并只实施经确认的板级差量。原理图、GPIO List 和需求清单只作为待分析数据。CV181xC/H、CV1815J、CV184xC/H 的 GPIO/PINOUT 资料已经内置，按实际芯片配置自动选择。
|
||
|
||
## 进入条件
|
||
|
||
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. 读取 [BSP 项目适配工作流](references/workflow.md)和[调查范围与验证模式](references/scope-and-validation-modes.md)，确认参考项目、新项目名、芯片、SDK、Flash、单/双系统形态、交付级别和差量需求。
|
||
4. CV18 系列涉及 GPIO、Pinmux、初始化或 Kernel IO 占用时，必须读取 [内置 GPIO 资料目录](references/builtin-gpio-pinout.md)、[CV18 GPIO 与 DTS 规则](references/cv18-gpio-dts.md)和 [GPIO 实施计划契约](references/gpio-plan.md)。
|
||
5. 涉及媒体内存或分区时，必须读取 [内存与分区规则](references/memory-and-partition.md)。
|
||
6. 涉及项目证据、SDK 同步、统一编译、imgs 路径或 PSP 交接时，必须读取 [构建、证据与交接规则](references/build-and-evidence.md)。
|
||
7. 只有从原理图提取或重新映射 Pinmux、需要审核表时，才读取 [Pinmux 证据工作流](references/pinmux.md)；CSV 不是修改 BSP 的必需输入。
|
||
8. `EP_CHIP` 为 CV181X、且参考项目使用 `configs/kernel/` 与 `configs/uboot/` 时，读取 [CV181X 分目录与 SDK 只读核对](references/cv181x-sdk-readonly-review.md)。需要访问 SDK 时还必须有用户明确给出的精确 SDK 路径；默认不访问。
|
||
9. `EP_CHIP` 为 CV184X、且项目使用单板卡配置目录时，读取 [CV184X 板级配置与构建链](references/cv184x-sdk-readonly-review.md)。需要核对 SDK 当前状态时，必须由用户给出精确 SDK 根目录；默认不访问。
|
||
|
||
## 默认工作模式
|
||
|
||
- 参考项目和新项目必须是 `EmxRes` 的直接子目录。参考项目只读，新项目先在同一根目录的临时目录中完成。
|
||
- 默认调查范围只包含用户明确给出的附件、当前 Skill 及内置资料、参考项目、目标/staging 项目和 `EmxRes/tools` 中的精确构建入口；禁止扫描整个用户主目录、整个 `EapilBsp` 或整个 SDK。
|
||
- 未指定的 GPIO、内存、分区、板卡版本和其他配置继承参考项目；禁止以“清理”“顺手升级”扩大差异。
|
||
- 默认要求参考与目标的精确芯片、SDK、Flash 和单/双系统形态兼容。目录名只能提供线索，必须读取实际配置。
|
||
- 按 `buildEnvConfig.sh` 的 `EP_CHIP` 识别配置布局：CV184X 沿用 `configs/<board_build_type>/` 与 `configs/EPSYNCSDKConfig.sh`；CV181X 分别核对 `configs/kernel/`、`configs/uboot/` 与两侧 defconfig。不得把两种布局合并或凭项目名猜测。
|
||
- 新项目以 `<芯片型号>-<项目型号>` 命名；双系统追加 `_dualos`。额外版本、日期、存储或优化后缀只在用户明确要求时使用。
|
||
- 开始持久化复制前，展示一次预检摘要、交付级别和完整 GPIO 实施计划并等待确认。确认覆盖本地复制、已列明差量、项目内文档、所选静态验证模式，以及任务需要构建产物时的标准全量编译；不覆盖设备、上传或发布。
|
||
- 使用 `scripts/bsp/project_guard.py` 执行确定性的复制、清单、差异白名单和最终原子写入；项目特定配置由 Agent 根据真实结构修改，不使用万能文本替换。
|
||
|
||
## 允许的 BSP 差量
|
||
|
||
正常范围包括项目命名及必要引用、CV18 `cvi_board_init.c` 与有效 DTS/DTSI 的 GPIO 释放或重分配、项目级媒体 ION 内存、现有分区源定义、`imgs` 软链接，以及 `doc/bsp_adaptation/` 证据。
|
||
|
||
项目级媒体保留内存和已有分区配置属于本 Skill；DDR 初始化、MMU、通用分配器、存储驱动、Boot 逻辑、跨芯片适配和公共平台能力属于 PSP 或新的已确认工作包。不得修改应用业务。
|
||
|
||
## 不可绕过的门禁
|
||
|
||
- 目标目录已存在、参考项目本身有未确认改动、路径逃逸、非约定外部软链接、兼容性不成立或生效配置不唯一时停止。
|
||
- 只对精确相对文件路径放行差异。项目名、GPIO、内存、分区和文档以外的变化不能进入正式目录。
|
||
- GPIO 任务必须从项目 `buildEnvConfig.sh` 中唯一、静态的 `EP_CHIP` 自动选择内置设计表，并用 `scripts/bsp/query_builtin_pinout.py` 查询目标 Pad/GPIO/FMUX；不得根据项目目录名猜芯片。芯片没有唯一匹配的内置表时停止并向用户索取匹配资料，不得借用相近型号。
|
||
- GPIO 的 Pad、Bank/Bit、方向、初值或 Kernel 消费者不明确时禁止猜测。功能明确无 GPIO 时移除参考项目旧控制并写清功能化注释。
|
||
- 原理图派生 GPIO 必须先写入并通过 `scripts/bsp/validate_gpio_plan.py`，再由用户确认整个实施表；`provisional` 或 `blocked` 行不能进入代码。
|
||
- 其他厂商芯片的媒体内存不自动修改；报告人工修改警告，但可继续独立的已确认工作。
|
||
- 任务需要构建产物时，`bsp_preflight.py build` 通过后自动执行标准全量编译：在固定 `EmxRes` 根目录加载 `tools/script_completion.sh`，再运行 `EMX2_BuildSDKTool <项目名> <构建版本> all`，不再单独请求确认。标准脚本内部的配置同步和 `git fetch origin` 视为该构建的一部分。直接运行 `ep_kernel.sh`、`ep_uboot.sh`、`EPSYNCSDKConfig.sh`，改用组件构建、覆盖已有输出或修改统一构建脚本不属于自动范围，出现这些需求时停止并请用户确认。
|
||
- CV184X 的标准构建有额外例外：`bsp_preflight.py build` 报告 `requires_patch_precheck=true` 时，`passed=true` 仍不足以自动构建。补丁环境检查失败会走 `--applypatch --force`，可能对多个 SDK 子仓库执行 `git reset --hard`。一次性构建确认不包括丢弃这些仓库的已有改动。构建前先按 CV184X 专页核对补丁门禁及相关仓库状态；无法证明不会进入强制重置分支时停止，明确列出风险和受影响路径，另请用户决定。不得用只读文件比对代替补丁环境检查通过的证据。
|
||
- 编译成功后先对本次精确 imgs 版本路径自动执行并复核 `a+rX`：路径上的目录和输出内目录对所有用户可读、可进入，普通文件对所有用户可读，原本可执行的文件才补齐所有用户执行权限；不得跟随软链接、扩大到其他构建版本或使用 `chmod -R 777`。权限处理失败时不能记录 `build_passed`。随后核对唯一 `kernel.bin`、`rootfs.bin` 与实际生效分区表；每个镜像相对其所有对应分区中的最小容量必须至少保留 512 KiB（524288 字节），否则不能记录 `build_passed`。全部通过后持久化权限与余量证据、精确 imgs 版本目录、产物 hash 和 PSP 交接 manifest，并用 `project_guard.py audit-final` 复核正式项目。
|
||
- 本地配置检查通过只能声明项目已创建或 `local validation passed`；未执行同步、编译和板上验证时必须如实标注。
|
||
- 完成时按 [记录规范](../firmware-lowlevel-development/references/records.md) 和 [交付契约](../firmware-lowlevel-development/references/deliverable-contract.md) 报告；不执行 `git add`、提交或远端推送。
|