# hlca **Repository Path**: elvin_gitee/hlca ## Basic Information - **Project Name**: hlca - **Description**: HLCA 固件工程模板 - **Primary Language**: Unknown - **License**: LGPL-2.1 - **Default Branch**: main - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2026-11-12 - **Last Updated**: 2026-11-16 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # HLCA 落地包(骨架 + 指南)v1.1.0 一个仓装下 HLCA 的**骨架与指南**;**技能**是独立仓 [`hlca-firmware-dev`](https://gitee.com/elvin_gitee/hlca-firmware-dev) (以 submodule 引入到 `.dsh/skills/`,父仓只钉 gitlink commit,不存源码)。 本仓不是某个具体项目:芯片事实默认全空,未填全时全链构建按设计失败。 | 产物 | 位置 | 作用 | 版本标识 | |---|---|---|---| | **骨架** | 仓库根(`app/ service/ driver/ bsp/ framework/ …`) | 可运行基线:四层 + 钩子/事件队列/调度器 + CMake 三门 + 门禁 | `cmake/template-version.cmake` | | **技能**(独立仓) | clone 到 `.dsh/skills/hlca-firmware-dev/` | 做法与验收口径 + 层规则/技能自检脚本;DSH 直接加载 | 技能仓 tag = `SKILL.md` 的 `metadata.version` | | **指南** | `docs/guide/` | 量产指南、技能评审报告、跨平台编译建议(设计依据) | — | `git clone` 得到骨架起手式,再按 [docs/new-project.md](docs/new-project.md) 删模板历史、 改工程身份、填芯片事实、放 SDK、跑门禁;技能另按需 clone: ```powershell git clone --depth 1 git@gitee.com:elvin_gitee/hlca.git <新工程目录> git clone https://gitee.com/elvin_gitee/hlca-firmware-dev.git <新工程目录>/.dsh/skills/hlca-firmware-dev ``` ## 目录 ``` . ├── app/ 组合根:钩子接线、业务决策(唯一允许 hook_register 的层) ├── service/ 状态机、去抖、协议、阈值 ├── driver/ 硬件语义化封装 ├── bsp/ 寄存器/中断/时钟;唯一允许碰 SDK 的层 ├── framework/ 调度器、钩子、事件队列、时间、临界区、错误码、断言、故障记录 ├── tests/host/ 主机单测(CTest) ├── cmake/ toolchain / 芯片事实(mcu-config)/ size 门禁 / 模板版本 ├── .dsh/skills/ 技能 submodule(hlca-firmware-dev / hlca-third-party-libs,独立仓 pin commit) ├── docs/ new-project、build-profile、project-facts、hook-wiring、error-actions、 │ guide/(量产指南等依据)、reference/、reviews/ ├── third_party/ sdk(厂商原样放入 `third_party/sdk//`)+ libs(基线仓 submodule)+ PATCHES.md ├── scripts/ 门禁:check_template(含 arch-manifest.txt 路径清单)/ check_copy_sync / check_layers / │ check_cmake / gates;工具:flash(烧录)/ sdk_scan(SDK 探测)/ stage_tag(先验证后打阶段标) ├── openocd/ 烧录配置槽位 ├── .github/workflows/gates.yml CI:先 clone 技能仓 → 技能自检 + 骨架门禁 + 副本一致性 └── main.c 目标端入口(层目录之外,不承载业务) ``` ## 门禁(CI 与本地同一组命令) ```powershell # 0) 落地包完整性:mcu-config 全空、SDK 槽位为空、路径清单(scripts/arch-manifest.txt)、技能是 submodule powershell -NoProfile -ExecutionPolicy Bypass -File scripts/check_template.ps1 # 1) 副本一致性:技能与工程两边的 check_layers 必须字节一致(未 clone 技能时跳过) powershell -NoProfile -ExecutionPolicy Bypass -File scripts/check_copy_sync.ps1 # 2) 层规则(R1~R9)与构建体检 powershell -NoProfile -ExecutionPolicy Bypass -File scripts/check_layers.ps1 -Root . powershell -NoProfile -ExecutionPolicy Bypass -File scripts/check_cmake.ps1 -Root . # 3) 技能自检(需先 clone 技能仓到 .dsh/skills/hlca-firmware-dev) powershell -NoProfile -ExecutionPolicy Bypass -File .dsh/skills/hlca-firmware-dev/scripts/check_skill.ps1 powershell -NoProfile -ExecutionPolicy Bypass -File .dsh/skills/hlca-firmware-dev/scripts/check_generic.ps1 # 4) 主机单测 / 目标端编译门 / 全链必须失败 cmake --preset host; cmake --build --preset host; ctest --preset host cmake --preset syntax; cmake --build --preset syntax cmake --preset debug # 期望非 0:一次列出全部缺失芯片事实 # 一键:上面的静态检查 + 主机单测 powershell -NoProfile -ExecutionPolicy Bypass -File scripts/gates.ps1 ``` ## 烧录(默认 OpenOCD,探针由你选) ```powershell scripts/flash.ps1 -Detect # 工具探测:openocd / 版本 / scripts 目录 scripts/flash.ps1 -InitProbe -Persist # 选探针并写入项目事实(如 stlink/jlink/picoprobe 等) scripts/flash.ps1 -Check # 事实 + .elf 校验(不擦写) scripts/flash.ps1 -DryRun # 打印将执行的 openocd 命令行 scripts/flash.ps1 -Execute # 真烧录(打印板卡/探针/target 三要素) # 等价:cmake --build --preset flash / flash-check ``` 细节与失败排查:`.dsh/skills/hlca-firmware-dev/references/flash-and-debug.md`。 验收标准:`check_template` / `check_copy_sync` / `check_layers` / `check_cmake` / `check_skill` / `check_generic` 全部 0 error,主机单测全绿,编译门全绿,`debug` 必须失败。 ## 铁律(复制到项目后依然生效) 1. 依赖只向下:`app → service → driver → bsp → 厂商 SDK`;`driver/` 及以上出现 `HAL_`/`LL_` 即违规。 2. 向上通信只走钩子;`hook_register` 只允许出现在 `app/`。 3. 零跨模块 `extern`;模块内部状态全 `static`;全系统禁 `malloc/free`。 4. 中断只 `eventq_post`:不 `hook_fire`、不打印、不阻塞。 5. 前后台共享多字节变量进临界区(保存/恢复 PRIMASK)。 6. 跨模块 API 统一 `err_t` + `RETURN_IF_ERR`,每类错误必须有动作(`docs/error-actions.md`)。 7. 芯片事实只写在 `cmake/mcu-config.cmake`:未确认就留空并让构建失败,**不许填经验默认值**。 ## 三件套的分工 - **技能**定做法与口径(分层方向、钩子语义、六阶段准出、评审判级),并自带 `check_layers` 等门禁脚本; 它不写任何项目事实(型号/晶振/主频/容量/SDK 版本),`check_generic` 会扫。 - **骨架**是技能的**可运行实例**:同一个 `fw_eventq` 满队列策略、同一个超期语义、同一套门禁版本。 - **指南**是设计预想与依据(`docs/guide/`),与技能冲突时以技能为准,并把结论回写指南(项目里落 ADR)。 ## 版本与升级 - 本仓 tag 发布骨架 + 指南(当前 `v1.1.0` = 骨架 v1.0.0 基线 + 指南归档); 技能另有自己的版本线(技能仓 tag = `SKILL.md` 的 `metadata.version`,当前 v2.24)。 项目实例在 `cmake/template-version.cmake` 与 `docs/build-profile.md` 记录来源 tag + sha。 - **可同步区**:`framework/`、`scripts/`、`cmake/`(除 mcu-config 项目值)、`tests/host/` 通用部分。 - **项目区**:`app/`、`service/`、`driver/`、`bsp/` 与项目自建的 `docs/adr/`(main 不保留 ADR)。 - **注释里的 ADR 编号**:代码/文档注释中的 `ADR 00xx` 是设计决策的稳定标识(例如事件队列语义、 看门狗进度序列),其正文在**实例分支**的 `docs/adr/` 与技能口径中;main 不保留 ADR 目录, 这些编号只作交叉索引,不是本仓的文件链接。 - 升骨架 = 比对本仓 tag 间 diff,只合可同步区;升技能 = `git submodule update --remote .dsh/skills/hlca-firmware-dev` (技能脚本更新后跑 `scripts/check_copy_sync.ps1` 同步 `scripts/` 副本)。 - **推 main 走 `scripts/push_main.ps1`**:推送前自动跑模板形态 + 层规则/构建体检 + 主机单测 + 目标端编译门,并断言全链构建按设计失败、相对 `origin/main` 是**快进**(禁止强推/改写历史); `-DryRun` 只校验不推送。托管平台(Gitee)没有 required checks,这个脚本是仓库侧的兜底门禁。 ## 演进简史 - **v1.0.0**:骨架从 001 工程冻结为事实无关模板(74 文件 + 模板 CI)。 - **v2.13 / v2.14(技能版号)**:技能删除内置 `assets/skeleton`(消双骨架),新增 README 人读入口。 - **v1.2.0**:烧录链路落地(默认 OpenOCD + 用户选探针 + 事实校验),技能升 2.16。 - **v1.1.0**:技能与指南并入本仓(`git subtree` 保留技能历史),新增 `check_copy_sync` 副本一致性门禁, 解决"技能/骨架/脚本三处分叉"。 - **技能 v2.20**:技能拆回独立仓 `hlca-firmware-dev`(解归档),本仓不再跟踪 `.dsh/` 的源码; 副本一致性改由"技能 submodule 在场才比对"兜底。