第 A 章 · 原书 399–401 页数据类型与编码风格
FreeRTOS 的代码风格与数据类型命名并非“个人洁癖”,而是为了让同一份内核源码能在 8/16/32 位、不同编译器、不同 ABI 上都编得过。理解这套约定,看源码和写移植层会顺很多。
A.1数据类型
内核不使用 int、short 这类宽度随平台变化的裸类型,而是统一用 typedef 定义的可移植类型(定义在 portmacro.h 中):
| 类型 | 含义 | 典型宽度 / 用途 |
|---|---|---|
| TickType_t | 节拍计数类型 | 32 位(configUSE_16_BIT_TICKS=0)或 16 位(=1);用于延时、超时、时间戳 |
| BaseType_t | 内核返回/布尔类型 | 架构上最高效的有符号类型(Cortex-M 为 32 位 int);返回值 pdPASS/pdFAIL、pdTRUE/pdFALSE 都用它 |
| UBaseType_t | BaseType_t 的无符号版本 | 用于计数、优先级等非负量 |
| portSTACK_TYPE / StackType_t | 任务栈单元类型 | Cortex-M 为 uint32_t;栈深度以“字数”计,不是字节 |
| portPOINTER_SIZE_TYPE | 指针宽度整数 | 用于需要按指针宽度做运算的场合 |
| StaticTask_t | 任务控制块(静态创建用) | 应用在 *Static 系列 API 中直接提供该结构 |
| StaticQueue_t / StaticSemaphore_t / StaticEventGroup_t / StaticTimer_t / StaticStreamBuffer_t | 各类对象的静态控制块 | 静态创建时由应用提供,避免动态内存 |
| EventBits_t / EventGroupHandle_t | 事件组位值与句柄 | 位宽受 configUSE_16_BIT_TICKS 影响(8 位或 24 位可用) |
| QueueHandle_t / SemaphoreHandle_t / TimerHandle_t / StreamBufferHandle_t / TaskHandle_t | 各类对象句柄 | 本质是指向内部结构的指针,可直接判 NULL |
| pdMS_TO_TICKS( xTimeInMs ) | 毫秒转节拍宏 | 依赖 configTICK_RATE_HZ;用于把人类时间换算成节拍 |
| portMAX_DELAY | 无限等待常量 | 只在 INCLUDE_vTaskSuspend 为 1 时真正“无限” |
两个常见误用:把
StackType_t 的“字”当成“字节”来配栈深(128 字在 32 位平台是 512 字节);以及把 BaseType_t 的返回值与 pdTRUE(值为 1)以外的非零值比较,导致判断失效——规范写法是 if( xResult == pdPASS ) 或 if( xResult != pdFAIL )。A.2变量与函数命名前缀
FreeRTOS 用一套“匈牙利式”前缀表达变量类型与作用域,读源码时可以靠前缀猜类型:
| 前缀 | 含义 | 示例 |
|---|---|---|
| c | char(字符) | cRxChar |
| s | short | sSample |
| l | long | lCounter |
| x | BaseType_t / 无固定宽度的整数(也用于结构体) | xTicksToWait、xTaskHandle |
| u | unsigned(无符号) | uxPriority(u + x) |
| ul | unsigned long | ulCounter |
| p | pointer(指针) | pvBuffer、pxTask |
| pc | pointer to char(字符串/字符指针) | pcTaskName |
| pv | pointer to void(通用指针) | pvParameters |
| pp | pointer to pointer | ppvParameters |
| v | void(函数无返回值或参数为 void) | vTaskDelete |
| e | 枚举类型(enum) | eState、eTaskState |
| prv | private(文件内静态函数) | prvIdleTask |
| ux | unsigned 且基于 UBaseType_t | uxTaskPriorityGet |
| xTask / vTask / pcTask | 作用于“任务”对象的函数/变量 | xTaskCreate |
函数命名格式一般是 返回类型前缀 + 对象名 + 动作,例如 vTaskDelay(void、Task、Delay)、xQueueSend(BaseType_t 返回值、Queue、Send)。同族 API 的变体后缀也有固定含义:
- FromISR:中断安全版本,通常在中断上下文中调用,多一个 pxHigherPriorityTaskWoken 参数。
- Static:静态分配版本,需要应用提供控制块。
- Recursive:递归版本(递归互斥量专用)。
- WithOverwrite / WithoutOverwrite:任务通知写入策略的差异(第 2 章)。
A.3编码风格要点
- 缩进 4 个空格,不使用制表符;大括号采用 K&R 风格(左括号不换行)。
- 宏名全大写并带下划线(如 configUSE_PREEMPTION、INCLUDE_vTaskDelay);函数名使用驼峰 + 前缀。
- 内核函数内部尽量使用
const修饰只读参数,返回值统一 pdPASS/pdFAIL 语义。 - 临界区与中断相关代码集中放在 port.c / portmacro.h,其它文件不直接操作中断寄存器。
- 所有“可能失败”的 API 都返回 BaseType_t(pdPASS/pdFAIL),调用方必须检查返回值——这一点在本文档各章的函数条目中都反复强调。