第 1 章 · 原书 18–21 页关于本手册
1.1范围
本手册是 FreeRTOS 内核(primary FreeRTOS API)以及 FreeRTOS 内核配置选项的技术参考。原书假定读者已经熟悉多任务应用程序的编写方法,并且了解实时内核所提供的基本原语(primitive)。
如果你还不熟悉这些基础概念,建议先读同作者的《Mastering the FreeRTOS Real Time Kernel – A Practical Guide》。那本书的写法更偏描述与实操,配有大量循序渐进的例子,可在 http://www.FreeRTOS.org/Documentation 获取。
原书说明了两点取舍,值得先知道:
- 本手册不包含 “alternative” API(另一套旧接口),因为官方已不再推荐使用它。
- 本手册不包含协程(co-routine)API,因为协程只对很小一部分应用有价值。
1.2函数在本手册中的排列顺序
原书把 API 函数分成五个组:任务与调度器相关、队列相关、信号量相关、软件定时器相关、事件组相关。每组各占一章,章内的函数按字母顺序排列。
但要注意:每个 API 函数的名字前面都带有一个或多个前缀字母,用来表示函数的返回类型;章内排序时忽略返回类型前缀。例如创建任务的函数叫 xTaskCreate():“x” 表示它返回一个非标准类型,“Task” 表示它属于任务类函数,因此排在第 2 章;排序时把 “x” 去掉,按 TaskCreate() 参与字母排序。
本中文版沿用这一编排,只做了两处工程上的补充:
- 在五组之外,把原书第 7 章(内核配置)与第 8、9 章(流缓冲区、消息缓冲区)按原书章序保留,成为第 7~9 章。
- 每个函数小节前增加了分类标签与所属头文件,并在全书末尾提供函数速查表,可按函数名或中文关键词检索。
1.3API 使用限制
使用 FreeRTOS API 时必须遵守以下规则,违反其中的任何一条,后果通常不是报错,而是随机死机或难以复现的时序错误。
规则 1:不以 “FromISR” 结尾的 API 函数,不得在中断服务程序(ISR)中使用。
部分 FreeRTOS 移植版本还有更严的限制:即使函数名以 “FromISR” 结尾,也不能用在优先级高于 configMAX_SYSCALL_INTERRUPT_PRIORITY(有些移植版本叫 configMAX_API_CALL_INTERRUPT_PRIORITY,视移植版本而定)的中断服务程序里。这一条限制的目的是保证:优先级高于该配置常量的中断,其时序、确定性与延迟不会受到 FreeRTOS 的影响。该常量在第 7 章(7.1 节)中说明。
规则 2:可能引起上下文切换的 API 函数,不得在调度器被挂起(suspended)期间调用。
规则 3:可能引起上下文切换的 API 函数,不得在临界区(critical section)内调用。
这三条规则的共同根源是:FreeRTOS 的很多 API 会在内部判断“是否需要进行一次任务切换”,如果此时内核状态不允许切换(调度器挂起、处于临界区、或处在不能调用内核的中断优先级上),判断结果与内核的实际状态就会不一致。
1.4函数名的前缀约定
函数名的前缀同时编码了返回类型与归属,读懂前缀就能猜到函数属于哪一章、返回什么。完整的约定见附录 A,这里先给出最常打交道的几种:
| 前缀 | 含义 |
|---|---|
| v | 返回 void |
| x | 返回非标准类型(通常是 BaseType_t,成功返回 pdPASS,失败返回 pdFAIL 或具体错误码) |
| ux | 返回无符号整型(UBaseType_t,通常是计数、长度、优先级) |
| px / pv / pc | 返回指针:px 指向结构体或队列,pv 为 void*,pc 指向常量字符(字符串) |
| ul | 返回无符号长整型(unsigned long) |
| e | 返回枚举类型(如 eTaskState) |
| xTask / xQueue / xSemaphore / xTimer / xEventGroup / xStreamBuffer / xMessageBuffer | 第二段前缀表示所属对象类别,即函数所在的章 |
| …FromISR | 后缀表示该版本可以在中断服务程序中调用,且通常多出一个 pxHigherPriorityTaskWoken 参数 |
例如 xQueueSendFromISR() 可以拆成四段来读:x(返回非标准类型)+ Queue(队列类)+ Send(动作:发送)+ FromISR(可在中断中调用)。
1.5关于本中文版
本中文版以原书章节编号为准重排为网页,章节号、函数名、参数名、常量名一律保留英文原文,只有说明性文字译为中文。这样做的原因是:你在代码里搜的是 xTaskCreate,不是“创建任务”,术语一致才能对照源码与官方文档。
几处排版约定:
- 每个函数小节固定顺序:原型 → 参数(含方向 in / out / in-out)→ 返回值 → 说明 → 注意;原书有示例代码的,示例中的注释保留英文,另加一句中文导语说明这段示例在演示什么。
- 参数方向标注:in 表示调用者传入、函数只读;out 表示函数通过它回传数据给调用者;in-out 表示两者兼有(例如 xTaskCheckForTimeOut() 的 pxTimeOut)。
- 原书的 List of Figures(4 张图)、List of Code Listings(96 段示例)、List of Tables 已内联到各小节,避免来回翻页。
- “任务状态”沿用 FreeRTOS 官方中文资料的习惯译法:Running 运行态、Ready 就绪态、Blocked 阻塞态、Suspended 挂起态。
最后提醒一句:本手册的代码片段来自原书(示例代码的英文注释未改),示例里的钩子函数、写串口、写 trace 之类的辅助函数并不是 FreeRTOS 的 API,只是演示用的占位函数。搬到自己工程里时,这些部分要换成你自己的实现。