📁 嵌入式工程目录结构规范

📁 嵌入式工程目录结构规范

适用于基于 ARM Cortex-M 的嵌入式系统开发，强调模块化、可维护性与团队协作。

一、项目整体结构

Project/
├── APP/                # 应用层代码（用户主程序、任务逻辑等）
├── BSP/                # 板级支持包（Board Support Package）
├── Config/             # 配置文件（外设初始化配置、宏定义等）
├── Core/               # 核心代码（MCU 核心驱动、启动文件、系统初始化）
├── Drivers/            # 外设驱动层（标准外设库或 HAL 库封装）
├── MDK-ARM/            # Keil 工程文件（可替换为 IAR、GCC 等）
├── Middleware/         # 中间件（RTOS、文件系统、协议栈等）
├── Utilities/          # 工具类函数与通用模块
└── README.md           # 项目说明文档

---

二、各目录详细说明

1. APP/ - 应用层

存放用户主程序和顶层业务逻辑。

APP/
├── app_task.c          # 任务调度逻辑（如使用 RTOS）
├── app_uart.c          # 串口应用逻辑（协议解析等）
├── app_sensor.c        # 传感器数据处理
└── app_config.h        # 应用层配置头文件

✅ 要求：

• 与硬件解耦，依赖 BSP 和 Middleware
• 不直接操作寄存器
• 模块化设计，每个功能独立 .c/.h 文件

---

2. BSP/ - 板级支持包

针对具体开发板的引脚定义、外设初始化和通用接口封装。

BSP/
├── bsp_led.c           # LED 控制接口
├── bsp_key.c           # 按键检测
├── bsp_usart.c         # 串口通信封装
├── bsp_timer.c         # 定时器服务（如滴答定时）
├── bsp_gpio.c          # GPIO 统一配置
└── bsp.h               # BSP 公共头文件

✅ 要求：

• 提供统一 API 给 APP 层调用
• 隐藏底层驱动细节
• 支持多板型时可用子目录区分（如 BSP/Board_V1.0/）

---

3. Config/ - 配置文件

存放系统及外设的配置参数，便于集中管理。

Config/
├── system_config.h     # 系统时钟、工作模式等配置
├── pin_config.h        # 引脚功能定义
├── module_enable.h     # 功能模块开关宏
└── rtos_config.h       # RTOS 配置（如 FreeRTOSConfig.h）

✅ 要求：

• 使用 #define 宏进行配置
• 避免硬编码在源码中
• 支持通过编译选项切换配置

---

4. Core/ - 核心层

MCU 核心相关代码，通常由芯片厂商提供。

Core/
├── startup_stm32f4xx.s  # 启动文件（汇编）
├── system_stm32f4xx.c  # 系统时钟初始化
├── core_cm4.h          # ARM Cortex-M4 内核寄存器定义
└── cmsis_version.h     # CMSIS 版本信息

⚠️ 注意：

• 一般不修改，除非有特殊需求
• 可链接外部 CMSIS 库路径，避免重复拷贝

---

5. Drivers/ - 外设驱动层

芯片原厂提供的标准外设库或 HAL/LL 库。

Drivers/
├── STM32F4xx_HAL_Driver/
│   ├── Inc/            # 头文件
│   └── Src/            # 源文件（hal_xxx.c）
└── CMSIS/              # 可选：CMSIS 标准库
    └── Device/

✅ 要求：

• 使用官方标准库保证稳定性
• 可替换为 LL 库以节省资源
• 不建议直接在驱动中写业务逻辑

---

6. MDK-ARM/ - Keil 工程文件

Keil µVision 项目文件（也可替换为 IAR/ 或 GCC/）。

MDK-ARM/
├── Project.uvprojx     # 工程配置文件
├── Project.uvgui       # 用户界面设置
├── startup.sct         # 链接脚本（scatter file）
└── Objects/            # 编译中间文件（建议加入 .gitignore）

✅ 建议：

• 使用相对路径
• .gitignore 忽略 Objects/, Listings/ 等生成文件
• 团队协作时统一工具链版本

---

7. Middleware/ - 中间件

第三方或自研中间件模块。

Middleware/
├── FreeRTOS/           # 实时操作系统
│   ├── include/
│   └── src/
├── FATFS/              # 文件系统
├── lwIP/               # 网络协议栈
├── USB/                # USB 设备/主机协议
└── cJSON/              # JSON 解析库

✅ 要求：

• 模块独立，易于替换
• 提供统一接口供 APP 调用
• 第三方库建议保留 LICENSE 文件

---

8. Utilities/ - 工具类

通用工具函数，提高开发效率。

Utilities/
├── debug_log.c         # 日志打印函数
├── ring_buffer.c       # 环形缓冲区
├── crc.c               # CRC 校验计算
├── delay.c             # 精确延时函数
├── string_utils.c      # 字符串处理
└── utilities.h         # 工具函数声明

✅ 要求：

• 无硬件依赖，可移植性强
• 提供单元测试接口（可选）
• 避免全局变量滥用

---

三、编码与命名规范建议

类型	命名规则	示例
目录	小写 + 下划线	middleware/, config/
源文件	小写 + 下划线	bsp_led.c
头文件	小写 + 下划线	app_task.h
函数	驼峰式或下划线	BSP_LED_On() 或 bsp_led_on()
宏定义	全大写 + 下划线	#define UART_RX_BUF_SIZE 256
变量	小写 + 下划线	uint8_t sensor_data;
结构体	首字母大写 + 后缀 _t	typedef struct { ... } SensorData_t;

---

四、版本控制建议（Git）

# 生成文件
/build/
/MDK-ARM/Objects/
/MDK-ARM/Listings/
*.o
*.axf
*.hex
*.bin

# IDE 文件
*.uvopt
*.uvproj
*.iic
*.dav

# 临时文件
*.tmp
*.log
.DS_Store

✅ 推荐提交内容：

• 所有源码、配置、文档
• 工程文件（.uvprojx 等）
• README.md 说明编译方式和依赖

---

五、总结

目录	职责	是否可移植
APP/	业务逻辑	✅（一般针对项目，可部分移植）
BSP/	板级硬件抽象	❌（依赖板子）
Config/	系统配置	✅
Core/	MCU 核心初始化	❌
Drivers/	外设驱动	❌
Middleware/	系统服务（RTOS、网络等）	✅
Utilities/	通用工具	✅

✅ 优点：层次清晰、便于团队协作、易于移植和维护。

---

📌 Tips：

• 新项目建议使用 CMake + VS Code + GCC 构建现代嵌入式开发环境
• 配合 CI/CD 工具进行自动化编译与静态检查（如 cppcheck）
• 添加 docs/ 目录存放设计文档和接口说明

---

✅ 适用场景：STM32、GD32、NXP、TI 等主流 MCU 项目开发
🔧 推荐工具链：Keil MDK、STM32CubeIDE、VS Code + EIDE + Cortex-Debug