FreeRTOS 中文参考手册 /1 关于本手册

第 1 章 · 原书 18–21 页关于本手册

Chapter 1 · About This Manual

1.1范围

本手册是 FreeRTOS 内核(primary FreeRTOS API)以及 FreeRTOS 内核配置选项的技术参考。原书假定读者已经熟悉多任务应用程序的编写方法,并且了解实时内核所提供的基本原语(primitive)。

如果你还不熟悉这些基础概念,建议先读同作者的《Mastering the FreeRTOS Real Time Kernel – A Practical Guide》。那本书的写法更偏描述与实操,配有大量循序渐进的例子,可在 http://www.FreeRTOS.org/Documentation 获取。

本手册只讲“怎么调用、参数是什么、返回值是什么”。任务为什么这样调度、优先级怎么反转、堆有哪几种实现,这些“为什么”的问题在原书的教程书里讲;本手册只在必要处给一两句背景。

原书说明了两点取舍,值得先知道:

1.2函数在本手册中的排列顺序

原书把 API 函数分成五个组:任务与调度器相关、队列相关、信号量相关、软件定时器相关、事件组相关。每组各占一章,章内的函数按字母顺序排列。

但要注意:每个 API 函数的名字前面都带有一个或多个前缀字母,用来表示函数的返回类型;章内排序时忽略返回类型前缀。例如创建任务的函数叫 xTaskCreate():“x” 表示它返回一个非标准类型,“Task” 表示它属于任务类函数,因此排在第 2 章;排序时把 “x” 去掉,按 TaskCreate() 参与字母排序。

本中文版沿用这一编排,只做了两处工程上的补充:

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 会在内部判断“是否需要进行一次任务切换”,如果此时内核状态不允许切换(调度器挂起、处于临界区、或处在不能调用内核的中断优先级上),判断结果与内核的实际状态就会不一致。

经验做法:中断里只调用 *FromISR 结尾的函数,并且用带 pxHigherPriorityTaskWoken 参数的那个版本;临界区里只做纯粹的数据操作,出临界区之后再调用会阻塞或会切换的 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,不是“创建任务”,术语一致才能对照源码与官方文档。

几处排版约定:

最后提醒一句:本手册的代码片段来自原书(示例代码的英文注释未改),示例里的钩子函数、写串口、写 trace 之类的辅助函数并不是 FreeRTOS 的 API,只是演示用的占位函数。搬到自己工程里时,这些部分要换成你自己的实现。