【产出】 > 用 FreeRTOS 队列在任务之间传递数据:会创建队列、按超时发送和接收、判断返回值,理解"按值拷贝"对变量生命周期的影响,并能写出多个生产者对一个消费者的标准结构,以及大数据块改传指针的写法。
【版本】 > 依据 FreeRTOS 内核官方手册(FreeRTOS Kernel Book)第 5 章 Queue Management 和内核源码
queue.h编写,适用于 FreeRTOS V10 / V11,与具体芯片无关。
一、队列解决什么问题
任务之间要交换数据时,最直接的想法是用全局变量。问题在于:一个任务写到一半被抢占,另一个任务读到的就是半新半旧的数据;而且接收方不知道数据什么时候更新,只能轮询。
队列把这两件事一起解决了:
- 写入和读出由内核保证完整,不会读到写了一半的数据。
- 队列空时,接收任务可以阻塞等待,有数据进来内核自动把它唤醒,等待期间不占 CPU。
- 队列满时,发送任务同样可以阻塞等待空位。
一个队列能存放固定数量(称为"长度")、固定大小的数据项。长度和每项大小都在创建时确定,之后不能改。默认按先进先出(FIFO)使用:从尾部写入,从头部读出。
二、创建队列:xQueueCreate
QueueHandle_t xQueueCreate(UBaseType_t uxQueueLength, /* 最多容纳多少项 */
UBaseType_t uxItemSize); /* 每项多少字节 */
| 参数 / 返回值 | 说明 |
|---|---|
uxQueueLength | 队列同时能存放的最大项数 |
uxItemSize | 每一项的大小,单位是字节,通常写 sizeof(类型) |
返回 NULL | FreeRTOS 堆不够,创建失败 |
返回非 NULL | 队列句柄,后续所有操作都用它 |
一个队列需要两块内存:队列控制结构本身,加上 长度 × 项大小 的存储区。xQueueCreate() 从 FreeRTOS 堆里分配这两块;如果项目不允许动态分配,可以用 xQueueCreateStatic(),它多两个参数,分别传入预先定义好的存储区和控制结构。
#include "FreeRTOS.h"
#include "queue.h"
QueueHandle_t xSensorQueue;
void app_create_queues(void)
{
xSensorQueue = xQueueCreate(8, sizeof(int32_t)); /* 8 个 int32_t */
configASSERT(xSensorQueue != NULL);
}
xQueueReset() 可以把一个已创建的队列恢复成空队列。
三、发送和接收
发送
BaseType_t xQueueSendToBack(QueueHandle_t xQueue,
const void *pvItemToQueue,
TickType_t xTicksToWait);
BaseType_t xQueueSendToFront(QueueHandle_t xQueue,
const void *pvItemToQueue,
TickType_t xTicksToWait);
xQueueSend() 和 xQueueSendToBack() 完全等价,写到队尾。xQueueSendToFront() 写到队头,下一次读出的就是它,适合插队的紧急消息。
接收
BaseType_t xQueueReceive(QueueHandle_t xQueue,
void * const pvBuffer,
TickType_t xTicksToWait);
读出的数据会从队列里删除。pvBuffer 指向的空间必须至少有创建队列时指定的 uxItemSize 字节,否则内核拷贝时会写越界。
只想看一眼、不想取走,用 xQueuePeek(),参数相同。想知道队列里现在有几项,用 uxQueueMessagesWaiting()。
返回值
| 函数 | 成功 | 失败 |
|---|---|---|
| 发送类 | pdPASS | errQUEUE_FULL(数值等于 pdFAIL),在等待时间内一直没有空位 |
xQueueReceive | pdPASS | errQUEUE_EMPTY(数值等于 pdFAIL),在等待时间内一直没有数据 |
【注意】 > 以上函数都不能在中断里调用。中断里要用
xQueueSendToBackFromISR()、xQueueSendToFrontFromISR()、xQueueReceiveFromISR()这些带FromISR后缀的版本,用法见本专区"中断与任务通知"一篇。
四、阻塞超时 xTicksToWait 怎么填
xTicksToWait 是任务在阻塞态里最多等多久,单位是系统节拍(tick),不是毫秒。
| 写法 | 行为 |
|---|---|
0 | 不等。队列满(发送)或空(接收)时立即返回失败 |
pdMS_TO_TICKS(100) | 最多等 100 ms,期间条件满足就提前返回 |
portMAX_DELAY | 一直等,没有超时。前提是 FreeRTOSConfig.h 里 INCLUDE_vTaskSuspend 为 1 |
几个容易忽略的规则:
- 多个任务同时阻塞在同一个队列上时,数据到来只唤醒一个:优先级最高的那个;优先级相同时,唤醒等待时间最长的那个。发送方等空位也是同样的规则。
- 超时返回失败不一定是故障。接收方用一个"略长于正常数据间隔"的超时,超时就说明上游停了,可以借此做通信丢失检测。
- 用
portMAX_DELAY时,任务没有任何机会发现上游出了问题。关键路径上建议给有限超时并处理失败分支。
五、按值拷贝:发送之后变量就可以改了
FreeRTOS 队列是拷贝数据,而不是记住数据的地址。发送时,内核把 pvItemToQueue 指向的 uxItemSize 个字节逐字节复制进队列存储区;接收时再复制到 pvBuffer。
这带来几个直接的好处:
| 情况 | 按值拷贝下的结果 |
|---|---|
| 发送一个局部变量,函数随后返回 | 没问题,队列里存的是副本 |
| 发送后立即修改同一个变量,准备下一条 | 没问题,已发出的那条不受影响 |
| 谁负责释放数据 | 不用操心,存储区由内核管理 |
| 带 MPU 内存保护的系统 | 数据可以跨保护边界传递,发送方和接收方不需要能访问同一块内存 |
代价是拷贝本身要花时间,队列存储区也要占 长度 × 项大小 的内存。传 4 字节的整数毫无压力;传几百字节的结构体,每次就是几百字节的两次拷贝,队列本身还要按最大长度预留存储区。
六、多个数据来源:在结构体里带上"是谁发的"
一个控制任务常常要同时接收多个来源的数据:串口命令、传感器读数、按键事件。官方手册给出的做法是只用一个队列,让每一项都是一个结构体,里面同时放数据和来源标识。
#include <stdint.h>
#include "FreeRTOS.h"
#include "task.h"
#include "queue.h"
typedef enum {
MSG_SENSOR_TEMP,
MSG_KEY_PRESS,
} MsgId_t;
typedef struct {
MsgId_t eId; /* 数据来源 / 含义 */
int32_t lValue; /* 数据本身 */
} Msg_t;
static QueueHandle_t xCtrlQueue;
/* 生产者 1:周期采集温度 */
static int32_t read_temp_x10(void) { return 253; } /* 示例桩函数,替换为真实采集 */
static void vTempTask(void *pv)
{
(void)pv;
Msg_t xMsg = { .eId = MSG_SENSOR_TEMP };
for (;;) {
xMsg.lValue = read_temp_x10();
if (xQueueSend(xCtrlQueue, &xMsg, pdMS_TO_TICKS(10)) != pdPASS) {
/* 队列满:控制任务处理不过来,这里计数或丢弃 */
}
vTaskDelay(pdMS_TO_TICKS(100));
}
}
/* 生产者 2:按键扫描 */
static int key_scan(void) { return 0; } /* 示例桩函数,返回键值,0 表示无按键 */
static void vKeyTask(void *pv)
{
(void)pv;
Msg_t xMsg = { .eId = MSG_KEY_PRESS };
for (;;) {
int k = key_scan();
if (k != 0) {
xMsg.lValue = k;
xQueueSend(xCtrlQueue, &xMsg, 0); /* 按键丢一次影响不大,不等待 */
}
vTaskDelay(pdMS_TO_TICKS(20));
}
}
/* 消费者:控制任务 */
static void vCtrlTask(void *pv)
{
(void)pv;
Msg_t xMsg;
for (;;) {
if (xQueueReceive(xCtrlQueue, &xMsg, pdMS_TO_TICKS(500)) == pdPASS) {
switch (xMsg.eId) {
case MSG_SENSOR_TEMP: /* 更新温度 */ break;
case MSG_KEY_PRESS: /* 处理按键 */ break;
}
} else {
/* 500 ms 内没有任何消息:温度任务每 100 ms 都应发一次,说明上游异常 */
}
}
}
void app_queue_demo_start(void)
{
xCtrlQueue = xQueueCreate(10, sizeof(Msg_t));
configASSERT(xCtrlQueue != NULL);
xTaskCreate(vTempTask, "temp", 256, NULL, 2, NULL);
xTaskCreate(vKeyTask, "key", 256, NULL, 2, NULL);
xTaskCreate(vCtrlTask, "ctrl", 256, NULL, 3, NULL);
}
优先级怎么安排会影响队列的样子
官方手册用两个对照例子说明了这一点:
| 安排 | 队列里通常有几项 | 特点 |
|---|---|---|
| 消费者优先级高于生产者 | 几乎总是 0 或 1 项 | 数据一进队列,消费者立刻抢占处理,延迟最小 |
| 消费者优先级低于生产者 | 通常是满的 | 消费者每取走一项,生产者马上补满,然后阻塞在"等空位"上 |
多数场合把消费者放在更高优先级,队列长度只需要应付突发。反过来安排时,生产者的发送超时就成了关键参数。
【提示】 > 队列长度没有通用公式。可以在调试阶段周期性打印
uxQueueMessagesWaiting(),或者在发送失败的分支里计数,看实际峰值再定长度。
七、大数据块:队列里只传指针
一帧几百字节的串口数据、一整块 ADC 采样缓冲,如果按值放进队列,拷贝时间和队列内存都不划算。官方的做法是:队列的每一项是一个指针,数据本身放在别处,队列里拷贝的只是 4 字节的地址。
xBufQueue = xQueueCreate(4, sizeof(Frame_t *)); /* 每项是一个指针 */
注意发送和接收时传的是指针变量的地址,即 &pFrame,内核拷贝的是指针的值。
指针方式不再有按值拷贝的保护,必须自己保证两件事:
- 所有权清楚。指针发出去之前只有发送方能碰这块内存,发出去之后只有接收方能碰。发送方发完再改,接收方读到的就是被改过的数据。
- 内存一直有效。绝不能把任务栈上局部数组的地址放进队列,函数返回或栈帧变化后那块内存就不归你了。动态分配或从缓冲池取出的内存,必须明确由哪一个任务负责释放。
下面用"空闲池 + 满队列"两个队列管理固定数量的缓冲区,全程不需要 malloc:
#include <stdint.h>
#include <string.h>
#include "FreeRTOS.h"
#include "task.h"
#include "queue.h"
#define FRAME_MAX 256
#define FRAME_NUM 4
typedef struct {
uint16_t usLen;
uint8_t ucData[FRAME_MAX];
} Frame_t;
static Frame_t xFramePool[FRAME_NUM]; /* 静态分配,不在任何任务栈上 */
static QueueHandle_t xFreeQueue; /* 存放空闲缓冲区的指针 */
static QueueHandle_t xFullQueue; /* 存放已填好数据的缓冲区指针 */
void frame_pool_init(void)
{
xFreeQueue = xQueueCreate(FRAME_NUM, sizeof(Frame_t *));
xFullQueue = xQueueCreate(FRAME_NUM, sizeof(Frame_t *));
configASSERT(xFreeQueue && xFullQueue);
for (int i = 0; i < FRAME_NUM; i++) {
Frame_t *p = &xFramePool[i];
xQueueSend(xFreeQueue, &p, 0); /* 一开始所有缓冲区都空闲 */
}
}
/* 生产者:取空缓冲 -> 填数据 -> 交给消费者 */
static void vProducerTask(void *pv)
{
(void)pv;
Frame_t *pFrame;
uint8_t ucSeq = 0;
for (;;) {
if (xQueueReceive(xFreeQueue, &pFrame, pdMS_TO_TICKS(100)) != pdPASS) {
continue; /* 没有空缓冲,消费者太慢 */
}
memset(pFrame->ucData, ucSeq++, 64);/* 示例:填 64 字节 */
pFrame->usLen = 64;
xQueueSend(xFullQueue, &pFrame, portMAX_DELAY);
/* 从这里开始,生产者不再访问 pFrame */
vTaskDelay(pdMS_TO_TICKS(50));
}
}
/* 消费者:取满缓冲 -> 处理 -> 归还空闲池 */
static void vConsumerTask(void *pv)
{
(void)pv;
Frame_t *pFrame;
for (;;) {
if (xQueueReceive(xFullQueue, &pFrame, portMAX_DELAY) == pdPASS) {
/* 处理 pFrame->ucData[0 .. usLen-1] */
xQueueSend(xFreeQueue, &pFrame, 0); /* 归还,池里一定有空位 */
}
}
}
void app_frame_demo_start(void)
{
frame_pool_init();
xTaskCreate(vProducerTask, "prod", 256, NULL, 2, NULL);
xTaskCreate(vConsumerTask, "cons", 256, NULL, 3, NULL);
}
这个结构里缓冲区总数固定为 4,内存占用在编译时就确定了;生产者拿不到空缓冲时自然被限速,不会无限制地堆积数据。
【注意】 > 中断里接收数据时,不要每收一个字节就往队列里送一次。官方手册明确说,演示工程里串口中断逐字节进队列的写法只是为了演示和给移植层施压,数据速率高时效率很差。生产代码建议用 DMA 收一整帧,再用任务通知唤醒处理任务。
八、只保留最新值:长度为 1 的"邮箱"
有些数据只关心最新值,比如当前设定温度、最新一次的姿态角。官方手册把长度为 1 的队列称为"邮箱":
- 写入用
xQueueOverwrite(xQueue, &value),队列满时直接覆盖旧值,从不阻塞。这个函数只能用于长度为 1 的队列。 - 读取用
xQueuePeek(),读完值仍留在队列里,多个任务都可以读。
static QueueHandle_t xSetpointBox;
void setpoint_init(void)
{
xSetpointBox = xQueueCreate(1, sizeof(float));
configASSERT(xSetpointBox != NULL);
}
void setpoint_write(float f)
{
xQueueOverwrite(xSetpointBox, &f);
}
BaseType_t setpoint_read(float *pf)
{
return xQueuePeek(xSetpointBox, pf, 0);
}
九、常见问题
| 现象 | 原因与处理 |
|---|---|
xQueueCreate 返回 NULL | FreeRTOS 堆不够;检查 configTOTAL_HEAP_SIZE,或者项大小算错了(比如把整个大结构体按值入队) |
| 收到的数据乱七八糟 | 接收缓冲比 uxItemSize 小导致越界;或者传指针时发送方发完又改了数据 |
| 收到的指针指向的内容随机变化 | 放进队列的是任务栈上局部数组的地址 |
发送总是返回 errQUEUE_FULL | 消费者优先级太低或阻塞在别处;加长队列只能延缓,要先查消费者 |
在中断里调用 xQueueSend 后系统异常 | 中断里必须用 FromISR 版本 |
portMAX_DELAY 不生效,等一会儿就返回 | INCLUDE_vTaskSuspend 没有设为 1 |
参考资料
- FreeRTOS 内核官方手册 第 5 章 Queue Management:https://github.com/FreeRTOS/FreeRTOS-Kernel-Book/blob/main/ch05.md
- FreeRTOS 内核源码 queue.h:https://github.com/FreeRTOS/FreeRTOS-Kernel/blob/main/include/queue.h
评价 (0)