API Reference

This section contains the complete API reference for all data structures and functions in the STM32 DevOps Template.

API Documentation:

Data Structures Overview

The STM32 DevOps Template provides several efficient data structures designed for embedded systems.

Header Files

The following header files contain the complete API definitions:

Queue Header

Regular Queue (FIFO) implementation for embedded systems.

This header provides a First-In-First-Out (FIFO) queue implementation using static memory allocation. The queue is suitable for embedded systems where dynamic memory allocation should be avoided.

See also

https://github.com/shishir-dey/stm32-devops-template

Author

Shishir Dey

Date

2025

Version

1.0.0

Key Features:

  • Static memory allocation (no malloc/free)

  • FIFO (First-In-First-Out) behavior

  • Circular array implementation for efficiency

  • Configurable maximum size via QUEUE_MAX_SIZE

  • Thread-safe operations (when used with proper locking)

Performance Characteristics:

  • Enqueue: O(1)

  • Dequeue: O(1)

  • Peek: O(1)

  • Size check: O(1)

Note

Include this header to use the regular queue functionality

Warning

Ensure QUEUE_MAX_SIZE is appropriate for your memory constraints

struct queue_t
#include <queue.h>

Queue data structure.

This structure maintains the queue state including the data array, front and rear pointers, and element count. The implementation uses circular indexing for efficient memory utilization.

Structure Layout:

  • data[]: Array to store queue elements

  • front: Index of the first element to be dequeued

  • rear: Index where the next element will be enqueued

  • count: Current number of elements in the queue

Note

All members should be considered private and accessed only through API functions

Warning

Direct modification of structure members may lead to undefined behavior

Public Members

void *data[QUEUE_MAX_SIZE]
int front
int rear
int count

Circular Queue Header

Circular Queue (Ring Buffer) implementation for embedded systems.

This header provides a circular queue implementation using static memory allocation. The circular queue is particularly useful for streaming data and fixed-size buffers where memory efficiency is crucial.

See also

https://github.com/shishir-dey/stm32-devops-template

Author

Shishir Dey

Date

2025

Version

1.0.0

Key Features:

  • Static memory allocation (no malloc/free)

  • Circular buffer behavior with wrap-around

  • Memory efficient reuse of buffer space

  • Configurable maximum size via CIRCULAR_QUEUE_MAX_SIZE

  • Distinction between full and empty states

Performance Characteristics:

  • Enqueue: O(1)

  • Dequeue: O(1)

  • Peek: O(1)

  • Size check: O(1)

Difference from Regular Queue:

Unlike regular queues, circular queues reuse the buffer space by wrapping around to the beginning when reaching the end. This makes them ideal for continuous data streaming applications.

Note

Include this header to use the circular queue functionality

Warning

Ensure CIRCULAR_QUEUE_MAX_SIZE is appropriate for your memory constraints

struct circular_queue_t
#include <circular_queue.h>

Circular queue data structure.

This structure maintains the circular queue state including the data array, front and rear pointers, and a full indicator. The circular nature is achieved through modulo arithmetic on the pointers.

Structure Layout:

  • data[]: Array to store queue elements

  • front: Index of the first element to be dequeued

  • rear: Index where the next element will be enqueued

  • is_full: Flag to distinguish between full and empty states

Full vs Empty Detection:

Since front == rear can mean both empty and full, the is_full flag is used to distinguish between these states.

Note

All members should be considered private and accessed only through API functions

Warning

Direct modification of structure members may lead to undefined behavior

Public Members

void *data[CIRCULAR_QUEUE_MAX_SIZE]

Array of void pointers to store any data type.

int front

Index of the front element (next to dequeue)

int rear

Index of the rear position (next enqueue location)

int is_full

Flag indicating if the queue is full (1) or not (0)

Priority Queue Header

Priority Queue (Binary Max-Heap) implementation for embedded systems.

This header provides a priority queue implementation using a binary max-heap with static memory allocation. Higher priority elements are served first, making it ideal for task scheduling and resource management in embedded systems.

See also

https://github.com/shishir-dey/stm32-devops-template

Author

Shishir Dey

Date

2025

Version

1.0.0

Key Features:

  • Static memory allocation (no malloc/free)

  • Binary max-heap implementation for efficient priority ordering

  • Higher numbers indicate higher priority

  • Configurable maximum size via PRIORITY_QUEUE_MAX_SIZE

  • O(log n) insertion and deletion operations

Performance Characteristics:

  • Enqueue: O(log n) - heap insertion with bubble-up

  • Dequeue: O(log n) - heap removal with bubble-down

  • Peek: O(1) - access to highest priority element

  • Size check: O(1)

Binary Heap Properties:

  • Complete binary tree structure stored in array

  • Parent node always has higher priority than children

  • Automatic rebalancing maintains heap property

  • Efficient array-based representation

Note

Include this header to use the priority queue functionality

Warning

Ensure PRIORITY_QUEUE_MAX_SIZE is appropriate for your memory constraints

Warning

Higher numbers indicate higher priority in this implementation

struct priority_queue_element_t
#include <priority_queue.h>

Priority queue element structure.

Each element in the priority queue contains both data and its associated priority value. This allows the heap to maintain proper ordering.

Priority Semantics:

Higher numerical values indicate higher priority. For example:

  • Priority 10 will be processed before priority 5

  • Priority 1 will be processed last among priorities 1, 5, 10

Note

Both data and priority are stored together for efficiency

Warning

Priority values should be chosen carefully to avoid overflow

Public Members

void *data

Pointer to the actual data element.

int priority

Priority value (higher numbers = higher priority)

struct priority_queue_t
#include <priority_queue.h>

Priority queue data structure.

This structure maintains the priority queue state including the heap array and current size. The heap property is maintained through specialized insertion and deletion algorithms.

Structure Layout:

  • elements[]: Array implementing the binary heap

  • size: Current number of elements in the heap

Heap Property:

For any element at index i: elements[i].priority >= elements[2*i+1].priority (left child) elements[i].priority >= elements[2*i+2].priority (right child)

Note

All members should be considered private and accessed only through API functions

Warning

Direct modification of structure members will break heap property

Public Members

priority_queue_element_t elements[PRIORITY_QUEUE_MAX_SIZE]

Heap array of elements.

int size

Current number of elements.

Linked List Header

Linked List implementation for embedded systems.

This header provides a traditional linked list implementation with head and tail operations. This was the original data structure in the template and demonstrates basic dynamic list operations.

See also

https://github.com/shishir-dey/stm32-devops-template

Author

Shishir Dey

Date

2025

Version

1.0.0

Key Features:

  • Traditional linked list structure with void* data

  • Head and tail insertion/deletion operations

  • Manual memory management (user provides nodes)

  • Suitable for dynamic collections of varying sizes

Performance Characteristics:

  • Insert at head: O(1)

  • Insert at tail: O(n) - requires traversal

  • Delete at head: O(1)

  • Delete at tail: O(n) - requires traversal

Memory Management:

Unlike the queue implementations, the linked list requires users to provide their own node structures. This gives more control but requires careful memory management.

Note

Include this header to use the linked list functionality

Warning

User is responsible for node allocation and data lifetime management

struct _Node
#include <linked_list.h>

Node structure for the linked list.

Each node contains a void pointer to data and a pointer to the next node. Users must allocate and manage these structures themselves.

Structure Layout:

  • data: Void pointer to user’s data

  • next: Pointer to the next node in the list

Usage Pattern:

  1. User allocates node_t structure

  2. User sets data pointer to their data

  3. User calls linked list functions to manage the node

  4. User is responsible for node cleanup

Note

The _Node prefix prevents naming conflicts with user structures

Warning

Users must ensure proper initialization of both data and next pointers

Public Members

void *data

Pointer to user-provided data.

struct _Node *next

Pointer to the next node in the list.

Common Types

Common type definitions for STM32 DevOps Template data structures.

This header provides shared type definitions used across all data structure implementations to maintain consistency and avoid naming conflicts between different modules.

See also

https://github.com/shishir-dey/stm32-devops-template

Author

Shishir Dey

Date

2025

Version

1.0.0

Note

This file should be included by all data structure headers to ensure consistent status type definitions across the entire project.

Main Application

Main header file for STM32 DevOps Template demonstrations.

This header provides declarations for the main demonstration functions that showcase the various data structure implementations.

See also

https://github.com/shishir-dey/stm32-devops-template

Author

Shishir Dey

Date

2025

Version

1.0.0

Note

This header is kept minimal as all functionality is demonstrated directly in main.c without requiring external declarations

Implementation Files

For detailed implementation information with function documentation:

Queue Implementation

Implementation of regular queue (FIFO) operations.

This file contains the implementation of all regular queue operations using circular array indexing for efficient memory utilization.

See also

queue.h for API documentation

Author

Shishir Dey

Date

2025

Version

1.0.0

Implementation Details:

  • Uses circular array with front/rear pointers

  • Count variable tracks current number of elements

  • Efficient O(1) operations for all queue functions

  • Prevents buffer overflow through proper bounds checking

Note

All functions include proper error checking and boundary validation

Circular Queue Implementation

Implementation of circular queue (ring buffer) operations.

This file contains the implementation of all circular queue operations using efficient modulo arithmetic for wrap-around behavior.

See also

circular_queue.h for API documentation

Author

Shishir Dey

Date

2025

Version

1.0.0

Note

All functions include proper error checking and boundary validation

Priority Queue Implementation

Implementation of priority queue (binary max-heap) operations.

This file contains the implementation of all priority queue operations using binary heap algorithms for efficient priority-based ordering.

See also

priority_queue.h for API documentation

Author

Shishir Dey

Date

2025

Version

1.0.0

Implementation Details:

  • Uses array-based binary heap representation

  • Heapify-up algorithm for insertion

  • Heapify-down algorithm for deletion

  • Parent-child relationships: parent(i) = (i-1)/2, children(i) = 2*i+1, 2*i+2

Note

All functions include proper error checking and heap property maintenance

Functions

static void swap_elements(priority_queue_element_t *a, priority_queue_element_t *b)

Swaps two priority queue elements.

Helper function that exchanges the contents of two priority queue elements including both data and priority values.

Note

This is an internal helper function used by heap operations

Note

Time complexity: O(1)

Parameters:

  • a – [inout] Pointer to the first element

  • b – [inout] Pointer to the second element

static void heapify_up(priority_queue_t *queue, int index)

Restores heap property by moving element upward.

Recursive function that compares an element with its parent and swaps if the element has higher priority. Continues until heap property is satisfied or root is reached.

Algorithm:

  1. Calculate parent index: (index - 1) / 2

  2. If current element has higher priority than parent, swap

  3. Recursively continue with parent index

  4. Stop when root is reached or heap property is satisfied

Note

This is an internal helper function used during insertion

Note

Time complexity: O(log n) where n is the number of elements

Parameters:

  • queue – [inout] Pointer to the priority queue

  • index – [in] Index of the element to heapify upward

static void heapify_down(priority_queue_t *queue, int index)

Restores heap property by moving element downward.

Recursive function that compares an element with its children and swaps with the highest priority child if necessary. Continues until heap property is satisfied or leaf is reached.

Algorithm:

  1. Calculate left child: 2 * index + 1

  2. Calculate right child: 2 * index + 2

  3. Find the largest priority among current, left, and right

  4. If largest is not current, swap and continue recursively

  5. Stop when heap property is satisfied or leaf is reached

Note

This is an internal helper function used during deletion

Note

Time complexity: O(log n) where n is the number of elements

Parameters:

  • queue – [inout] Pointer to the priority queue

  • index – [in] Index of the element to heapify downward

Linked List Implementation

Implementation of linked list operations.

This file contains the implementation of all linked list operations using a global head pointer and manual node management.

See also

linked_list.h for API documentation

Author

Shishir Dey

Date

2025

Version

1.0.0

Implementation Details:

  • Uses global static head pointer for list management

  • User-provided nodes with manual memory management

  • Traditional linked list traversal algorithms

  • Head operations are O(1), tail operations are O(n)

Note

All functions include proper error checking and NULL pointer validation

Note

Only one linked list instance can be active at a time

Variables

static node_t *head = NULL

Global head pointer for the linked list.

Static variable that maintains the reference to the first node in the linked list. Only one list can be active at a time.

Note

This global state limits the implementation to a single list instance

Warning

Direct access to this variable should be avoided

Main Application Implementation

Main demonstration file for STM32 DevOps Template queue implementations.

This file provides comprehensive examples of using three different queue implementations without dynamic memory allocation, suitable for embedded systems:

  • Regular Queue (FIFO)

  • Circular Queue (Ring Buffer)

  • Priority Queue (Binary Heap)

See also

https://github.com/shishir-dey/stm32-devops-template

Author

Shishir Dey

Date

2025

Version

1.0.0

Note

All queue implementations use statically allocated arrays to avoid heap fragmentation issues common in embedded systems.

Functions

int main()

Main entry point for the STM32 DevOps Template demonstration.

Executes demonstrations of all implemented data structures to showcase their usage in embedded systems. Each demonstration is independent and can be used as a reference implementation.

See also

demonstrate_linked_list()

See also

demonstrate_regular_queue()

See also

demonstrate_circular_queue()

See also

demonstrate_priority_queue()

Execution Flow:

  1. Linked list demonstration (original functionality)

  2. Regular queue demonstration (FIFO behavior)

  3. Circular queue demonstration (ring buffer)

  4. Priority queue demonstration (priority-based processing)

Note

All data structures use static allocation suitable for embedded systems

Note

This code is designed to run on STM32 microcontrollers but can be compiled for host testing as well

Returns:

int Always returns 0 for successful execution