/embedded-buffer-queue-libs

name: embedded-buffer-queue-libs
description: Use when integrating, porting, configuring, or debugging embedded ring buffers, circular buffers, FIFO queues, Ring-Buffer, or QueueForMcu libraries

Embedded Buffer Queue Libs

Overview

Use this skill for embedded ring buffers and lightweight queues. The core decision is ownership and concurrency: single producer/consumer, ISR-to-task, task-to-task, DMA-to-task, or multi-producer use.

When To Use

Use this skill when:

• The user wants to integrate or debug Ring-Buffer, QueueForMcu, circular buffers, FIFOs, UART RX buffers, log queues, or event queues.
• The issue involves overflow, data loss, race conditions, wraparound, off-by-one capacity, ISR safety, or DMA buffer handoff.

Do not use this skill for RTOS-native queues unless the issue is about wrapping a custom buffer around them.

First Questions

Ask for:

• Buffer/queue library and intended data type.
• Producer and consumer contexts: ISR, DMA, task, main loop, shell, or logger.
• Required behavior on full/empty: drop, overwrite oldest, block, error, or backpressure.
• Element size, capacity, maximum burst, and latency budget.
• Whether operations must be lock-free or protected by critical sections.

Integration Checklist

1. Define ownership. Specify exactly who writes, who reads, and whether there can be multiple producers or consumers.

1. Define full/empty semantics. Do not leave overwrite/drop/block behavior implicit.

1. Check capacity math. Many ring buffers hold `N-1` items to distinguish full from empty.

1. Protect concurrent access. Use interrupt masking, atomics, mutexes, or single-producer/single-consumer rules as appropriate.

1. Verify wraparound. Test writes and reads across the end of the buffer.

1. Add telemetry. Track high-water mark, overflow count, drop count, or queue full events.

Common Failures

• Race between ISR producer and task consumer.
• Off-by-one capacity causes one byte or one element to disappear.
• DMA writes into a buffer while CPU reads stale cached data.
• Full buffer silently overwrites critical data.
• Queue stores pointers to stack objects that go out of scope.

Verification

Before claiming buffer/queue works:

• State producer/consumer contexts and protection strategy.
• Confirm full, empty, wraparound, and overflow behavior.
• Confirm maximum burst fits capacity or drops are counted intentionally.
• For DMA/cache systems, state cache maintenance or memory placement.

Example

User:

UART 中断收数据用 ring buffer，偶尔丢字节。

Agent:

1. Asks for producer/consumer contexts, baud, buffer size, overflow policy, and critical sections. 1. Checks N versus N-1 capacity and ISR/task race. 1. Adds overflow counters and tests burst input across wraparound.