amos 2465ffc7cf Add 4 tasks from batch 28: ESP ringbuf, RT-Thread dataqueue and cond wait, NuttX NSH quoting
Batch 28 commit 3847b17 gave ESP ringbuf reserve/publish (1 of 3 passed)
and RT-Thread dataqueue wrap reset (0 of 3) as HARD, and RT-Thread
condition wait transitions and NuttX NSH quoted script flow (2 of 3) as
MEDIUM. Each task comes from the commit Qwen measured, its digest
matches, and it is still present at the batch branch head.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-05 04:00:02 +08:00

26 lines
2.5 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# 帧描述符队列合同
本工作区使用 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 由软件显式推进,不以墙上时间判断超时。