[bsp][stm32] sync docs

bsp/stm32/docs/STM32系列BSP制作教程.md

@@ -0,0 +1,262 @@
+# 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 框架结构如下图所示：
+
+![BSP 框架图](./figures/frame.png)
+
+每一个 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 进阶使用指南》， 外设驱动的添加方法可以参考《stm32 系列外设驱动添加指南》。
+
+- 了解 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/stm32f10x | F1 系列 BSP 模板 |
+| libraries/templates/stm32f4xx | F4 系列 BSP 模板 |
+| libraries/templates/stm32l4xx | L4 系列 BSP 模板 |
+
+本次示例所用的 F1 系列 BSP 模板文件夹结构如下所示：
+
+![F1 系列 BSP 模板文件夹内容](figures/bsp_template_dir.png)
+
+本次制作的 BSP 为 F1 系列，因此拷贝模板文件夹下的 `stm32f10x` 文件夹，并将该文件夹的名称改为 `stm32f103-atk-nano` ，如下图所示：
+
+![复制通用模板](./figures/copy.png)
+
+在接下来的 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` 工程，如下图所示：
+
+![open_cubemx](figures/open_cubemx.png)
+
+在 CubeMX 工程中将芯片型号为修改芯片型号为 STM32F103RBTx 。
+
+#### 3.2.1 生成 CubeMX 工程
+
+配置系统时钟、外设引脚等，步骤如下图所示：
+
+1. 打开外部时钟、设置下载方式、打开串口外设：
+
+![配置芯片引脚](./figures/CubeMX_1.png)
+
+2. 配置系统时钟：
+
+![配置系统时钟](./figures/CubeMX_2.png)
+
+3. 设置项目名称，并在指定地址重新生成 CubeMX 工程：
+
+![生成对应的配置代码](./figures/CubeMX_4.png)
+
+最终 CubeMX 生成的工程目录结构如下图所示：
+
+![CubeMX 图7](./figures/CubeMX_5.png)
+
+#### 3.2.2 拷贝初始化函数
+
+在 **board.c** 文件中存放了函数 `SystemClock_Config()` ，该函数负责初始化系统时钟。当使用 CubeMX 工具对系统时钟重新配置的时候，需要更新这个函数。
+
+该函数由 CubeMX 工具生成，默认存放在`board/CubeMX_Config/Src/main.c` 文件中。但是该文件并没有被包含到我们的工程中，因此需要将这个函数从 main.c 中拷贝到 board.c 文件中。在整个 BSP 的制作过程中，这个函数是唯一要要拷贝的函数，该函数内容如下所示：
+
+![board_1](./figures/board_1.png)
+
+在 **board.h** 文件中配置了 FLASH 和 RAM 的相关参数，这个文件中需要修改的是 `STM32_FLASH_SIZE` 和 `STM32_SRAM_SIZE` 这两个宏控制的参数。本次制作的 BSP 所用的 STM32F103RBTx 芯片的 flash 大小为 128k，ram 的大小为 20k，因此对该文件作出如下的修改：
+
+![修改 board.h](./figures/board_h.png)
+
+### 3.3 修改 Kconfig 选项
+
+在本小节中修改 `board/Kconfig` 文件的内容有如下两点：
+
+- 芯片型号和系列
+- BSP 上的外设支持选项
+
+芯片型号和系列的修改如下表所示：
+
+| 宏定义             | 意义     | 格式               |
+| ------------------ | -------- | ------------------ |
+| SOC_STM32F103RB    | 芯片型号 | SOC_STM32xxx       |
+| SOC_SERIES_STM32F1 | 芯片系列 | SOC_SERIES_STM32xx |
+
+关于 BSP 上的外设支持选项，一个初次提交的 BSP 仅仅需要支持 GPIO 驱动和串口驱动即可，因此在配置选项中只需保留这两个驱动配置项，如下图所示：
+
+![修改 Kconfig](./figures/Kconfig.png)
+
+### 3.4 修改工程构建相关文件
+接下来需要修改用于构建工程相关的文件。
+
+#### 3.4.1 修改链接脚本
+**linker_scripts** 链接文件如下图所示：
+
+![需要修改的链接脚本](./figures/linker_scripts.png)
+
+修改这些文件需要用户掌握链接脚本语法，根据相应的芯片进行修改。
+
+####  3.4.2 修改构建脚本
+**SConscript** 脚本决定 MDK/IAR 工程的生成以及编译过程中要添加文件。
+
+在这一步中需要修改芯片型号以及芯片启动文件的地址，修改内容如下图所示：
+
+![修改启动文件和芯片型号](./figures/SConscript.png)
+
+注意：如果在文件夹中找不到相应系列的 .s 文件，可能是多个系列的芯片重用了相同的启动文件，此时可以在 CubeMX 中生成目标芯片的工程，查看使用了哪个启动文件，然后再修改启动文件名。
+
+#### 3.4.3 修改工程模板
+
+**template** 文件是生成 MDK/IAR 工程的模板文件，通过修改该文件可以设置工程中使用的芯片型号以及下载方式。MDK4/MDK5/IAR 的工程模板文件，如下图所示：
+
+![MDK/IAR 工程模板](./figures/template_1.png)
+
+下面以 MDK5 模板的修改为例，介绍如何修改模板配置：
+
+![选择芯片型号](./figures/template_2.png)
+
+修改程序下载方式：
+
+![配置下载方式](./figures/template_3.png)
+
+### 3.5 重新生成工程
+
+重新生成工程需要使用 env 工具。
+
+#### 3.5.1 重新生成 rt_config.h 文件
+
+在 env 界面输入命令 menuconfig 对工程进行配置，并生成新的 rt_config.h 文件。如下图所示：
+
+![输入menuconfig进入配置界面](./figures/menuconfig_1.png)
+
+![选择要打开的外设](./figures/menuconfig_2.png)
+
+#### 3.5.2 重新 MDK/IAR 工程
+下面以重新生成 MDK 工程为例，介绍如何重新生成 BSP 工程。
+
+使用 env 工具输入命令 `scons --target=mdk5` 重新生成工程，如下图所示：
+
+![重新生成 BSP 工程](./figures/menuconfig_3.png)
+
+重新生成工程成功：
+
+![重新生成 BSP 工程](./figures/menuconfig_4.png)
+
+到这一步为止，新的 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 闪烁的程序
+  - LED_PIN 定义在 board.h，初始化在 board.c 完成
+- 在 `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 和驱动应该分开提交
+- 基础 BSP 包括串口驱动和 GPIO 驱动，能运行 FinSH 控制台
+- 不同的驱动也要分开提交，方便 review 和合并
+- 只提交 BSP 必要的文件，删除无关的中间文件
+- 提交 stm32 不同系列的 Library 库时，请参考 f1/f4 系列的 HAL 库，删除多余库文件
+- 提交前要对 BSP 进行编译测试，确保在不同编译器下编译正常
+- 提交前要对 BSP 进行功能测试，确保 BSP 的在提交前符合工程配置章节中的要求

bsp/stm32/docs/STM32系列BSP制作规范.md

@@ -1,35 +0,0 @@
-# STM32 系列 BSP 制作规范
-
-本文档为 RT-Thread STM32 系列 BSP 制作规范 ，规定了 STM32 BSP 制作需要遵守的准则和需要实现的基本功能。方便开发者快速完成 BSP 的制作。同时，开发人员在 BSP 制作完成后，也可以使用本规范进行检查。
-
-## BSP 制作规范
-
-STM32 BSP 的制作规范分为 3 个方面：工程配置，ENV 配置和 IDE 配置。下面将分别详细介绍这 3 个方面需要准守的准则。
-
-### 工程配置
-
-- Main 函数执行的功能要统一
-  - 如果有 LED 的话，main函数里只放一个 LED 1HZ 闪烁的程序
-  - LED_PIN 定义在board.h，初始化在 board.c 完成
-- 在 `rt_hw_board_init` 中需要完成堆的初始化：调用 `rt_system_heap_init`
-- 默认只初始化 GPIO 驱动和 FinSH 对应的串口驱动，不使用 DMA
-- 当使能板载外设驱动时，应做到不需要修改代码就能编译下载使用
-- 代码注释风格要统一
-
-### 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

bsp/stm32/docs/STM32系列BSP外设驱动使用教程.md

@@ -16,7 +16,7 @@
 
 ## 如何使用更多的板载资源
 
-开发板上一般有很多的板载资源，如 Flash、SD卡、以太网等，但是 BSP 工程默认没有添加对这些外设的支持。如何在工程里添加这些外设的支持呢？这就需要使用 ENV 工具了。下面以在正点原子阿波罗 F429 开发板上开启 SPI Flash 支持为例，一步步的展示如何使用 ENV 工具对 BSP 进行配置。
+开发板上一般有很多板载资源，如 Flash、SD卡、以太网等，但是 BSP 工程默认没有开启这些外设驱动。RT-Thread 提供了 ENV 工具来开启或关闭 BSP 的外设驱动。下面以在正点原子阿波罗 F429 开发板上开启 SPI Flash 驱动为例，一步步的展示如何使用 ENV 工具对 BSP 进行配置。
 
 ### 1）打开配置工具
 
@@ -78,38 +78,10 @@
 
 ![1543481275711](figures/on_chip_config.png)
 
-## 如何添加更多的片上资源选项
+配置完成后重新生成工程，编译下载，在 FinSH 控制台输入 `list_device` 命令，可以看到 I2C1 总线已经启用。
 
-如果想使用的片上外设是 `片上外设配置菜单` 里没有的，就需要自己添加了。下面以添加 SPI3 的驱动支持为例讲解如何添加更多片上外设支持。
+![i2c_device](figures/i2c_device.png)
 
-> 没有安装 stm32cubemx 软件的移步 STM32cube中文网：<http://www.stm32cube.com/> ，在 `资源下载` 里下载 stm32cubemx 软件。
+## 总结
 
-添加 SPI3 的外设支持需要以下几步：
-
-### 1）打开 Cube 的工程
-
-![1543486779576](figures/cubemx.png)
-
-### 2）配置好 SPI3 的引脚，并生成代码
-
-按照图中所示步骤操作：
-
-![1543487684698](figures/cube_spi3.png)
-
-### 3）修改 Konfig 文件
-
-打开board文件夹下的 Konfig 文件，拷贝 SPI2 的配置项，并重命名 SPI2 为 SPI3。
-
-![1543542657074](figures/Kconfig2.png)
-
-### 4）重新配置工程
-
-经过上一步的修改，此时重新打开 ENV 工具，在 menuconfig 中就会出现添加的 SPI3 的配置项。
-
-![1543543081284](figures/config5.png)
-
-### 5）生成工程，编译下载
-
-重新生成工程之后，编译下载到开发板，程序会自动开始运行。输入 `list_device` 命令可以看到 spi3 总线设备已经挂载成功了。
-
-![1543543446786](figures/run_spi3.png)
+当开发者需要使用未开启的外设时，只要在 ENV 工具中使能相关的外设即可，重新生成的工程中就会添加对应的驱动文件。开发者就可以利用 RT-Thread 提供的驱动开快速开发应用了。

bsp/stm32/docs/STM32系列BSP添加教程.md

@@ -1,167 +0,0 @@
-# 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 进行图形化配置；
-
-## BSP 框架介绍 
-
-BSP 框架结构如下图所示：
-
-![BSP 框架图](./figures/frame.png)
-
-STM32 BSP 由三部分组成，分别是 (1) 通用库、(2) BSP 模板和 (3) 特定芯片 BSP，下面的表格以 F1 系列 BSP 为例介绍这三个部分：
-
-|项目|文件夹|说明|
-| - | - | :-- |
-| 通用库 | stm32/libraries | 用于存放 HAL 库以及基于 HAL 库的通用驱动文件 |
-| F1 系列 BSP 工程模板 | stm32/libraries/templates/stm32f10x | F1系列 BSP 模板，通过修改该模板制作更多 F1系列 BSP |
-| 特定开发板 BSP | stm32/stm32f103-atk-nano | 在 BSP 模板的基础上修改而成 |
-
-## 新 BSP 添加方法
-
-本节以添加一个新的名为 `stm32f103-atk-nano` 的 BSP 为例，讲解如何添加一个新的 STM32 系列 BSP。
-
-新的 BSP 可以通过修改相应系列的 BSP 模板而快速得到，开发者需要修改的文件主要是在 board 文件夹下，下表总结了需要修改的文件内容：
-
-| 项目 | 需要修改的内容说明 |
-|-------------|-------------------------------------------------------|
-| CubeMX_Config （文件夹）| CubeMX 工程 |
-|board.c/h | 系统时钟、GPIO 初始化函数、芯片 SRAM 大小 |
-| Kconfig | 芯片型号、系列、外设资源 |
-| SConscript | 芯片启动文件、目标芯片型号 |
-| linker_scripts （文件夹）| BSP 特定的链接脚本 |
-| template.uvprojx ; template.uvproj ; template.ewp | MDK/IAR 工程模板：修改芯片型号、仿真器选项 |
-
-添加新 BSP 的过程分为如下五个步骤：
-
-1. 复制通用模板
-2. 使用 CubeMX 配置工程
-3. 修改 Kconfig 文件中 BSP 的特定选项
-4. 修改构建工程相关文件
-5. 重新生成工程
-
-在接下来的章节中将会详细介绍这五个步骤，帮助开发者快速创建所需要的 BSP。
-
-### 复制通用模板
-
-制作新 BSP 的第一步是复制一份同系列的 BSP 模板作为新 BSP 的基础，目前提供的通用 BSP 模板如下：
-
-| 工程模板 | 说明 |
-| ------- | ---- |
-| libraries/templates/stm32f10x | F1系列芯片模板 |
-| libraries/templates/stm32f4xx | F4系列芯片模板 |
-| libraries/templates/stm32f7xx | F7系列芯片模板 |
-| libraries/templates/stm32l4xx | L4系列芯片模板 |
-
-拷贝 `stm32/libraries/templates/stm32f10x` 文件夹并改名为 `stm32/stm32f103-atk-nano` 。如下图所示：
-
-![复制通用模板](./figures/copy.png)
-
-### 使用 CubeMX 配置工程
-
-这一步中需要在 **CubeMX_Config** 文件夹下创建一个基于目标芯片的 CubeMX 工程，本次创建示例 BSP 选择的芯片型号为 STM32F103RBTx 。
-
-#### 重新生成 CubeMX 工程
-
-配置系统时钟、外设引脚等，步骤如下图所示：
-
-1. 打开外部时钟、设置下载方式、打开串口外设：
-
-![配置芯片引脚](./figures/CubeMX_1.png)
-
-2. 配置系统时钟：
-
-![配置系统时钟](./figures/CubeMX_2.png)
-
-3. 设置项目名称，并在指定地址重新生成 CubeMX 工程：
-
-![生成对应的配置代码](./figures/CubeMX_4.png)
-
-最终 CubeMX 生成的工程目录结构如下图所示：
-
-![CubeMX 图7](./figures/CubeMX_5.png)
-
-#### 拷贝初始化函数
-
-**board.c** 文件中只包含 SystemClock_Config() 和 MX_GPIO_Init() 这两个函数。这两个函数由 CubeMX 工具生成，需要从目录 `board/CubeMX_Config/Src/main.c` 文件中拷贝到 board.c 文件中，如下图所示：
-
-![board_1](./figures/board_1.png)
-
- **board.h** 文件内 STM32_SRAM_SIZE 大小修改如下图所示：
-
-![board_2](./figures/board_2.png)
-
-### 修改 Kconfig 选项
-
-修改 `board/Kconfig` 文件内容，如下图所示：
-
-![Kconfig](./figures/Kconfig.png)
-
-上图中使用的宏定义说明如下所示：
-
-| 宏定义 | 意义 | 格式 |
-|-|-|-|
-| SOC_STM32F103RB | 芯片型号 | SOC_STM32xxx |
-| SOC_SERIES_STM32F1 | 芯片系列| SOC_SERIES_STM32xx |
-
-用户可参考这个链接学习 Kconfig语法：(https://blog.csdn.net/jianwen_hi/article/details/53398141)
-
-### 修改工程构建相关文件
-接下来需要修改用于构建工程相关的文件。
-
-#### 修改链接脚本
-**linker_scripts** 链接文件如下图所示：
-
-![需要修改的链接脚本](./figures/linker_scripts.png)
-
-修改这些文件需要用户掌握链接脚本语法，根据相应的芯片进行修改。
-
-####  修改 SConscript 构建脚本
-**SConscript** 脚本决定 MDK/IAR 工程的生成过程中要添加那些文件。在这一步中需要修改芯片型号以及芯片启动文件的地址，修改内容如下图所示：
-
-![修改启动文件和芯片型号](./figures/SConscript.png)
-
-注意：如果在文件夹中找不到相应系列的 .s 文件，可能是多个系列的芯片重用了相同的启动文件，此时可以在 CubeMX 中生成目标芯片的工程，查看使用了哪个启动文件，然后再修改启动文件名。
-
-#### 修改工程模板
-
-**template** 文件是生成 MDK/IAR 工程的模板文件，通过修改该文件可以设置工程中使用的芯片型号以及下载方式。MDK4/MDK5/IAR 的工程模板文件，如下图所示：
-
-![MDK/IAR 工程模板](./figures/template_1.png)
-
-下面以 MDK5 模板的修改为例，介绍如何修改模板配置：
-
-![选择芯片型号](./figures/template_2.png)
-
-修改程序下载方式：
-
-![配置下载方式](./figures/template_3.png)
-
-### 重新生成工程
-
-重新生成工程需要使用 env 工具，在 env 界面输入命令 menuconfig 对工程进行配置，并生成新的 rt_config.h 文件。如下图所示：
-
-![输入menuconfig进入配置界面](./figures/menuconfig_1.png)
-
-![选择要打开的外设](./figures/menuconfig_2.png)
-
-下面以重新生成 MDK 工程为例，介绍如何重新生成 BSP 工程。
-
-使用 env 工具输入命令 `scons --target=mdk5` 重新生成工程，如下图所示：
-
-![重新生成 BSP 工程](./figures/menuconfig_3.png)
-
-重新生成工程成功：
-
-![重新生成 BSP 工程](./figures/menuconfig_4.png)
-
-到这一步为止，新的 BSP 就制作完毕，可以使用了。

bsp/stm32/docs/STM32系列外设驱动添加指南.md

@@ -0,0 +1,98 @@
+# STM32 系列外设驱动添加指南
+
+## 1. 简介
+
+本文档是为需要给现有的 STM32 BSP 添加更多外设驱动的开发者准备的。通过阅读本文，开发者可以按照自己的实际情况给现有 BSP 添加自己需要的驱动。
+
+## 2. 前提要求
+
+- 熟练使用 ENV 工具，参考：[RT-Thread env 工具用户手册](https://www.rt-thread.org/document/site/rtthread-development-guide/rtthread-tool-manual/env/env-user-manual/)
+- 熟悉 Kconfig 语法
+- 熟悉 STM32CubeMX 工具
+- 对 RT-Thread 设备驱动框架有一定了解
+
+## 3. 如何添加更多的外设驱动选项
+
+本章节以添加片上外设驱动为例，讲解如何为 BSP 添加更多可用驱动。如果想使用的片上外设是 `片上外设配置菜单` 里没有的，就需要开发者自己添加了。下面我们将演示如何为 stm32f429-atk-apollo BSP 添加 SPI3 驱动。
+
+> 没有安装 stm32cubemx 软件的可以访问 STM32cube中文网：<http://www.stm32cube.com/> ，在 `资源下载` 里下载 stm32cubemx 软件。
+
+阿波罗 BSP 默认只支持 SPI1、SPI2 和 SPI5，是不支持 SPI3 的。开发者如果需要使用 SPI3，则需要自己添加。
+
+![spi_config](figures/spi_config.png)
+
+添加 SPI3 的外设支持需要以下几步：
+
+### 1）打开 STM32CubeMX 工程
+
+打开 BSP 的 STM32CubeMX 配置文件。
+
+![1543486779576](figures/cubemx.png)
+
+### 2）按原理图配置 SPI3 的引脚，并生成代码
+
+按图示顺序配置 SPI3，并生成代码。
+
+![1543487684698](figures/cube_spi3.png)
+
+> 为 BSP 添加驱动时，STM32CubeMX 工具可以快速的完成**使能外设**和**配置管脚**的工作。而外设初始化，中断配置，DMA配置等等则由 RT-Thread 提供的驱动文件来完成。也就是说，虽然 STM32CubeMX 生成了多个文件用来初始化外设，但 RT-Thread 只使用了 STM32CubeMX  生成的 `stm32fxx_hal_msp.c` 文件和 `stm32fxx_hal_conf.h` 文件。
+>
+> 对于不同的外设驱动，通过 STM32CubeMX 工具配置的内容也不一样。开发者可以参考本文档的附录 [CubeMX配置说明]() 章节来了解不同外设的配置方法。
+
+### 3）修改 Kconfig 文件
+
+打开 board 文件夹下的 Konfig 文件，拷贝 SPI2 的配置项，并重命名 SPI2 为 SPI3。
+
+![1543542657074](figures/Kconfig2.png)
+
+### 4）重新配置工程
+
+经过上一步的修改，此时重新打开 ENV 工具，在 menuconfig 中就会出现添加的 SPI3 的配置项。
+
+![1543543081284](figures/config5.png)
+
+### 5）生成工程，检查驱动文件
+
+使用 ENV 重新生成工程并打开，检查原有驱动文件是否支持新添加的驱动（查看是否有新驱动的配置文件，中断函数，DMA配置和中断函数等等），如不支持，需参考现有驱动添加相关的代码。
+
+![spi_code](figures/spi_code.png)
+
+### 6）编译下载
+
+检查完工程后，编译下载到开发板，程序会自动开始运行。输入 `list_device` 命令，可以看到 spi3 总线已经注册到内核，说明驱动已经添加成功。
+
+![1543543446786](figures/run_spi3.png)
+
+
+## 4. 注意事项
+
+- 部分驱动如果没有适配 BSP 所属的 STM32 系列，请等待 RT-Thread 团队更新。
+  - 驱动文件对 STM32 系列的支持情况可以查看 [STM32系列驱动介绍文档](STM32系列驱动介绍文档.md)。
+- 对于驱动文件或文档说明，有任何建议或者意见，欢迎反馈到 [RT_Thread GitHub](https://github.com/RT-Thread/rt-thread) 网站或 [RT-Thread 官方论坛](https://www.rt-thread.org/qa/forum.php)。
+
+## 5. 附录
+
+### 5.1 CubeMX配置说明
+
+本小节介绍 stm32 系列的 BSP 是如何利用 CubeMX 工具对 BSP 进行配置的。
+
+就像文档中提到的那样，stm32 系列的 BSP 只利用了  CubeMX 工具生成的  `stm32XXxx_hal_conf.h` 和 `stm32XXxx_hal_msp.c` 文件。在 HAL 库中， `stm32XXxx_hal_conf.h` 文件里提供的宏开关会决定 HAL 库将哪些外设驱动添加到工程中。 而`stm32XXxx_hal_msp.c` 文件中则存放了在 CubeMX 工具中开启的外设驱动的配置代码。
+
+### 5.2 外设配置总结
+
+当开发者想要在 BSP 中添加更多驱动时，需要使用 CubeMX 工具来配置这些外设。对于绝大多数驱动的配置，只需要在工具中使能相应的外设即可。但是对于一些复杂的外设，则需要更多的配置内容。下表展示了不同驱动在 CubeMX 工具配置步骤的总结：
+
+| 序号 | 驱动     | CubeMx 工程中的配置情况（**加粗部分为必做步骤**）            |
+| :--: | :------- | :----------------------------------------------------------- |
+|  1   | GPIO     | 无需任何操作                                                 |
+|  2   | UART     | **开启该外设** ，然后配置所需要的引脚（或者使用默认引脚）    |
+|  3   | SPI      | **开启该外设** ，然后配置所需要的引脚（或者使用默认引脚）    |
+|  4   | I2C      | 依赖于PIN 驱动，无需任何操作                                 |
+|  5   | TIMER    | **使能 internal Clock 时钟**                                 |
+|  7   | PWM      | **首先使能 internal Clock 时钟，然后为 channelx 选项选择PWM Generation CHx，** 最后配置所需要的引脚（或者使用默认引脚） |
+|  8   | ADC      | **开启该外设，然后选择使用的通道**                           |
+|  9   | RTC      | **开启该外设，然后在时钟树状图里将 RTC 选择为 LSE 时钟**     |
+|  10  | Watchdog | **开启该外设**                                               |
+|  11  | EMAC     | **配置 ETH 外设的工作模式（一般为 RMII 模式）**              |
+|  12  | SDRAM    | **需要根据板载的 SDRAM 型号配置片选脚，地址线，数据线等**    |
+

bsp/stm32/docs/STM32系列驱动介绍.md

@@ -0,0 +1,65 @@
+#  外设驱动介绍与应用
+
+在 RT-Thread 实时操作系统中，各种各样的设备驱动是通过一套  I/O 设备管理框架来管理的。设备管理框架给上层应用提供了一套标准的设备操作 API，开发者通过调用这些标准设备操作 API，可以高效地完成和底层硬件外设的交互。设备管理框架的结构如下图所示：
+
+![rt_device](figures/rt_device.png)
+
+使用 I/O 设备管理框架开发应用程序，有如下优点：
+
+- 使用同一套标准的 API 开发应用程序，使应用程序具有更好的移植性
+- 底层驱动的升级和修改不会影响到上层代码
+- 驱动和应用程序相互独立，方便多个开发者协同开发
+
+## 1. 驱动分类介绍
+
+本小节介绍 BSP 提供的不同类别驱动的概念，对一个 BSP 而言，有如下三类驱动：
+
+- **板载外设驱动**：指 MCU 之外，开发板上外设，例如 TF 卡、以太网和 LCD 等
+- **片上外设驱动**：指 MCU 芯片上的外设，例如硬件定时器、ADC 和看门狗等
+- **扩展模块驱动**：指可以通过扩展接口或者杜邦线连接的开发板的模块，例如 ESP8266 模块
+
+这三种外设的示意图如下所示：
+
+![Peripheral](figures/Peripheral.png)
+
+## 2. 外设驱动的使用方法
+
+当前 RT-Thread 提供的驱动库已经支持 STM32 多个系列的 BSP。点击下表中的驱动名称，即可跳转到对应驱动框架的介绍文档。开发者可以通过阅读相关资料，了解如何在应用开发中通过设备驱动框架来使用这些外设驱动。
+
+### 2.1 片上外设
+
+| 序号 | 驱动                                                         | 简介                                             |
+| ---- | ------------------------------------------------------------ | ------------------------------------------------ |
+| 1    | [GPIO](https://www.rt-thread.org/document/site/rtthread-application-note/driver/gpio/an0002-rtthread-driver-gpio/) | 操作 GPIO 管脚                                   |
+| 2    | UART                                                         | 通过串口收发数据                                 |
+| 3    | soft I2C                                                     | 通过软件 I2C 收发数据                            |
+| 4    | SPI                                                          | 通过 SPI 收发数据                                |
+| 5    | ADC                                                          | 测量管脚上的模拟量                               |
+| 6    | SDIO                                                         | 通过 SDIO 读写数据                               |
+| 7    | TIMER                                                        | 使用硬件定时器实现测量时间和定时执行回调函数功能 |
+| 8    | PWM                                                          | 在特定的管脚输出 PWM 波形                        |
+| 9    | RTC                                                          | 设置和读取时间                                   |
+| 10   | WDT                                                          | 看门狗驱动                                       |
+| 11   | QSPI                                                         | 通过 SPI（1、2、4线） 收发数据                   |
+
+### 2.2 板载外设
+
+| 序号 | 驱动    | 简介                                    |
+| ---- | ------- | --------------------------------------- |
+| 1    | SD      | 适用于 SPI 接口或 SDIO 接口的 SD(TF) 卡 |
+| 2    | ETH PHY | 以太网                                  |
+| 3    | USB PHY | USB                                     |
+| 4    | LCD     | 显示屏                                  |
+
+### 2.3 扩展模块
+
+| 序号 | 驱动     | 简介                   |
+| ---- | -------- | ---------------------- |
+| 1    | ESP8266  | 串口转 WIFI 模块       |
+| 2    | ENC28J60 | SPI 接口的以太网控制器 |
+
+### 2.4 驱动示例代码
+
+// TODO 添加驱动示例代码相关的介绍，考虑如何使用这些驱动示例代码，如果暂时没有，这一小结可以先删去
+
+在 RT-Thread 的 `examples\test` 目录下，有 RT-Thread 提供的基于不同外设驱动的示例代码。在 env 工具中开启 BSP 中要测试的驱动，并将 `examples\test` 中对应的驱动框架测试文件加入工程，即可快速测试 BSP 中提供的驱动。