Thread-safe shared buffer management for the OpenThread Application Framework. More...

Classes
struct	bufferConfig_t
	Buffer configuration structure. More...

Macros
#define	OTAPP_BUF_SIZE (OTAPP_BUF_KEY_1_SIZE + OTAPP_BUF_KEY_2_SIZE + OTAPP_BUF_KEY_3_SIZE)
	Total size of the buffer pool.

Functions
int8_t	otapp_buf_append (uint16_t key, const uint8_t *new_data, uint16_t len)
	Appends data to the buffer slot associated with the key.
int8_t	otapp_buf_getData (uint16_t key, uint8_t bufOut, uint16_t bufSize, uint16_t lenBufOut)
	Retrieves data from a buffer slot into a user-provided buffer.
const uint8_t *	otapp_buf_getReadOnly_ptr (uint16_t key, uint16_t *bufSize_out)
	Gets a read-only pointer to the buffer slot's payload.
uint8_t *	otapp_buf_getWriteOnly_ptr (uint16_t key, uint16_t required_size)
	Requests a write-only pointer for direct memory access (Zero-Copy).
int8_t	otapp_buff_clear (uint16_t key)
	Clears the data in a specific buffer slot.
uint16_t	otapp_buf_getMaxSize (uint16_t key)
	Returns the maximum capacity of a slot.
uint16_t	otapp_buf_getCurrentLenSize (uint16_t key)
	Returns the current length of data stored in a slot.
int8_t	otapp_buf_writeUnlock (uint16_t key)
	Unlocks a slot previously locked by otapp_buf_getWriteOnly_ptr.
void	otapp_buffer_init (void)
	Initializes the buffer module and creates the RTOS mutex.

Return Codes
#define	OTAPP_BUF_OK (-1)
	Operation successful.
#define	OTAPP_BUF_ERROR (-2)
	Generic error (null ptr, init missing).
#define	OTAPP_BUF_ERROR_OVERFLOW (-3)
	Buffer is full or data exceeds slot size.
#define	OTAPP_BUF_ERROR_KEY_NOT_FOUND (-4)
	The provided key does not exist in config.
#define	OTAPP_BUF_ERROR_WRITE_LOCK (-5)
	The slot is currently locked for direct writing.

Buffer Configuration Keys
#define	OTAPP_BUF_KEY_1 0x1001
	Key 1: General purpose buffer. Used by otapp_pair_uriParseMessage() and otapp_pair_uriResourcesCreate().
#define	OTAPP_BUF_KEY_1_SIZE 256
#define	OTAPP_BUF_KEY_2 0x1002
	Auxiliary buffer slot 2.
#define	OTAPP_BUF_KEY_2_SIZE 64
#define	OTAPP_BUF_KEY_3 0x1003
	Auxiliary buffer slot 3.
#define	OTAPP_BUF_KEY_3_SIZE 64

Detailed Description

Thread-safe shared buffer management for the OpenThread Application Framework.

This module manages a statically allocated memory pool divided into specific slots (Keys). It provides thread-safe access using FreeRTOS mutexes to prevent race conditions during read/write operations. Key Features:

Static Allocation: No heap fragmentation (uses HRO_SEC_NOINIT section).
Thread Safety: All API calls are protected by a mutex.
Zero-Copy Write: otapp_buf_getWriteOnly_ptr allows direct memory access with a locking mechanism.
Key-Based Access: Data is organized by predefined keys (e.g., OTAPP_BUF_KEY_1). Locking Mechanism (Zero-Copy): When utilizing direct write access (otapp_buf_getWriteOnly_ptr), the buffer slot is logically LOCKED. Any subsequent attempt to write to this key (from any thread) will return OTAPP_BUF_ERROR_WRITE_LOCK untill otapp_buf_writeUnlock is explicitly called.
Unit Test Verification
This module has been verified with a comprehensive suite of unit tests (HOST_ot_app_buffer_test.c) using the Unity framework:
Argument Validation: Verified rejection of NULL pointers, zero-length requests, and invalid keys.
Boundary Protection: Confirmed OTAPP_BUF_ERROR_OVERFLOW is returned when attempting to write beyond the allocated slot size.
Locking Logic: Verified that otapp_buf_getWriteOnly_ptr correctly locks the slot.
Concurrency & Thread Safety: Validated using a multi-threaded stress test ("Buffer Bomber"). The test simulates a Race Condition using pthread and confirms that the internal Mutex mechanism prevents data corruption.

Version: 0.1

Date: 03-02-2026

Author: Jan Łukaszewicz (plhar.nosp@m.eo@g.nosp@m.mail..nosp@m.com)

Copyright: © 2025 MIT LICENCE

Macro Definition Documentation

◆ OTAPP_BUF_ERROR

#define OTAPP_BUF_ERROR (-2)

Generic error (null ptr, init missing).

◆ OTAPP_BUF_ERROR_KEY_NOT_FOUND

#define OTAPP_BUF_ERROR_KEY_NOT_FOUND (-4)

The provided key does not exist in config.

◆ OTAPP_BUF_ERROR_OVERFLOW

#define OTAPP_BUF_ERROR_OVERFLOW (-3)

Buffer is full or data exceeds slot size.

◆ OTAPP_BUF_ERROR_WRITE_LOCK

#define OTAPP_BUF_ERROR_WRITE_LOCK (-5)

The slot is currently locked for direct writing.

◆ OTAPP_BUF_KEY_1

#define OTAPP_BUF_KEY_1 0x1001

Key 1: General purpose buffer. Used by otapp_pair_uriParseMessage() and otapp_pair_uriResourcesCreate().

◆ OTAPP_BUF_KEY_1_SIZE

#define OTAPP_BUF_KEY_1_SIZE 256

◆ OTAPP_BUF_KEY_2

#define OTAPP_BUF_KEY_2 0x1002

Auxiliary buffer slot 2.

◆ OTAPP_BUF_KEY_2_SIZE

#define OTAPP_BUF_KEY_2_SIZE 64

◆ OTAPP_BUF_KEY_3

#define OTAPP_BUF_KEY_3 0x1003

Auxiliary buffer slot 3.

◆ OTAPP_BUF_KEY_3_SIZE

#define OTAPP_BUF_KEY_3_SIZE 64

◆ OTAPP_BUF_OK

#define OTAPP_BUF_OK (-1)

Operation successful.

◆ OTAPP_BUF_SIZE

#define OTAPP_BUF_SIZE (OTAPP_BUF_KEY_1_SIZE + OTAPP_BUF_KEY_2_SIZE + OTAPP_BUF_KEY_3_SIZE)

Total size of the buffer pool.

Function Documentation

◆ otapp_buf_append()

int8_t otapp_buf_append	(	uint16_t	key,
		const uint8_t *	new_data,
		uint16_t	len )

Appends data to the buffer slot associated with the key.

Parameters

[in]	key	Buffer slot identifier.
[in]	new_data	Pointer to the data to be copied.
[in]	len	Length of data to copy.

Returns: int8_t OTAPP_BUF_OK on success, or error code (e.g. OTAPP_BUF_ERROR_OVERFLOW).

Note: Thread Safe (Mutex Protected): This function acquires the mutex to protect the current_len increment and memory copy from race conditions. The critical section covers the bounds check and memory update.

Warning: Returns OTAPP_BUF_ERROR_WRITE_LOCK if the slot is currently locked by otapp_buf_getWriteOnly_ptr.

◆ otapp_buf_getCurrentLenSize()

uint16_t otapp_buf_getCurrentLenSize ( uint16_t key )

Returns the current length of data stored in a slot.

Parameters

key	Buffer slot identifier.

Returns: uint16_t Current usage in bytes.

◆ otapp_buf_getData()

int8_t otapp_buf_getData	(	uint16_t	key,
		uint8_t *	bufOut,
		uint16_t	bufSize,
		uint16_t *	lenBufOut )

Retrieves data from a buffer slot into a user-provided buffer.

Parameters

[in]	key	Buffer slot identifier.
[out]	bufOut	Destination buffer.
[in]	bufSize	Size of the destination buffer.
[out]	lenBufOut	Pointer to store the actual number of bytes read.

Returns: int8_t OTAPP_BUF_OK on success.

◆ otapp_buf_getMaxSize()

uint16_t otapp_buf_getMaxSize ( uint16_t key )

Returns the maximum capacity of a slot.

Parameters

key	Buffer slot identifier.

Returns: uint16_t Max size in bytes.

◆ otapp_buf_getReadOnly_ptr()

const uint8_t * otapp_buf_getReadOnly_ptr	(	uint16_t	key,
		uint16_t *	bufSize_out )

Gets a read-only pointer to the buffer slot's payload.

Parameters

[in]	key	Buffer slot identifier.
[out]	bufSize_out	Pointer to store the size of valid data in the slot.

Returns: const uint8_t* Pointer to the data, or NULL on error.

Note: This function acquires the mutex briefly to read the current length, but returns a direct pointer to static memory.

◆ otapp_buf_getWriteOnly_ptr()

uint8_t * otapp_buf_getWriteOnly_ptr	(	uint16_t	key,
		uint16_t	required_size )

Requests a write-only pointer for direct memory access (Zero-Copy).

This function locks the slot for writing. After correctly returning the ptr to the memory slot, subsequent calls to otapp_buf_append or otapp_buf_getWriteOnly_ptr for this key will fail/block until otapp_buf_writeUnlock is called. This mechanism is intended for filling the buffer from a DMA source or complex parsing loops where intermediate copies are undesirable.

Parameters

[in]	key	Buffer slot identifier.
[in]	required_size	Number of bytes intended to be written (sets current_len immediately).

Returns: uint8_t* Pointer to the buffer slot start, or NULL if locked/full.

Warning: Blocking Behavior: If successful, this function explicitly LOCKS the slot. You MUST call otapp_buf_writeUnlock(key) immediately after finishing the write operation.

◆ otapp_buf_writeUnlock()

int8_t otapp_buf_writeUnlock ( uint16_t key )

Unlocks a slot previously locked by otapp_buf_getWriteOnly_ptr.

Parameters

key	Buffer slot identifier.

Returns: int8_t OTAPP_BUF_OK on success.

◆ otapp_buff_clear()

int8_t otapp_buff_clear ( uint16_t key )

Clears the data in a specific buffer slot.

Parameters

key	Buffer slot identifier.

Returns: int8_t OTAPP_BUF_OK on success.

◆ otapp_buffer_init()

void otapp_buffer_init ( void )

Initializes the buffer module and creates the RTOS mutex.

Note: This is called internally during the framework initialization.

Classes

Macros

Functions

Return Codes

Buffer Configuration Keys

Detailed Description

Macro Definition Documentation

◆ OTAPP_BUF_ERROR

◆ OTAPP_BUF_ERROR_KEY_NOT_FOUND

◆ OTAPP_BUF_ERROR_OVERFLOW

◆ OTAPP_BUF_ERROR_WRITE_LOCK

◆ OTAPP_BUF_KEY_1

◆ OTAPP_BUF_KEY_1_SIZE

◆ OTAPP_BUF_KEY_2

◆ OTAPP_BUF_KEY_2_SIZE

◆ OTAPP_BUF_KEY_3

◆ OTAPP_BUF_KEY_3_SIZE

◆ OTAPP_BUF_OK

◆ OTAPP_BUF_SIZE

Function Documentation

◆ otapp_buf_append()

◆ otapp_buf_getCurrentLenSize()

◆ otapp_buf_getData()

◆ otapp_buf_getMaxSize()

◆ otapp_buf_getReadOnly_ptr()

◆ otapp_buf_getWriteOnly_ptr()

◆ otapp_buf_writeUnlock()

◆ otapp_buff_clear()

◆ otapp_buffer_init()