FreeRTOS常用API

FreeRTOS 提供了丰富的 API 函数，覆盖任务管理、队列、信号量、内存管理等多个领域。以下是按照功能分类的 所有核心 API 函数 详细讲解，包含参数意义、功能说明及所需的宏定义：

一、任务管理 API

1. xTaskCreate()

• 功能：创建一个新任务并添加到就绪列表。
• 参数：
  • pxTaskCode：任务函数指针（原型：void vTaskFunction(void *pvParameters)）。
  • pcName：任务名称（用于调试，长度由 configMAX_TASK_NAME_LEN 定义，默认 16）。
  • usStackDepth：任务栈大小（单位为字，如 100 表示 100 个 32 位字）。
  • pvParameters：传递给任务的参数（可通过 pvParameters 在任务内访问）。
  • uxPriority：任务优先级（范围：0 到 configMAX_PRIORITIES - 1）。
  • pxCreatedTask：任务句柄指针（用于后续操作，如 vTaskDelete()）。
• 宏定义：需启用 configSUPPORT_DYNAMIC_ALLOCATION（默认启用）。
• 返回值：pdPASS（成功）或 errCOULD_NOT_ALLOCATE_REQUIRED_MEMORY（失败）。

2. xTaskCreateStatic()

• 功能：使用静态内存创建任务（无需动态分配）。
• 参数：
  • 同 xTaskCreate()，需额外提供：
  • puxStackBuffer：预分配的任务栈数组。
  • pxTaskBuffer：预分配的任务控制块（TCB）内存。
• 宏定义：需启用 configSUPPORT_STATIC_ALLOCATION，并实现 vApplicationGetIdleTaskMemory()。
• 返回值：任务句柄（NULL 表示失败）。

3. vTaskDelete()

• 功能：删除指定任务（释放任务资源）。
• 参数：
  • xTaskToDelete：任务句柄（传入 NULL 表示删除当前任务）。
• 宏定义：无特殊要求。

4. vTaskSuspend() 和 vTaskResume()

• 功能：
  • vTaskSuspend()：挂起任务（暂停调度，保留状态）。
  • vTaskResume()：恢复被挂起的任务。
• 参数：
  • xTaskToSuspendResume：目标任务句柄。
• 宏定义：无特殊要求。

5. vTaskDelay() 和 vTaskDelayUntil()

• 功能：
  • vTaskDelay()：延迟当前任务指定时间（相对延迟）。
  • vTaskDelayUntil()：使任务周期性执行（绝对延迟）。
• 参数：
  • xTicksToDelay：延迟的滴答数（1 tick = 1/configTICK_RATE_HZ 秒）。
  • pxPreviousWakeTime：上次唤醒时间（vTaskDelayUntil() 专用）。
• 宏定义：无特殊要求。

二、队列 API

1. xQueueCreate()

• 功能：创建一个队列。
• 参数：
  • uxQueueLength：队列长度（可存储的最大消息数）。
  • uxItemSize：单个消息的大小（字节）。
• 宏定义：需启用 configSUPPORT_DYNAMIC_ALLOCATION。
• 返回值：队列句柄（NULL 表示失败）。

2. xQueueSend() 和 xQueueSendFromISR()

• 功能：
  • xQueueSend()：向队列发送消息（任务级）。
  • xQueueSendFromISR()：中断中发送消息。
• 参数：
  • xQueue：队列句柄。
  • pvItemToQueue：消息指针。
  • xTicksToWait：等待队列空闲的超时时间（portMAX_DELAY 表示无限等待）。
  • pxHigherPriorityTaskWoken：中断中是否唤醒更高优先级任务（xQueueSendFromISR() 专用）。
• 宏定义：无特殊要求。
• 返回值：pdPASS（成功）或 errQUEUE_FULL（失败）。

3. xQueueReceive() 和 xQueueReceiveFromISR()

• 功能：
  • xQueueReceive()：从队列接收消息（任务级）。
  • xQueueReceiveFromISR()：中断中接收消息。
• 参数：同 xQueueSend()，pvBuffer 为存储消息的缓冲区。
• 返回值：pdPASS（成功）或 errQUEUE_EMPTY（失败）。

三、信号量 API

1. 信号量创建函数

c

xSemaphoreCreateBinary();          // 创建二进制信号量
xSemaphoreCreateCounting();        // 创建计数信号量
xSemaphoreCreateMutex();           // 创建互斥量
xSemaphoreCreateRecursiveMutex();  // 创建递归互斥量

• 参数：
  • uxMaxCount 和 uxInitialCount（xSemaphoreCreateCounting() 专用）。
• 宏定义：需启用 configUSE_MUTEXES（互斥量相关）。
• 返回值：信号量句柄（NULL 表示失败）。

2. 信号量操作函数

c

xSemaphoreTake();           // 获取信号量（任务级）
xSemaphoreTakeFromISR();    // 中断中获取信号量
xSemaphoreGive();           // 释放信号量（任务级）
xSemaphoreGiveFromISR();    // 中断中释放信号量

• 参数：
  • xSemaphore：信号量句柄。
  • xTicksToWait：等待超时时间。
  • pxHigherPriorityTaskWoken（中断版本专用）。
• 返回值：pdPASS（成功）或 pdFAIL（失败）。

四、事件组 API

1. xEventGroupCreate()

• 功能：创建事件组。
• 参数：无。
• 宏定义：需启用 configUSE_EVENT_GROUPS。
• 返回值：事件组句柄（NULL 表示失败）。

2. xEventGroupSetBits() 和 xEventGroupSetBitsFromISR()

• 功能：设置事件组中的位（任务级 / 中断级）。
• 参数：
  • xEventGroup：事件组句柄。
  • uxBitsToSet：要设置的位掩码（如 BIT_0 | BIT_1）。
• 返回值：更新后的事件位值。

3. xEventGroupWaitBits()

• 功能：等待事件组中的位满足条件。
• 参数：
  • xEventGroup：事件组句柄。
  • uxBitsToWaitFor：等待的位掩码。
  • xClearOnExit：是否在退出时清除位（pdTRUE/pdFALSE）。
  • xWaitForAllBits：等待所有位（pdTRUE）或任意位（pdFALSE）。
  • xTicksToWait：超时时间。
• 返回值：满足条件的位掩码。

五、任务通知 API

1. xTaskNotify() 和 xTaskNotifyFromISR()

• 功能：向任务发送通知（替代信号量 / 队列）。
• 参数：
  • xTaskToNotify：目标任务句柄。
  • ulValue：通知值。
  • eAction：通知动作（如 eSetBits, eIncrement 等）。
• 宏定义：需启用 configUSE_TASK_NOTIFICATIONS（默认启用）。
• 返回值：pdTRUE（任务已在等待通知）或 pdFALSE。

2. ulTaskNotifyTake() 和 xTaskNotifyWait()

• 功能：
  • ulTaskNotifyTake()：获取任务通知（用于替代信号量）。
  • xTaskNotifyWait()：等待任务通知（用于替代队列 / 事件组）。
• 参数：
  • ulBitsToClearOnEntry 和 ulBitsToClearOnExit（xTaskNotifyWait() 专用）。
• 返回值：通知值或 pdTRUE（成功）。

六、内存管理 API

1. pvPortMalloc() 和 vPortFree()

• 功能：动态内存分配与释放。
• 参数：
  • xWantedSize：请求的内存大小（字节）。
  • pv：要释放的内存指针。
• 宏定义：需选择堆实现（heap_1.c 至 heap_5.c）。

2. 堆信息查询

c

size_t xPortGetFreeHeapSize();           // 获取当前空闲堆大小
size_t xPortGetMinimumEverFreeHeapSize(); // 获取历史最小空闲堆大小

七、定时器 API

1. xTimerCreate()

• 功能：创建软件定时器。
• 参数：
  • pcTimerName：定时器名称。
  • xTimerPeriodInTicks：定时器周期（滴答数）。
  • uxAutoReload：是否自动重载（pdTRUE 为周期性定时器）。
  • pvTimerID：定时器 ID（用户数据）。
  • pxCallbackFunction：定时器回调函数（原型：void vTimerCallback(TimerHandle_t xTimer)）。
• 宏定义：需启用 configUSE_TIMERS。
• 返回值：定时器句柄（NULL 表示失败）。

2. 定时器控制

c

xTimerStart();         // 启动定时器
xTimerStop();          // 停止定时器
xTimerReset();         // 重置定时器
xTimerChangePeriod();  // 更改定时器周期

• 参数：
  • xTimer：定时器句柄。
  • xTicksToWait：操作超时时间。
• 返回值：pdPASS（成功）或 pdFAIL（失败）。

八、中断管理 API

1. portDISABLE_INTERRUPTS() 和 portENABLE_INTERRUPTS()

• 功能：禁用 / 启用全局中断。
• 参数：无。
• 宏定义：依赖硬件平台（如 Cortex-M 中使用 __asm("CPSID I")）。

2. taskYIELD() 和 taskYIELD_FROM_ISR()

• 功能：触发任务切换（任务级 / 中断级）。
• 参数：无。

九、系统状态查询 API

c

uxTaskGetSystemState();      // 获取系统任务状态
vTaskList();                 // 打印任务列表（需实现 vTaskGetRunTimeStats()）
vTaskGetRunTimeStats();      // 获取任务运行时间统计
uxTaskPriorityGet();         // 获取任务优先级
vTaskPrioritySet();          // 设置任务优先级

• 宏定义：需启用 configGENERATE_RUN_TIME_STATS（运行时间统计）。

十、钩子函数相关

c

vApplicationIdleHook();      // 空闲任务钩子
vApplicationTickHook();      // 滴答中断钩子
vApplicationMallocFailedHook(); // 内存分配失败钩子
vApplicationStackOverflowHook(); // 栈溢出钩子

• 宏定义：需启用对应钩子（如 configUSE_IDLE_HOOK）。

关键宏定义汇总

宏定义	作用
configUSE_PREEMPTION	启用抢占式调度（默认 1）
configTICK_RATE_HZ	系统滴答频率（如 1000 表示 1kHz）
configMAX_PRIORITIES	最大任务优先级数（建议不超过 32）
configMINIMAL_STACK_SIZE	空闲任务栈大小（单位为字）
configTOTAL_HEAP_SIZE	堆大小（字节，如 16384 表示 16KB）
configUSE_MUTEXES	启用互斥量（默认 0，需显式启用）
configUSE_TIMERS	启用软件定时器（默认 0）
configUSE_TASK_NOTIFICATIONS	启用任务通知（默认 1）
configUSE_TRACE_FACILITY	启用追踪功能（用于调试）
configASSERT()	断言函数（需用户实现）