Mastering the FreeRTOS Real Time Kernel · 中文版 /1 FreeRTOS 发布包

1 · 原书 35–50 页FreeRTOS 发布包

The FreeRTOS Distribution

1.1本章引言与范围

FreeRTOS 以单个 zip 压缩包的形式发布,其中包含全部官方 FreeRTOS 移植层,以及大量预配置的演示应用。

1.1.1范围

本章旨在帮助读者熟悉 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 为基础,再加以改造。

① 调度算法见 3.12 节。

1.2.4官方 FreeRTOS 发布包

FreeRTOS 打包在单个 zip 文件中,包含所有移植层的源码,以及所有演示应用的工程文件;还包含一部分 FreeRTOS+ 生态组件及其演示工程。

不要被发布包中的文件数量吓退:任何一个应用实际只需要其中极少一部分文件。

1.2.5发布包中的顶层目录

FreeRTOS 发布包的一、二级目录如图 1 所示。

FreeRTOS
  │
  ├─Source   存放 FreeRTOS 源文件的目录
  │
  └─Demo     存放预配置、与移植层相关的 FreeRTOS 演示工程的目录

FreeRTOS-Plus
    │
    ├─Source   存放部分 FreeRTOS+ 生态组件源码的目录
    │
    └─Demo     存放 FreeRTOS+ 生态组件演示工程的目录
图 1 · FreeRTOS 发布包中的顶层目录

zip 包中只包含一份 FreeRTOS 源文件;所有 FreeRTOS 演示工程与 FreeRTOS+ 演示工程都默认在 FreeRTOS/Source 目录下查找源码,目录结构一旦改动,可能无法构建。

1.2.6所有移植层通用的 FreeRTOS 源文件

FreeRTOS 核心源码只包含两个对所有移植层通用的 C 文件:tasks.c 与 list.c,它们直接位于 FreeRTOS/Source 目录下(见图 2)。同一目录下还包含以下源文件:

FreeRTOS
    │
    └─Source
        │
        ├─tasks.c         FreeRTOS 源文件 —— 始终需要
        ├─list.c          FreeRTOS 源文件 —— 始终需要
        ├─queue.c         FreeRTOS 源文件 —— 几乎总是需要
        ├─timers.c        FreeRTOS 源文件 —— 可选
        ├─event_groups.c  FreeRTOS 源文件 —— 可选
        └─croutine.c      FreeRTOS 源文件 —— 可选
图 2 · 目录树中的核心 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.]
图 3 · 目录树中移植层专用的源文件

1.2.8头文件包含路径

FreeRTOS 要求编译器的包含路径中加入三个目录:

1.2.9头文件

使用 FreeRTOS API 的源文件必须先包含 FreeRTOS.h,再包含承载所用 API 函数原型的头文件——即 task.h、queue.h、semphr.h、timers.h 或 event_groups.h 之一。

1.3演示应用

每个 FreeRTOS 移植层都至少附带一个演示应用,应当能够无错误、无警告地构建成功;不过有些演示较旧,演示发布之后构建工具的变化有时也会引发问题。

给 Linux 用户的提示:FreeRTOS 在 Windows 主机上开发与测试,因此偶尔会出现演示工程在 Linux 主机上构建报错的情况。这类构建错误几乎总是与引用文件名时的字母大小写、或文件路径中斜杠方向有关。如发现此类错误,请通过 FreeRTOS 联系表单(http://www.FreeRTOS.org/contact)告知我们。

演示应用有以下几方面用途:

每个演示工程位于 FreeRTOS/Demo 目录下一个独立的子目录中,子目录名即表示该演示所属的移植层。

每个演示应用在 FreeRTOS.org 网站上都有对应网页,其中包含:

所有演示工程都会创建一组公共演示任务的子集,这些任务的实现位于 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     由所有演示应用共同构建的文件
图 4 · 演示目录层级

1.4创建 FreeRTOS 工程

1.4.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 · 新 main() 函数的模板

1.4.2从零创建新工程

如前所述,推荐从现有演示工程创建新工程。如果确实不希望如此,可按以下流程创建:

文件位置
tasks.cFreeRTOS/Source
queue.cFreeRTOS/Source
list.cFreeRTOS/Source
timers.cFreeRTOS/Source
event_groups.cFreeRTOS/Source
所有 C 与汇编文件FreeRTOS/Source/portable/[compiler]/[architecture]
heap_n.cFreeRTOS/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_tFreeRTOS 配置了一个周期性中断,称为节拍中断(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函数命名

函数名同时带有返回类型前缀与定义所在文件的前缀。例如:

文件作用域(私有)函数以 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 源码中随处可见。

宏取值
pdTRUE1
pdFALSE0
pdPASS1
pdFAIL0

1.5.6大量强制类型转换的由来

FreeRTOS 源码可用多种不同编译器编译,而这些编译器在“何时、以何种方式产生警告”上各不相同;尤其是不同编译器对类型转换的使用要求也不一样。因此,FreeRTOS 源码中包含的类型转换比通常情况下更多。