#include <cmath>
#include <type_traits>
#include "OsAbstraction.h"
#include "OsUtility.h"
#include "FreeRTOSUtils.h"

Namespaces
namespace	anonymous_namespace{OsUtility.cpp}

Functions
void	os_delay_msec (uint16_t msec)
	Delays execution for the specified number of milliseconds.

void	os_delay_time (uint32_t timeBetweenSamples, time_unit_t timeUnit)
	Delays execution for the specified number of time.

uint32_t	os_get_elapsed_time_msec ()
	Retrieves the elapsed time in milliseconds.

uint32_t	os_get_elapsed_processor_cycle_count (uint32_t startCycleCount, time_unit_t unit)
	Function to get the elapsed time from a specified processor cycle count. The cycle count can be acquired through os_get_processor_cycle_count() function.

uint32_t	os_get_processor_cycle_count ()
	Gets the processor's current cycle count.

bool	os_mutex_create_ex (OS_Mutex &mutex, const char *mutexName, OS_Uint inherit, bool suppressVerbose) noexcept
	Creates a mutex with the specified parameters.

bool	os_mutex_create_p (OS_Mutex mutex, const char mutexName, OS_Uint inherit, bool suppressVerbose) noexcept
	Creates a mutex with the specified parameters.

bool	os_mutex_get_ex (OS_Mutex &mutex, OS_Ulong wait_option, bool suppressVerbose) noexcept
	Acquire (wait for) a TX mutex.

bool	os_mutex_get_p (OS_Mutex *mutex, OS_Ulong wait_option, bool suppressVerbose) noexcept
	Acquire (wait for) a TX mutex.

bool	os_mutex_put_ex (OS_Mutex &mutex, bool suppressVerbose) noexcept
	Release a TX mutex.

bool	os_mutex_put_p (OS_Mutex *mutex, bool suppressVerbose) noexcept
	Release a TX mutex.

bool	os_mutex_delete_ex (OS_Mutex &mutex, bool suppressVerbose) noexcept
	Deletes the specified mutex and logs any error.

bool	os_mutex_delete_p (OS_Mutex *mutex, bool suppressVerbose) noexcept
	Deletes the specified mutex and logs any error.

	__attribute__ ((weak)) uint32_t g_ssp_common_thread_count=0
	Provide a default definition if not supplied by higher-level code (weak symbol).

bool	os_thread_create_ex (OS_Thread txThread, const char name, void(entry_function)(OS_Ulong id), OS_Ulong entry_input, uint8_t stack, OS_Ulong stackSizeBytes, OS_Uint priority, OS_Uint preempt_threshold, OS_Ulong timeSliceAllowed, OS_Uint auto_start, bool suppressVerbose) noexcept
	Function to Create TX thread.

bool	os_thread_create_ex_pinned (OS_Thread txThread, const char name, void(entry_function)(OS_Ulong id), OS_Ulong entry_input, uint8_t stack, OS_Ulong stackSizeBytes, OS_Uint priority, OS_Uint preempt_threshold, OS_Ulong timeSliceAllowed, OS_Uint auto_start, int core_id, bool suppressVerbose) noexcept
	Pinned-to-core variant of os_thread_create_ex (FreeRTOS / SMP).

bool	os_thread_delete_ex (OS_Thread *txThread, bool suppressVerbose) noexcept
	Function to Delete TX thread.

bool	os_thread_resume_ex (OS_Thread *thread, bool suppressVerbose)
	Resumes the specified OS thread.

bool	os_thread_resume_if_suspended (OS_Thread *thread, bool suppressVerbose) noexcept
	Function to Resume TX thread only if it is suspended.

bool	os_thread_suspend_ex (OS_Thread *thread, bool suppressVerbose)
	Suspends the specified OS thread.

bool	os_queue_create_ex (OS_Queue &queue, const char queueName, OS_Uint messageSizeInWords, void queueStorage, OS_Ulong queueSize, bool suppressVerbose) noexcept
	Creates a queue with the specified parameters.

bool	os_queue_delete_ex (OS_Queue &queue, bool suppressVerbose) noexcept
	Deletes the specified queue and logs any error.

bool	os_queue_send_ex (OS_Queue &queue, void *message, OS_Ulong wait_option, bool suppressVerbose) noexcept
	Send a message to the queue.

bool	os_queue_receive_ex (OS_Queue &queue, void *message, OS_Ulong wait_option, bool suppressVerbose) noexcept
	Receive a message from the queue.

template<typename Callback >
OS_Uint	anonymous_namespace{OsUtility.cpp}::CreateTimer (OS_Timer &timer, char *name, Callback callback, uint32_t id, uint32_t initialTicks, uint32_t rescheduleTicks, OS_Uint autoActivate) noexcept

bool	os_timer_create_ex (OS_Timer &timer, const char name, void(callback)(uint32_t), uint32_t callbackExpirationInput, uint32_t initialTimeoutTicks, uint32_t rescheduleTimeoutTicks, OS_Uint autoActivate, bool suppressVerbose) noexcept
	Function to create a OS timer and report errors associated with the creation.

bool	os_timer_deactivate_and_delete_ex (OS_Timer &timer, bool suppressVerbose) noexcept
	Function to delete a OS timer and report errors associated with the deletion.

bool	os_timer_activate_ex (OS_Timer &timer, bool suppressVerbose) noexcept
	Activates a OS timer.

bool	os_timer_deactivate_ex (OS_Timer &timer, bool suppressVerbose) noexcept
	Deactivates a OS timer.

bool	os_semaphore_create_ex (OS_Semaphore txSemaphore, const char name, OS_Uint initial_count, bool suppressVerbose) noexcept
	Function to Create TX semaphore.

bool	os_semaphore_delete_ex (OS_Semaphore *txSemaphore, bool suppressVerbose) noexcept
	Function to Delete TX semaphore.

bool	os_semaphore_put_ex (OS_Semaphore *txSemaphore, bool suppressVerbose) noexcept
	Function to put (release) a TX semaphore.

bool	os_semaphore_get_ex (OS_Semaphore *txSemaphore, OS_Ulong wait_option, bool suppressVerbose) noexcept
	Function to get (wait for) a TX semaphore.

OS_Ulong	os_semaphore_get_count_ex (OS_Semaphore *txSemaphore, bool suppressVerbose) noexcept
	Function to get TX semaphore count.

bool	os_event_flags_create_ex (OS_EventGroup &eventFlags, const char *name, bool suppressVerbose) noexcept
	Creates an event flag group with the specified parameters.

bool	os_event_flags_delete_ex (OS_EventGroup &eventFlags, bool suppressVerbose) noexcept
	Deletes the specified event flag group and logs any error.

bool	os_event_flags_set_ex (OS_EventGroup &eventFlags, OS_Ulong flagsToSet, bool suppressVerbose) noexcept
	Set event flags in the event flag group.

bool	os_event_flags_clear_ex (OS_EventGroup &eventFlags, OS_Ulong flagsToClear, bool suppressVerbose) noexcept
	Clears event flags in the event flag group.

bool	os_event_flags_get_ex (OS_EventGroup &eventFlags, OS_Ulong flagsToGet, OS_Uint getOption, OS_Ulong &actualFlags, OS_Ulong wait_option, bool suppressVerbose) noexcept
	Get event flags from the event flag group.

void	os_stack_fault_handler (OS_Thread *thread)
	Handler for stack faults in threads.

Function Documentation

◆ attribute()

__attribute__ ( (weak) )

pure virtual

Provide a default definition if not supplied by higher-level code (weak symbol).

◆ os_delay_msec()

void os_delay_msec ( uint16_t msec )

Delays execution for the specified number of milliseconds.

Contains the declaration and definition of the utility functions related to the FreeRTOS RTOS.

Note: These functions are not thread or interrupt-safe and should be called called with appropriate guards if used within an ISR or shared between tasks.

Todo:: Add

Copyright: line once project copyright wording is finalised.

◆ os_delay_time()

void os_delay_time	(	uint32_t	timeBetweenSamples,
		time_unit_t	timeUnit
	)

Delays execution for the specified number of time.

Currently only supports MSEC AND S, everything else just returns

Parameters

msec	The delay duration in milliseconds.

◆ os_event_flags_clear_ex()

bool os_event_flags_clear_ex	(	OS_EventGroup &	eventFlags,
		OS_Ulong	flagsToClear,
		bool	suppressVerbose
	)

noexcept

Clears event flags in the event flag group.

Parameters

eventFlags	- The OS event flags to set
flagsToClear	- The flags to clear

◆ os_event_flags_create_ex()

bool os_event_flags_create_ex	(	OS_EventGroup &	eventFlags,
		const char *	name,
		bool	suppressVerbose
	)

noexcept

Creates an event flag group with the specified parameters.

Parameters

eventFlags	- The OS event flags to create
name	- The name for the event flag group

◆ os_event_flags_delete_ex()

bool os_event_flags_delete_ex	(	OS_EventGroup &	eventFlags,
		bool	suppressVerbose
	)

noexcept

Deletes the specified event flag group and logs any error.

Parameters

eventFlags - The OS event flags to delete

◆ os_event_flags_get_ex()

bool os_event_flags_get_ex	(	OS_EventGroup &	eventFlags,
		OS_Ulong	flagsToGet,
		OS_Uint	getOption,
		OS_Ulong &	actualFlags,
		OS_Ulong	wait_option,
		bool	suppressVerbose
	)

noexcept

Get event flags from the event flag group.

Parameters

eventFlags	- The OS event flags to get
flagsToGet	- The flags to get
getOption	- The option on how to get the flags
actualFlags	- The actual flags gotten
wait_option	- The option on how to wait if the flags are not available

◆ os_event_flags_set_ex()

bool os_event_flags_set_ex	(	OS_EventGroup &	eventFlags,
		OS_Ulong	flagsToSet,
		bool	suppressVerbose
	)

noexcept

Set event flags in the event flag group.

Parameters

eventFlags	- The OS event flags to set
flagsToSet	- The flags to set

◆ os_get_elapsed_processor_cycle_count()

uint32_t os_get_elapsed_processor_cycle_count	(	uint32_t	startCycleCount,
		time_unit_t	unit
	)

Function to get the elapsed time from a specified processor cycle count. The cycle count can be acquired through os_get_processor_cycle_count() function.

Parameters

startCycleCount	: value of the cycle count DWT->CYCCNT at first position of the program.
unit	: UNIT_MS, if the result is requested in milliseconds. UNIT_US, if the result is requested in microseconds. UNIT_SEC, if the result is requested in seconds.

Returns: Elapsed time in the unit specified

◆ os_get_elapsed_time_msec()

uint32_t os_get_elapsed_time_msec ( )

Retrieves the elapsed time in milliseconds.

Returns: The elapsed time in milliseconds.

◆ os_get_processor_cycle_count()

uint32_t os_get_processor_cycle_count ( )

Gets the processor's current cycle count.

Returns: Processor's current cycle count (DWT->CYCCNT)

◆ os_mutex_create_ex()

bool os_mutex_create_ex	(	OS_Mutex &	mutex,
		const char *	mutexName,
		OS_Uint	inherit,
		bool	suppressVerbose
	)

noexcept

Creates a mutex with the specified parameters.

Parameters

mutex	- The OS mutex to create
name	- The name fo rthe mutex
inherit	- The inherit property for the mutex

◆ os_mutex_create_p()

bool os_mutex_create_p	(	OS_Mutex *	mutex,
		const char *	mutexName,
		OS_Uint	priority = `OS_INHERIT`,
		bool	suppressVerbose = `true`
	)

noexcept

Creates a mutex with the specified parameters.

Parameters

mutex	- The OS mutex to create
name	- The name fo rthe mutex
name	- The priority for the mutex

◆ os_mutex_delete_ex()

bool os_mutex_delete_ex	(	OS_Mutex &	mutex,
		bool	suppressVerbose
	)

noexcept

Deletes the specified mutex and logs any error.

Parameters

mutex - The OS mutex to delete

◆ os_mutex_delete_p()

bool os_mutex_delete_p	(	OS_Mutex *	mutex,
		bool	suppressVerbose
	)

noexcept

Deletes the specified mutex and logs any error.

Parameters

mutex - The OS mutex to delete

◆ os_mutex_get_ex()

bool os_mutex_get_ex	(	OS_Mutex &	mutex,
		OS_Ulong	wait_option,
		bool	suppressVerbose
	)

noexcept

Acquire (wait for) a TX mutex.

Parameters

mutex_ptr	Pointer to the mutex control block.
wait_option	Specifies the maximum time to wait for the mutex.
suppressVerbose	Flag to suppress verbose output.

Returns: true if the mutex was successfully acquired, false otherwise.

◆ os_mutex_get_p()

bool os_mutex_get_p	(	OS_Mutex *	mutex,
		OS_Ulong	wait_option,
		bool	suppressVerbose
	)

noexcept

Acquire (wait for) a TX mutex.

Parameters

mutex_ptr	Pointer to the mutex control block.
wait_option	Specifies the maximum time to wait for the mutex.
suppressVerbose	Flag to suppress verbose output.

Returns: true if the mutex was successfully acquired, false otherwise.

◆ os_mutex_put_ex()

bool os_mutex_put_ex	(	OS_Mutex &	mutex,
		bool	suppressVerbose
	)

noexcept

Release a TX mutex.

Parameters

mutex_ptr	Pointer to the mutex control block.
suppressVerbose	Flag to suppress verbose output.

Returns: true if the mutex was successfully released, false otherwise.

◆ os_mutex_put_p()

bool os_mutex_put_p	(	OS_Mutex *	mutex,
		bool	suppressVerbose
	)

noexcept

Release a TX mutex.

Parameters

mutex_ptr	Pointer to the mutex control block.
suppressVerbose	Flag to suppress verbose output.

Returns: true if the mutex was successfully released, false otherwise.

◆ os_queue_create_ex()

bool os_queue_create_ex	(	OS_Queue &	queue,
		const char *	queueName,
		OS_Uint	messageSizeInWords,
		void *	queueStorage,
		OS_Ulong	queueSize,
		bool	suppressVerbose
	)

noexcept

Creates a queue with the specified parameters.

Parameters

queue	- The OS queue to create
queueName	- The name for the queue
messageSizeInWords	- The size of the messages that will be stored in the queue

◆ os_queue_delete_ex()

bool os_queue_delete_ex	(	OS_Queue &	queue,
		bool	suppressVerbose
	)

noexcept

Deletes the specified queue and logs any error.

Parameters

queue - The OS queue to delete

◆ os_queue_receive_ex()

bool os_queue_receive_ex	(	OS_Queue &	queue,
		void *	message,
		OS_Ulong	wait_option,
		bool	suppressVerbose
	)

noexcept

Receive a message from the queue.

Parameters

queue	- The OS queue to receive the message from
message	- The received message
wait_option	- The option on how to wait if the queue is empty

◆ os_queue_send_ex()

bool os_queue_send_ex	(	OS_Queue &	queue,
		void *	message,
		OS_Ulong	wait_option,
		bool	suppressVerbose
	)

noexcept

Send a message to the queue.

Parameters

queue	- The OS queue to send the message to
message	- The message to send
wait_option	- The option on how to wait if the queue is full

◆ os_semaphore_create_ex()

bool os_semaphore_create_ex	(	OS_Semaphore *	txSemaphore,
		const char *	name,
		OS_Uint	initial_count,
		bool	suppressVerbose
	)

noexcept

Function to Create TX semaphore.

Parameters

txSemaphore	Pointer to the OS semaphore control block.
name	Name of the semaphore.
initial_count	Initial count of the semaphore.

Returns: true if the semaphore was successfully created, false otherwise.

◆ os_semaphore_delete_ex()

bool os_semaphore_delete_ex	(	OS_Semaphore *	txSemaphore,
		bool	suppressVerbose
	)

noexcept

Function to Delete TX semaphore.

Parameters

txSemaphore Pointer to the OS semaphore control block to be deleted.

Returns: true if the semaphore was successfully deleted, false otherwise.

◆ os_semaphore_get_count_ex()

OS_Ulong os_semaphore_get_count_ex	(	OS_Semaphore *	txSemaphore,
		bool	suppressVerbose
	)

noexcept

Function to get TX semaphore count.

Parameters

txSemaphore Pointer to the OS semaphore control block.

Returns: the count of the semaphore.

◆ os_semaphore_get_ex()

bool os_semaphore_get_ex	(	OS_Semaphore *	txSemaphore,
		OS_Ulong	wait_option,
		bool	suppressVerbose
	)

noexcept

Function to get (wait for) a TX semaphore.

Parameters

txSemaphore	Pointer to the OS semaphore control block.
wait_option	Specifies the maximum time to wait for the semaphore.

Returns: true if the semaphore was successfully acquired, false otherwise.

◆ os_semaphore_put_ex()

bool os_semaphore_put_ex	(	OS_Semaphore *	txSemaphore,
		bool	suppressVerbose
	)

noexcept

Function to put (release) a TX semaphore.

Parameters

txSemaphore Pointer to the OS semaphore control block.

Returns: true if the semaphore was successfully released, false otherwise.

◆ os_stack_fault_handler()

void os_stack_fault_handler ( OS_Thread * thread )

Handler for stack faults in threads.

Parameters

thread The thread where the stack fault occurred.

◆ os_thread_create_ex()

bool os_thread_create_ex	(	OS_Thread *	txThread,
		const char *	name,
		void(*)(OS_Ulong id)	entry_function,
		OS_Ulong	entry_input,
		uint8_t *	stack,
		OS_Ulong	stackSizeBytes,
		OS_Uint	priority,
		OS_Uint	preempt_threshold,
		OS_Ulong	timeSliceAllowed,
		OS_Uint	auto_start,
		bool	suppressVerbose
	)

noexcept

Function to Create TX thread.

Parameters

txThread	Pointer to the OS thread control block.
name	Name of the thread.
entry_function	Pointer to the thread's entry function.
entry_input	Input value for the thread's entry function.
stack	Pointer to the thread's stack.
stackSizeBytes	Size of the thread's stack in bytes.
priority	Priority of the thread.
preempt_threshold	Preemption threshold of the thread.
timeSliceAllowed	Maximum length of time (in ticks) that the thread can execute before OS will reschedule.
auto_start	OS_AUTO_START if the thread should start immediately, or OS_DONT_START if it should not start until explicitly resumed.

Returns: true if the thread was successfully created, false otherwise.

Create the OS Thread

Add to the overall system thread count

TODO: log appropriate error here

◆ os_thread_create_ex_pinned()

bool os_thread_create_ex_pinned	(	OS_Thread *	txThread,
		const char *	name,
		void(*)(OS_Ulong id)	entry_function,
		OS_Ulong	entry_input,
		uint8_t *	stack,
		OS_Ulong	stackSizeBytes,
		OS_Uint	priority,
		OS_Uint	preempt_threshold,
		OS_Ulong	timeSliceAllowed,
		OS_Uint	auto_start,
		int	core_id,
		bool	suppressVerbose = `true`
	)

noexcept

Pinned-to-core variant of os_thread_create_ex (FreeRTOS / SMP).

Mirrors os_thread_create_ex but takes an additional core_id that is forwarded to os_thread_create_pinned. Pass core_id < 0 (e.g. -1) for "no affinity" — equivalent to the non-pinned variant.

Parameters

core_id CPU core to pin the new task to (0 or 1 on ESP32-S3), or any value < 0 for no affinity.

◆ os_thread_delete_ex()

bool os_thread_delete_ex	(	OS_Thread *	txThread,
		bool	suppressVerbose
	)

noexcept

Function to Delete TX thread.

Parameters

txThread Pointer to the OS thread control block to be deleted.

Returns: true if the thread was successfully deleted, false otherwise.

◆ os_thread_resume_ex()

bool os_thread_resume_ex	(	OS_Thread *	thread,
		bool	suppressVerbose = `true`
	)

Resumes the specified OS thread.

Parameters

thread The OS thread to resume.

◆ os_thread_resume_if_suspended()

bool os_thread_resume_if_suspended	(	OS_Thread *	txThread,
		bool	suppressVerbose = `true`
	)

noexcept

Function to Resume TX thread only if it is suspended.

Parameters

txThread Pointer to the OS thread control block to be resumed.

Returns: true if the thread was successfully resumed or if it was not suspended, false otherwise.

◆ os_thread_suspend_ex()

bool os_thread_suspend_ex	(	OS_Thread *	thread,
		bool	suppressVerbose = `true`
	)

Suspends the specified OS thread.

Parameters

thread The OS thread to resume.

◆ os_timer_activate_ex()

bool os_timer_activate_ex	(	OS_Timer &	timer,
		bool	suppressVerbose = `true`
	)

noexcept

Activates a OS timer.

Parameters

timer Reference to the timer to be activated.

Returns: Returns true if the timer was successfully activated, false otherwise.

◆ os_timer_create_ex()

bool os_timer_create_ex	(	OS_Timer &	timer,
		const char *	name,
		void(*)(uint32_t)	callback,
		uint32_t	callbackExpirationInput,
		uint32_t	initialTimeoutTicks,
		uint32_t	rescheduleTimeoutTicks,
		OS_Uint	autoActivate,
		bool	suppressVerbose
	)

noexcept

Function to create a OS timer and report errors associated with the creation.

Creates a OS timer and reports any errors associated with the creation.

Parameters

timer	Reference to timer control block.
name	Pointer to timer name.
callback	timer expiration callback function.
callbackExpirationInput	A uint32_t data point that can be passed to expiration callback function.
initialTimeoutTicks	Initial Expiration ticks.
rescheduleTimeoutTicks	Reschedule ticks.
autoActivate	The data value to set.

◆ os_timer_deactivate_and_delete_ex()

bool os_timer_deactivate_and_delete_ex	(	OS_Timer &	timer,
		bool	suppressVerbose
	)

noexcept

Function to delete a OS timer and report errors associated with the deletion.

Stops and deletes a OS timer, reporting any errors associated with the operation.

Parameters

timer The timer to delete.

◆ os_timer_deactivate_ex()

bool os_timer_deactivate_ex	(	OS_Timer &	timer,
		bool	suppressVerbose = `true`
	)

noexcept

Deactivates a OS timer.

Parameters

timer Reference to the timer to be deactivated.

Returns: Returns true if the timer was successfully deactivated, false otherwise.

Namespaces

Functions

Function Documentation

◆ __attribute__()

◆ os_delay_msec()

◆ os_delay_time()

◆ os_event_flags_clear_ex()

◆ os_event_flags_create_ex()

◆ os_event_flags_delete_ex()

◆ os_event_flags_get_ex()

◆ os_event_flags_set_ex()

◆ os_get_elapsed_processor_cycle_count()

◆ os_get_elapsed_time_msec()

◆ os_get_processor_cycle_count()

◆ os_mutex_create_ex()

◆ os_mutex_create_p()

◆ os_mutex_delete_ex()

◆ os_mutex_delete_p()

◆ os_mutex_get_ex()

◆ os_mutex_get_p()

◆ os_mutex_put_ex()

◆ os_mutex_put_p()

◆ os_queue_create_ex()

◆ os_queue_delete_ex()

◆ os_queue_receive_ex()

◆ os_queue_send_ex()

◆ os_semaphore_create_ex()

◆ os_semaphore_delete_ex()

◆ os_semaphore_get_count_ex()

◆ os_semaphore_get_ex()

◆ os_semaphore_put_ex()

◆ os_stack_fault_handler()

◆ os_thread_create_ex()

◆ os_thread_create_ex_pinned()

◆ os_thread_delete_ex()

◆ os_thread_resume_ex()

◆ os_thread_resume_if_suspended()

◆ os_thread_suspend_ex()

◆ os_timer_activate_ex()

◆ os_timer_create_ex()

◆ os_timer_deactivate_and_delete_ex()

◆ os_timer_deactivate_ex()

◆ attribute()