RT-Thread STM32 系列 BSP 制作教程

為了讓廣大開發者更好、更方便地使用 BSP 進行開發，RT-Thread 開發團隊重新整理了現有的 STM32 系列的 BSP，推出了新的 BSP 框架。新的 BSP 框架在易用性、移植便利性、驅動完整性、代碼規范性等方面都有較大提升，在新的 BSP 框架下進行開發，可以大大提高應用的開發效率。

和 RT-Thread 以往提供的 BSP 不同，在新的 BSP 文件夾中將不會包含固件庫、外設驅動等可以被多個 BSP 引用的代碼文件。而是將這些通用的文件統一存放在 Library 文件夾中，通過在特定 BSP 中引用這些文件的方式，來包含 BSP 中所需的庫文件或者驅動文件。這種方式不僅大大提高了代碼復用率，降低了 BSP 的維護成本，而且可以更方便地給開發者提供更豐富的驅動文件，讓開發者可以更容易地找到自己需要的資源。

新的 BSP 框架還引入了 CubeMX 工具，可以使用該工具來對 BSP 中使用的外設引腳進行配置。CubeMX 工具提供了圖形化的配置界面，這種圖形化的配置方式對開發者來說更加直觀，不僅可以讓開發者靈活地配置 BSP 中使用的資源，並且可以讓開發者對資源的使用情況一目了然。

新 BSP 框架的主要特性如下：

• 提供多系列 BSP 模板，大大降低新 BSP 的添加難度；
• 每個 BSP 都配有齊全的驅動文件，開發者可以方便地使用所有驅動；
• 開發者可以使用 CubeMX 工具對 BSP 進行圖形化配置；

1. BSP 框架介紹

BSP 框架結構如下圖所示：

每一個 STM32 系列的 BSP 由三部分組成，分別是通用庫、BSP 模板和特定開發板 BSP，下面的表格以 F1 系列 BSP 為例介紹這三個部分：

項目	文件夾	說明
通用庫	stm32/libraries	用於存放 HAL 庫以及基於 HAL 庫的多系列通用外設驅動文件
F1 系列 BSP 工程模板	stm32/libraries/templates/stm32f10x	F1系列 BSP 模板，可以通過修改該模板制作更多 F1系列 BSP
特定開發板 BSP	stm32/stm32f103-atk-nano	在 BSP 模板的基礎上修改而成

2. 知識准備

制作一個 BSP 的過程就是構建一個新系統的過程，因此想要制作出好用的 BSP，要對 RT-Thread 系統的構建過程有一定了解，需要的知識准備如下所示：

• 掌握 stm32 系列 BSP 的使用方法

  了解 BSP 的使用方法，可以閱讀 BSP 說明文檔 中使用教程表格內的文檔。了解外設驅動的添加方法可以參考《外設驅動添加指南》。

• 了解 scons 工程構建方法

  RT-Thread 使用 scons 作為系統的構建工具，因此了解 scons 的常用命令對制作新 BSP 是基本要求。

• 了解設備驅動框架

  在 RT-Thread 系統中，應用程序通過設備驅動框架來操作硬件，因此了解設備驅動框架，對添加 BSP 驅動是很重要的。

• 了解 kconfig 語法

  RT-Thread 系統通過 menuconfig 的方式進行配置，而 menuconfig 中的選項是由 kconfig 文件決定的，因此想要對 RT-Thread 系統進行配置，需要對 kconfig 語法有一定了解。

• 熟悉 CubeMX 工具的使用

  在新的 stm32 系列 BSP 中利用了 CubeMX 工具對底層硬件進行配置，因此需要了解 CubeMX 工具的使用方法。

3. BSP 制作方法

本節以制作正點原子 stm32f103-atk-nano 開發板的 BSP 為例，講解如何為一個新的開發板添加 BSP。

BSP 的制作過程分為如下五個步驟：

1. 復制通用模板
2. 使用 CubeMX 工具配置工程
3. 修改 BSP 中的 Kconfig 文件
4. 修改構建工程相關文件
5. 重新生成工程

在接下來的章節中將會詳細介紹這五個步驟，幫助開發者快速創建所需要的 BSP。

3.1 復制通用模板

制作新 BSP 的第一步是復制一份同系列的 BSP 模板作為基礎，通過對 BSP 模板的修改來獲得新 BSP。目前提供的 BSP 模板系列如下表所示：

工程模板	說明
libraries/templates/stm32f0xx	F0 系列 BSP 模板
libraries/templates/stm32f10x	F1 系列 BSP 模板
libraries/templates/stm32f4xx	F4 系列 BSP 模板
libraries/templates/stm32f7xx	F7 系列 BSP 模板
libraries/templates/stm32l4xx	L4 系列 BSP 模板

本次示例所用的 F1 系列 BSP 模板文件夾結構如下所示：

本次制作的 BSP 為 F1 系列，因此拷貝模板文件夾下的 stm32f10x 文件夾，並將該文件夾的名稱改為 stm32f103-atk-nano ，如下圖所示：

在接下來的 BSP 的制作過程中，將會修改 board 文件夾內的配置文件，將 F1 系列的 BSP 模板變成一個適用於正點原子 stm32f103-atk-nano 開發板的 BSP ，下表總結了 board 文件夾中需要修改的內容：

項目	需要修改的內容說明
CubeMX_Config （文件夾）	CubeMX 工程
linker_scripts （文件夾）	BSP 特定的鏈接腳本
board.c/h	系統時鍾、GPIO 初始化函數、芯片存儲器大小
Kconfig	芯片型號、系列、外設資源
SConscript	芯片啟動文件、目標芯片型號

3.2 使用 CubeMX 配置工程

在制作 BSP 的第二步，需要創建一個基於目標芯片的 CubeMX 工程。默認的 CubeMX 工程在 CubeMX_Config 文件夾中，雙擊打開 CubeMX_Config.ioc 工程，如下圖所示：

在 CubeMX 工程中將芯片型號為修改芯片型號為 STM32F103RBTx 。

3.2.1 生成 CubeMX 工程

配置系統時鍾、外設引腳等，步驟如下圖所示：

1. 打開外部時鍾、設置下載方式、打開串口外設（注意只需要選擇串口外設引腳即可，無需配置其他參數）：

2. 配置系統時鍾：

3. 設置項目名稱，並在指定地址重新生成 CubeMX 工程：

最終 CubeMX 生成的工程目錄結構如下圖所示：

3.2.2 拷貝初始化函數

在 board.c 文件中存放了函數 SystemClock_Config() ，該函數負責初始化系統時鍾。當使用 CubeMX 工具對系統時鍾重新配置的時候，需要更新這個函數。

該函數由 CubeMX 工具生成，默認存放在board/CubeMX_Config/Src/main.c 文件中。但是該文件並沒有被包含到我們的工程中，因此需要將這個函數從 main.c 中拷貝到 board.c 文件中。在整個 BSP 的制作過程中，這個函數是唯一要要拷貝的函數，該函數內容如下所示：

在 board.h 文件中配置了 FLASH 和 RAM 的相關參數，這個文件中需要修改的是 STM32_FLASH_SIZE 和 STM32_SRAM_SIZE 這兩個宏控制的參數。本次制作的 BSP 所用的 STM32F103RBTx 芯片的 flash 大小為 128k，ram 的大小為 20k，因此對該文件作出如下的修改：

3.2.3 堆內存配置講解

通常情況下，系統 RAM 中的一部分內存空間會被用作堆內存。下面代碼的作用是，在不同編譯器下規定堆內存的起始地址 HEAP_BEGIN 和結束地址 HEAP_END。這里 HEAP_BEGIN 和 HEAP_END 的值需要和后面 [3.4.1 修改鏈接腳本](# 3.4.1 修改鏈接腳本) 章節所修改的配置相一致。

在某些系列的芯片中，芯片 RAM 可能分布在不連續的多塊內存區域上。此時堆內存的位置可以和系統內存在同一片連續的內存區域，也可以存放在一片獨立的內存區域中。例如在 L4 系列的芯片上，就可以將堆內存配置在起始地址為 0x20000000 的大小為 96k 的內存空間，而將 0x10000000 開始的 32k 內存空間用作系統運行內存。

3.3 修改 Kconfig 選項

在本小節中修改 board/Kconfig 文件的內容有如下兩點：

• 芯片型號和系列
• BSP 上的外設支持選項

芯片型號和系列的修改如下表所示：

宏定義	意義	格式
SOC_STM32F103RB	芯片型號	SOC_STM32xxx
SOC_SERIES_STM32F1	芯片系列	SOC_SERIES_STM32xx

關於 BSP 上的外設支持選項，一個初次提交的 BSP 僅僅需要支持 GPIO 驅動和串口驅動即可，因此在配置選項中只需保留這兩個驅動配置項，如下圖所示：

3.4 修改工程構建相關文件

接下來需要修改用於構建工程相關的文件。

3.4.1 修改鏈接腳本

linker_scripts 鏈接文件如下圖所示：

下面以 MDK 使用的鏈接腳本 link.sct 為例，演示如何修改鏈接腳本：

本次制作 BSP 使用的芯片為 STM32F103RB，FLASH 為 128k，因此修改 LR_IROM1 和 ER_IROM1 的參數為 0x00020000。RAM 的大小為20k， 因此修改 RW_IRAM1 的參數為 0x00005000。這樣的修改方式在一般的應用下就夠用了，后續如果有特殊要求，則需要按照鏈接腳本的語法來根據需求修改。修改鏈接腳本時，可以參考 [3.2.3 堆內存配置講解](# 3.2.3 堆內存配置講解) 章節來確定 BSP 的內存分配。

其他兩個鏈接腳本的文件分別為 iar 使用的 link.icf 和 gcc 編譯器使用的 link.lds，修改的方式也是類似的，如下圖所示：

• link.icf 修改內容

  

• link.lds 修改內容

  

3.4.2 修改構建腳本

SConscript 腳本決定 MDK/IAR 工程的生成以及編譯過程中要添加文件。

在這一步中需要修改芯片型號以及芯片啟動文件的地址，修改內容如下圖所示：

注意：如果在文件夾中找不到相應系列的 .s 文件，可能是多個系列的芯片重用了相同的啟動文件，此時可以在 CubeMX 中生成目標芯片的工程，查看使用了哪個啟動文件，然后再修改啟動文件名。

3.4.3 修改工程模板

template 文件是生成 MDK/IAR 工程的模板文件，通過修改該文件可以設置工程中使用的芯片型號以及下載方式。MDK4/MDK5/IAR 的工程模板文件，如下圖所示：

下面以 MDK5 模板的修改為例，介紹如何修改模板配置：

修改程序下載方式：

3.5 重新生成工程

重新生成工程需要使用 env 工具。

3.5.1 重新生成 rtconfig.h 文件

在 env 界面輸入命令 menuconfig 對工程進行配置，並生成新的 rtconfig.h 文件。如下圖所示：

3.5.2 重新 MDK/IAR 工程

下面以重新生成 MDK 工程為例，介紹如何重新生成 BSP 工程。

使用 env 工具輸入命令 scons --target=mdk5 重新生成工程，如下圖所示：

重新生成工程成功：

到這一步為止，新的 BSP 就可以使用了。

接下來我們可以分別使用命令 scons --target=mdk4 和 scons --target=iar，來更新 mdk4 和 iar 的工程，使得該 BSP 變成一個完整的，可以提交到 GitHub 的 BSP。

感謝每一位貢獻代碼的開發者，RT-Thread 將與你一同成長。

4. 規范

本章節介紹 RT-Thread STM32 系列 BSP 制作與提交時應當遵守的規范 。開發人員在 BSP 制作完成后，可以根據本規范提出的檢查點對制作的 BSP 進行檢查，確保 BSP 在提交前有較高的質量 。

1. BSP 制作規范

STM32 BSP 的制作規范主要分為 3 個方面：工程配置，ENV 配置和 IDE 配置。在已有的 STM32 系列 BSP 的模板中，已經根據下列規范對模板進行配置。在制作新 BSP 的過程中，拷貝模板進行修改時，需要注意的是不要修改這些默認的配置。BSP 制作完成后，需要對新制作的 BSP 進行功能測試，功能正常后再進行代碼提交。

下面將詳細介紹 BSP 的制作規范。

工程配置

• 遵從RT-Thread 編碼規范，代碼注釋風格統一
• main 函數功能保持一致
  • 如果有 LED 的話，main 函數里只放一個 LED 1HZ 閃爍的程序
• 在 rt_hw_board_init 中需要完成堆的初始化：調用 rt_system_heap_init
• 默認只初始化 GPIO 驅動和 FinSH 對應的串口驅動，不使用 DMA
• 當使能板載外設驅動時，應做到不需要修改代碼就能編譯下載使用
• 提交前應檢查 gcc/mdk/iar 三種編譯器直接編譯或者重新生成后編譯是否成功
• 使用 dist 功能對 BSP 進行發布，檢查使用 dist 命令生成的工程是否可以正常使用

ENV 配置

• 系統心跳統一設置為 1000（宏：RT_TICK_PER_SECOND）
• BSP 中需要打開調試選項中的斷言（宏：RT_DEBUG）
• 系統空閑線程棧大小統一設置為 256（宏：IDLE_THREAD_STACK_SIZE）
• 開啟組件自動初始化（宏：RT_USING_COMPONENTS_INIT）
• 需要開啟 user main 選項（宏：RT_USING_USER_MAIN）
• 默認關閉 libc（宏：RT_USING_LIBC）
• FinSH 默認只使用 MSH 模式（宏：FINSH_USING_MSH_ONLY）

IDE 配置

• 使能下載代碼后自動運行
• 使能 C99 支持
• 使能 One ELF Setion per Function（MDK）
• keil/iar 生成的臨時文件分別放到build下的 keil/iar 文件夾下
• mdk/gcc/iar 生成 bin 文件名字統一成 rtthread.bin

2. BSP 提交規范

• 提交前請認真修改 BSP 的 README.md 文件，README.md 文件的外設支持表單只填寫 BSP 支持的外設，可參考其他 BSP 填寫。查看文檔《STM32系列驅動介紹》了解驅動分類。
• 提交 BSP 分為 2 個階段提交：
  • 第一階段：基礎 BSP 包括串口驅動和 GPIO 驅動，能運行 FinSH 控制台。完成 MDK4、MDK5 、IAR 和 GCC 編譯器支持，如果芯片不支持某款編譯器（比如MDK4）可以不用做。 BSP 的 README.md 文件需要填寫第二階段要完成的驅動。
  • 第二階段：完成板載外設驅動支持，所有板載外設使用 menuconfig 配置后就能直接使用。若開發板沒有板載外設，則此階段可以不用完成。不同的驅動也要分開提交，方便 review 和合並。
• 只提交 BSP 必要的文件，刪除無關的中間文件，能夠提交的文件請對照其他 BSP。
• 提交 stm32 不同系列的 Library 庫時，請參考 f1/f4 系列的 HAL 庫，刪除多余庫文件
• 提交前要對 BSP 進行編譯測試，確保在不同編譯器下編譯正常
• 提交前要對 BSP 進行功能測試，確保 BSP 的在提交前符合工程配置章節中的要求