jfen/stm32f407ve_black
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

优化实现串口驱动，SPI驱动 W25QXX还需要初始化验证修复

Browse Source
This commit is contained in:
冯佳
2026-01-23 09:59:43 +08:00
parent 51e8d79f78
commit b166bee1a9
69 changed files with 6253 additions and 1178 deletions
Download Patch File Download Diff File Expand all files Collapse all files

418
PORTING_GUIDE.md Normal file
View File

@ -0,0 +1,418 @@
# 项目移植指南
## 1. 项目架构概述
本项目采用分层架构设计，主要分为以下几个层次：
### 1.1 分层结构
- **HAL层（硬件抽象层）**：负责硬件抽象，将不同MCU的硬件操作封装为统一接口
- **BSP层（板级支持包）**：负责板级配置和初始化
- **Module层（模块层）**：实现具体功能模块，如LED、UART、Delay等
- **Middleware层（中间件层）**：提供通用功能，如日志记录等
- **Application层（应用层）**：用户应用代码
### 1.2 核心目录结构
```
├── BSP/ # 板级支持包
│ ├── Inc/ # BSP头文件
│ └── Src/ # BSP源文件
├── Core/ # 核心应用代码
├── Drivers/ # 官方驱动库
├── HAL/ # 硬件抽象层
│ ├── Inc/ # HAL头文件
│ │ └── arch/ # 架构特定头文件
│ └── Src/ # HAL源文件
│ └── arch/ # 架构特定源文件
├── Middlewares/ # 中间件
└── Modules/ # 功能模块
```
## 2. HAL层移植
### 2.1 HAL层架构
HAL层采用分层设计，分为通用层和架构特定层：
- **通用层**：提供统一的硬件抽象接口，如`hal_gpio.h`、`hal_uart.h`等
- **架构特定层**：针对不同MCU架构的具体实现，如`hal_stm32f4_gpio.c`等
### 2.2 支持的架构
目前支持以下架构：
- STM32F1
- STM32F4（默认）
- STM32F7
- STM32L4
### 2.3 添加新架构支持
要添加新的MCU架构支持，请按照以下步骤进行：
1. **在`HAL/Inc/hal.h`中添加架构定义**：
```c
#define HAL_ARCH_NEW_MCU 4 // 添加新的架构定义
```
2. **在`HAL/Inc/arch/`目录下创建新的架构目录**：
```
mkdir -p HAL/Inc/arch/new_mcu
```
3. **创建架构特定头文件`hal_new_mcu.h`**：
```c
#ifndef HAL_NEW_MCU_H
#define HAL_NEW_MCU_H
#include "stm32xxxx_hal.h" // 替换为新MCU的HAL头文件
#include "../../hal_gpio.h"
#include "../../hal_uart.h"
#include "../../hal_delay.h"
void hal_new_mcu_init(void);
#endif /* HAL_NEW_MCU_H */
```
4. **在`HAL/Src/arch/`目录下创建新的架构目录**：
```
mkdir -p HAL/Src/arch/new_mcu
```
5. **实现架构特定的GPIO驱动`hal_new_mcu_gpio.c`**：
```c
#include "hal.h"
#include "hal_gpio.h"
#include "stm32xxxx_hal.h"
void hal_new_mcu_gpio_init(void) {
// 实现GPIO初始化
}
void hal_new_mcu_gpio_write_pin(hal_gpio_port_t port, hal_gpio_pin_t pin, hal_gpio_pin_state_t state) {
// 实现GPIO写操作
}
// 实现其他GPIO函数...
```
6. **实现架构特定的UART驱动`hal_new_mcu_uart.c`**：
```c
#include "hal.h"
#include "hal_uart.h"
#include "stm32xxxx_hal.h"
#include "stm32xxxx_hal_uart.h"
void hal_new_mcu_uart_init(void) {
// 实现UART初始化
}
void hal_new_mcu_uart_send(hal_uart_instance_t instance, const uint8_t *data, size_t length) {
// 实现UART发送
}
// 实现其他UART函数...
```
7. **更新`HAL/Inc/hal.h`中的架构包含**：
```c
#elif HAL_TARGET_ARCH == HAL_ARCH_NEW_MCU
#include "arch/new_mcu/hal_new_mcu.h"
```
8. **更新各HAL驱动文件，添加新架构支持**：
```c
#elif HAL_TARGET_ARCH == HAL_ARCH_NEW_MCU
hal_new_mcu_gpio_init();
```
## 3. BSP层移植
### 3.1 BSP层架构
BSP层负责板级配置和初始化，主要包含以下组件：
- **板级配置结构体**：`bsp_board_config_t`，定义了板子的硬件配置
- **板级初始化**：负责初始化板子的硬件资源
- **板级管理器**：`bsp_board_manager.c`，负责管理多个板子配置
### 3.2 添加新板子支持
要添加新的板子支持，请按照以下步骤进行：
1. **创建新的板子配置文件`new_board.c`**：
```c
#include "bsp_board.h"
#include "bsp_config.h"
#include "hal_gpio.h"
#include "hal_uart.h"
// 实现默认初始化函数
static void default_led_init(const void* config) {
// LED初始化实现
}
// 实现其他默认初始化函数...
// 定义板子配置
const bsp_board_config_t new_board_config = {
.name = "NEW_BOARD",
.led = {
.port = HAL_GPIO_PORT_A,
.pin = HAL_GPIO_PIN_6,
.mode = HAL_GPIO_MODE_OUTPUT_PP,
.speed = HAL_GPIO_SPEED_MEDIUM,
.pull = HAL_GPIO_PULL_NO
},
// 配置其他外设...
.led_init = default_led_init,
// 配置其他初始化函数...
.clock_speed = 168000000,
.uart_count = 6
};
```
2. **在`bsp_board.h`中添加extern声明**：
```c
extern const bsp_board_config_t new_board_config;
```
3. **在`bsp_board_manager.c`中添加新板子配置**：
```c
/* Forward declarations for board configurations */
extern const bsp_board_config_t new_board_config;
/**
* @brief List of supported board configurations
*/
static const bsp_board_config_t* supported_boards[] = {
&stm32f407vet6_board_config,
&new_board_config, // 添加新板子配置
/* Add more board configurations here */
};
```
4. **创建新的板子配置头文件`bsp_config_new_board.h`**：
```c
#define BOARD_NAME "NEW_BOARD"
/**
* @brief LED hardware configuration
*/
#define BSP_LED_PORT HAL_GPIO_PORT_A
#define BSP_LED_PIN HAL_GPIO_PIN_6
/**
* @brief UART hardware configuration
*/
#define BSP_UART_INSTANCE BSP_UART_INSTANCE_1
#define BSP_UART_BAUDRATE 115200
#define BSP_UART_PARITY HAL_UART_PARITY_NONE
#define BSP_UART_STOPBITS HAL_UART_STOPBITS_1
#define BSP_UART_DATABITS HAL_UART_DATABITS_8
```
5. **在编译时选择目标板子**：
通过修改`BSP/Src/bsp_board.c`中的`current_board_index`或在编译命令中定义宏来选择目标板子。
## 4. 模块层移植
### 4.1 模块层架构
模块层实现具体的功能模块，如LED、UART、Delay等。每个模块包含：
- **模块配置结构体**：定义模块的配置参数
- **模块实例结构体**：保存模块的状态
- **模块API**：提供模块的操作接口
### 4.2 添加新模块
要添加新的功能模块，请按照以下步骤进行：
1. **创建模块目录**：
```
mkdir -p Modules/new_module/inc
mkdir -p Modules/new_module/src
```
2. **创建模块头文件`new_module.h`**：
```c
#ifndef NEW_MODULE_H
#define NEW_MODULE_H
#include <stdint.h>
/**
* @brief New module configuration structure
*/
typedef struct {
// 配置参数
} new_module_config_t;
/**
* @brief New module instance structure
*/
typedef struct {
new_module_config_t config;
uint8_t initialized;
} new_module_t;
/**
* @brief Initialize new module
* @param instance: Pointer to module instance
* @param config: Pointer to module configuration
*/
void new_module_init(new_module_t *instance, const new_module_config_t *config);
// 其他模块API...
#endif /* NEW_MODULE_H */
```
3. **创建模块源文件`new_module.c`**：
```c
#include "new_module.h"
void new_module_init(new_module_t *instance, const new_module_config_t *config) {
if (instance == NULL || config == NULL) {
return;
}
// 初始化实现
instance->config = *config;
instance->initialized = 1;
}
// 实现其他模块API...
```
4. **更新模块的CMakeLists.txt**：
```cmake
# Add new_module library
add_library(new_module STATIC)
# Add new_module sources
target_sources(new_module PRIVATE
src/new_module.c
)
# Add new_module include directories
target_include_directories(new_module PUBLIC
inc
)
# Link new_module dependencies
target_link_libraries(new_module PRIVATE
hal
)
```
## 5. 编译配置
### 5.1 选择目标架构
在`HAL/Inc/hal.h`中定义`HAL_TARGET_ARCH`宏来选择目标架构：
```c
#ifndef HAL_TARGET_ARCH
#define HAL_TARGET_ARCH HAL_ARCH_STM32F4
#endif
```
或者在编译命令中定义：
```bash
cmake -DHAL_TARGET_ARCH=HAL_ARCH_STM32F4 ..
```
### 5.2 选择目标板子
通过修改`bsp_board_manager.c`中的`current_board_index`来选择目标板子：
```c
/**
* @brief Current board configuration index
*/
static uint8_t current_board_index = 0; // 0表示第一个板子配置
```
或者调用`bsp_board_set_by_name()`或`bsp_board_set_by_index()`函数来动态选择：
```c
bsp_board_set_by_name("NEW_BOARD");
```
## 6. 常见问题与解决方案
### 6.1 编译错误：undefined reference to `hal_new_mcu_gpio_init'
**原因**：未实现新架构的GPIO初始化函数。
**解决方案**：按照第2节的步骤，实现新架构的GPIO初始化函数。
### 6.2 运行时错误：串口无输出
**原因**：可能是UART初始化失败或GPIO配置错误。
**解决方案**：
1. 检查UART的GPIO配置是否正确
2. 检查UART的时钟是否使能
3. 检查UART的波特率设置是否正确
### 6.3 移植后LED不亮
**原因**：可能是GPIO配置错误或初始化顺序问题。
**解决方案**：
1. 检查LED的GPIO配置是否正确
2. 检查LED的初始化函数是否被调用
3. 检查GPIO的时钟是否使能
## 7. 示例移植流程
### 7.1 STM32F1移植示例
1. **添加STM32F1架构支持**：
- 在`hal.h`中添加`HAL_ARCH_STM32F1`定义
- 创建`hal_stm32f1.h`和`hal_stm32f1.c`文件
- 实现STM32F1特定的GPIO、UART等驱动
2. **添加STM32F1板子配置**：
- 创建`stm32f103c8t6_board.c`文件
- 定义`stm32f103c8t6_board_config`结构体
- 在`bsp_board_manager.c`中添加该配置
3. **配置编译选项**：
- 设置`HAL_TARGET_ARCH=HAL_ARCH_STM32F1`
- 更新Linker脚本为STM32F1的链接脚本
4. **编译和测试**：
- 编译项目
- 烧录到STM32F1开发板
- 测试LED和UART功能
## 8. 最佳实践
1. **遵循分层设计原则**：保持各层之间的独立性，避免跨层调用
2. **使用统一的接口**：尽量使用HAL层提供的统一接口，避免直接操作硬件
3. **实现完整的初始化**：确保所有硬件资源都正确初始化
4. **添加必要的错误检查**：在关键函数中添加参数检查和错误处理
5. **编写清晰的文档**：为新添加的代码编写清晰的注释和文档
6. **测试所有功能**：移植后测试所有关键功能，确保正常工作
## 9. 资源
- [STM32CubeMX](https://www.st.com/en/development-tools/stm32cubemx.html)：用于生成初始化代码
- [ARM Cortex-M4 Technical Reference Manual](https://developer.arm.com/documentation/ddi0439/b/)：Cortex-M4架构参考
- [STM32F4 Reference Manual](https://www.st.com/resource/en/reference_manual/dm00031020-stm32f405-415-stm32f407-417-stm32f427-437-and-stm32f429-439-advanced-arm-based-32-bit-mcus-stmicroelectronics.pdf)：STM32F4参考手册
## 10. 联系方式
如果您在移植过程中遇到问题，请联系项目维护者获取帮助。
---
**文档版本**：v1.0
**更新日期**：2026-01-23
**适用项目**：stm32f407vet6_cmake