21ic电子技术开发论坛 › 单片机与嵌入式系统 › 瑞萨MCU/MPU › 使用瑞萨移植并验证软件算法-24 通用队列管理篇 ...
返回列表 发新帖我要提问

[RA4 & RA6] 使用瑞萨移植并验证软件算法-24 通用队列管理篇

[复制链接]
59|1
暮雨之仁 发表于 2026-9-1 19:20 | 显示全部楼层 |阅读模式
移植, 瑞萨, , , ,
        之前分享的环形缓冲区是面向字节流的通信专用工具，擅长处理串口 / CAN 的连续字节数据。但在多任务通信、事件驱动、指令缓存等场景中，我们往往需要存储结构体、整型、事件包等不同类型的定长数据。今天带来的通用队列管理采用元素级抽象设计，支持任意数据类型的入队出队，纯静态内存预分配，标准先进先出逻辑，一套代码适配所有队列场景。
整体架构        通用队列采用「控制块 + 数据存储区」的分离设计，控制块管理队列状态与指针，数据存储区按字节存储任意类型的元素，通过 memcpy 实现元素的原子读写，保证不同类型数据的一致性。
878626a96b283cb041.png
核心特性
  • ✅ 任意数据类型：支持字节、整型、结构体等任意定长元素，元素大小可配置
  • ✅ 纯静态内存：无需 malloc/free，预分配缓冲区，零内存碎片，适合嵌入式
  • ✅ 完整操作集：入队、出队、判空、判满、获取队列长度、清空队列
  • ✅ 多队列独立：可同时创建多个不同类型、不同深度的队列，互不干扰
  • ✅ 天然线程安全：单生产者 + 单消费者场景无需加锁，中断写 + 主循环读安全
  • ✅ 资源开销极低：单个队列控制块仅 16 字节 RAM，代码体积约 1KB Flash

一、函数封装实现头文件（queue.h）
复制
  1. #ifndef QUEUE_H
    

  2. #define QUEUE_H
    


  3. 

  4. #include <stdint.h>
    

  5. #include <stdbool.h>
    

  6. #include <stddef.h>
    


  7. 

  8. // 队列控制块结构体
    

  9. typedef struct {
    

  10.     uint8_t  *buf;          // 数据存储区首地址
    

  11.     uint16_t elem_size;     // 单个元素大小（字节）
    

  12.     uint16_t max_elem;      // 最大元素数量
    

  13.     uint16_t head;          // 头指针（出队位置）
    

  14.     uint16_t tail;          // 尾指针（入队位置）
    

  15.     uint16_t count;         // 当前元素数量
    

  16. } queue_t;
    


  17. 

  18. /**
    

  19.  * [url=/u/brief]@brief[/url]  初始化队列
    

  20.  * @param  q        队列控制块指针
    

  21.  * @param  buf      预分配的数据存储区地址
    

  22.  * @param  elem_size 单个元素的字节大小
    

  23.  * @param  max_elem 最大可容纳元素数量
    

  24.  * [url=/u/return]@return[/url] true成功，false参数非法
    

  25.  */
    

  26. bool queue_init(queue_t *q, void *buf, uint16_t elem_size, uint16_t max_elem);
    


  27. 

  28. /**
    

  29.  * @brief  元素入队
    

  30.  * @param  q        队列控制块指针
    

  31.  * @param  elem     待入队元素指针
    

  32.  * @return true成功，false队列已满
    

  33.  */
    

  34. bool queue_enqueue(queue_t *q, const void *elem);
    


  35. 

  36. /**
    

  37.  * @brief  元素出队
    

  38.  * @param  q        队列控制块指针
    

  39.  * @param  elem_out 接收出队元素的缓冲区指针
    

  40.  * @return true成功，false队列为空
    

  41.  */
    

  42. bool queue_dequeue(queue_t *q, void *elem_out);
    


  43. 

  44. /**
    

  45.  * @brief  查看队头元素（不取出）
    

  46.  * @param  q        队列控制块指针
    

  47.  * @param  elem_out 接收队头元素的缓冲区指针
    

  48.  * @return true成功，false队列为空
    

  49.  */
    

  50. bool queue_peek(const queue_t *q, void *elem_out);
    


  51. 

  52. /**
    

  53.  * @brief  判断队列是否为空
    

  54.  */
    

  55. bool queue_is_empty(const queue_t *q);
    


  56. 

  57. /**
    

  58.  * @brief  判断队列是否已满
    

  59.  */
    

  60. bool queue_is_full(const queue_t *q);
    


  61. 

  62. /**
    

  63.  * @brief  获取当前队列元素数量
    

  64.  */
    

  65. uint16_t queue_get_count(const queue_t *q);
    


  66. 

  67. /**
    

  68.  * @brief  清空队列
    

  69.  */
    

  70. void queue_clear(queue_t *q);
    


  71. 

  72. #endif
实现文件（queue.c）
复制
  1. #include "queue.h"
    

  2. #include <string.h>
    


  3. 

  4. bool queue_init(queue_t *q, void *buf, uint16_t elem_size, uint16_t max_elem)
    

  5. {
    

  6.     if (q == NULL || buf == NULL || elem_size == 0 || max_elem == 0) {
    

  7.         return false;
    

  8.     }
    


  9. 

  10.     q->buf = (uint8_t *)buf;
    

  11.     q->elem_size = elem_size;
    

  12.     q->max_elem = max_elem;
    

  13.     q->head = 0;
    

  14.     q->tail = 0;
    

  15.     q->count = 0;
    

  16.     return true;
    

  17. }
    


  18. 

  19. bool queue_enqueue(queue_t *q, const void *elem)
    

  20. {
    

  21.     if (q == NULL || elem == NULL) return false;
    

  22.     if (q->count >= q->max_elem) return false; // 队列满
    


  23. 

  24.     // 计算尾指针位置，复制元素
    

  25.     uint8_t *dst = q->buf + q->tail * q->elem_size;
    

  26.     memcpy(dst, elem, q->elem_size);
    


  27. 

  28.     // 尾指针循环前进
    

  29.     q->tail = (q->tail + 1) % q->max_elem;
    

  30.     q->count++;
    

  31.     return true;
    

  32. }
    


  33. 

  34. bool queue_dequeue(queue_t *q, void *elem_out)
    

  35. {
    

  36.     if (q == NULL || elem_out == NULL) return false;
    

  37.     if (q->count == 0) return false; // 队列空
    


  38. 

  39.     // 计算头指针位置，复制元素
    

  40.     const uint8_t *src = q->buf + q->head * q->elem_size;
    

  41.     memcpy(elem_out, src, q->elem_size);
    


  42. 

  43.     // 头指针循环前进
    

  44.     q->head = (q->head + 1) % q->max_elem;
    

  45.     q->count--;
    

  46.     return true;
    

  47. }
    


  48. 

  49. bool queue_peek(const queue_t *q, void *elem_out)
    

  50. {
    

  51.     if (q == NULL || elem_out == NULL) return false;
    

  52.     if (q->count == 0) return false;
    


  53. 

  54.     const uint8_t *src = q->buf + q->head * q->elem_size;
    

  55.     memcpy(elem_out, src, q->elem_size);
    

  56.     return true;
    

  57. }
    


  58. 

  59. bool queue_is_empty(const queue_t *q)
    

  60. {
    

  61.     return (q == NULL) ? true : (q->count == 0);
    

  62. }
    


  63. 

  64. bool queue_is_full(const queue_t *q)
    

  65. {
    

  66.     return (q == NULL) ? true : (q->count >= q->max_elem);
    

  67. }
    


  68. 

  69. uint16_t queue_get_count(const queue_t *q)
    

  70. {
    

  71.     return (q == NULL) ? 0 : q->count;
    

  72. }
    


  73. 

  74. void queue_clear(queue_t *q)
    

  75. {
    

  76.     if (q == NULL) return;
    

  77.     q->head = 0;
    

  78.     q->tail = 0;
    

  79.     q->count = 0;
    

  80. }


二、移植到瑞萨 e²s IDE 的方法
  • 将queue.c和queue.h复制到工程src/utils/目录；
  • 在 e²s 工程上右键 → Add Files，将queue.c加入编译路径；
  • 根据业务需求定义对应类型的存储缓冲区与队列控制块；
  • 在生产者（中断、任务）中调用queue_enqueue放入数据；
  • 在消费者（主循环、任务）中轮询判空，调用queue_dequeue取出数据处理。


三、使用方法
  • 定义存储区与控制块：声明一个对应类型的数组作为数据存储区，同时定义一个queue_t控制块；
复制
  1. // 示例：定义一个最多存8个事件结构体的队列
    

  2. typedef struct {
    

  3. uint8_t event_id;
    

  4. uint16_t param;
    

  5. } event_t;
    


  6. 

  7. event_t event_buf[8]; // 数据存储区
    

  8. queue_t event_queue; // 队列控制块

  • 初始化队列：调用queue_init，传入控制块、存储区地址、单个元素大小、最大元素数；

复制
  1. queue_init(&event_queue, event_buf, sizeof(event_t), 8);
  • 生产者入队：在中断或任务中，构造好元素后调用queue_enqueue入队；
  • 消费者出队：在主循环或任务中，调用queue_dequeue取出元素处理；
  • 状态查询：可随时调用queue_is_empty/queue_get_count判断是否有数据待处理。


四、调用代码与实测验证测试场景设计覆盖数值型队列、结构体队列、边界条件、清空操作四大场景，验证通用性与鲁棒性：
  • 基础数值队列：uint16_t 类型，入队 5 个元素，分批出队
  • 满队列边界：队列深度 4，入队 5 个，验证第 5 个入队失败
  • 结构体队列：自定义事件结构体，验证复杂类型存取正确性
  • 清空与判空：入队后清空，验证状态复位
验证代码（基于瑞萨 RA6M5 + e²s IDE）
复制
  1. #include "hal_data.h"
    

  2. #include "queue.h"
    

  3. #include <stdio.h>
    

  4. #include <string.h>
    


  5. 

  6. void uart_print(const char *str) {
    

  7.     R_SCI_UART_Write(&g_uart0_ctrl, (uint8_t *)str, strlen(str));
    

  8. }
    


  9. 

  10. // 测试用事件结构体
    

  11. typedef struct {
    

  12.     uint8_t  id;
    

  13.     uint16_t data;
    

  14. } test_event_t;
    


  15. 

  16. void queue_test(void)
    

  17. {
    

  18.     char buf[128];
    

  19.     uint16_t val;
    

  20.     test_event_t evt;
    


  21. 

  22.     uart_print("=== 通用队列功能验证 ===\r\n\r\n");
    


  23. 

  24.     // ========== 测试1：基础数值队列 ==========
    

  25.     uart_print("--- 测试1：uint16数值队列 ---\r\n");
    

  26.     uint16_t num_buf[8];
    

  27.     queue_t num_q;
    

  28.     queue_init(&num_q, num_buf, sizeof(uint16_t), 8);
    


  29. 

  30.     // 入队5个元素
    

  31.     for (int i = 1; i <= 5; i++) {
    

  32.         uint16_t x = i * 10;
    

  33.         queue_enqueue(&num_q, &x);
    

  34.     }
    

  35.     snprintf(buf, sizeof(buf), "入队5个，当前队列长度：%d\r\n", queue_get_count(&num_q));
    

  36.     uart_print(buf);
    


  37. 

  38.     // 分2次出队
    

  39.     uart_print("出队元素：");
    

  40.     for (int i = 0; i < 3; i++) {
    

  41.         queue_dequeue(&num_q, &val);
    

  42.         snprintf(buf, sizeof(buf), "%d ", val);
    

  43.         uart_print(buf);
    

  44.     }
    

  45.     snprintf(buf, sizeof(buf), "\r\n剩余队列长度：%d\r\n\r\n", queue_get_count(&num_q));
    

  46.     uart_print(buf);
    


  47. 

  48.     // ========== 测试2：满队列边界 ==========
    

  49.     uart_print("--- 测试2：满队列边界测试（深度4） ---\r\n");
    

  50.     uint16_t small_buf[4];
    

  51.     queue_t small_q;
    

  52.     queue_init(&small_q, small_buf, sizeof(uint16_t), 4);
    


  53. 

  54.     bool ret;
    

  55.     for (int i = 0; i < 5; i++) {
    

  56.         uint16_t x = i;
    

  57.         ret = queue_enqueue(&small_q, &x);
    

  58.         snprintf(buf, sizeof(buf), "入队%d：%s\r\n", i, ret ? "成功" : "失败");
    

  59.         uart_print(buf);
    

  60.     }
    

  61.     uart_print("\r\n");
    


  62. 

  63.     // ========== 测试3：结构体队列 ==========
    

  64.     uart_print("--- 测试3：事件结构体队列 ---\r\n");
    

  65.     test_event_t evt_buf[4];
    

  66.     queue_t evt_q;
    

  67.     queue_init(&evt_q, evt_buf, sizeof(test_event_t), 4);
    


  68. 

  69.     test_event_t e1 = {1, 100};
    

  70.     test_event_t e2 = {2, 200};
    

  71.     test_event_t e3 = {3, 300};
    

  72.     queue_enqueue(&evt_q, &e1);
    

  73.     queue_enqueue(&evt_q, &e2);
    

  74.     queue_enqueue(&evt_q, &e3);
    


  75. 

  76.     uart_print("出队事件：\r\n");
    

  77.     while (!queue_is_empty(&evt_q)) {
    

  78.         queue_dequeue(&evt_q, &evt);
    

  79.         snprintf(buf, sizeof(buf), "  ID:%d  Data:%d\r\n", evt.id, evt.data);
    

  80.         uart_print(buf);
    

  81.     }
    

  82.     uart_print("\r\n");
    


  83. 

  84.     // ========== 测试4：清空与判空 ==========
    

  85.     uart_print("--- 测试4：清空与判空 ---\r\n");
    

  86.     queue_enqueue(&num_q, &val);
    

  87.     snprintf(buf, sizeof(buf), "入队1个后，是否为空：%s\r\n", queue_is_empty(&num_q) ? "是" : "否");
    

  88.     uart_print(buf);
    

  89.     queue_clear(&num_q);
    

  90.     snprintf(buf, sizeof(buf), "清空后，是否为空：%s，长度：%d\r\n", 
    

  91.              queue_is_empty(&num_q) ? "是" : "否", queue_get_count(&num_q));
    

  92.     uart_print(buf);
    

  93. }
    


  94. 

  95. void hal_entry(void) {
    

  96.     R_SCI_UART_Open(&g_uart0_ctrl, &g_uart0_cfg);
    

  97.     queue_test();
    

  98.     while(1);
    

  99. }

五、结果对比
    我们通过串口助手验证数据与其是否相符：
856976a96b48ea2d38.png
六、注意事项
  • 线程安全说明：
    • 单生产者 + 单消费者场景（如中断入队、主循环出队）是天然线程安全的，无需加锁；
    • 多生产者或多消费者场景，需在操作队列前关中断 / 加互斥锁，防止指针错乱。
  • 元素类型约束：
    • 单个队列的元素大小固定，不支持变长元素；如需变长可存储指针 + 长度，或使用环形缓冲区；
    • 元素中若包含指针，入队仅复制指针值，不会复制指针指向的内容，需注意生命周期。
  • 缓冲区对齐：
    • 若元素为 32 位整型、结构体等，建议存储区按 4 字节对齐，避免非对齐访问导致的性能下降或 HardFault。
  • 与环形缓冲区的区别：
    • 通用队列：面向定长元素，适合事件、指令、结构体等结构化数据，使用简单；
    • 环形缓冲区：面向字节流，适合串口 / CAN 等连续数据流，支持批量读写、覆盖模式。
  • 适用场景：
    • 事件驱动架构的事件队列、指令队列；
    • 多任务间的数据传递、消息邮箱；
    • 传感器数据缓存、按键事件缓存等。

回复

收藏 举报

相关帖子
闪烁黎明 发表于 2026-9-2 17:27 | 显示全部楼层
注意检查buf指针是否为空，初始化时确保elem_size和max_elem正确设置，避免溢出。
回复

收藏 举报

返回列表 发新帖
高级模式
B Color Image Link Quote Code Smilies
您需要登录后才可以回帖 登录 | 注册

本版积分规则

暮雨之仁

33

主题

68

帖子

0

粉丝
快速回复 在线客服 返回列表 返回顶部
0