FreeRTOS 学习：（七）FreeRTOS 中相关的 API 函数的命名规则

上一篇	下一篇
port.c 和 heap_4.c

---

FreeRTOS 中相关的 API 函数的命名规则

FreeRTOS 中的 API 函数命名是有规则的，主要体现在函数名的前缀上。这些前缀不仅指明了函数的返回值类型，也暗示了该函数所属的功能模块。比如说：xTaskCreate()、vTaskDelete()、eTaskGetState()、uxTaskPriorityGet() 这些函数。

1）返回值类型前缀（主流的四个）

这是最核心的规则，函数名的 第一个字母（或前几个字母） 明确指出了其返回值的数据类型：

• v: 代表 void。
  • 含义: 该函数不返回任何值。
  • 例子: vTaskDelete() - 删除一个任务，执行后没有返回值。
• x: 代表 signed BaseType_t。
  • 含义: 该函数返回一个布尔值或状态码。在 FreeRTOS 中，BaseType_t 通常被定义为 int 或 long，其值通常为 pdTRUE (非零) 或 pdFALSE (零)，用于表示成功/失败、真/假等。
  • 例子: xTaskCreate() - 创建一个任务，如果创建成功返回 pdPASS，失败则返回错误码。
• e: 代表 enumerated (枚举类型)。
  • 含义: 该函数返回一个枚举值。枚举类型用于定义一组命名的整数常量，使代码更具可读性。
  • 例子: eTaskGetState() - 获取任务的状态，返回值是 eRunning, eReady, eBlocked, eSuspended, eDeleted 等枚举值之一。
• ux: 代表 unsigned BaseType_t。
  • 含义: 该函数返回一个无符号的 BaseType_t 类型的值。ux 中的 u 代表 unsigned，x 代表 BaseType_t。
  • 例子: uxTaskPriorityGet() - 获取任务的优先级，返回一个无符号整数，表示任务的优先级数值。

2）模块/功能前缀

紧跟在返回值类型前缀之后的是描述函数所属功能模块的单词。

• Task: 所有与任务（Task）管理相关的函数都包含 Task 这个词。
  • 例子: xTaskCreate(), vTaskDelete(), eTaskGetState(), uxTaskPriorityGet() 都是任务管理 API。

3）命名模式总结

因此，一个典型的 FreeRTOS API 函数名称可以分解为：

[返回值类型前缀][功能模块][具体操作]

以 xTaskCreate() 为例：

• x -> 返回 BaseType_t (成功/失败)
• Task -> 属于任务管理模块
• Create -> 执行创建操作

4）其他常见前缀

• pv: 代表 pointer to void (void 指针)。
  • 例子: pvPortMalloc() - 动态内存分配，返回分配内存的指针。
• pc: 代表 pointer to char (字符指针)。
  • 例子: pcTaskGetTaskName() - 获取任务名称，返回指向任务名称字符串的指针。
• ul: 代表 unsigned long。
  • 例子: ulTaskGetIdleRunTimeCounter() - 获取空闲任务的运行时间计数器，返回一个 unsigned long 类型的值。

---