[STM32][DOC][翻译] 修复‘STM32系列BSP制作教程’的小问题，增加对应翻译

bsp/stm32/docs/How to make a STM32 BSP for RT-Thread.md

@@ -0,0 +1,245 @@
+# How to make a STM32 BSP for RT-Thread
+
+In order to allow developers to use BSP for development better and more conveniently, the RT-Thread team rearranged the existing STM32 series of BSPs and launched a new BSP framework. The new BSP framework has been greatly improved in terms of ease of use, portability, driver integrity, and code standardization. Development under the new BSP framework can greatly improve the efficiency of application development. 
+
+The new BSP framework also introduces the CubeMX tool, which can be used to configure the peripheral pins which are used in the BSP. The CubeMX tool provides a graphical configuration interface. This graphical configuration method is more intuitive for developers. It not only allows developers to flexibly configure the resources used in the BSP, but also allows developers to understand the use of resources at a glance .
+
+The main features of the new STM32 BSP framework are as follows: 
+
+- Provide multiple series of BSP templates, greatly reducing the difficulty of adding new BSPs; 
+- Each BSP is equipped with a complete set of driver files, so that developers can easily use all drivers; 
+- Developers can use the CubeMX tool to configure the BSP graphically.
+
+## 1. Introduction to BSP Framework 
+
+The BSP frame structure is shown in the figure below: 
+
+![BSP 框架图](./figures/frame.png)
+
+Each BSP of the STM32 series consists of three parts, namely the general library, the BSP template and the specific development board BSP. The following table uses the F1 series BSP as an example to introduce these three parts: 
+
+| Item                                | Folder                              | Detail                                                       |
+| ----------------------------------- | ----------------------------------- | :----------------------------------------------------------- |
+| General library                     | stm32/libraries                     | Used to place HAL library and multi-series general peripheral driver files developed based on HAL library |
+| STM32F1 series BSP project template | stm32/libraries/templates/stm32f10x | You can make more F1 series BSP by modifying this template   |
+| Specific development board BSP      | stm32/stm32f103-blue-pill           | Modified on the basis of the BSP template                    |
+
+## 2. Knowledge of background
+
+## 3. Make a STM32 BSP for steps
+
+Making a STM32 BSP is divided into the following five steps: 
+
+1. Copy the generic template 
+2. Use CubeMX tool to configure the project
+3. Modify the Kconfig file in the BSP 
+4. Modify the relevant files of the build project
+5. Regenerate the project
+
+In the following chapters, these five steps will be introduced in detail to help developers quickly create the required BSP. 
+
+### 3.1 Copy the generic template 
+
+The first step in making a new BSP is to copy a BSP template of the same series as the basis, and obtain a new BSP by modifying the BSP template. 
+
+The folder structure of the F1 series BSP template used in this example is as follows: 
+
+![F1 系列 BSP 模板文件夹内容](figures/bsp_template_dir.png)
+
+Copy the `stm32f10x` folder under the template folder and change the name of the folder to `stm32f103-blue-pill`, as shown in the following figure: 
+
+![复制通用模板](./figures/copy.png)
+
+Modify the configuration file in the board folder. The modified content is shown in the following table: 
+
+| Item                      | Instruction                                                  |
+| ------------------------- | ------------------------------------------------------------ |
+| CubeMX_Config （folder）  | CubeMX project                                               |
+| linker_scripts （folder） | BSP link script                                              |
+| board.c/h                 | System clock, GPIO initialization function, chip memory size |
+| Kconfig                   | Chip series, peripheral resources                            |
+| SConscript                | Chip startup file, target chip model                         |
+
+### 3.2 Use CubeMX to configure the project 
+
+Create a CubeMX project based on the target chip. The default CubeMX project is in the **CubeMX_Config** folder, double-click to open the `CubeMX_Config.ioc` project, as shown in the figure below: 
+
+![open_cubemx](figures/open_cubemx.png)
+
+Change the chip model to STM32F103C8Tx in the CubeMX project. 
+
+#### 3.2.1 Generate CubeMX project 
+
+Configure the system clock, peripheral pins, etc. The steps are shown in the figure below: 
+
+1. Turn on the external clock, set the download mode, and turn on the serial peripherals (note that only the pins of the serial peripherals need to be selected, no other parameters need to be configured): 
+
+   ![配置芯片引脚](./figures/CubeMX_1.png)
+
+2. Configure the system clock: 
+
+   ![配置系统时钟](./figures/CubeMX_2.png)
+
+3. Set the project name and regenerate the CubeMX project at a specified address: 
+
+   ![生成对应的配置代码](./figures/CubeMX_4.png)
+
+   Note: When generating the code, do not check the following options (ie: Do not let it generate a peripheral initialization as a pair of .c/.h files per perioheral.) 
+
+   ![generate-code](figures/generate-code.png)
+
+4. The final project directory structure generated by CubeMX is shown in the figure below: 
+
+   ![CubeMX 图7](./figures/CubeMX_5.png)
+
+#### 3.2.2 Copy initialization function 
+
+The function `SystemClock_Config()` is placed in the **board.c** file, which is responsible for initializing the system clock. When using the CubeMX tool to reconfigure the system clock, this function needs to be updated. This function is generated by the CubeMX tool and is placed in the file `board/CubeMX_Config/Src/main.c` by default. However, this file does not include in our project, so we need to copy this function from main.c to the board.c file. In the entire BSP making process, this function is the only function to be copied. The content of this function is as follows: 
+
+![board_1](./figures/board_1.png)
+
+The relevant parameters of FLASH and RAM are configured in the **board.h** file. What needs to be modified in this file is the parameters controlled by the two macros `STM32_FLASH_SIZE` and `STM32_SRAM_SIZE`. The flash size of the STM32F103C8Tx chip used in the BSP produced this time is 64k, and the size of the ram is 20k, so the file is modified as follows: 
+
+![修改 board.h](./figures/board_h.png)
+
+#### 3.2.3 Heap memory configuration 
+
+Normally, a part of the memory space in the system RAM will be used as heap memory. The function of the following code is to specify the start address **HEAP_BEGIN** and end address **HEAP_END** of the heap memory under different compilers. The values of **HEAP_BEGIN** and **HEAP_END** here need to be consistent with the configuration modified in the following section [3.4.1 Modify Link Script](# 3.4.1 Modify Link Script).
+
+In some series of chips, the chip RAM may be distributed in multiple discrete memory areas. At this time, the location of the heap memory can be in the same continuous memory area as the system memory, or it can be stored in a separate memory area. For example, on the L4 series of chips, the heap memory can be configured in a 96k memory space with a starting address of `0x20000000`, and the 32k memory space starting from `0x10000000` can be used as the system running memory. 
+
+![heap_config](figures/heap_config.png)
+
+### 3.3 Modify Kconfig configuration
+
+Modify the contents of the `board/Kconfig` file in this section as follows: 
+
+- Chip model and series 
+- Peripheral support options on BSP 
+
+The modification of chip model and series is shown in the following table: 
+
+| Macro Definition   | Meaning     | Format             |
+| ------------------ | ----------- | ------------------ |
+| SOC_STM32F103RB    | Chip model  | SOC_STM32xxx       |
+| SOC_SERIES_STM32F1 | Chip series | SOC_SERIES_STM32xx |
+
+Regarding the peripheral support options on the BSP, a BSP submitted for the first time only needs to support the GPIO driver and the serial port driver, which means only these two driver configuration items need to be retained in the configuration options, as shown in the following figure: 
+
+![修改 Kconfig](./figures/Kconfig.png)
+
+### 3.4 Modify project building related files 
+
+#### 3.4.1 Modify the link script 
+
+**linker_scripts** The link file is as shown in the figure below: 
+
+![需要修改的链接脚本](./figures/linker_scripts.png)
+
+The following uses the link script link.sct used by MDK as an example to demonstrate how to modify the link script: 
+
+![linkscripts_change](figures/linkscripts_change.png)
+
+The chip used to make the BSP this time is STM32F103RB, and the FLASH is 128k, so modify the parameters of LR_IROM1 and ER_IROM1 to 0x00020000. The size of RAM is 20k, so modify the parameter of RW_IRAM1 to 0x00005000. Such a modification method is sufficient for general applications. If there are special requirements in the future, you need to modify it as required according to the syntax of the link script. When modifying the link script, you can refer to the [**3.2.3 Heap memory configuration**](# 3.2.3 Heap memory configuration) chapter to determine the BSP memory allocation. 
+
+The other two link script files are link.icf used by IAR and link.lds used by the GCC compiler. The modification method is similar, as shown in the following figure: 
+
+![link_icf](figures/link_icf.png)
+
+![link_lds](figures/link_lds.png)
+
+#### 3.4.2 Modify the build script 
+
+The **SConscript** script determines the files to be added during the generation and compilation of the MDK/IAR project. 
+
+In this step, you need to modify the chip model and the address of the chip startup file. The modification content is shown in the figure below: 
+
+![修改启动文件和芯片型号](./figures/SConscript.png)
+
+Note: If you cannot find the .s file of the corresponding series in the folder, it may be that multiple series of chips reuse the same startup file. At this time, you can generate the target chip project in CubeMX to see which startup file is used. Then modify the startup file name. 
+
+#### 3.4.3 Modify the project template 
+
+The **template** file is a template file for generating the MDK/IAR project. By modifying the file, you can set the chip model used in the project and the download method. The project template file of MDK4/MDK5/IAR, as shown in the figure below: 
+
+![MDK/IAR 工程模板](./figures/template_1.png)
+
+The following takes the modification of the MDK5 template as an example to introduce how to modify the template configuration: 
+
+![选择芯片型号](./figures/template_2.png)
+
+Modify the program download method: 
+
+![配置下载方式](./figures/template_3.png)
+
+### 3.5 Regenerate the project 
+
+Env tool is required to regenerate the project. 
+
+#### 3.5.1 Regenerate the rtconfig.h file 
+
+Enter the command menuconfig in the Env interface to configure the project and generate a new rtconfig.h file. As shown below: 
+
+![输入menuconfig进入配置界面](./figures/menuconfig_1.png)
+
+#### 3.5.2 Rebuild the MDK/IAR project 
+
+The following takes regenerating the MDK project as an example to introduce how to regenerate the BSP project. Use the Env tool to enter the command `scons --target=mdk5` to regenerate the project, as shown in the following figure: 
+
+![重新生成 BSP 工程](./figures/menuconfig_3.png)
+
+Rebuild the project successfully: 
+
+![重新生成 BSP 工程](./figures/menuconfig_4.png)
+
+At this point, the new BSP can be used. Next, we can use the commands `scons --target=mdk4` and `scons --target=iar` respectively to update the MDK4 and IAR projects so that the BSP becomes a complete BSP that can be submitted to GitHub (Making MDK4 project is optional). 
+
+## 4. Specifications 
+
+This chapter introduces the specifications that should be followed when making and submitting the RT-Thread STM32 series BSP. After the BSP is produced, the developer can check the produced BSP according to the checkpoints set out in this specification to ensure that the BSP has a higher quality before submission. 
+
+### 4.1 Specification of making BSP
+
+The specifications of making STM32 BSP are mainly divided into three aspects: engineering configuration, ENV configuration and IDE configuration. In the existing STM32 series BSP templates, the templates have been configured according to the following specifications. In the process of making a new BSP, when copying the template for modification, you need to be careful not to modify these default configurations. After the BSP is completed, the newly-made BSP needs to be tested for its function, and the code is submitted after the function is normal. The production specifications of the BSP will be described in detail below:
+
+#### 4.1.1 Project configuration 
+
+- Comply with RT-Thread coding standard, unified code comment style 
+
+- The main function remains the same   
+  - If there is an LED, **only put ONE** LED 1HZ flashing program in the main function 
+- Heap initialization needs to be completed in `rt_hw_board_init`: call `rt_system_heap_init` 
+- By default, only the GPIO driver and the serial port driver corresponding to FinSH are initialized, and DMA is not used 
+- When the onboard peripheral driver is enabled, it should be able to compile, download and use without modifying the code
+- Before submitting, check whether the three compilers of GCC/MDK/IAR are directly compiled or compiled successfully after regenerating 
+- Use the `dist` command to publish the BSP and check whether the project generated by the dist command can be used normally 
+
+#### 4.1.2 ENV configuration 
+
+- The system heartbeat is uniformly set to 1000 (Macro: RT_TICK_PER_SECOND) 
+- The assertion in the debugging option needs to be turned on in the BSP (macro: RT_DEBUG) 
+- The system idle thread stack size is uniformly set to 256 (Macro: IDLE_THREAD_STACK_SIZE) 
+- Turn on automatic component initialization (Macro: RT_USING_COMPONENTS_INIT) 
+- Need to enable the user main option (Macro: RT_USING_USER_MAIN) 
+- Disable libc by default (Macro: RT_USING_LIBC) 
+- FinSH only uses MSH mode by default (Macro: FINSH_USING_MSH_ONLY) 
+
+#### 4.1.3 IDE configuration
+
+- Enable automatic operation after downloading the code 
+- Enable C99 support 
+- Enable One ELF Section per Function (MDK)
+- Temporary files generated by MDK/IAR are placed in the keil/iar folder under build
+- The names of bin files generated by MDK/GCC/IAR are unified into rtthread.bin 
+
+### 4.2 Specification of BSP submission
+
+- Please carefully modify the README.md file of the BSP before submission. The peripheral support form of the README.md file only fills in the peripherals supported by the BSP. You can refer to other BSPs to fill in. 
+- Submission of BSP is divided into two stages: 
+  - The first stage: Basic BSP includes serial port driver and GPIO driver, and can run FinSH console. Completion of MDK4, MDK5, IAR and GCC compiler support, if the chip does not support a certain type of compiler (such as MDK4), you don’t need to do it.
+  - The second stage: complete the onboard peripheral driver support, all onboard peripherals can be used directly after they are configured using `menuconfig`. If the development board does not have on-board peripherals, this stage don't need to be completed. Different drivers should be submitted separately to facilitate review and merging. 
+
+- Only submit documents necessary for the BSP and delete irrelevant intermediate documents. Please check other BSPs for documents that can be submitted. 
+- When submitting libraries of different series of STM32, please refer to the HAL libraries of f1/f4 series and delete redundant library files.
+- Compile and test the BSP before submission to ensure that it compiles properly under different compilers.
+- Perform functional tests on the BSP before submission to ensure that the BSP meets the requirements in the engineering configuration chapter before submission.

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

@@ -214,17 +214,17 @@ BSP 的制作过程分为如下五个步骤：
 
 ### 3.5 重新生成工程
 
-重新生成工程需要使用 env 工具。
+重新生成工程需要使用 Env 工具。
 
 #### 3.5.1 重新生成 rtconfig.h 文件
 
-在 env 界面输入命令 menuconfig 对工程进行配置，并生成新的 rtconfig.h 文件。如下图所示：
+在 Env 界面输入命令 menuconfig 对工程进行配置，并生成新的 rtconfig.h 文件。如下图所示：
 
 ![输入menuconfig进入配置界面](./figures/menuconfig_1.png)
 
 ![选择要打开的外设](./figures/menuconfig_2.png)
 
-#### 3.5.2 重新 MDK/IAR 工程
+#### 3.5.2 重新生成 MDK/IAR 工程
 下面以重新生成 MDK 工程为例，介绍如何重新生成 BSP 工程。
 
 使用 env 工具输入命令 `scons --target=mdk5` 重新生成工程，如下图所示：
@@ -237,7 +237,7 @@ BSP 的制作过程分为如下五个步骤：
 
 到这一步为止，新的 BSP 就可以使用了。
 
-接下来我们可以分别使用命令 `scons --target=mdk4` 和 `scons --target=iar`，来更新 mdk4 和 iar 的工程，使得该 BSP 变成一个完整的，可以提交到 GitHub 的 BSP。
+接下来我们可以分别使用命令 `scons --target=mdk4` 和 `scons --target=iar`，来更新 MDK4 和 IAR 的工程，使得该 BSP 变成一个完整的，可以提交到 GitHub 的 BSP （MDK4工程的制作为可选）。
 
 感谢每一位贡献代码的开发者，RT-Thread 将与你一同成长。
 
@@ -245,13 +245,13 @@ BSP 的制作过程分为如下五个步骤：
 
 本章节介绍 RT-Thread STM32 系列 BSP 制作与提交时应当遵守的规范 。开发人员在 BSP 制作完成后，可以根据本规范提出的检查点对制作的 BSP 进行检查，确保 BSP 在提交前有较高的质量 。
 
-### 1. BSP 制作规范
+### 4.1 BSP 制作规范
 
 STM32 BSP 的制作规范主要分为 3 个方面：工程配置，ENV 配置和 IDE 配置。在已有的 STM32 系列 BSP 的模板中，已经根据下列规范对模板进行配置。在制作新 BSP 的过程中，拷贝模板进行修改时，需要注意的是不要修改这些默认的配置。BSP 制作完成后，需要对新制作的 BSP 进行功能测试，功能正常后再进行代码提交。
 
 下面将详细介绍 BSP 的制作规范。
 
-#### 工程配置
+#### 4.1.1 工程配置
 
 - 遵从RT-Thread 编码规范，代码注释风格统一
 - main 函数功能保持一致
@@ -259,10 +259,10 @@ STM32 BSP 的制作规范主要分为 3 个方面：工程配置，ENV 配置和
 - 在 `rt_hw_board_init` 中需要完成堆的初始化：调用 `rt_system_heap_init`
 - 默认只初始化 GPIO 驱动和 FinSH 对应的串口驱动，不使用 DMA
 - 当使能板载外设驱动时，应做到不需要修改代码就能编译下载使用
-- 提交前应检查 gcc/mdk/iar 三种编译器直接编译或者重新生成后编译是否成功
+- 提交前应检查 GCC/MDK/IAR 三种编译器直接编译或者重新生成后编译是否成功
-- 使用 dist 功能对 BSP 进行发布，检查使用 dist 命令生成的工程是否可以正常使用
+- 使用 `dist` 命令对 BSP 进行发布，检查使用 `dist` 命令生成的工程是否可以正常使用
 
-#### ENV 配置
+#### 4.1.2 ENV 配置
 
 - 系统心跳统一设置为 1000（宏：RT_TICK_PER_SECOND）
 - BSP 中需要打开调试选项中的断言（宏：RT_DEBUG）
@@ -272,21 +272,21 @@ STM32 BSP 的制作规范主要分为 3 个方面：工程配置，ENV 配置和
 - 默认关闭 libc（宏：RT_USING_LIBC）
 - FinSH 默认只使用 MSH 模式（宏：FINSH_USING_MSH_ONLY）
 
-#### IDE 配置
+#### 4.1.3 IDE 配置
 
 - 使能下载代码后自动运行
 - 使能 C99 支持
-- 使能 One ELF Setion per Function（MDK）
+- 使能 One ELF Section per Function（MDK）
-- keil/iar 生成的临时文件分别放到build下的 keil/iar 文件夹下
+- MDK/IAR 生成的临时文件分别放到build下的 MDK/IAR 文件夹下
-- mdk/gcc/iar 生成 bin 文件名字统一成 rtthread.bin
+- MDK/GCC/IAR 生成 bin 文件名字统一成 rtthread.bin
 
-### 2. BSP 提交规范
+### 4.2 BSP 提交规范
 
 - 提交前请认真修改 BSP 的 README.md 文件，README.md 文件的外设支持表单只填写 BSP 支持的外设，可参考其他 BSP 填写。查看文档[《STM32系列驱动介绍》](./STM32系列驱动介绍.md)了解驱动分类。
 - 提交 BSP 分为 2 个阶段提交：
   - 第一阶段：基础 BSP 包括串口驱动和 GPIO 驱动，能运行 FinSH 控制台。完成 MDK4、MDK5 、IAR 和 GCC 编译器支持，如果芯片不支持某款编译器（比如MDK4）可以不用做。 BSP 的 README.md 文件需要填写第二阶段要完成的驱动。
-  - 第二阶段：完成板载外设驱动支持，所有板载外设使用 menuconfig 配置后就能直接使用。若开发板没有板载外设，则此阶段可以不用完成。不同的驱动也要分开提交，方便 review 和合并。
+  - 第二阶段：完成板载外设驱动支持，所有板载外设使用 menuconfig 配置后就能直接使用。若开发板没有板载外设，则此阶段可以不用完成。不同的驱动要分开提交，方便 review 和合并。
 - 只提交 BSP 必要的文件，删除无关的中间文件，能够提交的文件请对照其他 BSP。
-- 提交 stm32 不同系列的 Library 库时，请参考 f1/f4 系列的 HAL 库，删除多余库文件
+- 提交 STM32 不同系列的 Library 库时，请参考 f1/f4 系列的 HAL 库，删除多余库文件
 - 提交前要对 BSP 进行编译测试，确保在不同编译器下编译正常
-- 提交前要对 BSP 进行功能测试，确保 BSP 的在提交前符合工程配置章节中的要求
+- 提交前要对 BSP 进行功能测试，确保 BSP 的在提交前符合工程配置章节中的要求