轉載：https://github.com/RT-Thread/rt-thread/blob/master/bsp/stm32/docs/STM32%E7%B3%BB%E5%88%97BSP%E5%88%B6%E4%BD%9C%E6%95%99%E7%A8%8B.md
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 檔案夾中需要修改的内容：
3.2 使用 CubeMX 配置工程
在制作 BSP 的第二步，需要建立一個基于目标晶片的 CubeMX 工程。預設的 CubeMX 工程在 CubeMX_Config 檔案夾中，輕按兩下打開 CubeMX_Config.ioc 工程，如下圖所示：
在 CubeMX 工程中将晶片型号為修改晶片型号為 STM32F103RBTx 。
3.2.1 生成 CubeMX 工程
配置系統時鐘、外設引腳等，步驟如下圖所示：
打開外部時鐘、設定下載下傳方式、打開序列槽外設（注意隻需要選擇序列槽外設引腳即可，無需配置其他參數）：
配置晶片引腳
配置系統時鐘：
配置系統時鐘
設定項目名稱，并在指定位址重新生成 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 的在送出前符合工程配置章節中的要求