# 帧描述符队列合同 本工作区使用 RT-Thread 的设备驱动数据队列和内核任务 API。下列条款是帧搬运服务在本次修复中依赖的接口合同,整理自队列公开声明和驱动实现。头文件给出参数类型,`include/rtdef.h` 给出错误码常量。 **R01** 服务在任务上下文中使用已初始化的队列,容量为 1 到 1024,低水位在 0 到容量之间,事件回调传入 NULL;同一队列的 API 调用由任务串行执行,不涉及 ISR、SMP 或异步硬件时钟。 **R02** `rt_data_queue_init(queue, capacity, low_watermark, NULL)` 在分配成功时返回 RT_EOK,建立一个空队列;释放后可以再次初始化该队列对象。 **R03** `rt_data_queue_push` 成功返回 RT_EOK,并在队尾保存调用者给出的指针与长度;队列不复制或释放指针指向的数据,调用者在描述符使用期间保持数据有效,长度可以为零。 **R04** `rt_data_queue_pop` 成功返回 RT_EOK,按成功入队的先后顺序取出一个指针与长度,且移除该项;任何有限长度的合法操作序列都保持这一语义。 **R05** 满队列的 push 和空队列的 pop 在 timeout 为零时返回 -RT_ETIMEOUT,不改变队列已有项。 **R06** `rt_data_queue_peak` 在队列非空时返回 RT_EOK 和队首指针、长度,且不移除该项;空队列返回 -RT_EEMPTY。 **R07** `rt_data_queue_reset` 丢弃当前所有队列项,使队列为空并可继续使用;正在该队列上等待的 push 和 pop 任务以 -RT_ERROR 结束本次操作,已经取消的等待不会被旧定时器再次完成。 **R08** 非零 timeout 允许任务等待:空队列的 pop 等待可用项;满队列的 push 等待占用量达到低水位或更低。满足条件后等待操作正常完成;正 timeout 在相应数量的内核 tick 后仍未满足条件时返回 -RT_ETIMEOUT。负 timeout 表示一直等待。 **R09** `rt_data_queue_deinit` 以 -RT_ERROR 结束队列上的等待操作并释放队列存储,返回 RT_EOK;调用者之后只能重新初始化该对象,不能使用已释放队列。 **R10** `rt_data_queue_len(queue)` 返回当前成功入队且尚未取出的项数,包括零和容量值;查询不改变队列项。 调用者为输出参数提供有效地址,不依赖队列结构的字段、索引宽度、宏或内存布局。回调事件的次数与任务之间无关操作的次序不属于本场景交付标准。内核 tick 由软件显式推进,不以墙上时间判断超时。