摘要：本文是"公司 BSP"系列的第 41 篇，聚焦代码仓库的组织方式。文章从四层模型（Application → Zephyr BSP → Company HAL → SoC）出发，系统讲解 HAL 与 Zephyr 的依赖边界、SoC Family 与 Board 的复用策略、DTS/Binding/Driver/Kconfig 的归属，以及 West Manifest 如何把多仓库组合成可重复构建的 SDK workspace。本文目录一、先看最终形态—— 成熟 BSP 仓库全貌二、先建立四层模型—— 四层职责与边界三、Repository Architecture 的核心问题—— 谁依赖谁四、Company HAL 应该独立—— HAL 平台无关五、Zephyr BSP 再把 HAL 接进来—— Module 集成层六、Zephyr Driver 和 HAL 不要混成一个东西—— 职责分离七、SoC Repository 怎么组织？—— Family 目录结构八、为什么需要 SoC Family？—— 共享与差异九、Board Repository 怎么组织？—— 板级描述十、Board 和 SoC 的关系—— SoC ≠ Board十一、Devicetree 应该放哪里？—— DTS 归属十二、Binding 属于哪里？—— 描述硬件十三、Drivers Repository—— Zephyr 抽象实现十四、一个完整的 UART 路径—— 全链路串联十五、Kconfig 放哪里？—— 分层配置十六、不要让 Board 决定太多 SoC 东西—— 职责收敛十七、West Manifest 是整个 Repository 的"胶水"—— 多仓组合十八、为什么不把所有代码放一个 Git Repo？—— 拆分时机十九、一个比较典型的企业级布局—— SDK 布局二十、SDK 和 BSP 也不是一回事—— 概念辨析二十一、CI 应该放在哪里？—— 自动化验证二十二、Repository 中最重要的不是目录，而是 Ownership—— 代码所有权二十三、再看一次完整 Dependency Graph—— 依赖全景二十四、一个实际 Company BSP Repository—— Acme 实例二十五、最重要的几个架构原则—— 七条原则二十六、把 20～41 篇串起来—— 系列总览核心结论：BSP Repository Architecture 的本质是解决"代码所有权"和"依赖方向"问题，目录结构只是表象，Ownership 才是关键。公司 BSP Repository Architecture前面20～40 篇，我们已经把"公司 BSP"从零拆到了：SoC → Startup → IRQ → Clock/Reset → Devicetree → Binding → Driver → Board → Kconfig → CMake → Linker → Runner → Validation → BSP 生命周期这一篇再往前走一步：如果这是一个真正公司的 BSP，代码仓库到底应该怎么组织？这一步非常重要。因为个人学习时，你可以把所有东西塞进一个 Zephyr repository；但公司真正维护 BSP 时，通常会遇到：一个 SoC，多个芯片型号 一个 SoC family，多个 board 一个 HAL，被 Zephyr、FreeRTOS、裸机共同使用 多个产品团队同时开发 BSP 要独立版本发布 Zephyr 升级不能把公司的 HAL 一起搞乱 不同客户/产品需要不同 feature CI 要测试几十块板子 SDK、HAL、BSP、Application 必须有清晰边界所以：BSP Repository Architecture 本质上是在解决"代码所有权"和"依赖方向"的问题。一、先看最终形态一个成熟的公司 BSP，通常不会只有：zephyr/ └── soc/而更像：company-bsp/ │ ├── hal/ │ └── company/ │ ├── include/ │ ├── src/ │ ├── drivers/ │ ├── startup/ │ └── linker/ │ ├── zephyr/ │ └── modules/ │ └── hal_company/ │ ├── boards/ │ └── company/ │ ├── board_a/ │ ├── board_b/ │ └── board_c/ │ ├── soc/ │ └── company/ │ ├── family_a/ │ │ ├── soc.c │ │ ├── Kconfig │ │ ├── CMakeLists.txt │ │ └──... │ │ │ └── family_b/ │ ├── drivers/ │ ├── uart/ │ ├── spi/ │ ├── i2c/ │ ├── gpio/ │ └── timer/ │ ├── dts/ │ ├── bindings/ │ └── include/ │ ├── samples/ │ ├── tests/ │ ├── scripts/ │ ├── ci/ │ ├── west.yml ├── README.md └── VERSION但这还不是唯一答案。真正关键的是：哪些东西属于 Company HAL？哪些属于 Zephyr BSP？哪些属于 Board？哪些属于 Application？二、先建立四层模型建议先把公司 BSP 看成四层。┌──────────────────────────────────────┐ │ Application │ │ │ │ Product / Demo / Sample │ └──────────────────┬───────────────────┘ │ ▼ ┌──────────────────────────────────────┐ │ Zephyr BSP │ │ │ │ Board / Devicetree / Kconfig │ │ Zephyr Drivers / SoC Integration │ └──────────────────┬───────────────────┘ │ ▼ ┌──────────────────────────────────────┐ │ Company HAL │ │ │ │ Registers / LL / Peripheral HAL │ │ Clock / Reset / Pinmux / Startup │ └──────────────────┬───────────────────┘ │ ▼ ┌──────────────────────────────────────┐ │ SoC │ │ │ │ CPU / Bus / UART / SPI / GPIO /... │ └──────────────────────────────────────┘这个结构非常重要。因为：Zephyr Driver │ ▼ Company HAL │ ▼ Hardware和：Application │ ▼ Zephyr API │ ▼ Driver下面用一张表格横向对比这四层的职责边界、典型内容、依赖方向与跨平台复用能力：层级职责边界典型内容依赖方向是否可跨平台复用Application只关心产品业务逻辑，不直接操作寄存器Product / Demo / Sample、业务状态机、协议栈只依赖 Zephyr API（uart_poll_out等）否，绑定具体产品Zephyr BSP把硬件能力适配成 Zephyr 抽象，实现 Zephyr APIBoard / Devicetree / Kconfig、Zephyr Drivers、SoC Integration依赖 Zephyr，向下调用 Company HAL否，绑定 Zephyr 平台Company HAL封装寄存器与底层外设，提供平台无关的 LL/Peripheral HALRegisters / LL / Peripheral HAL、Clock / Reset / Pinmux / Startup只依赖硬件（寄存器定义），不依赖任何 RTOS是，可被 Zephyr、FreeRTOS、裸机复用SoC物理硬件本身，是依赖链的最底层CPU / Bus / UART / SPI / GPIO / Timer / 中断控制器无软件依赖，被 HAL 访问否，硬件实体为什么 HAL 层必须保持平台无关？因为 HAL 是整条依赖链中唯一被多个软件平台共享的基础设施——Zephyr、FreeRTOS、裸机都要通过它访问同一份硬件。一旦 HAL 里出现#include zephyr/kernel.h或device_is_ready()，它就被某个平台"绑架"，其他平台无法复用，公司就不得不为每个 RTOS 各维护一份 HAL，成本成倍上升。保持 HAL 只认识寄存器、不认识任何 RTOS，才能让"一份 HAL，多平台复用"成为可能，再来看一组「错误架构 vs 正确架构」的对比，把最容易踩的坑和对应的正确做法放在一起：常见错误做法后果正确做法改进方向HAL 里#include zephyr/kernel.h或调用device_is_ready()HAL 被 Zephyr 绑架，FreeRTOS / 裸机无法复用，被迫为每个 RTOS 各维护一份 HALHAL 只包含寄存器定义（company/regs.h），只操作CTRL/STATUS/TXDATA等寄存器把 Zephyr 相关调用上移到 Zephyr Driver 层，HAL 保持纯硬件抽象Zephyr Driver 直接操作寄存器（UART0-CTRL = ...）Driver 同时承担 HAL 工作，寄存器、时钟、复位、pinmux 全混在一起，越来越难维护Driver 只实现 Zephyr API，向下调用company_uart_hal_write()等 HAL 接口拆出独立 Company HAL 层，Driver 只做 Zephyr abstraction 的适配Board 的Kconfig.defconfig塞满CONFIG_SOC_CX120=y、CONFIG_UART_COMPANY=y等 SoC/Driver 配置Board 变成"超级配置文件"，SoC 能力与板级选择耦合，换 SoC 时配置难以复用Board 只选择 SoC 并描述 PCB 连接；SoC 提供 capabilities，Application 选择需要的 peripheral按「Board → SoC → Driver → HAL」分层收敛 Kconfig 归属每个芯片型号单独复制一份 BSP（soc/cx100/、soc/cx110/）三份 BSP 大量重复，改一个公共 bug 要同步三处，维护成本成倍上升按 SoC Family 组织（soc/company/family_a/{cx100,cx110,cx120}），共享 common 部分提取 Family 公共代码，芯片差异只保留 Flash/RAM/CAN 等少量配置Board 重新实现 UART / SPI / GPIO DriverBoard 层职责越界，驱动逻辑与板级描述耦合，无法跨板复用Board 只提供board.dts、Kconfig.board等描述性文件，驱动由 BSP/Driver 层统一提供明确 Board 只描述"这块 PCB 如何连接这个 SoC"，不写驱动逻辑小结：这五类错误的共同根源都是依赖方向被打破——HAL 反向依赖 Zephyr、Driver 越界碰寄存器、Board 越权决定 SoC 配置。只要坚持「Application → Zephyr → Driver → HAL → Hardware」的单向依赖链，并让每一层只做自己职责内的事，BSP 就能长期保持可维护、可复用、可独立发布。这正是四层模型里 HAL 独立存在的意义。是两条不同的抽象边界。三、Repository Architecture 的核心问题公司 BSP repository 最重要的问题其实不是目录。而是：谁依赖谁？理想依赖关系：Application │ ▼ Zephyr │ ▼ Company BSP │ ▼ Company HAL │ ▼ Hardware但是不能出现：Company HAL │ ▼ Zephyr例如 HAL 里面出现：#includezephyr/kernel.h通常就是一个非常明显的架构问题。因为 HAL 应该尽量不知道：Zephyr FreeRTOS Linux Bare-metal它只知道：hardware四、Company HAL 应该独立例如：hal_company/ ├── include/ │ └── company/ │ ├── uart.h │ ├── gpio.h │ ├── clock.h │ └── spi.h │ ├── src/ │ ├── uart.c │ ├── gpio.c │ ├── clock.c │ └── spi.c │ └── startup/ ├── startup.c └── system.c下面是一个完整的company_uart_hal_write()实现示例，包含寄存器操作、参数校验和返回值定义：/* hal_company/src/uart.c */#include"company/uart.h"#include