Operating System Abstraction Layer (OSAL)¶
Overview¶
The OSAL has been developed to allow AMC source to be agnostic to any target operating system, allowing target OS to be configured at compilation via the cmake build process (see - Profiles and CMake build process).
A common API has been developed, and used throughout AMC source code. OS specific source implementations of the OSAL prevent any code changes throughout AMC when porting to a new OS. Two implementations of the OSAL are currently available with AMC (Linux and FreeRTOS).
API¶
General¶
Get OS Version¶
iOSAL_GetOsVersion
/**
* @brief This function will return OS type and version information for the OSAL
* implementation being used.
*
* @param pcOs Pointer to OS Name buffer.
* @param ucVersionMajor Pointer to uint8_t holding OS version major.
* @param ucVersionMinor Pointer to uint8_t holding OS version minor.
* @param ucVersionBuild Pointer to uint8_t holding OS version build.
*
* @return OSAL_ERRORS_NONE no errors, call was successful
* OSAL_ERRORS_PARAMS invalid parameters passed in to function
* OSAL_ERRORS_OS_IMPLEMENTATION error code returned from os implementation
*
*/
int iOSAL_GetOsVersion( char pcOs[ OSAL_OS_NAME_LEN ],
uint8_t* pucVersionMajor,
uint8_t* pucVersionMinor,
uint8_t* pucVersionBuild );
Scheduler APIs¶
Start RTOS scheduler¶
iOSAL_StartOS
/**
* @brief This function will create an initial task, and then start the RTOS Scheduler.
*
* @param iRoundRobinEnabled Flag indicating if round robin scheduling should be used.
* If TRUE, Round-Robin is enabled. If FALSE, Round-Robin is disabled.
* @param ppvTaskHandle Pointer-to-pointer that will be cast to appropriate OS Task Handle data type
* @param pvStartTask Pointer to Start Task function
* @param usStartTaskStackSize The number of bytes to allocate for use as the start task's stack.
* @param ulStartTaskPriority The priority at which the the created start task will execute
*
* @return OSAL_ERRORS_NONE no errors, call was successful
* OSAL_ERRORS_PARAMS invalid parameters passed in to function
* OSAL_ERRORS_INVALID_HANDLE invalid / un-initialised handle passed into to function
* OSAL_ERRORS_OS_IMPLEMENTATION error code returned from os implementation
*
* @note If successful, this function should never return.
*/
int iOSAL_StartOS( int iRoundRobinEnabled,
void** ppvTaskHandle,
void ( *pvStartTask )( void ),
uint16_t usStartTaskStackSize,
uint32_t ulStartTaskPriority );
Get Tick count since scheduler started¶
ulOSAL_GetUptimeTicks
/**
* @brief Returns tick count since OS was initialised.
*
* @return Count of ticks since OS was initialised.
*
* @note This function cannot be called from an ISR.
*/
uint32_t ulOSAL_GetUptimeTicks( void );
Get ms count since scheduler started¶
ulOSAL_GetUptimeMs
/**
* @brief Returns ms count since OS was initialised.
*
* @return Ms since OS was initialised.
*
* @note This function cannot be called from an ISR.
*/
uint32_t ulOSAL_GetUptimeMs( void );
Task APIs¶
Create OSAL Task¶
iOSAL_Task_Create
/**
* @brief Create a new OSAL task.
*
* @param ppvTaskHandle Pointer-to-pointer that will be cast to appropriate OS Task Handle data type
* @param pvTaskFunction Pointer to Task function
* @param usTaskStackSize The number of bytes to allocate for use as the task's stack.
* @param pvTaskParam The value to be passed as the parameter to the Task function
* @param ulTaskPriority The priority at which the the created task will execute
* @param pcTaskName Descriptive name for the task
*
* @return OSAL_ERRORS_NONE no errors, call was successful
* OSAL_ERRORS_INVALID_HANDLE invalid / un-initialised handle passed into to function
* OSAL_ERRORS_OS_IMPLEMENTATION error code returned from os implementation
* OSAL_ERRORS_OS_NOT_STARTED OS has not been started
*
* @note The Task Handle must be initialised as NULL.
*/
int iOSAL_Task_Create( void** ppvTaskHandle,
void ( *pvTaskFunction )( void* pvTaskParam ),
uint16_t usTaskStackSize,
void* pvTaskParam,
uint32_t ulTaskPriority,
const char* pcTaskName );
Delete OSAL Task¶
iOSAL_Task_Delete
/**
* @brief Remove OSAL task from RTOS Kernal.
*
* @param ppvTaskHandle Pointer-to-pointer that will be cast to appropriate OS Task Handle data type
*
* @return OSAL_ERRORS_NONE no errors, call was successful
* OSAL_ERRORS_INVALID_HANDLE invalid / un-initialised handle passed into to function
* OSAL_ERRORS_OS_NOT_STARTED OS has not been started
*
* @note pvTaskHandle must have been previously initialised with iOSAL_Task_Create.
* If successful, the handle will be reset to NULL.
*/
int iOSAL_Task_Delete( void** ppvTaskHandle );
Suspend OSAL Task¶
iOSAL_Task_Suspend
/**
* @brief Suspend any OSAL task.
*
* @param pvTaskHandle Pointer that will be cast to appropriate OS Task Handle data type
*
* @return OSAL_ERRORS_NONE no errors, call was successful
* OSAL_ERRORS_INVALID_HANDLE invalid / un-initialised handle passed into to function
* OSAL_ERRORS_OS_NOT_STARTED OS has not been started
*
* @note Setting pvTaskHandle NULL, should cause calling task to be suspended
*/
int iOSAL_Task_Suspend( void* pvTaskHandle );
Resume OSAL Task¶
iOSAL_Task_Resume
/**
* @brief Resume any OSAL task.
*
* @param pvTaskHandle Pointer that will be cast to appropriate OS Task Handle data type
*
* @return OSAL_ERRORS_NONE no errors, call was successful
* OSAL_ERRORS_INVALID_HANDLE invalid / un-initialised handle passed into to function
* OSAL_ERRORS_OS_NOT_STARTED OS has not been started
*
* @note Setting pvTaskHandle NULL, should cause calling task to be resumed
*/
int iOSAL_Task_Resume( void* pvTaskHandle );
OSAL Task Sleep (Ticks)¶
iOSAL_Task_SleepTicks
/**
* @brief Delay a task for a given number of ticks.
*
* @param ulSleepTicks The amount of time, in tick periods, that the calling task should block.
*
* @return OSAL_ERRORS_NONE no errors, call was successful
* OSAL_ERRORS_PARAMS invalid parameters passed in to function
* OSAL_ERRORS_OS_IMPLEMENTATION error code returned from os implementation
* OSAL_ERRORS_OS_NOT_STARTED OS has not been started
*
*/
int iOSAL_Task_SleepTicks( uint32_t ulSleepTicks );
OSAL Task Sleep (ms)¶
iOSAL_Task_SleepMs
/**
* @brief Delay a task for a given number of ms.
*
* @param ulSleepMs The amount of time, in ms, that the calling task should block.
*
* @return OSAL_ERRORS_NONE no errors, call was successful
* OSAL_ERRORS_PARAMS invalid parameters passed in to function
* OSAL_ERRORS_OS_IMPLEMENTATION error code returned from os implementation
* OSAL_ERRORS_OS_NOT_STARTED OS has not been started
*
*/
int iOSAL_Task_SleepMs( uint32_t ulSleepMs );
Semaphore APIs¶
Create OSAL Semaphore¶
iOSAL_Semaphore_Create
/**
* @brief Creates a binary or counting semaphore, and sets OS Semaphore Handle by which the semaphore can be referenced.
*
* @param ppvSemHandle Pointer-to-pointer that will be cast to appropriate OS Semaphore Handle data type.
* @param ullCount The initial count value assigned to the semaphore when it is created.
* @param ullBucket The maximum count value that can be reached.
* @param pcSemName Descriptive name for the semaphore.
*
* @return OSAL_ERRORS_NONE no errors, call was successful
* OSAL_ERRORS_OS_IMPLEMENTATION error code returned from os implementation
*
* @note The Semaphore Handle must be initialised as NULL.
* To create a binary semaphore, set ullBucket to 1.
*/
int iOSAL_Semaphore_Create( void** ppvSemHandle,
uint32_t ullCount,
uint32_t ullBucket,
const char* pcSemName );
Delete OSAL Semaphore¶
iOSAL_Semaphore_Destroy
/**
* @brief Deletes the binary or counting semaphore, to which the handle refers.
*
* @param ppvSemHandle Pointer-to-pointer that will be cast to appropriate OS Semaphore Handle data type.
*
* @return OSAL_ERRORS_NONE no errors, call was successful
* OSAL_ERRORS_INVALID_HANDLE invalid / un-initialised handle passed into to function
*
* @note If successful, the handle will be reset to NULL.
*/
int iOSAL_Semaphore_Destroy( void** ppvSemHandle );
Pend to OSAL Semaphore¶
iOSAL_Semaphore_Pend
/**
* @brief Pends to / obtains a previously created semaphore, to which the handle refers.
*
* @param pvSemHandle Pointer that will be cast to appropriate OS Semaphore Handle data type.
* @param ulTimeoutMs Timeout in ms to wait for a semaphore to become available.
*
* @return OSAL_ERRORS_NONE no errors, call was successful
* OSAL_ERRORS_PARAMS invalid parameters passed in to function
* OSAL_ERRORS_INVALID_HANDLE invalid / un-initialised handle passed into to function
* OSAL_ERRORS_OS_IMPLEMENTATION error code returned from os implementation
*
*/
int iOSAL_Semaphore_Pend( void* pvSemHandle, uint32_t ulTimeoutMs );
Post to OSAL Semaphore¶
iOSAL_Semaphore_Post
/**
* @brief Posts / Releases a previously created semaphore, to which the handle refers.
*
* @param pvSemHandle Pointer that will be cast to appropriate OS Semaphore Handle data type
*
* @return OSAL_ERRORS_NONE no errors, call was successful
* OSAL_ERRORS_INVALID_HANDLE invalid / un-initialised handle passed into to function
* OSAL_ERRORS_OS_IMPLEMENTATION error code returned from os implementation
*
* @note If calling from an ISR, iOSAL_Semaphore_PostFromISR is recommended.
*/
int iOSAL_Semaphore_Post( void* pvSemHandle );
Post to OSAL Semaphore (From ISR)¶
iOSAL_Semaphore_PostFromISR
/**
* @brief A version of iOSAL_Semaphore_Post() that can be called from an ISR.
*
* @param pvSemHandle Pointer that will be cast to appropriate OS Semaphore Handle data type
*
* @return OSAL_ERRORS_NONE no errors, call was successful
* OSAL_ERRORS_INVALID_HANDLE invalid / un-initialised handle passed into to function
* OSAL_ERRORS_OS_IMPLEMENTATION error code returned from os implementation
*
*/
int iOSAL_Semaphore_PostFromISR( void* pvSemHandle );
Mutex APIs¶
Create OSAL Mutex¶
iOSAL_Mutex_Create
/**
* @brief Creates a Mutex, and sets OS Mutex Handle by which the Mutex can be referenced.
*
* @param ppvMutexHandle Pointer-to-pointer that will be cast to appropriate OS Mutex Handle data type
* @param pcMutexName Descriptive name for the Mutex
*
* @return OSAL_ERRORS_NONE no errors, call was successful
* OSAL_ERRORS_OS_IMPLEMENTATION error code returned from os implementation
*
* @note The Mutex Handle must be initialised as NULL.
*/
int iOSAL_Mutex_Create( void** ppvMutexHandle,
const char* pcMutexName );
Delete OSAL Mutex¶
iOSAL_Mutex_Destroy
/**
* @brief Deletes a Mutex, to which the handle refers.
*
* @param ppvMutexHandle Pointer-to-pointer that will be cast to appropriate OS Mutex Handle data type
*
* @return OSAL_ERRORS_NONE no errors, call was successful
* OSAL_ERRORS_INVALID_HANDLE invalid / un-initialised handle passed into to function
* OSAL_ERRORS_OS_IMPLEMENTATION error code returned from os implementation
*
* @note If successful, the handle will be reset to NULL.
*/
int iOSAL_Mutex_Destroy( void** ppvMutexHandle );
Take OSAL Mutex¶
iOSAL_Mutex_Take
/**
* @brief Obtains a previously created Mutex, to which the handle refers.
*
* @param pvMutexHandle Pointer that will be cast to appropriate OS Mutex Handle data type.
* @param ulTimeoutMs Timeout in ms to wait for a Mutex to become available.
*
* @return OSAL_ERRORS_NONE no errors, call was successful
* OSAL_ERRORS_PARAMS invalid parameters passed in to function
* OSAL_ERRORS_INVALID_HANDLE invalid / un-initialised handle passed into to function
* OSAL_ERRORS_OS_IMPLEMENTATION error code returned from os implementation
*
*/
int iOSAL_Mutex_Take( void* pvMutexHandle,
uint32_t ulTimeoutMs );
Release OSAL Mutex¶
iOSAL_Mutex_Release
/**
* @brief Releases a previously created Mutex, to which the handle refers.
*
* @param pvMutexHandle Pointer that will be cast to appropriate OS Mutex Handle data type.
*
* @return OSAL_ERRORS_NONE no errors, call was successful
* OSAL_ERRORS_INVALID_HANDLE invalid / un-initialised handle passed into to function
* OSAL_ERRORS_OS_IMPLEMENTATION error code returned from os implementation
*
*/
int iOSAL_Mutex_Release( void* pvMutexHandle );
Mailbox APIs¶
Create OSAL Mailbox¶
iOSAL_MBox_Create
/**
* @brief Creates a new MailBox, and sets OS MailBox Handle by which the MailBox can be referenced.
*
* @param ppvMBoxHandle Pointer-to-pointer that will be cast to appropriate OS MailBox Handle data type.
* @param ulMBoxLength The max number of items the MailBox can hold.
* @param ulItemSize Size (Bytes) of each item in the MailBox.
* @param pcMBoxName Descriptive name for the MailBox.
*
* @return OSAL_ERRORS_NONE no errors, call was successful
* OSAL_ERRORS_OS_IMPLEMENTATION error code returned from os implementation
*
* @note The MailBox Handle must be initialised as NULL.
*/
int iOSAL_MBox_Create( void** ppvMBoxHandle,
uint32_t ulMBoxLength,
uint32_t ulItemSize,
const char* pcMBoxName );
Delete OSAL Mailbox¶
iOSAL_MBox_Destroy
/**
* @brief Resets a MailBox, to which the handle refers.
*
* @param ppvMBoxHandle Pointer-to-pointer that will be cast to appropriate OS MailBox Handle data type.
*
* @return OSAL_ERRORS_NONE no errors, call was successful
* OSAL_ERRORS_INVALID_HANDLE invalid / un-initialised handle passed into to function
* OSAL_ERRORS_OS_IMPLEMENTATION error code returned from os implementation
*
* @note If successful, the handle will be reset to NULL.
*/
int iOSAL_MBox_Destroy( void** ppvMBoxHandle );
Pend to OSAL Mailbox¶
iOSAL_MBox_Pend
/**
* @brief Recieve an item from a message Mailbox, to which the handle refers.
*
* @param pvMBoxHandle Pointer that will be cast to appropriate OS Mailbox Handle data type.
* @param pvMBoxBuffer A pointer to the buffer into which the received item will be copied.
* @param ulTimeoutMs The maximum amount of time (ms) the task should block waiting for an item to receive.
*
* @return OSAL_ERRORS_NONE no errors, call was successful
* OSAL_ERRORS_PARAMS invalid parameters passed in to function
* OSAL_ERRORS_INVALID_HANDLE invalid / un-initialised handle passed into to function
* OSAL_ERRORS_OS_IMPLEMENTATION error code returned from os implementation
*
*/
int iOSAL_MBox_Pend( void* pvMBoxHandle,
void* pvMBoxBuffer,
uint32_t ulTimeoutMs );
Post to OSAL Mailbox¶
iOSAL_MBox_Post
/**
* @brief Posts an item onto a MailBox, to which the handle refers.
*
* @param pvMBoxHandle Pointer that will be cast to appropriate OS MailBox Handle data type.
* @param pvMBoxItem A pointer to the item that is to be placed on the mailBox.
* @param ulTimeoutMs The maximum amount of time (ms) the task should block waiting for space to become available on the mailBox.
*
* @return OSAL_ERRORS_NONE no errors, call was successful
* OSAL_ERRORS_PARAMS invalid parameters passed in to function
* OSAL_ERRORS_INVALID_HANDLE invalid / un-initialised handle passed into to function
* OSAL_ERRORS_OS_IMPLEMENTATION error code returned from os implementation
*
* @note If calling from an ISR, iOSAL_MBox_PostFromISR is recommended.
*/
int iOSAL_MBox_Post( void* pvMBoxHandle,
void* pvMBoxItem,
uint32_t ulTimeoutMs );
Post to OSAL Mailbox (From ISR)¶
iOSAL_MBox_PostFromISR
/**
* @brief A version of iOSAL_MBox_Post() that can be called from an ISR.
*
* @param pvMBoxHandle Pointer that will be cast to appropriate OS MailBox Handle data type.
* @param pvMBoxItem A pointer to the item that is to be placed on the mailBox.
*
* @return OSAL_ERRORS_NONE no errors, call was successful
* OSAL_ERRORS_PARAMS invalid parameters passed in to function
* OSAL_ERRORS_INVALID_HANDLE invalid / un-initialised handle passed into to function
* OSAL_ERRORS_OS_IMPLEMENTATION error code returned from os implementation
*
*/
int iOSAL_MBox_PostFromISR( void* pvMBoxHandle, void* pvMBoxItem );
Event APIs¶
Create OSAL Event Group¶
iOSAL_EventFlag_Create
/**
* @brief Creates a new Event Flag group, and sets OS Handle by which the Event Flag group can be referenced.
*
* @param ppvEventFlagHandle Pointer-to-pointer that will be cast to appropriate OS Event Flag Handle data type.
* @param pcEventFlagName Descriptive name for the MailBox.
*
* @return OSAL_ERRORS_NONE no errors, call was successful
* OSAL_ERRORS_OS_IMPLEMENTATION error code returned from os implementation
*
* @note The Event Flag Handle must be initialised as NULL.
*/
int iOSAL_EventFlag_Create( void** ppvEventFlagHandle, const char* pcEventFlagName );
Delete OSAL Event Group¶
iOSAL_EventFlag_Destroy
/**
* @brief Deletes an Event Flag group, to which the handle refers.
*
* @param pvEventFlagHandle Pointer that will be cast to appropriate OS Event Flag Handle data type.
*
* @return OSAL_ERRORS_NONE no errors, call was successful
* OSAL_ERRORS_INVALID_HANDLE invalid / un-initialised handle passed into to function
* OSAL_ERRORS_OS_IMPLEMENTATION error code returned from os implementation
*
* @note If successful, the handle will be reset to NULL.
*/
int iOSAL_EventFlag_Destroy( void** ppvEventFlagHandle );
Pend to OSAL Event Group¶
iOSAL_EventFlag_Pend
/**
* @brief Pend task to Wait for a bit or group of bits to become set.
*
* @param pvEventFlagHandle Pointer that will be cast to appropriate OS Event Flag Handle data type.
* @param ulFlagWait Bitwise value to specify the bits to wait on being set or cleared.
* @param ulTimeoutMs The maximum amount of time (ms) the task should block waiting specified bits to be set.
*
* @return OSAL_ERRORS_NONE no errors, call was successful
* OSAL_ERRORS_PARAMS invalid parameters passed in to function
* OSAL_ERRORS_INVALID_HANDLE invalid / un-initialised handle passed into to function
* OSAL_ERRORS_OS_IMPLEMENTATION error code returned from os implementation
*
* @note This function cannot be called from an ISR.
*/
int iOSAL_EventFlag_Pend( void* pvEventFlagHandle, uint32_t ulFlagWait, uint32_t ulTimeoutMs );
Post to OSAL Event Group¶
iOSAL_EventFlag_Post
/**
* @brief Sets or clears event flag bits, to which the handle refers.
*
* @param pvEventFlagHandle Pointer that will be cast to appropriate OS Event Flag Handle data type.
* @param ulFlagSet Bitwise value to specify the bits to be set or cleared.
*
* @return OSAL_ERRORS_NONE no errors, call was successful
* OSAL_ERRORS_PARAMS invalid parameters passed in to function
* OSAL_ERRORS_INVALID_HANDLE invalid / un-initialised handle passed into to function
* OSAL_ERRORS_OS_IMPLEMENTATION error code returned from os implementation
*
* @note If calling from an ISR, iOSAL_EventFlag_PostFromISR is recommended.
*/
int iOSAL_EventFlag_Post( void* pvEventFlagHandle, uint32_t ulFlagSet );
Post to OSAL Event Group (From ISR)¶
iOSAL_EventFlag_PostFromISR
/**
* @brief A version of iOSAL_EventFlag_Post() that can be called from an ISR.
*
* @param pvEventFlagHandle Pointer that will be cast to appropriate OS Event Flag Handle data type.
* @param ulFlagSet Bitwise value to specify the bits to be set or cleared.
*
* @return OSAL_ERRORS_NONE no errors, call was successful
* OSAL_ERRORS_PARAMS invalid parameters passed in to function
* OSAL_ERRORS_INVALID_HANDLE invalid / un-initialised handle passed into to function
* OSAL_ERRORS_OS_IMPLEMENTATION error code returned from os implementation
*
*/
int iOSAL_EventFlag_PostFromISR( void* pvEventFlagHandle, uint32_t ulFlagSet );
Timer APIs¶
Create OSAL Timer¶
iOSAL_Timer_Create
/**
* @brief Creates a new software timer instance, and sets OS Handle by which the Timer can be referenced.
*
* @param ppvTimerHandle Pointer-to-pointer that will be cast to appropriate OS Timer Handle data type.
* @param xTimerConfig Timer config defining if timer is one-shot or periodic
* @param pvTimerCallback The function to call when the timer expires.
* @param pcTimerName A human readable text name assigned to the timer.
*
* @return OSAL_ERRORS_NONE no errors, call was successful
* OSAL_ERRORS_PARAMS invalid parameters passed in to function
* OSAL_ERRORS_OS_IMPLEMENTATION error code returned from os implementation
*
* @note The Timer Handle must be initialised as NULL.
*/
int iOSAL_Timer_Create( void** ppvTimerHandle,
OSAL_TIMER_CONFIG xTimerConfig,
void ( *pvTimerCallback )( void* pvTimerHandle ),
const char* pcTimerName );
Delete OSAL Timer¶
iOSAL_Timer_Destroy
/**
* @brief Deletes a Timer, to which the handle refers.
*
* @param ppvTimerHandle Pointer-to-pointer that will be cast to appropriate OS Timer Handle data type.
*
* @return OSAL_ERRORS_NONE no errors, call was successful
* OSAL_ERRORS_PARAMS invalid parameters passed in to function
* OSAL_ERRORS_INVALID_HANDLE invalid / un-initialised handle passed into to function
* OSAL_ERRORS_OS_IMPLEMENTATION error code returned from os implementation
*
* @note If successful, the handle will be reset to NULL.
*/
int iOSAL_Timer_Destroy( void** ppvTimerHandle );
Start OSAL Timer¶
iOSAL_Timer_Start
/**
* @brief Starts a Timer, to which the handle refers.
*
* @param pvTimerHandle Pointer that will be cast to appropriate OS Timer Handle data type.
* @param ulDurationMs Number of ms until the timer callback is triggered.
*
* @return OSAL_ERRORS_NONE no errors, call was successful
* OSAL_ERRORS_PARAMS invalid parameters passed in to function
* OSAL_ERRORS_INVALID_HANDLE invalid / un-initialised handle passed into to function
* OSAL_ERRORS_OS_IMPLEMENTATION error code returned from os implementation
*
*/
int iOSAL_Timer_Start( void* pvTimerHandle, uint32_t ulDurationMs );
Stop OSAL Timer¶
iOSAL_Timer_Stop
/**
* @brief Stops a Timer, to which the handle refers.
*
* @param pvTimerHandle Pointer that will be cast to appropriate OS Timer Handle data type.
*
* @return OSAL_ERRORS_NONE no errors, call was successful
* OSAL_ERRORS_PARAMS invalid parameters passed in to function
* OSAL_ERRORS_INVALID_HANDLE invalid / un-initialised handle passed into to function
* OSAL_ERRORS_OS_IMPLEMENTATION error code returned from os implementation
*
*/
int iOSAL_Timer_Stop( void* pvTimerHandle );
Reset OSAL Timer¶
iOSAL_Timer_Reset
/**
* @brief Re-Starts a Timer, to which the handle refers.
*
* @param pvTimerHandle Pointer that will be cast to appropriate OS Timer Handle data type.
* @param ulDurationMs Number of ms until the timer callback is triggered.
*
* @return OSAL_ERRORS_NONE no errors, call was successful
* OSAL_ERRORS_PARAMS invalid parameters passed in to function
* OSAL_ERRORS_INVALID_HANDLE invalid / un-initialised handle passed into to function
* OSAL_ERRORS_OS_IMPLEMENTATION error code returned from os implementation
*
*/
int iOSAL_Timer_Reset( void* pvTimerHandle, uint32_t ulDurationMs );
Interrupt APIs¶
Setup OSAL Interrupt¶
iOSAL_Interrupt_Setup
/**
* @brief Sets up interrupt handler callback with appropriate interrupt ID
*
* @param ucInterruptID Interrupt ID (defined in BSP)
* @param pvInterruptHandler Pointer to interrupt handler callback function.
* @param pvCallBackRef Param to be passed into interrupt handler callback function
*
* @return OSAL_ERRORS_NONE no errors, call was successful
* OSAL_ERRORS_PARAMS invalid parameters passed in to function
* OSAL_ERRORS_OS_IMPLEMENTATION error code returned from os implementation
*
*/
int iOSAL_Interrupt_Setup( uint8_t ucInterruptID,
void ( *pvInterruptHandler )( void* pvCallBackRef ),
void* pvCallBackRef );
Enable OSAL Interrupt¶
iOSAL_Interrupt_Enable
/**
* @brief Enable OSAL interrupts
*
* @param ucInterruptID Interrupt ID (defined in BSP)
*
* @return OSAL_ERRORS_NONE no errors, call was successful
* OSAL_ERRORS_PARAMS invalid parameters passed in to function
* OSAL_ERRORS_OS_IMPLEMENTATION error code returned from os implementation
*
*/
int iOSAL_Interrupt_Enable( uint8_t ucInterruptID );
Disable OSAL Interrupt¶
iOSAL_Interrupt_Disable
/**
* @brief Disable OSAL interrupts
*
* @param ucInterruptID Interrupt ID (defined in BSP)
*
* @return OSAL_ERRORS_NONE no errors, call was successful
* OSAL_ERRORS_PARAMS invalid parameters passed in to function
* OSAL_ERRORS_OS_IMPLEMENTATION error code returned from os implementation
*
*/
int iOSAL_Interrupt_Disable( uint8_t ucInterruptID );
Thread safe APIs¶
Mark the start of critical code region¶
vOSAL_EnterCritical
/**
* @brief Mark the start of critical code region.
*
* @return N/A.
*
*/
void vOSAL_EnterCritical( void );
Mark the end of critical code region¶
vOSAL_ExitCritical
/**
* @brief Mark the end of critical code region.
*
* @return N/A.
*
*/
void vOSAL_ExitCritical( void );
OSAL malloc¶
pvOSAL_MemAlloc
/**
* @brief OSAL wrapper for task/thread safe memory allocation.
*
* @param uint16_t The number of bytes to allocate.
*
* @return Pointer to the beginning of newly allocated memory.
* NULL if unsuccessful.
*
*/
void* pvOSAL_MemAlloc( uint16_t xSize );
OSAL memset¶
pvOSAL_MemSet
/**
* @brief OSAL wrapper for task/thread safe memory set.
*
* @param pvDestination Pointer to the block of memory to be set.
* @param iValue The value to be set.
* @param usSize The number of bytes to be set, to the specified valve.
*
* @return Pointer to the beginning of newly set memory.
* NULL if unsuccessful.
*
*/
void* pvOSAL_MemSet( void* pvDestination, int iValue, uint16_t usSize );
OSAL memcpy¶
pvOSAL_MemCpy
/**
* @brief OSAL wrapper for task/thread safe memory copy.
*
* @param pvDestination Pointer to the destination where the content is to be copied.
* @param pvSource Pointer to the source of data to be copied.
* @param usSize The number of bytes to copy.
*
* @return Pointer to the destination where the content is copied.
* NULL if unsuccessful.
*
*/
void* pvOSAL_MemCpy( void* pvDestination, const void* pvSource, uint16_t usSize );
OSAL free¶
vOSAL_MemFree
/**
* @brief OSAL wrapper for task/thread safe memory deallocation.
*
* @param ppv Pointer-to-pointer to the memory to deallocate.
*
* @return N/A.
*
* @note After free'ing the allocated memory, this function will also
* nullify the pointer to the deallocated memory.
*/
void vOSAL_MemFree( void** ppv );
OSAL printf¶
vOSAL_Printf
/**
* @brief OSAL wrapper for task/thread safe prints.
*
* @param pcFormat C string that contains the text to be written.
*
* @return N/A.
*
*/
void vOSAL_Printf( const char* pcFormat, ... );
OSAL getchar¶
cOSAL_GetChar
/**
* @brief OSAL wrapper for task/thread safe char reading.
*
* @return character read from STDIN.
*
*/
char cOSAL_GetChar( void );
Debug stats APIs¶
Print all stats¶
vOSAL_PrintAllStats
/**
* @brief Prints OSAL debug stats.
*
* @param eVerbosity Verbosity level for the debug data.
* @param eStatType Type of stat to print.
*
*/
void vOSAL_PrintAllStats( OSAL_STATS_VERBOSITY eVerbosity, OSAL_STATS_TYPE eStatType );
Clear all stats¶
vOSAL_ClearAllStats
/**
* @brief Clears debug stats and frees associated memory.
*
*/
void vOSAL_ClearAllStats( void );
Examples¶
iOSAL_GetOsVersion
char pcOs[ OSAL_OS_NAME_LEN ] = { 0 };
uint8_t ucVersionMajor = 0;
uint8_t ucVersionMinor = 0;
uint8_t ucVersionBuild = 0;
if( OSAL_ERRORS_NONE != iOSAL_GetOsVersion( pcOs,
&ucVersionMajor,
&ucVersionMinor,
&ucVersionBuild) )
{
/* Get OS version failed */
}
else
{
/* Get OS version success */
}
Scheduler APIs¶
Start RTOS scheduler example¶
iOSAL_StartOS
void* pvMainTaskHandle = NULL;
void vTaskFuncMain( void )
{
/* implement main task function */
}
/* Start scheduler (with Round Robin Enabled) and create main test task */
if( OSAL_ERRORS_NONE != iOSAL_StartOS( TRUE,
&pvMainTaskHandle,
&vTaskFuncMain,
0x1000,
1 ) )
{
/* Start OS failed */
}
else if( NULL == pvMainTaskHandle )
{
/* Start OS failed */
}
Get Tick count since scheduler started example¶
ulOSAL_GetUptimeTicks
uint32_t UpTimeTicksBeforeSleep = 0;
uint32_t UpTimeTicksAfterSleep = 0;
UpTimeTicksBeforeSleep = ulOSAL_GetUptimeTicks();
iOSAL_Task_SleepTicks( 500 ); /* delay task - 500 Ticks */
UpTimeTicksAfterSleep = ulOSAL_GetUptimeTicks();
Get ms count since scheduler started example¶
ulOSAL_GetUptimeMs
uint32_t UpTimeMsBeforeSleep = 0;
uint32_t UpTimeMsAfterSleep = 0;
UpTimeMsBeforeSleep = ulOSAL_GetUptimeMs();
iOSAL_Task_SleepMs( 5000 ); /* delay task - 2s */
UpTimeMsAfterSleep = ulOSAL_GetUptimeMs();
Task APIs¶
Create OSAL Task Example¶
iOSAL_Task_Create
void *pvTaskHandle = NULL;
void *pvArg = NULL; /* set to task argument */
/* Define task function */
void vTaskFunc( void* pvArg )
{
FOREVER
{
/* Task implementation */
}
}
if( OSAL_ERRORS_NONE != iOSAL_Task_Create( &pvTaskHandle, &vTaskFunc, pvArg, 10, 0x1000, "test_task" ) )
{
/* task create failed */
}
else if( NULL == pvTaskHandle )
{
/* task create failed */
}
else
{
/* task create success */
}
Delete OSAL Task Example¶
iOSAL_Task_Delete
if( OSAL_ERRRORS_NONE != iOSAL_Task_Delete( &pvTaskHandle ) )
{
/* task delete failed */
}
else if( NULL != pvTaskHandle0 )
{
/* task delete failed */
}
else
{
/* task delete success */
}
Suspend OSAL Task Example¶
iOSAL_Task_Suspend
if( OSAL_ERRRORS_NONE != iOSAL_Task_Suspend( pvTaskHandle ) )
{
/* task suspend failed */
}
else
{
/* task suspend success */
}
Resume OSAL Task Example¶
iOSAL_Task_Resume
if( OSAL_ERRRORS_NONE != iOSAL_Task_Resume( pvTaskHandle ) )
{
/* task resume failed */
}
else
{
/* task resume success */
}
OSAL Task Sleep (Ticks)¶
iOSAL_Task_SleepTicks
iOSAL_Task_SleepTicks( 500 ); /* delay main task - 500 Ticks */
OSAL Task Sleep (ms)¶
iOSAL_Task_SleepMs
iOSAL_Task_SleepMs( 2000 ); /* delay main task - 2s */
Semaphore APIs¶
Create OSAL Semaphore¶
iOSAL_Semaphore_Create
static void* pvSemBinaryHandle = NULL;
static void* pvSemCountingHandle = NULL;
/* Create Binary Semaphore */
if( OSAL_ERRORS_NONE != iOSAL_Semaphore_Create( &pvSemBinaryHandle,
1,
1,
"Test Binary Semaphore" ) ) {
/* semaphore create failed */
}
else if( NULL == pvSemBinaryHandle )
{
/* semaphore create failed */
}
else
{
/* semaphore create success */
}
/* Create Counting Semaphore */
if( OSAL_ERRORS_NONE != iOSAL_Semaphore_Create( &pvSemCountingHandle,
5,
5,
"Test Binary Semaphore" ) ) {
/* semaphore create failed */
}
else if( NULL == pvSemCountingHandle )
{
/* semaphore create failed */
}
else
{
/* semaphore create success */
}
Delete OSAL Semaphore¶
iOSAL_Semaphore_Destroy
if( OSAL_ERRORS_NONE != iOSAL_Semaphore_Destroy( &pvSemBinaryHandle ) )
{
/* semaphore delete failed */
}
else if( NULL != pvSemBinaryHandle )
{
/* semaphore delete failed */
}
else
{
/* semaphore delete success */
}
if( OSAL_ERRORS_NONE != iOSAL_Semaphore_Destroy( &pvSemCountingHandle ) )
{
/* semaphore delete failed */
}
else if( NULL != pvSemCountingHandle )
{
/* semaphore delete failed */
}
else
{
/* semaphore delete success */
}
Pend to OSAL Semaphore¶
iOSAL_Semaphore_Pend
if( OSAL_ERRORS_NONE != iOSAL_Semaphore_Pend( pvSemBinaryHandle, OSAL_TIMEOUT_WAIT_FOREVER ) )
{
/* semaphore pend failed */
}
else
{
/* semaphore pend success */
}
if( OSAL_ERRORS_NONE != iOSAL_Semaphore_Pend( pvSemCountingHandle, OSAL_TIMEOUT_WAIT_FOREVER ) )
{
/* semaphore pend failed */
}
else
{
/* semaphore pend success */
}
Post to OSAL Semaphore¶
iOSAL_Semaphore_Post
if( OSAL_ERRORS_NONE != iOSAL_Semaphore_Post( pvSemBinaryHandle ) )
{
/* semaphore post failed */
}
else
{
/* semaphore post success */
}
if( OSAL_ERRORS_NONE != iOSAL_Semaphore_Post( pvSemCountingHandle ) )
{
/* semaphore post failed */
}
else
{
/* semaphore post success */
}
Mutex APIs¶
Create OSAL Mutex¶
iOSAL_Mutex_Create
static void* pvMutexHandle = NULL;
if( OSAL_ERRORS_NONE != iOSAL_Mutex_Create( &pvMutexHandle, "test_mutex" ) )
{
/* mutex create failed */
}
else if( NULL == pvMutexHandle )
{
/* mutex create failed */
}
else
{
/* mutex create success */
}
Delete OSAL Mutex¶
iOSAL_Mutex_Destroy
if( OSAL_ERRORS_NONE != iOSAL_Mutex_Destroy( &pvMutexHandle ) )
{
/* mutex delete failed */
}
else if( NULL != pvMutexHandle )
{
/* mutex delete failed */
}
else
{
/* mutex delete success */
}
Take OSAL Mutex¶
iOSAL_Mutex_Take
if( OSAL_ERRORS_NONE != iOSAL_Mutex_Take( pvMutexHandle, OSAL_TIMEOUT_WAIT_FOREVER ) )
{
/* mutex take failed */
}
else
{
/* mutex take success */
}
Release OSAL Mutex¶
iOSAL_Mutex_Release
if( OSAL_ERRORS_NONE != iOSAL_Mutex_Release( pvMutexHandle ) )
{
/* mutex release failed */
}
else
{
/* mutex release success */
}
Mailbox APIs¶
Create OSAL Mailbox¶
iOSAL_MBox_Create
static void* pvMBoxHandle = NULL;
uint32_t ulMBoxLength = 10; /* set to mailbox length */
uint32_t ulItemSize = sizeof( uint32_t ); /* set to item size */
if( OSAL_ERRORS_NONE != iOSAL_MBox_Create( &pvMBoxHandle, ulMBoxLength, ulItemSize, "test_mbox" ) )
{
/* Mailbox create failed */
}
else if( NULL == pvMBoxHandle )
{
/* Mailbox create failed */
}
else
{
/* Mailbox create success */
}
Delete OSAL Mailbox¶
iOSAL_MBox_Destroy
if( OSAL_ERRORS_NONE != iOSAL_MBox_Destroy( &pvMBoxHandle ) )
{
/* Mailbox delete failed */
}
else if( NULL != pvMBoxHandle )
{
/* Mailbox delete failed */
}
else
{
/* Mailbox delete success */
}
Pend to OSAL Mailbox¶
iOSAL_MBox_Pend
ulRxData = 0;
uint32_t ulTimeoutMs = 2000; /* set to desired timeout (ms) */
if( OSAL_ERRORS_NONE != iOSAL_MBox_Pend( pvMBoxHandle, ( void* )&ulRxData, ulTimeoutMs ) )
{
/* Mailbox pend failed */
}
else
{
/* Mailbox pend success */
}
Post to OSAL Mailbox¶
iOSAL_MBox_Post
static uint32_t ulTxData = 0x12345678; /* set to desired data */
if( OSAL_ERRORS_NONE != iOSAL_MBox_Post( pvMBoxHandle, ( void* )&ulTxData ), OSAL_NO_WAIT )
{
/* Mailbox post failed */
}
else
{
/* Mailbox post success */
}
Event APIs¶
Create OSAL Event Group¶
iOSAL_EventFlag_Create
static void* pvEventFlagHandle = NULL;
/* Create Event Flag Group */
if( OSAL_ERRORS_NONE != iOSAL_EventFlag_Create( &pvEventFlagHandle, "test_event" ) )
{
/* Event Group create failed */
}
else if( NULL == pvEventFlagHandle )
{
/* Event Group create failed */
}
else
{
/* Event Group create success */
}
Delete OSAL Event Group¶
iOSAL_EventFlag_Destroy
if( OSAL_ERRORS_NONE != iOSAL_EventFlag_Destroy( &pvEventFlagHandle ) )
{
/* Event Group delete failed */
}
else if( NULL != pvEventFlagHandle )
{
/* Event Group delete failed */
}
else
{
/* Event Group delete success */
}
Pend to OSAL Event Group¶
iOSAL_EventFlag_Pend
#define EVENT_BIT_0 ( 1 << 0 )
#define EVENT_BIT_1 ( 1 << 1 )
/* pend for event bits 0 and 1 */
if( OSAL_ERRORS_NONE != iOSAL_EventFlag_Pend( pvEventFlagHandle,
( EVENT_BIT_0 | EVENT_BIT_1 ),
OSAL_TIMEOUT_WAIT_FOREVER ) )
{
/* Event Group pend failed */
}
else
{
/* Event Group pend success */
}
Post to OSAL Event Group¶
iOSAL_EventFlag_Post
#define EVENT_BIT_0 ( 1 << 0 )
#define EVENT_BIT_1 ( 1 << 1 )
/* Post Event Flag bits 0 and 1 */
if( OSAL_ERRORS_NONE != iOSAL_EventFlag_Post( pvEventFlagHandle,
( EVENT_BIT_0 | EVENT_BIT_1 ) ) )
{
/* Event Group post failed */
}
else
{
/* Event Group post success */
}
Timer APIs¶
Create OSAL Timer¶
iOSAL_Timer_Create
void* pvTimerHandle = NULL;
void vTimerCallback( void* pvTimerHandle )
{
TEST_PRINTF( "Timer Callback Called" );
iOSAL_Timer_Stop( pvTimerHandle );
}
if( OSAL_ERRORS_NONE != iOSAL_Timer_Create( &pvTimerHandle,
OSAL_TIMER_CONFIG_ONE_SHOT,
( void* )0,
vTimerCallback,
"Timer 1" ) )
{
/* Timer create failed */
}
else if( NULL == pvTimerHandle )
{
/* Timer create failed */
}
else
{
/* Timer create success */
}
Delete OSAL Timer¶
iOSAL_Timer_Destroy
if( OSAL_ERRORS_NONE != iOSAL_Timer_Destroy( &pvTimerHandle ) )
{
/* Timer delete failed */
}
else if( NULL != pvTimerHandle )
{
/* Timer delete failed */
}
else
{
/* Timer delete success */
}
Start OSAL Timer¶
iOSAL_Timer_Start
if( OSAL_ERRORS_NONE != iOSAL_Timer_Start( pvTimerHandle,
1000 ) )
{
/* Timer start failed */
}
else
{
/* Timer start success */
}
Stop OSAL Timer¶
iOSAL_Timer_Stop
if( OSAL_ERRORS_NONE != iOSAL_Timer_Stop( pvTimerHandle ) )
{
/* Timer stop failed */
}
else
{
/* Timer stop success */
}
Reset OSAL Timer¶
iOSAL_Timer_Reset
if( OSAL_ERRORS_NONE != iOSAL_Timer_Reset( pvTimerHandle,
2000 ) )
{
/* Timer reset failed */
}
else
{
/* Timer reset success */
}
Interrupt APIs¶
Setup OSAL Interrupt¶
iOSAL_Interrupt_Setup
#define FABRIC_INTERRUPT_HANDLE ( XPAR_FABRIC_UARTLITE_1_VEC_ID )
void vInterruptHandler( void* pvCallBackRef )
{
if( NULL != pvCallBackRef )
{
/* interrupt handler implementation */
}
}
if( OSAL_ERRORS_NONE != iOSAL_Interrupt_Setup( FABRIC_INTERRUPT_HANDLE,
vInterruptHandler,
NULL ) )
{
/* Interrupt setup failed */
}
else
{
/* Interrupt setup success */
}
Enable OSAL Interrupt¶
iOSAL_Interrupt_Enable
#define FABRIC_INTERRUPT_HANDLE ( XPAR_FABRIC_UARTLITE_1_VEC_ID )
if( OSAL_ERRORS_NONE != iOSAL_Interrupt_Enable( FABRIC_INTERRUPT_HANDLE ) )
{
/* Interrupt enable failed */
}
else
{
/* Interrupt enable success */
}
Disable OSAL Interrupt¶
iOSAL_Interrupt_Disable
#define FABRIC_INTERRUPT_HANDLE ( XPAR_FABRIC_UARTLITE_1_VEC_ID )
if( OSAL_ERRORS_NONE != iOSAL_Interrupt_Disable( FABRIC_INTERRUPT_HANDLE ) )
{
/* Interrupt disable failed */
}
else
{
/* Interrupt disable success */
}
Thread safe APIs¶
Mark the start of critical code region¶
vOSAL_EnterCritical
/* simply call API where needed. No parameters required */
vOSAL_EnterCritical();
Mark the end of critical code region¶
vOSAL_ExitCritical
/* simply call API where needed. No parameters required */
vOSAL_ExitCritical();
OSAL malloc / memset / memcpy / free¶
pvOSAL_MemAlloc
/* all OSAL memory functions can be safely called from within tasks */
void vMemoryTaskFunc( void* pvArg )
{
/* allocate 5 bytes memory */
pucMemBuff1 = ( uint8_t* )pvOSAL_MemAlloc( 5*sizeof( uint8_t ) );
/* store values in memory */
pucMemBuff1[ 0 ] = 0x11;
pucMemBuff1[ 1 ] = 0x22;
pucMemBuff1[ 2 ] = 0x33;
pucMemBuff1[ 3 ] = 0x44;
pucMemBuff1[ 4 ] = 0x55;
/* set memory */
pvOSAL_MemSet( pucMemBuff1, 0, 5 );
/* copy memory */
pvOSAL_MemCpy( pucMemBuff1, pucMemSourceBuff, 5 );
vOSAL_MemFree( pucMemBuff1 ); /* free allocated memory */
pucMemBuff1 = NULL; /* nullify pointer */
FOREVER
{
iOSAL_Task_SleepMs( 100 );
}
}
OSAL printf¶
vOSAL_Printf
/* OSAL printf can be safely called from within tasks */
void vPrintTaskFunc( void* pvArg )
{
int* iThisTask = ( int* )( pvArg );
for( ( *iThisTask ) = 0; ( *iThisTask ) < 5; ( *iThisTask )++ )
{
vOSAL_Printf("Print statement %d, from Task 1", ( *iThisTask ) );
}
FOREVER
{
iOSAL_Task_SleepMs( 100 );
}
}
OSAL getchar¶
cOSAL_GetChar
#define DAL_MAX_INPUT ( 256 )
int iInputLen = 0;
char cLastChar = '\0';
char pcLastCmd[ DAL_MAX_INPUT ] = { 0 };
while( ( '\r' != cLastChar ) && ( '\n' != cLastChar ) &&
( DAL_MAX_INPUT > iInputLen ) )
{
cLastChar = cOSAL_GetChar();
pcLastCmd[ iInputLen++ ] = cLastChar;
vOSAL_Printf( "%c", cLastChar );
}
Debug stats APIs¶
Print all stats¶
vOSAL_PrintAllStats
/* specify verbosity level and stats type */
vOSAL_PrintAllStats( OSAL_STATS_VERBOSITY_FULL, OSAL_STATS_TYPE_ALL );
Clear all stats¶
vOSAL_ClearAllStats
/* simply call API, no params needed */
vOSAL_ClearAllStats();
Page Revision: v. 64