# mcu_temp_cmake

**Repository Path**: work_s/mcu_temp_cmake

## Basic Information

- **Project Name**: mcu_temp_cmake
- **Description**: mcu芯片开发，基于cmake管理，ninjia构建
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-06-16
- **Last Updated**: 2026-06-19

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 标准单片机开发框架模板

该模板从当前工程结构抽象而来，保留 `arch / boards / kernel / drivers / services / platform / imported / app` 分层，但去掉具体业务和芯片强绑定代码。目标是让应用开发、BSP 芯片包、第三方库三者在代码接口和目录上隔离。

## 1. 构建方式

工程使用 CMake + Ninja。

```powershell
# PC 侧冒烟构建，验证框架和用户代码
cmake --preset host
cmake --build --preset host

# MCU Debug 固件构建
cmake --preset firmware-debug
cmake --build --preset firmware-debug

# MCU Release 固件构建
cmake --preset firmware-release
cmake --build --preset firmware-release
```

固件构建默认使用 `cmake/toolchain/arm-none-eabi-gcc.cmake`，需要 `arm-none-eabi-gcc`、`arm-none-eabi-g++`、`arm-none-eabi-objcopy`、`arm-none-eabi-size` 在 `PATH` 中。

## 2. 固定开发位置

用户业务只放这里：

```text
apps/user/include/  用户头文件
apps/user/src/      用户 C/C++ 源文件
```

CMake 会自动收集：

```text
apps/user/src/*.c
apps/user/src/*.cpp
apps/user/src/*.cc
apps/user/src/*.cxx
```

用户入口固定为：

```c
int user_app_init(void);
void user_app_loop(void);
```

示例实现在 `apps/user/src/user_app.c`。

## 3. BSP 芯片包固定位置

BSP 芯片包只放这里：

```text
imported/bsp/<MCU_CHIP>/
```

默认 `MCU_CHIP=template_chip`。可通过 Preset 或命令行切换：

```powershell
cmake --preset firmware-debug -DMCU_CHIP=stm32f4xx
```

约定的自动收集目录：

```text
imported/bsp/<MCU_CHIP>/include
imported/bsp/<MCU_CHIP>/Include
imported/bsp/<MCU_CHIP>/inc
imported/bsp/<MCU_CHIP>/Inc
imported/bsp/<MCU_CHIP>/src
imported/bsp/<MCU_CHIP>/Src
imported/bsp/<MCU_CHIP>/source
imported/bsp/<MCU_CHIP>/Source
```

如果厂商包目录很复杂，只修改 `imported/bsp/CMakeLists.txt`，不要让应用代码直接 include 厂商头文件。

## 4. 第三方库固定位置

第三方库只放这里：

```text
imported/third_party/<lib_name>/
```

通过 `MCU_THIRD_PARTY_LIBS` 指定参与构建的库：

```powershell
cmake --preset firmware-debug -DMCU_THIRD_PARTY_LIBS="FreeRTOS;lwip;mbedtls"
```

默认约定的自动收集目录：

```text
imported/third_party/<lib_name>/include
imported/third_party/<lib_name>/Include
imported/third_party/<lib_name>/inc
imported/third_party/<lib_name>/Inc
imported/third_party/<lib_name>/src
imported/third_party/<lib_name>/Src
imported/third_party/<lib_name>/source
imported/third_party/<lib_name>/Source
```

应用代码不要直接 include FreeRTOS、lwIP、mbedTLS 等头文件，统一通过 `include/mcu_framework/` 下的接口访问。

## 5. 接口隔离规则

应用层允许 include：

```text
include/mcu_framework/*.h
include/mcu_framework/*.hpp
apps/user/include/*.h
```

BSP 适配只放：

```text
ports/bsp/src/
```

第三方库适配只放：

```text
ports/third_party/src/
```

默认接口：

| 接口 | 作用 |
| --- | --- |
| `mcu_framework/bsp.h` | 板级初始化、tick、delay、console 输出 |
| `mcu_framework/os.h` | OS/调度器抽象，默认 baremetal，可切 FreeRTOS |
| `mcu_framework/log.h` | 日志抽象，默认 console stub |
| `mcu_framework/user_app.h` | 用户应用入口 |
| `mcu_framework/device_tree.hpp` | 板级设备树描述 |
| `mcu_framework/driver_registry.hpp` | 驱动注册和探测 |
| `mcu_framework/service_registry.hpp` | 服务注册和生命周期 |

## 6. 目录职责

```text
arch/                  启动文件、链接脚本、CPU 架构相关代码
boards/                板级内存和设备节点描述
cmake/                 CMake 模块和工具链文件
drivers/               框架驱动注册，不直接写业务
include/mcu_framework/ 对外稳定接口
kernel/                启动编排、设备树、注册表
services/              框架服务注册
platform/              平台说明和可选平台层扩展
ports/bsp/             BSP 适配层，隔离厂商芯片包
ports/third_party/     第三方库适配层，隔离外部库 API
imported/bsp/          固定 BSP 芯片包目录
imported/third_party/  固定第三方库目录
apps/user/             固定用户业务目录
tools/                 烧录、打包、辅助工具
docs/                  架构和开发说明
```

## 7. 替换真实芯片时的最小步骤

1. 将芯片 BSP 放到 `imported/bsp/<MCU_CHIP>/`。
2. 在 `ports/bsp/src/` 新增或替换 BSP 适配实现，内部可以 include 厂商头文件。
3. 在 `boards/<board_name>/board_device_tree.cpp` 描述内存、外设、IRQ 和启用状态。
4. 修改 `MCU_CPU / MCU_FLOAT_ABI / MCU_FPU / MCU_LINKER_SCRIPT`。
5. 用户只在 `apps/user/include` 和 `apps/user/src` 增加业务文件。