1 · 原书 35–50 页FreeRTOS 发布包
1.1本章引言与范围
FreeRTOS 以单个 zip 压缩包的形式发布,其中包含全部官方 FreeRTOS 移植层,以及大量预配置的演示应用。
1.1.1范围
本章旨在帮助读者熟悉 FreeRTOS 的文件与目录,具体包括:
- 给出 FreeRTOS 目录结构的顶层视图;
- 说明某个具体的 FreeRTOS 工程实际需要哪些文件;
- 介绍演示应用;
- 提供如何创建新工程的相关信息。
这里的描述只针对官方 FreeRTOS 发布包。本书配套示例采用的组织方式略有不同。
1.2理解 FreeRTOS 发布包
1.2.1定义:FreeRTOS 移植层(Port)
FreeRTOS 可用约二十种不同的编译器构建,可运行在三十多种不同的处理器架构上。每一种受支持的“编译器 + 处理器”组合,都被视为一个独立的 FreeRTOS 移植层(port)。
1.2.2构建 FreeRTOS
可以把 FreeRTOS 看作一个库:它为原本的裸机应用提供多任务能力。
FreeRTOS 以一组 C 源文件的形式提供。其中一部分源文件对所有移植层通用,另一部分则是某个移植层专用的。把这些源文件作为工程的一部分参与构建,应用即可使用 FreeRTOS API。为方便使用,每个官方移植层都附带一个演示应用;该演示应用已预配置为构建正确的源文件、包含正确的头文件。
演示应用应当能够“开箱即用”地构建成功;不过有些演示较旧,且演示发布之后构建工具发生的变化,有时也会引发问题。演示应用在 1.3 节介绍。
1.2.3FreeRTOSConfig.h
FreeRTOS 通过一个名为 FreeRTOSConfig.h 的头文件进行配置。
该头文件用于把 FreeRTOS 裁剪适配到具体应用。例如,其中包含 configUSE_PREEMPTION 这样的常量,其取值决定内核使用协作式还是抢占式调度算法①。由于 FreeRTOSConfig.h 包含应用相关的定义,它应位于被构建应用所属的目录中,而不是存放 FreeRTOS 源码的目录中。
每个 FreeRTOS 移植层都提供了一个演示应用,而每个演示应用都包含一个 FreeRTOSConfig.h 文件。因此你永远不需要从零编写该文件;推荐的做法是:先以所用移植层配套演示应用中的 FreeRTOSConfig.h 为基础,再加以改造。
1.2.4官方 FreeRTOS 发布包
FreeRTOS 打包在单个 zip 文件中,包含所有移植层的源码,以及所有演示应用的工程文件;还包含一部分 FreeRTOS+ 生态组件及其演示工程。
不要被发布包中的文件数量吓退:任何一个应用实际只需要其中极少一部分文件。
1.2.5发布包中的顶层目录
FreeRTOS 发布包的一、二级目录如图 1 所示。
FreeRTOS
│
├─Source 存放 FreeRTOS 源文件的目录
│
└─Demo 存放预配置、与移植层相关的 FreeRTOS 演示工程的目录
FreeRTOS-Plus
│
├─Source 存放部分 FreeRTOS+ 生态组件源码的目录
│
└─Demo 存放 FreeRTOS+ 生态组件演示工程的目录zip 包中只包含一份 FreeRTOS 源文件;所有 FreeRTOS 演示工程与 FreeRTOS+ 演示工程都默认在 FreeRTOS/Source 目录下查找源码,目录结构一旦改动,可能无法构建。
1.2.6所有移植层通用的 FreeRTOS 源文件
FreeRTOS 核心源码只包含两个对所有移植层通用的 C 文件:tasks.c 与 list.c,它们直接位于 FreeRTOS/Source 目录下(见图 2)。同一目录下还包含以下源文件:
queue.c:同时提供队列与信号量服务(本书后文介绍),几乎总是需要。timers.c:提供软件定时器功能(本书后文介绍),只有实际使用软件定时器时才需纳入构建。event_groups.c:提供事件组功能(本书后文介绍),只有实际使用事件组时才需纳入构建。croutine.c:实现 FreeRTOS 协程功能,只有实际使用协程时才需纳入构建。协程面向极小的微控制器,如今已很少使用,维护级别也低于其他特性;本书不介绍协程。
FreeRTOS
│
└─Source
│
├─tasks.c FreeRTOS 源文件 —— 始终需要
├─list.c FreeRTOS 源文件 —— 始终需要
├─queue.c FreeRTOS 源文件 —— 几乎总是需要
├─timers.c FreeRTOS 源文件 —— 可选
├─event_groups.c FreeRTOS 源文件 —— 可选
└─croutine.c FreeRTOS 源文件 —— 可选需要承认,这些文件名可能引发命名空间冲突,因为许多工程本来就包含同名文件。但现在再改名会带来问题:那样做会破坏与成千上万个使用 FreeRTOS 的工程、自动化工具及 IDE 插件的兼容性。
1.2.7某个移植层专用的 FreeRTOS 源文件
移植层专用源文件位于 FreeRTOS/Source/portable 目录。该目录按层级组织:先按编译器、再按处理器架构划分,如图 3 所示。
如果你要在架构为 “architecture”、编译器为 “compiler” 的处理器上运行 FreeRTOS,那么除核心源文件外,还必须构建 FreeRTOS/Source/portable/[compiler]/[architecture] 目录下的文件。
如第 2 章(堆内存管理)所述,FreeRTOS 把堆内存分配也视为可移植层的一部分。使用 V9.0.0 之前版本的工程必须包含一个堆内存管理器;从 V9.0.0 起,只有当 FreeRTOSConfig.h 中 configSUPPORT_DYNAMIC_ALLOCATION 设为 1、或该宏未定义时,才需要堆内存管理器。
FreeRTOS 提供五种示例堆分配方案,命名为 heap_1 到 heap_5,分别由 heap_1.c 到 heap_5.c 实现。这些方案位于 FreeRTOS/Source/portable/MemMang 目录。若已配置使用动态内存分配,就需要在工程中构建这五个源文件之一,除非你的应用自己提供了替代实现。
FreeRTOS
│
└─Source
│
└─portable 存放所有移植层专用源文件的目录
│
├─MemMang 存放 5 种可选堆分配源文件的目录
│
├─[compiler 1] 存放编译器 1 专用移植文件的目录
│ │
│ ├─[architecture 1] 编译器 1 / 架构 1 移植的文件
│ ├─[architecture 2] 编译器 1 / 架构 2 移植的文件
│ └─[architecture 3] 编译器 1 / 架构 3 移植的文件
│
└─[compiler 2] 存放编译器 2 专用移植文件的目录
│
├─[architecture 1] 编译器 2 / 架构 1 移植的文件
├─[architecture 2] 编译器 2 / 架构 2 移植的文件
└─[etc.]1.2.8头文件包含路径
FreeRTOS 要求编译器的包含路径中加入三个目录:
- 核心 FreeRTOS 头文件所在路径,固定为
FreeRTOS/Source/include; - 所用移植层专用源文件所在路径,即
FreeRTOS/Source/portable/[compiler]/[architecture]; FreeRTOSConfig.h头文件所在路径。
1.2.9头文件
使用 FreeRTOS API 的源文件必须先包含 FreeRTOS.h,再包含承载所用 API 函数原型的头文件——即 task.h、queue.h、semphr.h、timers.h 或 event_groups.h 之一。
1.3演示应用
每个 FreeRTOS 移植层都至少附带一个演示应用,应当能够无错误、无警告地构建成功;不过有些演示较旧,演示发布之后构建工具的变化有时也会引发问题。
演示应用有以下几方面用途:
- 提供一个可运行、已预配置的工程示例:包含正确的文件、设置正确的编译器选项;
- 以最少的配置和前置知识实现“开箱即用”的实验;
- 演示 FreeRTOS API 的使用方式;
- 作为创建真实应用的基础。
每个演示工程位于 FreeRTOS/Demo 目录下一个独立的子目录中,子目录名即表示该演示所属的移植层。
每个演示应用在 FreeRTOS.org 网站上都有对应网页,其中包含:
- 如何在 FreeRTOS 目录结构中定位演示工程文件;
- 工程配置使用的硬件;
- 如何搭建运行演示的硬件;
- 如何构建演示;
- 演示预期的运行行为。
所有演示工程都会创建一组公共演示任务的子集,这些任务的实现位于 FreeRTOS/Demo/Common/Minimal 目录。公共演示任务纯粹用于演示 FreeRTOS API 的用法,并不实现任何特定的实用功能。较新的演示工程还可以构建一个入门级 “blinky”(闪烁)工程;blinky 工程非常基础,通常只创建两个任务和一个队列。
每个演示工程都包含一个名为 main.c 的文件,其中的 main() 函数是创建所有演示任务的入口。该演示特有的信息见各 main.c 文件内的注释。FreeRTOS/Demo 目录层级如图 4 所示。
FreeRTOS
│
└─Demo 存放所有演示工程的目录
│
├─[Demo x] 构建演示 “x” 的工程文件
│
├─[Demo y] 构建演示 “y” 的工程文件
│
├─[Demo z] 构建演示 “z” 的工程文件
│
└─Common 由所有演示应用共同构建的文件1.4创建 FreeRTOS 工程
1.4.1改造现有演示工程
每个移植层都至少附带一个预配置、可无错误无警告构建的演示应用。推荐通过改造现有工程来创建新工程:这样工程天然包含正确的文件、安装了正确的中断处理函数、设置了正确的编译器选项。
从现有演示工程起步开发新应用的步骤:
- 打开配套演示工程,确认它能按预期构建并运行;
- 删除定义演示任务的源文件;
Demo/Common目录下的任何文件都可以从工程中移除; - 删除
main()内除prvSetupHardware()与vTaskStartScheduler()之外的所有函数调用,如清单 1 所示; - 检查工程仍能构建通过。
完成这些步骤后,得到的工程已包含正确的 FreeRTOS 源文件,但尚未定义任何功能。
int main( void )
{
/* Perform any hardware setup necessary. */
prvSetupHardware();
/* --- APPLICATION TASKS CAN BE CREATED HERE --- */
/* Start the created tasks running. */
vTaskStartScheduler();
/* Execution will only reach here if there was insufficient heap to
start the scheduler. */
for( ;; );
return 0;
}1.4.2从零创建新工程
如前所述,推荐从现有演示工程创建新工程。如果确实不希望如此,可按以下流程创建:
- 使用所选工具链创建一个尚未包含任何 FreeRTOS 源文件的新工程;
- 确保新工程能够构建、下载到目标硬件并运行;
- 只有在确认已有一个可运行工程之后,再把表 1 所列的 FreeRTOS 源文件加入工程;
- 把所用移植层配套演示工程中的
FreeRTOSConfig.h复制到工程目录; - 把以下目录加入工程搜索头文件的路径:
FreeRTOS/Source/include;FreeRTOS/Source/portable/[compiler]/[architecture](其中 [compiler]、[architecture] 对应你所选移植层);以及存放FreeRTOSConfig.h的目录; - 从相关演示工程复制编译器设置;
- 安装可能需要的 FreeRTOS 中断处理函数;以描述所用移植层的网页及配套演示工程为参考。
| 文件 | 位置 |
|---|---|
| tasks.c | FreeRTOS/Source |
| queue.c | FreeRTOS/Source |
| list.c | FreeRTOS/Source |
| timers.c | FreeRTOS/Source |
| event_groups.c | FreeRTOS/Source |
| 所有 C 与汇编文件 | FreeRTOS/Source/portable/[compiler]/[architecture] |
| heap_n.c | FreeRTOS/Source/portable/MemMang,n 取 1、2、3、4 或 5。该文件从 V9.0.0 起变为可选:旧版本工程必须构建其中一个 heap_n.c;V9.0.0 起仅当 configSUPPORT_DYNAMIC_ALLOCATION 设为 1 或未定义时才需要。详见第 2 章。 |
1.5数据类型与编码风格指南
1.5.1数据类型
每个 FreeRTOS 移植层都有一个独立的 portmacro.h 头文件,其中(在其他内容之外)定义了两个移植层专用数据类型:TickType_t 与 BaseType_t,见表 2。
| 宏 / 类型名 | 实际类型与说明 |
|---|---|
| TickType_t | FreeRTOS 配置了一个周期性中断,称为节拍中断(tick interrupt)。自应用启动以来发生的节拍中断次数称为节拍计数(tick count),用作时间度量;两次节拍中断之间的时间称为节拍周期(tick period),时间以节拍周期的倍数表示。TickType_t 就是保存节拍计数值、指定时间长度所用的数据类型。它可以是无符号 16 位或无符号 32 位类型,取决于 FreeRTOSConfig.h 中 configUSE_16_BIT_TICKS 的设置:为 1 时定义为 uint16_t,为 0 时定义为 uint32_t。在 8 位、16 位架构上使用 16 位类型可显著提升效率,但会严重限制可指定的最大阻塞周期;在 32 位架构上没有理由使用 16 位类型。 |
| BaseType_t | 始终定义为该架构上效率最高的数据类型:32 位架构上通常是 32 位类型,16 位架构上是 16 位类型,8 位架构上是 8 位类型。BaseType_t 一般用于取值范围很有限的返回类型,以及 pdTRUE/pdFALSE 这类布尔值。 |
有些编译器把所有未加限定的 char 变量视为无符号,另一些则视为有符号。因此 FreeRTOS 源码中对每一处 char 都显式加上 signed 或 unsigned 限定,除非该 char 用于保存 ASCII 字符,或 char 指针用于指向字符串。源码中从不使用裸 int 类型。
1.5.2变量命名
变量以类型前缀开头:c 表示 char,s 表示 int16_t(short),l 表示 int32_t(long),x 表示 BaseType_t 及其他非标准类型(结构体、任务句柄、队列句柄等)。
若变量是无符号的,再加前缀 u;若是指针,再加前缀 p。例如 uint8_t 类型变量前缀为 uc,char 指针类型变量前缀为 pc。
1.5.3函数命名
函数名同时带有返回类型前缀与定义所在文件的前缀。例如:
vTaskPrioritySet():返回 void,定义于 task.c;xQueueReceive():返回BaseType_t类型变量,定义于 queue.c;pvTimerGetTimerID():返回 void 指针,定义于 timers.c。
文件作用域(私有)函数以 prv 为前缀。
1.5.4排版
一个制表符始终按四个空格设置。
1.5.5宏命名
大多数宏写成大写,并以小写字母前缀表明宏的定义位置。前缀见表 3。
| 前缀 | 宏定义位置 |
|---|---|
| port(如 portMAX_DELAY) | portable.h 或 portmacro.h |
| task(如 taskENTER_CRITICAL()) | task.h |
| pd(如 pdTRUE) | projdefs.h |
| config(如 configUSE_PREEMPTION) | FreeRTOSConfig.h |
| err(如 errQUEUE_FULL) | projdefs.h |
注意:信号量 API 几乎完全以一组宏实现,但遵循的是函数命名约定,而不是宏命名约定。
表 4 所列宏在 FreeRTOS 源码中随处可见。
| 宏 | 取值 |
|---|---|
| pdTRUE | 1 |
| pdFALSE | 0 |
| pdPASS | 1 |
| pdFAIL | 0 |
1.5.6大量强制类型转换的由来
FreeRTOS 源码可用多种不同编译器编译,而这些编译器在“何时、以何种方式产生警告”上各不相同;尤其是不同编译器对类型转换的使用要求也不一样。因此,FreeRTOS 源码中包含的类型转换比通常情况下更多。