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
Define ownership.
Specify exactly who writes, who reads, and whether there can be multiple producers or consumers.
Define full/empty semantics.
Do not leave overwrite/drop/block behavior implicit.
Check capacity math.
Many ring buffers hold N-1 items to distinguish full from empty.
Protect concurrent access.
Use interrupt masking, atomics, mutexes, or single-producer/single-consumer rules as appropriate.
Verify wraparound.
Test writes and reads across the end of the buffer.
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:
- Asks for producer/consumer contexts, baud, buffer size, overflow policy, and critical sections.
- Checks N versus N-1 capacity and ISR/task race.
- Adds overflow counters and tests burst input across wraparound.
1---2name: embedded-buffer-queue-libs3description: Use when integrating, porting, configuring, or debugging embedded ring buffers, circular buffers, FIFO queues, Ring-Buffer, or QueueForMcu libraries4---56# Embedded Buffer Queue Libs78## Overview910Use 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.1112## When To Use1314Use this skill when:1516- The user wants to integrate or debug Ring-Buffer, QueueForMcu, circular buffers, FIFOs, UART RX buffers, log queues, or event queues.17- The issue involves overflow, data loss, race conditions, wraparound, off-by-one capacity, ISR safety, or DMA buffer handoff.1819Do not use this skill for RTOS-native queues unless the issue is about wrapping a custom buffer around them.2021## First Questions2223Ask for:2425- Buffer/queue library and intended data type.26- Producer and consumer contexts: ISR, DMA, task, main loop, shell, or logger.27- Required behavior on full/empty: drop, overwrite oldest, block, error, or backpressure.28- Element size, capacity, maximum burst, and latency budget.29- Whether operations must be lock-free or protected by critical sections.3031## Integration Checklist32331. Define ownership.34 Specify exactly who writes, who reads, and whether there can be multiple producers or consumers.35361. Define full/empty semantics.37 Do not leave overwrite/drop/block behavior implicit.38391. Check capacity math.40 Many ring buffers hold `N-1` items to distinguish full from empty.41421. Protect concurrent access.43 Use interrupt masking, atomics, mutexes, or single-producer/single-consumer rules as appropriate.44451. Verify wraparound.46 Test writes and reads across the end of the buffer.47481. Add telemetry.49 Track high-water mark, overflow count, drop count, or queue full events.5051## Common Failures5253- Race between ISR producer and task consumer.54- Off-by-one capacity causes one byte or one element to disappear.55- DMA writes into a buffer while CPU reads stale cached data.56- Full buffer silently overwrites critical data.57- Queue stores pointers to stack objects that go out of scope.5859## Verification6061Before claiming buffer/queue works:6263- State producer/consumer contexts and protection strategy.64- Confirm full, empty, wraparound, and overflow behavior.65- Confirm maximum burst fits capacity or drops are counted intentionally.66- For DMA/cache systems, state cache maintenance or memory placement.6768## Example6970User:7172```text73UART 中断收数据用 ring buffer，偶尔丢字节。74```7576Agent:77781. Asks for producer/consumer contexts, baud, buffer size, overflow policy, and critical sections.791. Checks N versus N-1 capacity and ISR/task race.801. Adds overflow counters and tests burst input across wraparound.
easyzoom