1# Infineon-PSOC6 系列 BSP 制作教程
2
3为了让广大开发者更好、更方便地使用 BSP 进行开发，RT-Thread 开发团队为 Infineon-PSOC6 系列推出了 BSP 框架。
4
5BSP 文件夹中不会包含固件库、外设驱动等可以被多个 BSP 引用的代码文件。而是将这些通用的文件统一存放在 Library 文件夹中，通过在特定 BSP 中引用这些文件的方式，来包含 BSP 中所需的库文件或者驱动文件。这种方式不仅大大提高了代码复用率，降低了 BSP 的维护成本，而且可以更方便地给开发者提供更丰富的驱动文件，让开发者可以更容易地找到自己需要的资源。
6
7## 1.BSP 框架介绍
8
9![](./figures/frame.png)
10
11每一个 PSOC6 系列的 BSP 由三部分组成，分别是通用库、BSP 模板和特定开发板 BSP，下面的表格以 PSOC62 系列 BSP 为例介绍这三个部分：
12
13| 项目                    | 文件夹                              | 说明                                                         |
14| ----------------------- | ----------------------------------- | :----------------------------------------------------------- |
15| 通用库                  | Infineon/libraries                  | 用于存放 HAL 库以及基于 HAL 库的多系列通用外设驱动文件       |
16| PSOC6 系列 BSP 工程模板 | Infineon/libraries/templates/PSOC6X | PSOC6 系列 BSP 模板，可以通过修改该模板制作更多 PSOC6 系列 BSP |
17| 特定开发板 BSP          | Infineon/psoc6-cy8ckit-062S2-43012  | 在 BSP 模板的基础上修改而成                                  |
18
19## 2. 知识准备
20
21制作一个 BSP 的过程就是构建一个新系统的过程，因此想要制作出好用的 BSP，要对 RT-Thread 系统的构建过程有一定了解，需要的知识准备如下所示：
22
23- 掌握  PSOC6 系列 BSP 的使用方法
24
25  了解 BSP 的使用方法，可以阅读 [BSP 说明文档](../psoc6-cy8ckit-062S2-43012/README.md) 中使用教程表格内的文档。了解外设驱动的添加方法可以参考《外设驱动添加指南》。
26
27- 了解 Scons 工程构建方法
28
29  RT-Thread 使用 Scons 作为系统的构建工具，因此了解 Scons 的常用命令对制作新 BSP 是基本要求。
30
31- 了解设备驱动框架
32
33  在 RT-Thread 系统中，应用程序通过设备驱动框架来操作硬件，因此了解设备驱动框架，对添加 BSP 驱动是很重要的。
34
35- 了解 Kconfig 语法
36
37  RT-Thread 系统通过 menuconfig 的方式进行配置，而 menuconfig 中的选项是由 Kconfig 文件决定的，因此想要对 RT-Thread 系统进行配置，需要对 kconfig 语法有一定了解。
38
39## 3. BSP 制作方法
40
41本节以制作 `psoc6-cy8ckit-062S2-43012` 开发板的 BSP 为例，讲解如何为一个新的开发板添加 BSP。
42
43BSP 的制作过程分为如下四个步骤：
44
451. 复制通用模板
462. 修改芯片基本配置文件
473. 修改 BSP 中的 Kconfig 文件
484. 修改构建工程相关文件
495. 重新生成工程
50
51在接下来的章节中将会详细介绍这四个步骤，帮助开发者快速创建所需要的 BSP。
52
53### 3.1 复制通用模板
54
55制作新 BSP 的第一步是复制一份同系列的 BSP 模板作为基础，通过对 BSP 模板的修改来获得新 BSP。目前提供的 BSP 模板系列如下表所示：
56
57| 工程模板                   | 说明                 |
58| -------------------------- | -------------------- |
59| libraries/templates/PSOC62 | PSOC62 系列 BSP 模板 |
60
61本次示例所用的 PSOC62 系列 BSP 模板文件夹结构如下所示：
62
63![](./figures/bsp_template_dir.png)
64
65在接下来的 BSP 的制作过程中，将会修改 board 文件夹内的配置文件，将 PSOC62 系列的 BSP 模板变成一个适用于 `psoc6-cy8ckit-062S2-43012` 开发板的 BSP ，下表总结了 board 文件夹中需要修改的内容：
66
67| 项目                      | 需要修改的内容说明                        |
68| ------------------------- | ----------------------------------------- |
69| linker_scripts （文件夹） | BSP 特定的链接脚本                        |
70| board.c/h                 | 系统时钟、GPIO 初始化函数、芯片存储器大小 |
71| Kconfig                   | 芯片型号、系列、外设资源                  |
72| SConscript                | 芯片启动文件、目标芯片型号                |
73
74### 3.2 修改芯片基本配置
75
76在 **board.h** 文件中配置了 FLASH 和 RAM 的相关参数，`IFX_SRAM_SIZE` 这个宏控制的参数。本次制作的 BSP 所用的 CY8CKIT-062S2-43012 芯片 RAM 的大小为 1M，因此对该文件作出如下的修改：
77
78![](./figures/board_h.png)
79
80#### 3.2.1 堆内存配置讲解
81
82通常情况下，系统 RAM 中的一部分内存空间会被用作堆内存。下面代码的作用是，在不同编译器下规定堆内存的起始地址 **HEAP_BEGIN** 和结束地址 **HEAP_END**。这里 **HEAP_BEGIN** 和 **HEAP_END** 的值需要和后面  [3.5.1 修改链接脚本](# 3.5.1 修改链接脚本) 章节所修改的配置相一致。
83
84在某些系列的芯片中，芯片 RAM 可能分布在不连续的多块内存区域上。此时堆内存的位置可以和系统内存在同一片连续的内存区域，也可以存放在一片独立的内存区域中。
85
86![](figures/heap_config.png)
87
88### 3.3 修改 Kconfig 选项
89
90在本小节中修改 `board/Kconfig` 文件的内容有如下两点：
91
92- 芯片型号和系列
93- BSP 上的外设支持选项
94
95芯片型号和系列的修改如下表所示：
96
97| 宏定义               | 意义     | 格式                   |
98| -------------------- | -------- | ---------------------- |
99| SOC_CY8C624ABZI_S2D44 | 芯片型号 | SOC_CY8C6xxx_xxxx  |
100| SOC_SERIES_IFX_PSOC62 | 芯片系列 | SOC_SERIES_IFX_PSOC6x |
101
102关于 BSP 上的外设支持选项，一个初次提交的 BSP 仅仅需要支持串口驱动即可，因此在配置选项中只需保留这两个驱动配置项，如下图所示：
103
104![](./figures/Kconfig.png)
105
106### 3.4 添加外设相关文件
107
108#### 3.4.1 添加底层外设库
109
110接下来为 BSP 添加底层外设库文件，下图的文件是从 Modus 生成的文件夹中拷贝而来。**（只有移植新的系列才需要做此步骤，同 PSOC6 系列无需此步骤）**
111
112![](./figures/hal_config2.png)
113
114Modus 生成的源库文件路径如下图，在 Modus 工作空间下的 `mtb_shared` 文件夹下：**（只有移植新的系列才需要做此步骤，同 PSOC6 系列无需此步骤）**
115
116![](./figures/hal_config3.png)
117
118将以上文件拷贝至 BSP 的 `libraries/IFX_PSOC6_HAL` 文件夹下。**（只有移植新的系列才需要做此步骤，同 PSOC6 系列无需此步骤）**
119
120![](./figures/hal_config1.png)
121
122接下来需要添加板级配置文件，接下来介绍使用英飞凌官方以及非官方开发板的添加步骤：
123
1241、**英飞凌官方开发板步骤**
125
126打开 `ModusToolbox` 软件(版本需 >=V3.0.0)，点击新建项目：
127
128![](./figures/ModusToolbox.png)
129
130输入开发板型号信息，然后选择下一步：
131
132![](./figures/ModusToolbox1.png)
133
134选择 `Hello World` 模板工程，接下来点击创建该工程：
135
136![](./figures/ModusToolbox2.png)
137
138值得注意的是，`APP_CY8CKIT-062S2-43012` 这个 bsp 需要为 4.1.0 版本：
139
140![](./figures/ModusToolbox2.2.png)
141
142等待下载完成后，打开对应的 BSP 文件夹，找到 bsps 下生成的文件：
143
144![](./figures/ModusToolbox3.png)
145
146拷贝其中的内容到 RT-Thread 具体 BSP 的 libs文件夹下，例如下图：
147
148![](./figures/hal_config4-1.png)
149
150同时按照具体路径配置 `SConscript` 脚本文件。
151
1522、**非英飞凌官方开发板步骤**
153
154首先找到 ModusToolbox 安装路径下 `BSP Assistant` 这个软件：
155
156![](./figures/ModusToolbox4.png)
157
158点击 File->New 进行新建项目，按照下图选择目标芯片等：
159
160![](./figures/ModusToolbox5.png)
161
162点击 `Device Configurator 4.0` 后进入图形化配置界面进行外设配置：
163
164![](./figures/ModusToolbox6.png)
165
166引脚部分，swd 的引脚配置是必须的，保持默认即可
167
168![](./figures/ModusToolbox7.png)
169
170时钟相关配置，最初保持默认即可：
171
172![](./figures/ModusToolbox8.png)
173
174全部都配置好后，在界面中按 `ctrl+s ` 即可自动生成配置文件，然后拷贝其中的内容到 RT-Thread 具体 BSP 的 libs文件夹下，例如下图：
175
176![](./figures/hal_config4-1.png)
177
178同时按照具体路径配置 `SConscript` 脚本文件。
179
180### 3.5 修改工程构建相关文件
181
182接下来需要修改用于构建工程相关的文件。
183
184#### 3.5.1 修改链接脚本
185
186**linker_scripts** 链接文件如下图所示：
187
188![](./figures/linker_scripts.png)
189
190以 **GCC** 工具链使用的链接脚本 link.ld 为例，演示如何修改链接脚本：
191
192![](./figures/link_lds.png)
193
194**方式一（推荐）：**
195
196**FLASH** 和 **RAM** 大小信息可以参考上述拷贝的 **TARGET_CY8CKIT-062S2-43012** 文件夹下的链接脚本，进行修改，其路径在 TARGET_CY8CKIT-062S2-43012/COMPONENT_CM4/TOOLCHAIN_ARM（TOOLCHAIN_GCC_ARM）/cy8c6xxa_cm4_dual.sct（.ld）：
197
198![](./figures/link_ifx1.png)
199
200![](./figures/link_ifx2.png)
201
202**方式二：**
203
204本次制作 BSP 使用的芯片为  `CY8CKIT-062S2-43012` ，FLASH 为 **2M**，因此修改 FLASH_SIZE 的参数为 `0x00020000`。RAM 的大小为 **1M**， 因此修改 RAM_SIZE 的参数为 `0x000FD800`。修改链接脚本时，可以参考 [**3.2.1 堆内存配置讲解**](# 3.2.1 堆内存配置讲解) 章节来确定 BSP 的内存分配。
205
206---
207
208MDK 编译器使用的 link.sct，修改的方式也是类似的，如下图所示：
209
210* link.sct 修改内容
211
212![](./figures/linkscripts_change.png)
213
214####  3.5.2 修改构建脚本
215
216**SConscript** 脚本决定 **MDK/IAR/RT-Thread Studio** 工程的生成以及编译过程中要添加文件。
217
218根据具体的路径添加通用外设配置**（只有移植新的系列才需要做此步骤，同 PSOC6 系列无需此步骤）**
219
220![](./figures/hal_config5.png)
221
222添加专有芯片相关文件，如下图：
223
224![](./figures/hal_config5-1.png)
225
226首次移植，需要使用串口外设**（只有移植新的系列才需要做此步骤，同 PSOC6 系列无需此步骤）**
227
228![](./figures/hal_config6.png)
229
230添加库所使用到的头文件路径，如下图：
231
232![](./figures/hal_config7.png)
233
234在这一步中需要修改芯片型号以及芯片启动文件的地址，修改内容如下图所示：其中 **CPPDEFINES**  的参数要根据芯片底层库中定义的芯片型号去填写。
235
236![](./figures/SConscript2.png)
237
238BSP 下的 lib/SConscript 中需要根据不同编译器选择不同的启动文件。
239
240![](./figures/SConscript1.png)
241
242**注意：**
243
244需要特别注意的是，假如使用的是 GCC 工具链，那么需要对启动文件做如下修改：将原有的 **main** 改成 **entry**
245
246![](./figures/entry.png)
247
248#### 3.5.3 修改编译选项
249
250rtconfig.py 用于选择编译工具链，可以自行在 **CROSS_TOOL** 后面选择修改编译工程所需要的工具链，目前 PSCOC6 支持 GCC 和 ArmClang 两种工具链。
251
252![](./figures/rt_configpy.png)
253
254#### 3.5.4 修改工程模板
255
256MDK 为例：
257
258**template** 文件是生成 MDK/IAR 工程的模板文件，通过修改该文件可以设置工程中使用的芯片型号以及下载方式。MDK4/MDK5/IAR 的工程模板文件，如下图所示：
259
260![](./figures/template_1.png)
261
262下面以 MDK5 模板的修改为例，介绍如何修改模板配置：
263
264![](./figures/template_2.png)
265
266修改程序下载方式：
267
268![](./figures/template_3.png)
269
270---
271
272**RT-Thread Studio** 为例，介绍如何导入，修改模板配置：
273
2741、打开 ENV 工具，在工程目录使用 `scons --dist` 命令将工程打包。（整个过程需要保证没有错误）
275
276![](./figures/dist1.png)
277
278打包完成后，可以在 BSP 目录下看到生成的 `dist` 文件夹：
279
280![](./figures/dist2.png)
281
282使用 dist 后生成的工程就可以直接导入到 RT-Thread Studio 中进行开发了。
283
284![](./figures/dist3.png)
285
286打开 RT-Thread Studio ，在 IDE 的左上角点击 `文件—>导入—>RT-Thread Studio 项目到工作空间中`
287
288![](./figures/studio1.png)
289
290选择 dist 出来工程的路径：
291
292![](./figures/studio2.png)
293
294点击 finsh 即可导入到 Studio 中：
295
296![](./figures/studio2-1.png)
297
298导入成功后，文件资源管理器窗口中会显示如下结构，其中 RT-Thread Settings 为图形化工程配置文件，双击打开即可。
299
300![](./figures/studio3.png)
301
302RT-Thread Settings 中硬件相关配置是在 board/Kconfig 中描述的。移植过程如需添加/修改配置，请修改此文件。
303
304![](./figures/studio4.png)
305
306### 3.6 重新生成工程
307
308* MDK5 ：重新生成工程需要使用 Env 工具。
309
310* RT-Thread Studio：使用 Env 工具/同步 scons 配置至项目
311
312同步 scons 配置至项目：
313
314![](./figures/studio5.png)
315
316#### 3.6.1 重新生成 rtconfig.h 文件
317
318**MDK5：**
319
320在 Env 界面输入命令 menuconfig 对工程进行配置，并生成新的 rtconfig.h 文件。如下图所示：
321
322![](./figures/menuconfig_1.png)
323
324![](./figures/menuconfig_2.png)
325
326---
327
328**RT-Thread Studio：**
329
330使用上述方法/点击同步 scons 配置至项目。
331
332#### 3.6.2 重新生成 MDK 工程
333
334以重新生成 MDK 工程为例，介绍如何重新生成 BSP 工程。
335
336使用 env 工具输入命令 `scons --target=mdk5` 重新生成工程，如下图所示：
337
338![](./figures/menuconfig_3.png)
339
340到这一步为止，新的 BSP 就可以使用了。
341
342接下来我们可以分别使用命令 `scons --target=mdk4` 和 `scons --target=iar`，来更新 MDK4 和 IAR 的工程，使得该 BSP 变成一个完整的，可以提交到 GitHub 的 BSP （MDK4工程的制作为可选）。
343
344---
345
346**RT-Thread Studio：** 使用上述方法/点击同步 scons 配置至项目
347
348感谢每一位贡献代码的开发者，RT-Thread 将与你一同成长。
349
350### 3.7 RT-Thread Studio 下载配置
351
3521、点击 Studio 顶部导航栏中的配置按钮：
353
354![](./figures/studio_cfg1.png)
355
3562、确保可执行文件选择配置如下图：
357
358![](./figures/studio_cfg2.png)
359
3603、Debugger 配置项，需按照不同的芯片选择目标文件，OpenOCD 会根据此文件进行烧录：
361
362![](./figures/studio_cfg3.png)
363
364## 4. 规范
365
366本章节介绍 RT-Thread PSOC6 系列 BSP 制作与提交时应当遵守的规范 。开发人员在 BSP 制作完成后，可以根据本规范提出的检查点对制作的 BSP 进行检查，确保 BSP 在提交前有较高的质量 。
367
368### 4.1 BSP 制作规范
369
370PSOC6 BSP 的制作规范主要分为 3 个方面：工程配置，ENV 配置和 IDE 配置。在已有的 PSOC6 系列 BSP 的模板中，已经根据下列规范对模板进行配置。在制作新 BSP 的过程中，拷贝模板进行修改时，需要注意的是不要修改这些默认的配置。BSP 制作完成后，需要对新制作的 BSP 进行功能测试，功能正常后再进行代码提交。
371
372下面将详细介绍 BSP 的制作规范。
373
374#### 4.1.1 工程配置
375
376- 遵从RT-Thread 编码规范，代码注释风格统一
377- main 函数功能保持一致
378  - 如果有 LED 的话，main 函数里**只放一个**  LED 1HZ 闪烁的程序
379- 在 `rt_hw_board_init` 中需要完成堆的初始化：调用 `rt_system_heap_init`
380- 默认只初始化 GPIO 驱动和 FinSH 对应的串口驱动，不使用 DMA
381- 当使能板载外设驱动时，应做到不需要修改代码就能编译下载使用
382- 提交前应检查 GCC/MDK/IAR 三种编译器直接编译或者重新生成后编译是否成功
383- 使用 `dist` 命令对 BSP 进行发布，检查使用 `dist` 命令生成的工程是否可以正常使用
384
385#### 4.1.2 ENV 配置
386
387- 系统心跳统一设置为 1000（宏：RT_TICK_PER_SECOND）
388- BSP 中需要打开调试选项中的断言（宏：RT_USING_DEBUG）
389- 系统空闲线程栈大小统一设置为 256（宏：IDLE_THREAD_STACK_SIZE）
390- 开启组件自动初始化（宏：RT_USING_COMPONENTS_INIT）
391- 需要开启 user main 选项（宏：RT_USING_USER_MAIN）
392- FinSH 默认只使用 MSH 模式（宏：FINSH_USING_MSH_ONLY）
393
394### 4.2 BSP 提交规范
395
396- 提交前请认真修改 BSP 的 README.md 文件，README.md 文件的外设支持表单只填写 BSP 支持的外设，可参考其他 BSP 填写。
397- 提交 BSP 分为 2 个阶段提交：
398  - 第一阶段：基础 BSP 包括串口驱动和 GPIO 驱动，能运行 FinSH 控制台。完成 MDK5 、IAR 和 GCC 编译器支持，如果芯片不支持某款编译器（比如MDK4）可以不用做。 BSP 的 README.md 文件需要填写第二阶段要完成的驱动。
399  - 第二阶段：完成板载外设驱动支持，所有板载外设使用 menuconfig 配置后就能直接使用。若开发板没有板载外设，则此阶段可以不用完成。不同的驱动要分开提交，方便 review 和合并。
400- 只提交 BSP 必要的文件，删除无关的中间文件，能够提交的文件请对照其他 BSP。
401- 提交 PSOC6 不同系列的 Library 库时，请参考 PSOC62 系列的 HAL 库，删除多余库文件
402- 提交前要对 BSP 进行编译测试，确保在不同编译器下编译正常
403- 提交前要对 BSP 进行功能测试，确保 BSP 的在提交前符合工程配置章节中的要求
404