# RA 系列 BSP 制作教程

本文主要介绍 RENESAS RA 系列开发板的 BSP 制作教程，此教程能够帮助开发者更加方便快捷的制作新的 RA 系列 BSP，更好的理解 RA 系列 BSP 的框架结构。

在 RA 系列的每个 BSP 目录中包含 RA 模板工程、board、RT-Thread 的工程配置及构建脚本等，而对接到 RT-Thread 系统的通用驱动文件则存放在`renesas\libraries\HAL_Drivers`中。这两个部分共同组成一个完整的 BSP 工程。

在 RA 系列的 BSP 中引入了瑞萨电子的**[灵活配置软件包](https://www2.renesas.cn/jp/zh/software-tool/flexible-software-package-fsp)**（下文简称 FSP）配置工具，为使用 RA 系列 ARM 微控制器的嵌入式系统设计提供简单易用且可扩展的高质量软件。FSP 包括高性能、低内存占用的业界一流的 HAL 驱动程序，具有图形化配置界面和智能代码生成器。

RA 系列 BSP 框架的主要特性如下：

- 使用 FSP 生成的 RA 模板工程，降低新 BSP 的添加难度；
- 通用的驱动文件，开发者可以方便地使用所有驱动；
- 使用 FSP 配置工具对芯片外设进行图形化配置；

## 1. BSP 框架介绍 

BSP 框架结构如下图所示：

![BSP 框架图](./figures/frame.png)

每一个 BSP 主要由两部分组成，分别是通用驱动库、特定开发板 BSP，下面的表格以 ra6m4-cpk 为例介绍这几个部分：

|项目|文件夹|说明|
| - | - | :-- |
| 通用库 | renesas\libraries\HAL_Drivers | 用于存放对接 RT-Thread 驱动框架的通用外设驱动 |
| 特定开发板 BSP | renesas\ra6m4-cpk | CPK-RA6M4 开发板的 BSP 工程 |

## 2. 知识准备

制作一个 BSP 的过程就是构建一个新系统的过程，因此想要制作出好用的 BSP，要对 RT-Thread 系统的构建过程有一定了解，需要的知识准备如下所示：

- 掌握 RA 系列 BSP 的使用方法

  了解 BSP 的使用方法，可以阅读 [BSP 说明文档](../README.md) 中使用教程表格内的文档。了解外设驱动的添加方法可以参考《外设驱动添加指南》。

- 了解 [Scons](https://www.rt-thread.org/document/site/#/development-tools/scons/scons) 工程构建方法

  RT-Thread 使用 Scons 作为系统的构建工具，因此了解 Scons 的常用命令对制作新 BSP 是基本要求。

- 了解[设备驱动框架](https://www.rt-thread.org/document/site/#/rt-thread-version/rt-thread-standard/programming-manual/device/device)

  在 RT-Thread 系统中，应用程序通过设备驱动框架来操作硬件，因此了解设备驱动框架，对添加 BSP 驱动是很重要的。

- 了解 [Kconfig](https://www.rt-thread.org/document/site/#/development-tools/kconfig/kconfig) 语法

  RT-Thread 系统通过 menuconfig 的方式进行配置，而 menuconfig 中的选项是由 Kconfig 文件决定的，因此想要对 RT-Thread 系统进行配置，需要对 kconfig 语法有一定了解。

- 熟悉 [FSP](https://www2.renesas.cn/jp/zh/software-tool/flexible-software-package-fsp) 配置工具的使用

  FSP 提供了图形化配置工具和智能代码生成器，在制作和使用 BSP 的过程中经常会用到 FSP 配置工具。

## 3. BSP 制作方法

本节以制作 CPK-RA6M4 开发板的 BSP 为例，讲解如何为一个新的开发板添加 BSP，最终制作完成的 BSP 将支持 MDK 和 scons 两种方式构建。

BSP 的制作过程分为如下步骤：

1. 创建 BSP 目录
2. 创建 RA 模板工程
3. 配置模板工程
4. 修改 Kconfig 文件
5. 修改工程构建和配置文件
6. 重新生成工程
7. 添加 GCC 格式链接脚本
8. 修改 rtconfig.py 中的编译参数

在接下来的章节中将会详细介绍这些步骤，帮助开发者创建所需要的 BSP。

### 3.1 创建 BSP 目录

- 创建 BSP 目录不需要直接创建空文件夹，只要复制 BSP 模板 `\renesas\libraries\bsp-template` 文件夹到 `\renesas` 目录并将名称修改为待添加的开发板名即可。命令可参考 **CPK-RA6M4** 的 BSP 命名为 **ra6m4-cpk**，因为 ra6m4-cpk 已经存在，所以本教程使用 **ra6m4-test** 作为新创建的 BSP 名称。

![image-20220217155725977](figures/bsp_crate.png) 

![image-20220217160140135](figures/bsp_crate1.png) 

![image-20220217161302858](figures/bsp_crate2.png) 

### 3.2 创建 RA 模板工程

第一步是使用 FSP 来创建一个 RA 模板工程。

- 在 FSP 安装目录下找到 /eclipse/rasc.exe 双击打开，开启后会自动进入创建工程界面。

![fsp_crate](figures/fsp_crate.png) 

![fsp_crate1](figures/fsp_crate1.png) 

![fsp_crate2](figures/fsp_crate2.png) 

![fsp_crate3](figures/fsp_crate3.png) 

![fsp_crate4](figures/fsp_crate4.png) 

![fsp_crate5](figures/fsp_crate5.png) 

![image-20220211182959790](figures/fsp_crate6.png) 

创建完成后会得到一个 RA 模板工程和 BSP 最基本的配置文件和驱动文件，如上图所示。

### 3.3 配置模板工程

RA 模板工程创建完成后，需要做些修改并添加基础外设 GPIO、UART。

- 打开模板工程 `template.uvprojx` 

![image-20220214174740157](figures/template_open.png) 

- 修改 MDK 工程配置
> **Debug 配置：** 先截图记录下修改前的 Debug 页配置，修改 Device 后 Debug 页的部分配置会发生修改，改完 Device 后手动修改到默认配置。

![img](figures/template_config4.png) 

> **Device 配置：**修改 Device 选项，根据开发板使用的具体芯片型号选择 device。

![img](figures/template_config.png) 

> **Output 配置：** 修改 `Name of Exexutable`为 rtthread，勾选 `Create HEX File`，因为最终烧录的是 HEX 文件。

![image-20220218144358105](figures/template_config1.png) 

> **User 配置：**在用到 TrustZone 时，有额外调用的划分 Secure & Non-Secure 用到的一些指令，如果开发时用的都是 Flat mode 的话，这部分可以忽略。如果需要可以添加命令【cmd /c "start "Renesas" /w cmd /c ""$Slauncher\rasc_launcher.bat" "3.5.0" --gensecurebundle --compiler ARMv6 "$Pconfiguration.xml" "$L%L" 2> "%%TEMP%%\rasc_stderr.out"""】

![img](figures/template_config2.png) 

> **C/C++ 配置：**修改编译参数选项关闭部分警告，删除“-Wextra“、”-Wconversion“、”-Wshadow ” 。
>
> 以 ra6m4-cpk 为例修改后为：-Wno-license-management -Wuninitialized -Wall -Wmissing-declarations -Wpointer-arith -Waggregate-return -Wfloat-equal

![img](figures/template_config3.png)  

> **Utilities 配置：**如图勾选`Use External Tool for Flash Programming`。配置完成点击 `OK` 保存配置。

![img](figures/template_config5.png) 

- 从 MDK 打开 FSP

> **如何在 MDK 中打开 FSP：**
>
> 1. 打开 MDK，选择 “Tools -> Customize Tools Menu…”
> 2. 点击 “new” 图标，添加一条自定义命令: RA Smart Configurator
> 3. Command 输入工具的安装路径， 点击“…”找到安装路径下的“rasc.exe”文件并选中 (setup_fsp_xxxxx 安装目录下)
> 4. Initial Folder 输入参数: $P
> 5. Arguments 输入参数: --device $D --compiler ARMv6 configuration.xml
> 6. 点击 OK 保存命令“Tools -> RA smart Configurator”  
  ![img](figures/fsp_config.png) 
> 7. 点击添加的命令打开配置工具：**RA Smart Config**  
  ![img](figures/fsp_config1.png) 

- 添加 UART 端口
> 选择 Stacks 配置页，点击 New Stack 找到 UART。  
  ![image](figures/fsp_uart.png) 
> 确认开发板可用于 msh 的 UART 通道。配置 UART 参数，因为需要适配 RT-Thread 驱动中使用的命名所以需要修改，设置 **name** 、**channel**  、**callback** 为一致的标号。格式：channel = **X**，name = g_uart**X**、callback = user_uart**X**_callback  
  ![image](figures/fsp_uart1.png) 

### 3.4 修改 Kconfig 选项

在本小节中修改 `board/Kconfig` 文件的内容有如下两点：

- 芯片型号和系列
- BSP 上的外设支持选项

芯片系列的定义在`renesas\libraries\Kconfig` 中，修改前先确认是否存在添加的芯片系列定义，如果是一个未添加的系列，需要先添加该芯片系列的定义。芯片型号和系列的命名格式如下表所示。

| 宏定义             | 意义     | 格式               |
| ------------------ | -------- | ------------------ |
| SOC_R7FA6M4AF      | 芯片型号 | SOC_R7FAxxxxx      |
| SOC_SERIES_R7FA6M4 | 芯片系列 | SOC_SERIES_R7FAxxx |

关于 BSP 上的外设支持选项，一个初次提交的 BSP 仅仅需要支持 GPIO 驱动和串口驱动即可，因此在配置选项中只需保留这两个驱动配置项，如下图所示：

![修改 Kconfig](./figures/Kconfig.png) 

### 3.5 修改工程构建和配置文件
接下来需要修改用于构建工程相关的文件。

- 修改启动文件 startup.c

>  源文件路径：**ra6m4-cpk\ra\fsp\src\bsp\cmsis\Device\RENESAS\Source\startup.c**

```c
#ifdef __ARMCC_VERSION
    main();
#elif defined(__GNUC__)
    extern int entry(void);
    entry();
#endif
```

![img](figures/startup_c.png) 

- 修改 SRAM 大小配置

![image-20220303113833249](figures/board_config.png)

- 修改 GPIO 中断配置

根据 BSP 使用芯片支持的 IRQ 中断情况修改配置文件。可以使用 FSP 配置工具对照查看 IO 引脚号对应的 IRQ 通道。

![image-20220217174433724](figures/bsp_gpio.png) 

- 修改初始应用层代码

在 RA 系列的 BSP 中，应用层代码存放在 `src/hal_entry.c` 中。使用 FSP 生成的默认应用代码需要全部替换为如下代码，如果开发板没有板载 LED 可以将 `while(1)` 中的代码删除。

```c
/*
 * Copyright (c) 2006-2021, RT-Thread Development Team
 *
 * SPDX-License-Identifier: Apache-2.0
 *
 * Change Logs:
 * Date           Author        Notes
 * 2021-10-10     Sherman       first version
 */

#include <rtthread.h>
#include "hal_data.h"
#include <rtdevice.h>

#define LED_PIN    BSP_IO_PORT_01_PIN_06 /* Onboard LED pins */

void hal_entry(void)
{
    rt_kprintf("\nHello RT-Thread!\n");

    while (1)
    {
        rt_pin_write(LED_PIN, PIN_HIGH);
        rt_thread_mdelay(500);
        rt_pin_write(LED_PIN, PIN_LOW);
        rt_thread_mdelay(500);
    }
}
```



### 3.6 重新生成工程

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

- 重新生成 rtconfig.h 文件

在 Env 界面输入命令 menuconfig 对工程进行配置，并生成新的 rtconfig.h 文件。如下图所示：

![输入menuconfig进入配置界面](./figures/menuconfig_1.png) 

打开 GPIO 和 console 使用的 UART 端口。

![选择要打开的外设](./figures/menuconfig_2.png) 

修改 console 输出使用的设备名称。

![image-20220303103240414](figures/menuconfig2.png) 

- 生成 MDK 应用工程
下面以重新生成 MDK 工程为例，介绍如何重新生成 BSP 工程。

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

![重新生成 BSP 工程](./figures/menuconfig_3.png) 

重新生成工程成功：

![重新生成 BSP 工程](./figures/menuconfig_4.png) 

到这一步，基于 MDK 开发的 BSP 就可以使用了。如果要使用 GCC 工具链编译还需加入 GCC 格式的链接脚本。 

### 3.7 添加 GCC 格式链接脚本

GCC 格式的链接脚本需要使用到瑞萨的 IDE 工具 e2studio。在 e2studio 中创建新的工程，步骤如下：

![image-20220218114041568](figures/e2studio1.png) 

![image-20220218113955219](figures/e2studio.png) 

![image-20220218114633339](figures/e2studio2.png) 

![image-20220218114839257](figures/e2studio3.png) 

![image-20220218115035562](figures/e2studio4.png) 

![image-20220218115332866](figures/e2studio5.png) 

工程创建完成后，我们需要将工程中的两个 xxx.ld 文件 copy 到 BSP 中的 script 目录下。

![image-20220218115715957](figures/e2studio6.png) 

- 修改链接脚本

> 链接脚本文件路径：**ra6m4-cpk\script\fsp.ld**

![image-20220215182642126](figures/linkscript1.png) 

> 将下面的代码复制到 text 段中，**注意要添加到 text{  } 括号内**

```shell
/* section information for finsh shell */
. = ALIGN(4);
__fsymtab_start = .;
KEEP(*(FSymTab))
__fsymtab_end = .;

. = ALIGN(4);
__vsymtab_start = .;
KEEP(*(VSymTab))
__vsymtab_end = .;

/* section information for initial. */
. = ALIGN(4);
__rt_init_start = .;
KEEP(*(SORT(.rti_fn*)))
__rt_init_end = .;

. = ALIGN(4);
KEEP(*(FalPartTable))
```

> 添加后如下图所示：

![img](figures/linkscript.png) 

### 3.8 修改 rtconfig.py 中的编译参数

![image-20220303165348085](figures/rtconfig_py.png) 

除了上图的内核类型，还有编译参数的配置需要确认。相关配置项说明可查看文档中心对于 scons 工具的介绍。[跳转链接](https://www.rt-thread.org/document/site/#/development-tools/scons/scons?id=编译器选项)



至此，一个基础的支持 GCC 和 MDK 的 BSP 工程就创建完成了，接着就可以使用 MDK 或 scons 验证开发的工程是否可编译、可运行。

感谢每一位贡献代码的开发者，RT-Thread 将与你一同成长。

## 4. 规范

本章节介绍 RT-Thread RA 系列 BSP 制作与提交时应当遵守的规范 。开发人员在 BSP 制作完成后，可以根据本规范提出的检查点对制作的 BSP 进行检查，确保 BSP 在提交前有较高的质量 。

### 4.1 BSP 制作规范

RA 的制作规范主要分为 3 个方面：工程配置，ENV 配置和 IDE 配置。在已有的 RA 系列 BSP 的模板中，已经根据下列规范对模板进行配置。在制作新 BSP 的过程中，拷贝模板进行修改时，需要注意的是不要修改这些默认的配置。BSP 制作完成后，需要对新制作的 BSP 进行功能测试，功能正常后再进行代码提交。

下面将详细介绍 BSP 的制作规范。

#### 4.1.1 工程配置

- 遵从RT-Thread 编码规范，代码注释风格统一
- main 函数功能保持一致
  - 如果有 LED 的话，main 函数里**只放一个**  LED 1HZ 闪烁的程序
- 在 `rt_hw_board_init` 中需要完成堆的初始化：调用 `rt_system_heap_init`
- 默认只初始化 GPIO 驱动和 FinSH 对应的串口驱动，不使用 DMA
- 当使能板载外设驱动时，应做到不需要修改代码就能编译下载使用
- 提交前应检查 GCC、MDK 编译器直接编译或者重新生成后编译是否成功
- 使用 `scons --dist` 命令对 BSP 进行发布，检查使用 `dist` 命令生成的工程是否可以正常使用

#### 4.1.2 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）

#### 4.1.3 IDE 配置

- 使能下载代码后自动运行
- 使能 C99 支持
- 使能 One ELF Section per Function（MDK）
- MDK/IAR 生成的临时文件分别放到build下的 MDK/IAR 文件夹下
- MDK/GCC/IAR 生成 hex 文件名字统一成 rtthread.hex

### 4.2 BSP 提交规范

- 提交前请认真修改 BSP 的 README.md 文件，README.md 文件的外设支持表单只填写 BSP 支持的外设，可参考其他 BSP 填写。查看文档[《RA系列驱动介绍》](./RA系列驱动介绍.md)了解驱动分类。
- 提交 BSP 分为 2 个阶段提交：
  - 第一阶段：基础 BSP 包括串口驱动和 GPIO 驱动，能运行 FinSH 控制台。完成 MDK5 、IAR 和 GCC 编译器支持，如果芯片不支持某款编译器（比如MDK4）可以不用做。 BSP 的 README.md 文件需要填写第二阶段要完成的驱动。
  - 第二阶段：完成板载外设驱动支持，所有板载外设使用 menuconfig 配置后就能直接使用。若开发板没有板载外设，则此阶段可以不用完成。不同的驱动要分开提交，方便 review 和合并。
- 只提交 BSP 必要的文件，删除无关的中间文件，能够提交的文件请对照其他 BSP。
- 提交前要对 BSP 进行编译测试，确保在不同编译器下编译正常
- 提交前要对 BSP 进行功能测试，确保 BSP 的在提交前符合工程配置章节中的要求