OSAL API Reference¶

This section documents the OS Abstraction Layer (OSAL) API.

OSAL Definitions¶

enum osal_status_t¶

OSAL status codes.

Values:

enumerator OSAL_OK¶: Operation successful

enumerator OSAL_ERROR¶: Generic error

enumerator OSAL_ERROR_INVALID_PARAM¶: Invalid parameter

enumerator OSAL_ERROR_NULL_POINTER¶: Null pointer

enumerator OSAL_ERROR_NO_MEMORY¶: Out of memory

enumerator OSAL_ERROR_TIMEOUT¶: Operation timeout

enumerator OSAL_ERROR_NOT_INIT¶: Not initialized

enumerator OSAL_ERROR_BUSY¶: Resource busy

enumerator OSAL_ERROR_NOT_FOUND¶: Resource not found

enumerator OSAL_ERROR_FULL¶: Queue/buffer full

enumerator OSAL_ERROR_EMPTY¶: Queue/buffer empty

enumerator OSAL_ERROR_ISR¶: Called from ISR context

OSAL_WAIT_FOREVER¶: Wait forever timeout value.

OSAL_NO_WAIT¶: No wait timeout value.

OSAL_IS_OK(status)¶: Check if status is OK.

OSAL_IS_ERROR(status)¶: Check if status is error.

OSAL_VALIDATE_PTR(ptr)¶

Validate pointer is not NULL.

Note

Requirements: 1.2

Parameters:

ptr – [in] Pointer to validate

Returns:

Returns OSAL_ERROR_NULL_POINTER if ptr is NULL

OSAL_VALIDATE_PARAM(cond, err)¶

Validate condition or return error.

Note

Requirements: 1.3

Parameters:

cond – [in] Condition to validate
err – [in] Error code to return if condition is false

Returns:

Returns err if condition is false

OSAL_CHECK_NOT_ISR()¶

Check not in ISR context.

Note

Requirements: 1.4

Note

Requires osal_is_isr() to be declared before use

Returns:: Returns OSAL_ERROR_ISR if called from ISR

OSAL_VALIDATE_HANDLE_PTR(handle)¶

Validate handle (basic NULL check version)

Note

Requirements: 1.1

Note

For full handle validation with magic number checking, use OSAL_VALIDATE_HANDLE from osal_internal.h

Parameters:

handle – [in] Handle to validate

Returns:

Returns OSAL_ERROR_NULL_POINTER if handle is NULL

Task API¶

enum osal_task_priority_t¶

Task priority levels.

Note

Priority range is 0-31, where 0 is lowest and 31 is highest

Values:

enumerator OSAL_TASK_PRIORITY_IDLE¶: Idle priority (lowest)

enumerator OSAL_TASK_PRIORITY_LOW¶: Low priority

enumerator OSAL_TASK_PRIORITY_NORMAL¶: Normal priority

enumerator OSAL_TASK_PRIORITY_HIGH¶: High priority

enumerator OSAL_TASK_PRIORITY_REALTIME¶: Real-time priority (highest)

enum osal_task_state_t¶

Task state enumeration.

Values:

enumerator OSAL_TASK_STATE_READY¶: Task is ready to run

enumerator OSAL_TASK_STATE_RUNNING¶: Task is currently running

enumerator OSAL_TASK_STATE_BLOCKED¶: Task is blocked

enumerator OSAL_TASK_STATE_SUSPENDED¶: Task is suspended

enumerator OSAL_TASK_STATE_DELETED¶: Task has been deleted

typedef void *osal_task_handle_t¶: Task handle type.

typedef void (*osal_task_func_t)(void *arg)¶

Task function type.

Param arg:: [in] Task argument

osal_status_t osal_task_create(const osal_task_config_t *config, osal_task_handle_t *handle)¶

Create a new task.

Creates a task in the baremetal cooperative scheduler. Tasks are stored in a fixed-size array and run in round-robin fashion when the scheduler is started.

Creates a FreeRTOS task with the specified configuration. The OSAL priority (0-31) is mapped to FreeRTOS priority range.

Note

Requirements: 4.1, 4.7, 10.1, 10.2

Note

Requirements: 4.1, 4.7, 10.1, 10.2

Parameters:

config – [in] Task configuration
handle – [out] Pointer to store task handle

Return values:

OSAL_OK – Task created successfully
OSAL_ERROR_NULL_POINTER – config or handle is NULL
OSAL_ERROR_INVALID_PARAM – Invalid configuration parameters
OSAL_ERROR_NO_MEMORY – Memory allocation failed

Returns:

OSAL_OK on success, error code otherwise

osal_status_t osal_task_delete(osal_task_handle_t handle)¶

Delete a task.

Marks a task as deleted in the baremetal scheduler. If handle is NULL, deletes the calling task.

Deletes a FreeRTOS task. If handle is NULL, deletes the calling task.

Note

Requirements: 4.2

Note

Requirements: 4.2

Parameters:

handle – [in] Task handle (NULL for current task)

Return values:

OSAL_OK – Task deleted successfully
OSAL_ERROR_INVALID_PARAM – Invalid task handle

Returns:

OSAL_OK on success, error code otherwise

osal_status_t osal_task_suspend(osal_task_handle_t handle)¶

Suspend a task.

Suspends a task in the baremetal scheduler. The task will not run until resumed.

Suspends a FreeRTOS task. The task will not run until resumed.

Note

Requirements: 4.3

Note

Requirements: 4.3

Parameters:

handle – [in] Task handle

Return values:

OSAL_OK – Task suspended successfully
OSAL_ERROR_NULL_POINTER – handle is NULL
OSAL_ERROR_INVALID_PARAM – Invalid task handle

Returns:

OSAL_OK on success, error code otherwise

osal_status_t osal_task_resume(osal_task_handle_t handle)¶

Resume a task.

Resumes a previously suspended task in the baremetal scheduler.

Resume a task.

Resumes a previously suspended FreeRTOS task.

Note

Requirements: 4.4

Note

Requirements: 4.4

Parameters:

handle – [in] Task handle

Return values:

OSAL_OK – Task resumed successfully
OSAL_ERROR_NULL_POINTER – handle is NULL
OSAL_ERROR_INVALID_PARAM – Invalid task handle

Returns:

OSAL_OK on success, error code otherwise

osal_status_t osal_task_delay(uint32_t ms)¶

Delay current task.

Blocks the calling task for the specified number of milliseconds using busy-wait delay.

Blocks the calling task for the specified number of milliseconds.

Note

Requirements: 4.5

Note

In baremetal cooperative scheduling, this is a busy-wait.

Note

Requirements: 4.5

Parameters:

ms – [in] Delay time in milliseconds

Return values:

OSAL_OK – Delay completed successfully
OSAL_ERROR_ISR – Called from ISR context

Returns:

OSAL_OK on success, error code otherwise

osal_status_t osal_task_yield(void)¶

Yield current task.

In cooperative scheduling, yield does nothing special. The scheduler will pick the next task when current task returns.

Yields the processor to another task of equal or higher priority.

Note

Requirements: 4.6

Note

Requirements: 4.6

Return values:

OSAL_OK – Yield completed successfully
OSAL_ERROR_ISR – Called from ISR context

Returns:

OSAL_OK on success, error code otherwise

osal_task_handle_t osal_task_get_current(void)¶

Get current task handle.

Note

Requirements: 4.8

Returns:: Current task handle, or NULL if scheduler not running

const char *osal_task_get_name(osal_task_handle_t handle)¶

Get task name.

Note

Requirements: 4.9

Parameters:: handle – [in] Task handle
Returns:: Task name string, or NULL if handle is invalid

uint8_t osal_task_get_priority(osal_task_handle_t handle)¶

Get task priority.

Returns the current priority of the specified task. The FreeRTOS priority is mapped back to OSAL priority range.

Returns the current priority of the specified task.

Note

Returns 0 for invalid handles, which is also a valid priority value (OSAL_TASK_PRIORITY_IDLE)

Note

Requirements: 9.1

Note

Requirements: 9.1

Parameters:: handle – [in] Task handle
Returns:: Task priority (0-31), or 0 if handle is invalid

osal_status_t osal_task_set_priority(osal_task_handle_t handle, uint8_t priority)¶

Set task priority.

Changes the priority of the specified task at runtime. The OSAL priority is mapped to FreeRTOS priority range.

Changes the priority of the specified task at runtime.

Note

Requirements: 9.2

Note

Requirements: 9.2

Parameters:

handle – [in] Task handle
priority – [in] New priority (0-31)

Return values:

OSAL_OK – Priority set successfully
OSAL_ERROR_NULL_POINTER – handle is NULL
OSAL_ERROR_INVALID_PARAM – Invalid priority value or handle

Returns:

OSAL_OK on success, error code otherwise

size_t osal_task_get_stack_watermark(osal_task_handle_t handle)¶

Get task stack high watermark.

Returns the minimum amount of remaining stack space that was available to the task since the task started executing. This is the high water mark of stack usage.

Returns an estimated value for stack watermark. Native platform does not have direct stack monitoring, so this returns a placeholder value.

Note

Returns the minimum amount of remaining stack space that has existed since the task was created

Note

Requirements: 9.3

Note

Requirements: 9.3

Parameters:: handle – [in] Task handle
Returns:: Minimum free stack space in bytes, or 0 if invalid

osal_task_state_t osal_task_get_state(osal_task_handle_t handle)¶

Get task state.

Returns the current state of the specified task. Maps FreeRTOS task state to OSAL task state enumeration.

Returns the current state of the specified task.

Note

Requirements: 9.4

Note

Requirements: 9.4

Parameters:

handle – [in] Task handle

Return values:

OSAL_TASK_STATE_READY – Task is ready to run
OSAL_TASK_STATE_RUNNING – Task is currently running
OSAL_TASK_STATE_BLOCKED – Task is blocked
OSAL_TASK_STATE_SUSPENDED – Task is suspended
OSAL_TASK_STATE_DELETED – Task has been deleted or invalid

Returns:

Task state enumeration value

struct osal_task_config_t¶

#include <osal_task.h>

Task configuration structure.

Public Members

const char *name¶: Task name

osal_task_func_t func¶: Task function

void *arg¶: Task argument

uint8_t priority¶: Task priority (0-31)

size_t stack_size¶: Stack size in bytes

Mutex API¶

typedef void *osal_task_handle_t: Forward declaration of task handle type.

typedef void *osal_mutex_handle_t¶: Mutex handle type.

osal_status_t osal_mutex_create(osal_mutex_handle_t *handle)¶

Create a mutex.

Creates a mutex in the baremetal implementation. Mutexes support recursive locking by the same task.

Creates a FreeRTOS mutex using xSemaphoreCreateMutex(). FreeRTOS mutexes support priority inheritance to prevent priority inversion.

Note

Requirements: 5.1, 5.5

Note

Requirements: 5.1, 5.5

Parameters:

handle – [out] Pointer to store mutex handle

Return values:

OSAL_OK – Mutex created successfully
OSAL_ERROR_NULL_POINTER – handle is NULL
OSAL_ERROR_NO_MEMORY – Memory allocation failed

Returns:

OSAL_OK on success, error code otherwise

osal_status_t osal_mutex_delete(osal_mutex_handle_t handle)¶

Delete a mutex.

Deletes a mutex and releases its slot in the control block array.

Deletes a FreeRTOS mutex using vSemaphoreDelete().

Note

Requirements: 5.2

Note

Requirements: 5.2

Parameters:

handle – [in] Mutex handle

Return values:

OSAL_OK – Mutex deleted successfully
OSAL_ERROR_NULL_POINTER – handle is NULL
OSAL_ERROR_INVALID_PARAM – Invalid mutex handle
OSAL_ERROR_BUSY – Mutex is currently locked

Returns:

OSAL_OK on success, error code otherwise

osal_status_t osal_mutex_lock(osal_mutex_handle_t handle, uint32_t timeout_ms)¶

Lock a mutex.

Acquires a mutex with optional timeout. Supports recursive locking by the same task. In baremetal cooperative scheduling, blocking is implemented as busy-wait.

Lock a mutex.

Acquires a FreeRTOS mutex using xSemaphoreTake(). This function blocks until the mutex is acquired or the timeout expires.

Note

Requirements: 5.3, 5.5, 5.6

Note

Requirements: 5.3, 5.5, 5.6

Parameters:

handle – [in] Mutex handle
timeout_ms – [in] Timeout in milliseconds (OSAL_WAIT_FOREVER for infinite wait, OSAL_NO_WAIT for no wait)

Return values:

OSAL_OK – Mutex locked successfully
OSAL_ERROR_NULL_POINTER – handle is NULL
OSAL_ERROR_INVALID_PARAM – Invalid mutex handle
OSAL_ERROR_TIMEOUT – Lock operation timed out
OSAL_ERROR_ISR – Called from ISR context

Returns:

OSAL_OK on success, error code otherwise

osal_status_t osal_mutex_unlock(osal_mutex_handle_t handle)¶

Unlock a mutex.

Releases a mutex. Handles recursive unlock by decrementing the lock count.

Releases a FreeRTOS mutex using xSemaphoreGive().

Note

Requirements: 5.4

Note

Requirements: 5.4

Parameters:

handle – [in] Mutex handle

Return values:

OSAL_OK – Mutex unlocked successfully
OSAL_ERROR_NULL_POINTER – handle is NULL
OSAL_ERROR_INVALID_PARAM – Invalid mutex handle
OSAL_ERROR – Mutex not owned by current task

Returns:

OSAL_OK on success, error code otherwise

osal_task_handle_t osal_mutex_get_owner(osal_mutex_handle_t handle)¶

Get mutex owner task.

Returns the task handle of the task that currently holds the mutex. Uses xSemaphoreGetMutexHolder() FreeRTOS API.

Returns the task handle of the task that currently holds the mutex.

Note

Requirements: 10.1

Note

Requirements: 10.1

Note

Requirements: 10.1

Parameters:

handle – [in] Mutex handle

Return values:

NULL – Mutex is not locked or handle is invalid
non-NULL – Task handle of the mutex owner

Returns:

Owner task handle, or NULL if not locked or invalid handle

bool osal_mutex_is_locked(osal_mutex_handle_t handle)¶

Check if mutex is locked.

Returns true if the mutex is currently held by any task. Uses xSemaphoreGetMutexHolder() to check ownership.

Returns true if the mutex is currently held by any task.

Note

Requirements: 10.2

Note

Requirements: 10.2

Note

Requirements: 10.2

Parameters:

handle – [in] Mutex handle

Return values:

true – Mutex is currently locked
false – Mutex is not locked or handle is invalid

Returns:

true if locked, false otherwise

Semaphore API¶

typedef void *osal_sem_handle_t¶: Semaphore handle type.

osal_status_t osal_sem_create(uint32_t initial_count, uint32_t max_count, osal_sem_handle_t *handle)¶

Create a semaphore.

Creates a counting semaphore with the specified initial and maximum count values.

Create a semaphore.

Creates a FreeRTOS counting semaphore with the specified initial and maximum count values.

Note

Requirements: 6.1, 6.2

Note

Requirements: 6.1, 6.2

Parameters:

initial_count – [in] Initial count value
max_count – [in] Maximum count value
handle – [out] Pointer to store semaphore handle

Return values:

OSAL_OK – Semaphore created successfully
OSAL_ERROR_NULL_POINTER – handle is NULL
OSAL_ERROR_INVALID_PARAM – initial_count > max_count or max_count is zero
OSAL_ERROR_NO_MEMORY – Memory allocation failed

Returns:

OSAL_OK on success, error code otherwise

osal_status_t osal_sem_create_binary(uint32_t initial, osal_sem_handle_t *handle)¶

Create a binary semaphore.

Creates a binary semaphore with maximum count of 1.

Creates a FreeRTOS binary semaphore using xSemaphoreCreateBinary(). Binary semaphores have a maximum count of 1.

Note

Requirements: 6.1

Note

Requirements: 6.1

Parameters:

initial – [in] Initial value (0 or 1)
handle – [out] Pointer to store semaphore handle

Return values:

OSAL_OK – Semaphore created successfully
OSAL_ERROR_NULL_POINTER – handle is NULL
OSAL_ERROR_INVALID_PARAM – initial > 1
OSAL_ERROR_NO_MEMORY – Memory allocation failed

Returns:

OSAL_OK on success, error code otherwise

osal_status_t osal_sem_create_counting(uint32_t max_count, uint32_t initial, osal_sem_handle_t *handle)¶

Create a counting semaphore.

Creates a counting semaphore with specified maximum count.

Creates a FreeRTOS counting semaphore using xSemaphoreCreateCounting().

Note

Requirements: 6.2

Note

Requirements: 6.2

Parameters:

max_count – [in] Maximum count value
initial – [in] Initial count value
handle – [out] Pointer to store semaphore handle

Return values:

OSAL_OK – Semaphore created successfully
OSAL_ERROR_NULL_POINTER – handle is NULL
OSAL_ERROR_INVALID_PARAM – initial > max_count or max_count is zero
OSAL_ERROR_NO_MEMORY – Memory allocation failed

Returns:

OSAL_OK on success, error code otherwise

osal_status_t osal_sem_delete(osal_sem_handle_t handle)¶

Delete a semaphore.

Deletes a semaphore and releases its slot in the control block array.

Deletes a FreeRTOS semaphore using vSemaphoreDelete().

Note

Requirements: 6.3

Note

Requirements: 6.3

Parameters:

handle – [in] Semaphore handle

Return values:

OSAL_OK – Semaphore deleted successfully
OSAL_ERROR_NULL_POINTER – handle is NULL
OSAL_ERROR_INVALID_PARAM – Invalid semaphore handle

Returns:

OSAL_OK on success, error code otherwise

osal_status_t osal_sem_take(osal_sem_handle_t handle, uint32_t timeout_ms)¶

Take (wait for) a semaphore.

Waits for a semaphore to become available. In baremetal cooperative scheduling, blocking is implemented as busy-wait with timeout.

Take (wait for) a semaphore.

Waits for a FreeRTOS semaphore using xSemaphoreTake(). This function blocks until the semaphore is available or the timeout expires.

Note

Requirements: 6.4

Note

Requirements: 6.4

Parameters:

handle – [in] Semaphore handle
timeout_ms – [in] Timeout in milliseconds (OSAL_WAIT_FOREVER for infinite wait, OSAL_NO_WAIT for no wait)

Return values:

OSAL_OK – Semaphore taken successfully
OSAL_ERROR_NULL_POINTER – handle is NULL
OSAL_ERROR_INVALID_PARAM – Invalid semaphore handle
OSAL_ERROR_TIMEOUT – Take operation timed out
OSAL_ERROR_ISR – Called from ISR context with blocking timeout

Returns:

OSAL_OK on success, error code otherwise

osal_status_t osal_sem_give(osal_sem_handle_t handle)¶

Give (signal) a semaphore.

Signals a semaphore by incrementing its count up to the maximum value.

Signals a FreeRTOS semaphore using xSemaphoreGive().

Note

Requirements: 6.5

Note

Requirements: 6.5

Parameters:

handle – [in] Semaphore handle

Return values:

OSAL_OK – Semaphore given successfully
OSAL_ERROR_NULL_POINTER – handle is NULL
OSAL_ERROR_INVALID_PARAM – Invalid semaphore handle
OSAL_ERROR_FULL – Semaphore count at maximum

Returns:

OSAL_OK on success, error code otherwise

osal_status_t osal_sem_give_from_isr(osal_sem_handle_t handle)¶

Give (signal) a semaphore from ISR.

Same as osal_sem_give for baremetal implementation since there is no separate ISR-safe API needed.

Give (signal) a semaphore from ISR.

Signals a FreeRTOS semaphore from an interrupt service routine using xSemaphoreGiveFromISR(). This function handles the higher priority task woken flag and triggers a context switch if needed.

Note

This function is safe to call from interrupt context

Note

Requirements: 6.6

Note

Requirements: 6.6

Parameters:

handle – [in] Semaphore handle

Return values:

OSAL_OK – Semaphore given successfully
OSAL_ERROR_NULL_POINTER – handle is NULL
OSAL_ERROR_INVALID_PARAM – Invalid semaphore handle
OSAL_ERROR_FULL – Semaphore count at maximum

Returns:

OSAL_OK on success, error code otherwise

uint32_t osal_sem_get_count(osal_sem_handle_t handle)¶

Get semaphore current count.

Returns the current count of the semaphore using uxSemaphoreGetCount() FreeRTOS API.

Returns the current count of the semaphore.

Note

Requirements: 10.3

Note

Requirements: 10.3

Note

Requirements: 10.3

Parameters:: handle – [in] Semaphore handle
Returns:: Current count, or 0 if handle is invalid

osal_status_t osal_sem_reset(osal_sem_handle_t handle, uint32_t count)¶

Reset semaphore to specified count.

Resets the semaphore count to the specified value. This is done by taking all available counts and then giving the semaphore the specified number of times.

Resets the semaphore count to the specified value.

Note

Requirements: 10.4

Note

Requirements: 10.4

Note

This operation is not atomic and should be used with care in multi-threaded environments.

Note

Requirements: 10.4

Parameters:

handle – [in] Semaphore handle
count – [in] New count value

Return values:

OSAL_OK – Count reset successfully
OSAL_ERROR_NULL_POINTER – handle is NULL
OSAL_ERROR_INVALID_PARAM – count exceeds max_count or invalid handle

Returns:

OSAL_OK on success, error code otherwise

Queue API¶

enum osal_queue_mode_t¶

Queue mode enumeration.

Values:

enumerator OSAL_QUEUE_MODE_NORMAL¶: Normal mode - block when full

enumerator OSAL_QUEUE_MODE_OVERWRITE¶: Overwrite mode - overwrite oldest

typedef void *osal_queue_handle_t¶: Queue handle type.

osal_status_t osal_queue_create(size_t item_size, size_t item_count, osal_queue_handle_t *handle)¶

Create a message queue.

Creates a FIFO message queue with the specified item size and capacity. Uses a fixed-size buffer for storage.

Creates a FreeRTOS queue using xQueueCreate(). The queue can hold item_count items, each of item_size bytes.

Note

Requirements: 7.1

Note

Requirements: 7.1

Parameters:

item_size – [in] Size of each item in bytes
item_count – [in] Maximum number of items
handle – [out] Pointer to store queue handle

Return values:

OSAL_OK – Queue created successfully
OSAL_ERROR_NULL_POINTER – handle is NULL
OSAL_ERROR_INVALID_PARAM – item_size or item_count is zero
OSAL_ERROR_NO_MEMORY – Memory allocation failed

Returns:

OSAL_OK on success, error code otherwise

osal_status_t osal_queue_delete(osal_queue_handle_t handle)¶

Delete a message queue.

Deletes a queue and releases its slot in the control block array.

Deletes a FreeRTOS queue using vQueueDelete().

Note

Requirements: 7.2

Note

Requirements: 7.2

Parameters:

handle – [in] Queue handle

Return values:

OSAL_OK – Queue deleted successfully
OSAL_ERROR_NULL_POINTER – handle is NULL
OSAL_ERROR_INVALID_PARAM – Invalid queue handle

Returns:

OSAL_OK on success, error code otherwise

osal_status_t osal_queue_send(osal_queue_handle_t handle, const void *item, uint32_t timeout_ms)¶

Send item to queue.

Sends an item to the back of a FreeRTOS queue using xQueueSend(). This function blocks until space is available or the timeout expires.

Note

Requirements: 7.3

Parameters:

handle – [in] Queue handle
item – [in] Pointer to item to send
timeout_ms – [in] Timeout in milliseconds (OSAL_WAIT_FOREVER for infinite wait, OSAL_NO_WAIT for no wait)

Return values:

OSAL_OK – Item sent successfully
OSAL_ERROR_NULL_POINTER – handle or item is NULL
OSAL_ERROR_INVALID_PARAM – Invalid queue handle
OSAL_ERROR_TIMEOUT – Send operation timed out
OSAL_ERROR_FULL – Queue is full (with OSAL_NO_WAIT)

Returns:

OSAL_OK on success, error code otherwise

osal_status_t osal_queue_send_front(osal_queue_handle_t handle, const void *item, uint32_t timeout_ms)¶

Send item to front of queue.

Sends an item to the front of a FreeRTOS queue using xQueueSendToFront(). This function blocks until space is available or the timeout expires.

Note

Requirements: 7.4

Parameters:

handle – [in] Queue handle
item – [in] Pointer to item to send
timeout_ms – [in] Timeout in milliseconds (OSAL_WAIT_FOREVER for infinite wait, OSAL_NO_WAIT for no wait)

Return values:

OSAL_OK – Item sent successfully
OSAL_ERROR_NULL_POINTER – handle or item is NULL
OSAL_ERROR_INVALID_PARAM – Invalid queue handle
OSAL_ERROR_TIMEOUT – Send operation timed out
OSAL_ERROR_FULL – Queue is full (with OSAL_NO_WAIT)

Returns:

OSAL_OK on success, error code otherwise

osal_status_t osal_queue_receive(osal_queue_handle_t handle, void *item, uint32_t timeout_ms)¶

Receive item from queue.

Receives an item from a FreeRTOS queue using xQueueReceive(). This function blocks until an item is available or the timeout expires.

Note

Requirements: 7.5

Parameters:

handle – [in] Queue handle
item – [out] Pointer to store received item
timeout_ms – [in] Timeout in milliseconds (OSAL_WAIT_FOREVER for infinite wait, OSAL_NO_WAIT for no wait)

Return values:

OSAL_OK – Item received successfully
OSAL_ERROR_NULL_POINTER – handle or item is NULL
OSAL_ERROR_INVALID_PARAM – Invalid queue handle
OSAL_ERROR_TIMEOUT – Receive operation timed out
OSAL_ERROR_EMPTY – Queue is empty (with OSAL_NO_WAIT)

Returns:

OSAL_OK on success, error code otherwise

osal_status_t osal_queue_peek(osal_queue_handle_t handle, void *item)¶

Peek item from queue (without removing)

Peeks at the front item of a FreeRTOS queue using xQueuePeek(). The item is copied to the output buffer but remains in the queue.

Note

Requirements: 7.6

Parameters:

handle – [in] Queue handle
item – [out] Pointer to store peeked item

Return values:

OSAL_OK – Item peeked successfully
OSAL_ERROR_NULL_POINTER – handle or item is NULL
OSAL_ERROR_INVALID_PARAM – Invalid queue handle
OSAL_ERROR_EMPTY – Queue is empty

Returns:

OSAL_OK on success, error code otherwise

size_t osal_queue_get_count(osal_queue_handle_t handle)¶

Get number of items in queue.

Returns the number of items currently in the queue using uxQueueMessagesWaiting().

Note

Requirements: 7.7

Parameters:: handle – [in] Queue handle
Returns:: Number of items in queue, or 0 if handle is invalid

bool osal_queue_is_empty(osal_queue_handle_t handle)¶

Check if queue is empty.

Parameters:

handle – [in] Queue handle

Return values:

true – Queue is empty or handle is invalid
false – Queue contains items

Returns:

true if empty, false otherwise

bool osal_queue_is_full(osal_queue_handle_t handle)¶

Check if queue is full.

Checks if the queue has reached its capacity using uxQueueSpacesAvailable().

Parameters:

handle – [in] Queue handle

Return values:

true – Queue is full
false – Queue has available space or handle is invalid

Returns:

true if full, false otherwise

osal_status_t osal_queue_send_from_isr(osal_queue_handle_t handle, const void *item)¶

Send item to queue from ISR.

Sends an item to a FreeRTOS queue from an interrupt service routine using xQueueSendFromISR(). This function handles the higher priority task woken flag and triggers a context switch if needed.

Note

This function is safe to call from interrupt context

Note

Requirements: 7.8

Parameters:

handle – [in] Queue handle
item – [in] Pointer to item to send

Return values:

OSAL_OK – Item sent successfully
OSAL_ERROR_NULL_POINTER – handle or item is NULL
OSAL_ERROR_INVALID_PARAM – Invalid queue handle
OSAL_ERROR_FULL – Queue is full

Returns:

OSAL_OK on success, error code otherwise

osal_status_t osal_queue_receive_from_isr(osal_queue_handle_t handle, void *item)¶

Receive item from queue from ISR.

Receives an item from a FreeRTOS queue from an interrupt service routine using xQueueReceiveFromISR(). This function handles the higher priority task woken flag and triggers a context switch if needed.

Note

This function is safe to call from interrupt context

Note

Requirements: 7.9

Parameters:

handle – [in] Queue handle
item – [out] Pointer to store received item

Return values:

OSAL_OK – Item received successfully
OSAL_ERROR_NULL_POINTER – handle or item is NULL
OSAL_ERROR_INVALID_PARAM – Invalid queue handle
OSAL_ERROR_EMPTY – Queue is empty

Returns:

OSAL_OK on success, error code otherwise

size_t osal_queue_get_available_space(osal_queue_handle_t handle)¶

Get available space in queue.

Returns the number of free slots in the queue using uxQueueSpacesAvailable().

Returns the number of free slots in the queue.

Note

Requirements: 8.1

Note

Requirements: 8.1

Note

Requirements: 8.1

Parameters:: handle – [in] Queue handle
Returns:: Number of free slots, or 0 if handle is invalid

osal_status_t osal_queue_reset(osal_queue_handle_t handle)¶

Reset queue (clear all items)

Resets the queue to its empty state using xQueueReset(). All items in the queue are discarded.

Resets the queue to its empty state. All items in the queue are discarded.

Note

Requirements: 8.2

Note

Requirements: 8.2

Note

Requirements: 8.2

Parameters:

handle – [in] Queue handle

Return values:

OSAL_OK – Queue reset successfully
OSAL_ERROR_NULL_POINTER – handle is NULL
OSAL_ERROR_INVALID_PARAM – Invalid queue handle

Returns:

OSAL_OK on success, error code otherwise

osal_status_t osal_queue_set_mode(osal_queue_handle_t handle, osal_queue_mode_t mode)¶

Set queue mode.

Sets the queue operating mode. In FreeRTOS, the standard queue does not support overwrite mode directly. This function is provided for API compatibility but overwrite mode requires using xQueueOverwrite() for single-item queues. For multi-item queues, overwrite mode is not natively supported.

Sets the queue operating mode. In native platform, this function accepts the mode for API compatibility but the actual overwrite behavior would need to be implemented in the send function.

Note

Requirements: 8.3

Note

Requirements: 8.3 FreeRTOS limitation: Overwrite mode only works for single-item queues using xQueueOverwrite().

Note

Requirements: 8.3

Parameters:

handle – [in] Queue handle
mode – [in] Queue mode (normal or overwrite)

Return values:

OSAL_OK – Mode set successfully
OSAL_ERROR_NULL_POINTER – handle is NULL
OSAL_ERROR_INVALID_PARAM – Invalid queue handle or mode

Returns:

OSAL_OK on success, error code otherwise

osal_status_t osal_queue_peek_from_isr(osal_queue_handle_t handle, void *item)¶

Peek item from queue in ISR context.

Peeks at the front item of a FreeRTOS queue from an interrupt service routine using xQueuePeekFromISR(). The item is copied to the output buffer but remains in the queue.

In native platform, ISR context is the same as normal context. This function peeks at the front item without removing it.

Note

This function is safe to call from interrupt context

Note

Requirements: 8.5

Note

Requirements: 8.5

Note

Requirements: 8.5

Parameters:

handle – [in] Queue handle
item – [out] Pointer to store peeked item

Return values:

OSAL_OK – Item peeked successfully
OSAL_ERROR_NULL_POINTER – handle or item is NULL
OSAL_ERROR_INVALID_PARAM – Invalid queue handle
OSAL_ERROR_EMPTY – Queue is empty

Returns:

OSAL_OK on success, error code otherwise

Nexus Embedded Platform

Navigation

Related Topics

OSAL API Reference¶

OSAL Definitions¶

Task API¶

Mutex API¶

Semaphore API¶

Queue API¶