firmware-lowlevel-development/skills/firmware-lowlevel-bsp-development/SKILL.md

name, description

name	description
firmware-lowlevel-bsp-development	基于 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. 先读取并遵守统一的流程文档写法，所有面向人的流程文档使用简体中文和直白表达。
2. 读取统一入口的 项目所有权契约、治理工作流 和 风险等级。
3. 读取 BSP 项目适配工作流和调查范围与验证模式，确认参考项目、新项目名、芯片、SDK、Flash、单/双系统形态、交付级别和差量需求。
4. CV18 系列涉及 GPIO、Pinmux、初始化或 Kernel IO 占用时，必须读取 内置 GPIO 资料目录、CV18 GPIO 与 DTS 规则和 GPIO 实施计划契约。
5. 涉及媒体内存或分区时，必须读取 内存与分区规则。
6. 涉及项目证据、SDK 同步、统一编译、imgs 路径或 PSP 交接时，必须读取 构建、证据与交接规则。
7. 只有从原理图提取或重新映射 Pinmux、需要审核表时，才读取 Pinmux 证据工作流；CSV 不是修改 BSP 的必需输入。
8. EP_CHIP 为 CV181X、且参考项目使用 configs/kernel/ 与 configs/uboot/ 时，读取 CV181X 分目录与 SDK 只读核对。需要访问 SDK 时还必须有用户明确给出的精确 SDK 路径；默认不访问。
9. EP_CHIP 为 CV184X、且项目使用单板卡配置目录时，读取 CV184X 板级配置与构建链。需要核对 SDK 当前状态时，必须由用户给出精确 SDK 根目录；默认不访问。

开发范围与准确表述

BSP 开发改动只写入当前 EmxRes/<项目名> 及其 staging 项目；SDK 在调查阶段只读。已确认的原生全量编译会将 RES 配置同步到 SDK，并写入生成文件，这属于构建实际写入，不能承诺 SDK 目录完全不变。不得把 SDK 同步目标列为人工开发修改清单。

形成方案、说明 SDK 差异或报告构建结果前，读取并遵守 RES、SDK 与表述边界。SDK 编辑、软链接改造、已有改动恢复及共享构建脚本修改均不属于默认 BSP 工作范围。

默认工作模式

• 参考项目和新项目必须是 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 差量

正常范围限于当前 RES 项目中的项目命名及必要引用、CV18 cvi_board_init.c 与有效 DTS/DTSI 的 GPIO 释放或重分配、项目级媒体 ION 内存、现有分区源定义、imgs 软链接，以及 doc/bsp_adaptation/ 证据。SDK 中的对应路径只作为调查映射和原生构建同步目标。

项目级媒体保留内存和已有分区配置属于本 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 的补丁检查由项目统一编译脚本负责；Skill 不额外运行 --check-env、检查补丁完整性或访问 SDK 子仓库。不得主动或通过统一脚本自动执行 --applypatch --force。构建预检只读取精确的项目构建入口，发现该脚本可能调用强制打补丁时停止，不运行编译；先由构建脚本所有者改成失败即返回错误，不代改共享脚本、不通过检查通过与否绕开风险。安全入口就绪后运行原生全量编译，记录真实退出码、失败原因和产物结果。
• 编译成功后先对本次精确 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；未执行同步、编译和板上验证时必须如实标注。
• 完成时按 记录规范 和 交付契约 报告；不执行 git add、提交或远端推送。