FreeRTOS 函数参考手册

一、任务管理函数

1. xTaskCreate - 创建任务

功能描述：动态创建一个任务

函数原型：

BaseType_t xTaskCreate(
    TaskFunction_t pxTaskCode,
    const char * const pcName,
    const configSTACK_DEPTH_TYPE usStackDepth,
    void * const pvParameters,
    UBaseType_t uxPriority,
    TaskHandle_t * const pxCreatedTask
)

参数说明：

参数 描述
pxTaskCode 任务函数指针，任务函数原型为void TaskFunction(void *pvParameters)
pcName 任务名称，用于调试，长度不超过configMAX_TASK_NAME_LEN
usStackDepth 任务栈大小，单位为word，如128表示128个word（512字节）
pvParameters 传递给任务函数的参数
uxPriority 任务优先级，范围0~(configMAX_PRIORITIES-1)
pxCreatedTask 用于保存任务句柄的指针，可设为NULL

返回值：

  • pdPASS：创建成功
  • 其他：创建失败（通常因内存不足）

参数取值示例：

TaskHandle_t xTaskHandle;
xTaskCreate(
    vMyTaskFunction,        // 任务函数
    "MyTask",               // 任务名称
    128,                    // 栈大小128 word
    NULL,                   // 无参数
    osPriorityNormal,       // 正常优先级
    &xTaskHandle            // 保存任务句柄
);

2. vTaskDelete - 删除任务

功能描述：删除指定任务

函数原型：

void vTaskDelete(TaskHandle_t xTaskToDelete)

参数说明：

参数 描述
xTaskToDelete 要删除的任务句柄，NULL表示删除自身

返回值：无

参数取值示例：

// 在其他任务中删除指定任务
vTaskDelete(xOtherTaskHandle);

// 在任务自身中删除自己
vTaskDelete(NULL);

3. vTaskDelay - 任务延时

功能描述：使任务进入阻塞状态指定时间

函数原型：

void vTaskDelay(const TickType_t xTicksToDelay)

参数说明：

参数 描述
xTicksToDelay 延时的Tick数，可使用pdMS_TO_TICKS(100)转换为100ms

返回值：无

参数取值示例：

// 延时500ms
vTaskDelay(pdMS_TO_TICKS(500));

// 延时10个Tick
vTaskDelay(10);

4. uxTaskPriorityGet - 获取任务优先级

功能描述：获取指定任务的优先级

函数原型：

UBaseType_t uxTaskPriorityGet(const TaskHandle_t xTask)

参数说明：

参数 描述
xTask 任务句柄，NULL表示获取自身优先级

返回值：任务优先级

参数取值示例：

UBaseType_t priority = uxTaskPriorityGet(xTaskHandle);

二、内存管理函数

1. pvPortMalloc - 分配内存

功能描述：从堆中分配内存

函数原型：

void *pvPortMalloc(size_t xWantedSize)

参数说明：

参数 描述
xWantedSize 要分配的内存大小（字节）

返回值：

  • 非NULL：分配成功，返回内存指针
  • NULL：分配失败

参数取值示例：

uint8_t *buffer = (uint8_t *)pvPortMalloc(100);
if (buffer != NULL) {
    // 使用buffer
}

2. vPortFree - 释放内存

功能描述：释放已分配的内存

函数原型：

void vPortFree(void *pv)

参数说明：

参数 描述
pv 要释放的内存指针，必须是pvPortMalloc返回的指针

返回值：无

参数取值示例：

vPortFree(buffer);

三、队列操作函数

1. xQueueCreate - 创建队列

功能描述：动态创建一个队列

函数原型：

QueueHandle_t xQueueCreate(
    UBaseType_t uxQueueLength,
    UBaseType_t uxItemSize
)

参数说明：

参数 描述
uxQueueLength 队列长度（可存储的项目数）
uxItemSize 每个项目的大小（字节）

返回值：

  • 非NULL：创建成功，返回队列句柄
  • NULL：创建失败

参数取值示例：

QueueHandle_t xQueue = xQueueCreate(10, sizeof(int));

2. xQueueSend - 向队列发送数据（任务版本）

功能描述：向队列尾部发送数据，任务版本

函数原型：

BaseType_t xQueueSend(
    QueueHandle_t xQueue,
    const void *pvItemToQueue,
    TickType_t xTicksToWait
)

参数说明：

参数 描述
xQueue 队列句柄
pvItemToQueue 要发送的数据指针
xTicksToWait 阻塞时间（Tick数），0表示不阻塞，portMAX_DELAY表示一直阻塞

返回值：

  • pdPASS：发送成功
  • errQUEUE_FULL：队列已满，发送失败

参数取值示例：

int data = 42;
xQueueSend(xQueue, &data, portMAX_DELAY);

3. xQueueSendFromISR - 向队列发送数据（ISR版本）

功能描述：向队列尾部发送数据，ISR版本

函数原型：

BaseType_t xQueueSendFromISR(
    QueueHandle_t xQueue,
    const void *pvItemToQueue,
    BaseType_t *pxHigherPriorityTaskWoken
)

参数说明：

参数 描述
xQueue 队列句柄
pvItemToQueue 要发送的数据指针
pxHigherPriorityTaskWoken 用于标记是否需要任务切换，ISR中需传入&xHigherPriorityTaskWoken

返回值：

  • pdPASS：发送成功
  • pdFAIL：发送失败

参数取值示例：

BaseType_t xHigherPriorityTaskWoken = pdFALSE;
int data = 42;
xQueueSendFromISR(xQueue, &data, &xHigherPriorityTaskWoken);
portYIELD_FROM_ISR(xHigherPriorityTaskWoken);

4. xQueueReceive - 从队列接收数据（任务版本）

功能描述：从队列头部接收数据，任务版本

函数原型：

BaseType_t xQueueReceive(
    QueueHandle_t xQueue,
    void *const pvBuffer,
    TickType_t xTicksToWait
)

参数说明：

参数 描述
xQueue 队列句柄
pvBuffer 接收数据的缓冲区指针
xTicksToWait 阻塞时间（Tick数）

返回值：

  • pdPASS：接收成功
  • errQUEUE_EMPTY：队列已空，接收失败

参数取值示例：

int receivedData;
if (xQueueReceive(xQueue, &receivedData, portMAX_DELAY) == pdPASS) {
    // 处理receivedData
}

四、信号量操作函数

1. xSemaphoreCreateBinary - 创建二进制信号量

功能描述：创建一个二进制信号量

函数原型：

SemaphoreHandle_t xSemaphoreCreateBinary(void)

参数说明：无

返回值：

  • 非NULL：创建成功，返回信号量句柄
  • NULL：创建失败

参数取值示例：

SemaphoreHandle_t xBinarySem = xSemaphoreCreateBinary();

2. xSemaphoreGive - 释放信号量（任务版本）

功能描述：释放信号量，任务版本

函数原型：

BaseType_t xSemaphoreGive(SemaphoreHandle_t xSemaphore)

参数说明：

参数 描述
xSemaphore 信号量句柄

返回值：

  • pdTRUE：释放成功
  • pdFALSE：释放失败（二进制信号量已为1时）

参数取值示例：

xSemaphoreGive(xBinarySem);

3. xSemaphoreTake - 获取信号量（任务版本）

功能描述：获取信号量，任务版本

函数原型：

BaseType_t xSemaphoreTake(
    SemaphoreHandle_t xSemaphore,
    TickType_t xTicksToWait
)

参数说明：

参数 描述
xSemaphore 信号量句柄
xTicksToWait 阻塞时间（Tick数）

返回值：

  • pdTRUE：获取成功
  • pdFALSE：获取失败（超时或信号量为0）

参数取值示例：

if (xSemaphoreTake(xBinarySem, portMAX_DELAY) == pdTRUE) {
    // 访问临界资源
    xSemaphoreGive(xBinarySem);
}

五、互斥量操作函数

1. xSemaphoreCreateMutex - 创建互斥量

功能描述：创建一个互斥量

函数原型：

SemaphoreHandle_t xSemaphoreCreateMutex(void)

参数说明：无

返回值：

  • 非NULL：创建成功，返回互斥量句柄
  • NULL：创建失败

参数取值示例：

SemaphoreHandle_t xMutex = xSemaphoreCreateMutex();

2. xSemaphoreGive - 释放互斥量（任务版本）

功能描述：释放互斥量，任务版本

函数原型：

BaseType_t xSemaphoreGive(SemaphoreHandle_t xSemaphore)

参数说明：

参数 描述
xSemaphore 互斥量句柄

返回值：

  • pdTRUE：释放成功
  • pdFALSE：释放失败

参数取值示例：

xSemaphoreGive(xMutex);

3. xSemaphoreTake - 获取互斥量（任务版本）

功能描述：获取互斥量，任务版本

函数原型：

BaseType_t xSemaphoreTake(
    SemaphoreHandle_t xSemaphore,
    TickType_t xTicksToWait
)

参数说明：

参数 描述
xSemaphore 互斥量句柄
xTicksToWait 阻塞时间（Tick数）

返回值：

  • pdTRUE：获取成功
  • pdFALSE：获取失败

参数取值示例：

if (xSemaphoreTake(xMutex, portMAX_DELAY) == pdTRUE) {
    // 访问临界资源
    xSemaphoreGive(xMutex);
}

六、事件组操作函数

1. xEventGroupCreate - 创建事件组

功能描述：创建一个事件组

函数原型：

EventGroupHandle_t xEventGroupCreate(void)

参数说明：无

返回值：

  • 非NULL：创建成功，返回事件组句柄
  • NULL：创建失败

参数取值示例：

EventGroupHandle_t xEventGroup = xEventGroupCreate();

2. xEventGroupSetBits - 设置事件组位（任务版本）

功能描述：设置事件组中的指定位，任务版本

函数原型：

EventBits_t xEventGroupSetBits(
    EventGroupHandle_t xEventGroup,
    const EventBits_t uxBitsToSet
)

参数说明：

参数 描述
xEventGroup 事件组句柄
uxBitsToSet 要设置的位掩码，如`(1 << 0)

返回值：设置前的事件组值

参数取值示例：

xEventGroupSetBits(xEventGroup, (1 << 0));

3. xEventGroupWaitBits - 等待事件组位（任务版本）

功能描述：等待事件组中的指定位，任务版本

函数原型：

EventBits_t xEventGroupWaitBits(
    EventGroupHandle_t xEventGroup,
    const EventBits_t uxBitsToWaitFor,
    const BaseType_t xClearOnExit,
    const BaseType_t xWaitForAllBits,
    TickType_t xTicksToWait
)

参数说明：

参数 描述
xEventGroup 事件组句柄
uxBitsToWaitFor 等待的位掩码
xClearOnExit 是否在返回前清除位：pdTRUE清除，pdFALSE不清除
xWaitForAllBits 等待方式：pdTRUE等待所有位，pdFALSE等待任意位
xTicksToWait 阻塞时间（Tick数）

返回值：满足条件的事件组值

参数取值示例：

EventBits_t events = xEventGroupWaitBits(
    xEventGroup,
    (1 << 0) | (1 << 1),
    pdTRUE,
    pdFALSE,
    portMAX_DELAY
);

七、任务通知函数

1. xTaskNotifyGive - 发送任务通知（递增通知值）

功能描述：向任务发送通知，通知值递增1

函数原型：

BaseType_t xTaskNotifyGive(TaskHandle_t xTaskToNotify)

参数说明：

参数 描述
xTaskToNotify 目标任务句柄

返回值：pdPASS

参数取值示例：

xTaskNotifyGive(xTargetTaskHandle);

2. ulTaskNotifyTake - 获取任务通知（递减通知值）

功能描述：获取任务通知，通知值递减1或清零

函数原型：

uint32_t ulTaskNotifyTake(
    BaseType_t xClearCountOnExit,
    TickType_t xTicksToWait
)

参数说明：

参数 描述
xClearCountOnExit 退出时操作：pdTRUE清零，pdFALSE递减1
xTicksToWait 阻塞时间（Tick数）

返回值：获取的通知值

参数取值示例：

uint32_t notificationValue = ulTaskNotifyTake(pdTRUE, portMAX_DELAY);

八、软件定时器函数

1. xTimerCreate - 创建软件定时器

功能描述：创建一个软件定时器

函数原型：

TimerHandle_t xTimerCreate(
    const char * const pcTimerName,
    const TickType_t xTimerPeriodInTicks,
    const UBaseType_t uxAutoReload,
    void * const pvTimerID,
    TimerCallbackFunction_t pxCallbackFunction
)

参数说明：

参数 描述
pcTimerName 定时器名称
xTimerPeriodInTicks 定时周期（Tick数）
uxAutoReload 是否自动重加载：pdTRUE自动重加载，pdFALSE一次性
pvTimerID 定时器ID，可用于回调函数区分定时器
pxCallbackFunction 定时器回调函数

返回值：

  • 非NULL：创建成功，返回定时器句柄
  • NULL：创建失败

参数取值示例：

TimerHandle_t xTimer = xTimerCreate(
    "MyTimer",
    pdMS_TO_TICKS(1000),  // 1000ms周期
    pdTRUE,               // 自动重加载
    NULL,
    vTimerCallback
);

2. xTimerStart - 启动软件定时器（任务版本）

功能描述：启动软件定时器，任务版本

函数原型：

BaseType_t xTimerStart(
    TimerHandle_t xTimer,
    TickType_t xTicksToWait
)

参数说明：

参数 描述
xTimer 定时器句柄
xTicksToWait 阻塞时间（Tick数）

返回值：

  • pdPASS：启动成功
  • pdFAIL：启动失败

参数取值示例：

xTimerStart(xTimer, portMAX_DELAY);

九、中断相关函数

1. taskENTER_CRITICAL - 进入临界区（屏蔽中断）

功能描述：进入临界区，屏蔽低优先级中断

函数原型：

void taskENTER_CRITICAL(void)

参数说明：无

返回值：无

参数取值示例：

taskENTER_CRITICAL();
// 访问临界资源
taskEXIT_CRITICAL();

2. vTaskSuspendAll - 暂停任务调度

功能描述：暂停任务调度器，禁止任务切换

函数原型：

void vTaskSuspendAll(void)

参数说明：无

返回值：无

参数取值示例：

vTaskSuspendAll();
// 执行不希望被任务切换打断的操作
xTaskResumeAll();

十、调试函数

1. vApplicationMallocFailedHook - 内存分配失败回调

功能描述：内存分配失败时调用的回调函数

函数原型：

void vApplicationMallocFailedHook(void)

参数说明：无

返回值：无

参数取值示例：

void vApplicationMallocFailedHook(void) {
    // 内存分配失败处理，如打印日志、复位系统等
    for(;;); // 卡死等待调试
}

2. vApplicationStackOverflowHook - 栈溢出回调

功能描述：任务栈溢出时调用的回调函数

函数原型：

void vApplicationStackOverflowHook(
    TaskHandle_t xTask,
    char *pcTaskName
)

参数说明：

参数 描述
xTask 栈溢出的任务句柄
pcTaskName 任务名称

返回值：无

参数取值示例：

void vApplicationStackOverflowHook(TaskHandle_t xTask, char *pcTaskName) {
    // 栈溢出处理，如打印任务信息、复位系统等
    for(;;); // 卡死等待调试
}
# c语言
Logo
openvela

openvela 操作系统专为 AIoT 领域量身定制，以轻量化、标准兼容、安全性和高度可扩展性为核心特点。openvela 以其卓越的技术优势，已成为众多物联网设备和 AI 硬件的技术首选，涵盖了智能手表、运动手环、智能音箱、耳机、智能家居设备以及机器人等多个领域。

更多推荐

cover

声音克隆 小米大模型 OmniVoice 完整使用指南｜3 秒克隆人声｜支持 600 多种语言和中文方言详细安装教程

avatar openvela
cover

智能进化觉醒！openvela trunk-5.5 发布：端侧 AI Agent 开源和多方位升级

avatar openvela

小米开源 OmniVoice：3 秒克隆人声、600 种语言、中文吊打 ElevenLabs，免费商用！

ElevenLabs 能做的，OmniVoice 都能做。它免费、开源、支持本地部署，并覆盖 600+ 语言。600+ 语言Apache-2.0中文 WER 0.84%3 秒音频克隆人声。

avatar openvela