419 lines
11 KiB
Markdown
419 lines
11 KiB
Markdown
# 项目移植指南
|
||
|
||
## 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
|