# xiaoxinpro/queueformcu architecture

> Architecture diagram of the GitHub repository xiaoxinpro/queueformcu, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-09-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/xiaoxinpro/queueformcu
- Repository: https://github.com/xiaoxinpro/queueformcu

## Overview

##### Project type and purpose
- This is an embedded-C library (“QueueForMcu”) that implements a generic, fixed-size circular queue (FIFO) for 8/16/32-bit MCUs running without an RTOS.
- It provides APIs to initialize a queue, push/pop single or multiple items, peek, clear, and count elements.

##### File structure
- Top-level files:
- queue.h – public interface, data types, configuration macro (QUEUE_DATA_T)
- queue.c – implementation of queue operations
- queue.h/.c together form a self-contained module.
- No subdirectories, build scripts, or other dependencies—it’s a header+source library.

##### README for architectural insights
- Describes the QUEUE_HandleTypeDef struct (head, tail, buffer_length, buffer pointer)
- Shows how the user allocates a buffer array in .bss or .data and passes it plus the handle into Queue_Init.
- No threads/RTOS, so all queue operations are called synchronously by application code.

##### Main components
a. MCU Application – user firmware that calls queue APIs
b. Queue Library Module (queue.c / queue.h) – implements:
- Queue_Init
- Queue_Push, Queue_Push_Array
- Queue_Pop, Queue_Pop_Array
- Queue_Peek, Queue_Peek_Array
- Queue_Clear, Queue_Count
c. Queue Handle (QUEUE_HandleTypeDef) – control block in memory, holds pointers and state
d. Data Buffer – contiguous array of QUEUE_DATA_T elements in RAM
e. CPU/Data Bus/Memory – underlying embedded hardware resources
f. (Optional) ISR or other subsystems if user calls queue from interrupt context

##### Relationships and data flows
- On system startup or before use, Application → Queue_Init(handle, buffer, length) → sets up Handle + Buffer
- During runtime:
- Push: Application → Queue_Push(handle, data) → Library updates handle.tail, writes into Buffer at tail index → increments tail.
- Pop: Application → Queue_Pop(handle, &data) → Library reads Buffer at head index → increments head.
- Peek/Count/Clear similarly interact with Handle & Buffer.
- All operations touch the same control block (Handle) and buffer array in RAM.

##### Architectural patterns and principles
- Modular Encapsulation: queue.c/.h export only APIs and type definitions.
- Data Abstraction: QUEUE_HandleTypeDef hides internal indices.
- Value-semantics for data items, pointer-to-buffer for flexibility.
- No dynamic memory; user-provided buffer improves portability/real-time safety.

##### Relevant technologies and languages
- C99 (or earlier) on bare-metal MCUs
- Macro configuration (QUEUE_DATA_T) for element size
- Standard embedded toolchains (GCC-ARM, IAR, Keil, etc.)

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Microcontroller Firmware"
        direction TB
        App["MCU Application\n(Application Code)"]:::software
        subgraph "Queue Library"
            direction TB
            API["Public Interface & Types\n(queue.h)"]:::software
            Impl["Implementation Module\n(queue.c)"]:::software
        end
        Handle["QUEUE_HandleTypeDef\n(Control Block)"]:::data
        Buffer["QUEUE_DATA_T Buffer\n(RAM Array)"]:::data
        Docs["API Documentation\n(README.md)"]:::software
    end
    Hardware["Hardware\nCPU/Bus/Memory"]:::hardware

    App -->|"Queue_Init(handle, buffer, length)"| API
    App -->|"Queue_Push(), Queue_Pop(), Queue_Peek(),\nQueue_Clear(), Queue_Count()"| API
    API -->|calls| Impl
    Impl -->|updates head/tail,\nwrites/reads Buffer| Handle
    Handle -->|indexes into| Buffer
    Buffer -->|resides in| Hardware
    App -->|refers to| Docs

    click Impl "https://github.com/xiaoxinpro/queueformcu/blob/master/queue.c"
    click API "https://github.com/xiaoxinpro/queueformcu/blob/master/queue.h"
    click Docs "https://github.com/xiaoxinpro/queueformcu/blob/master/README.md"

    classDef software fill:#E3F2FD,stroke:#1565C0,color:#000;
    classDef data fill:#E8F5E9,stroke:#2E7D32,color:#000;
    classDef hardware fill:#ECEFF1,stroke:#455A64,color:#000;
```
