PAL A Platform Abstraction Layer connects the mbed-client with the underlying platform.

- Main Page
- Data Structures
- Files

- File List
- Globals

Data Structures | Macros | Typedefs | Enumerations | Functions
pal_rtos.h File Reference
`#include <stdint.h>`
`#include "pal_macros.h"`
`#include "pal_types.h"`

Go to the source code of this file.

## Data Structures
struct | pal_threadLocalStore

## Macros
#define | PAL_RTOS_WAIT_FOREVER PAL_MAX_UINT32
| Wait forever define. used for Semaphores and Mutexes. More...
#define | PAL_PRINTF(ARGS...) dbgPrintf(__FUNCTION__,__LINE__, ARGS);

## Typedefs
typedef uintptr_t | palThreadID_t
| Primitives IDs types declarations. More...
typedef uintptr_t | palTimerID_t
typedef uintptr_t | palMutexID_t
typedef uintptr_t | palSemaphoreID_t
typedef uintptr_t | palMemoryPoolID_t
typedef uintptr_t | palMessageQID_t
typedef enum palTimerType | palTimerType_t
| Timers types supported in PAL. More...
typedef void(* | palTimerFuncPtr) (void const *funcArgument)
| PAL timer function prototype. More...
typedef void(* | palThreadFuncPtr) (void const *funcArgument)
| PAL thread function prototype. More...
typedef enum pal_osPriority | palThreadPriority_t
| Available priorities in PAL implementation, each priority can appear only once. More...
typedef struct pal_threadLocalStore | palThreadLocalStore_t

## Enumerations
enum | palTimerType { palOsTimerOnce = 0, palOsTimerPeriodic = 1 }
| Timers types supported in PAL. More...
enum | pal_osPriority { PAL_osPriorityIdle = -3, PAL_osPriorityLow = -2, PAL_osPriorityBelowNormal = -1, PAL_osPriorityNormal = 0, PAL_osPriorityAboveNormal = +1, PAL_osPriorityHigh = +2, PAL_osPriorityRealtime = +3, PAL_osPriorityError = 0x84 }
| Available priorities in PAL implementation, each priority can appear only once. More...

## Functions
void | pal_osReboot (void)
uint32_t | pal_osKernelSysTick (void)
uint64_t | pal_osKernelSysTick64 (void)
uint64_t | pal_osKernelSysTickMicroSec (uint64_t microseconds)
uint64_t | pal_osKernelSysMilliSecTick (uint64_t sysTicks)
uint64_t | pal_osKernelSysTickFrequency (void)
palStatus_t | pal_osThreadCreate (palThreadFuncPtr function, void *funcArgument, palThreadPriority_t priority, uint32_t stackSize, uint32_t *stackPtr, palThreadLocalStore_t *store, palThreadID_t *threadID)
palStatus_t | pal_osThreadTerminate (palThreadID_t *threadID)
palThreadID_t | pal_osThreadGetId (void)
void * | pal_osThreadGetLocalStore (void)
palStatus_t | pal_osDelay (uint32_t milliseconds)
palStatus_t | pal_osTimerCreate (palTimerFuncPtr function, void *funcArgument, palTimerType_t timerType, palTimerID_t *timerID)
palStatus_t | pal_osTimerStart (palTimerID_t timerID, uint32_t millisec)
palStatus_t | pal_osTimerStop (palTimerID_t timerID)
palStatus_t | pal_osTimerDelete (palTimerID_t *timerID)
palStatus_t | pal_osMutexCreate (palMutexID_t *mutexID)
palStatus_t | pal_osMutexWait (palMutexID_t mutexID, uint32_t millisec)
palStatus_t | pal_osMutexRelease (palMutexID_t mutexID)
palStatus_t | pal_osMutexDelete (palMutexID_t *mutexID)
palStatus_t | pal_osSemaphoreCreate (uint32_t count, palSemaphoreID_t *semaphoreID)
palStatus_t | pal_osSemaphoreWait (palSemaphoreID_t semaphoreID, uint32_t millisec, int32_t *countersAvailable)
palStatus_t | pal_osSemaphoreRelease (palSemaphoreID_t semaphoreID)
palStatus_t | pal_osSemaphoreDelete (palSemaphoreID_t *semaphoreID)
palStatus_t | pal_osPoolCreate (uint32_t blockSize, uint32_t blockCount, palMemoryPoolID_t *memoryPoolID)
void * | pal_osPoolAlloc (palMemoryPoolID_t memoryPoolID)
void * | pal_osPoolCAlloc (palMemoryPoolID_t memoryPoolID)
palStatus_t | pal_osPoolFree (palMemoryPoolID_t memoryPoolID, void *block)
palStatus_t | pal_osPoolDestroy (palMemoryPoolID_t *memoryPoolID)
palStatus_t | pal_osMessageQueueCreate (uint32_t messageQSize, palMessageQID_t *messageQID)
palStatus_t | pal_osMessagePut (palMessageQID_t messageQID, uint32_t info, uint32_t timeout)
palStatus_t | pal_osMessageGet (palMessageQID_t messageQID, uint32_t timeout, uint32_t *messageValue)
palStatus_t | pal_osMessageQueueDestroy (palMessageQID_t *messageQID)
int32_t | pal_osAtomicIncrement (int32_t *valuePtr, int32_t increment)
void | dbgPrintf (const char *function, uint32_t line, const char *format,...)

## Macro Definition Documentation

#define PAL_PRINTF | ( |  | ARGS... | ) | dbgPrintf(__FUNCTION__,__LINE__, ARGS);

#define PAL_RTOS_WAIT_FOREVER PAL_MAX_UINT32

Wait forever define. used for Semaphores and Mutexes.

## Typedef Documentation

typedef uintptr_t palMemoryPoolID_t

typedef uintptr_t palMessageQID_t

typedef uintptr_t palMutexID_t

typedef uintptr_t palSemaphoreID_t

typedef void(* palThreadFuncPtr) (void const *funcArgument)

PAL thread function prototype.

typedef uintptr_t palThreadID_t

Primitives IDs types declarations.

typedef struct pal_threadLocalStore palThreadLocalStore_t

Thread priority levels for PAL threads - each thread must have a different priority Thread Local Store struct. Can be used to hold: State, configurations and etc inside the thread.

typedef enum pal_osPriority palThreadPriority_t

Available priorities in PAL implementation, each priority can appear only once.

typedef void(* palTimerFuncPtr) (void const *funcArgument)

PAL timer function prototype.

typedef uintptr_t palTimerID_t

typedef enum palTimerType palTimerType_t

Timers types supported in PAL.

## Enumeration Type Documentation

enum pal_osPriority

Available priorities in PAL implementation, each priority can appear only once.

Enumerator
PAL_osPriorityIdle |
PAL_osPriorityLow |
PAL_osPriorityBelowNormal |
PAL_osPriorityNormal |
PAL_osPriorityAboveNormal |
PAL_osPriorityHigh |
PAL_osPriorityRealtime |
PAL_osPriorityError |

enum palTimerType

Timers types supported in PAL.

Enumerator
palOsTimerOnce |
palOsTimerPeriodic | One shot timer

## Function Documentation

void dbgPrintf | ( | const char * | function,
|  | uint32_t | line,
|  | const char * | format,
|  |  | ...
| ) |  |

Printf like function with prefix of function and line.

Parameters

  [in] | function | name of the current function
  [in] | line | line number to be printed
  [in] | format | print format (just like printf)

Returns
  the function returns the value of the valuePtr after the increment operation.

int32_t pal_osAtomicIncrement | ( | int32_t * | valuePtr,
|  | int32_t | increment
| ) |  |

Perform an atomic increment for a signed32 bit value

Parameters

  [in,out] | valuePtr | the address of the value to increment

palStatus_t pal_osDelay | ( | uint32_t | milliseconds | ) |

Wait for a specified time period in milliseconds.

Parameters

  [in] | milliseconds | the amount of milliseconds to wait before proceeding.

Returns
  the function returns the status in the form of palStatus_t which will be PAL_SUCCESS(0) in case of success and another negative value indicating a specific error code in case of failure

uint64_t pal_osKernelSysMilliSecTick | ( | uint64_t | sysTicks | ) |

Converts value from kernel system ticks to milliseconds.

Parameters

  [in] | sysTicks | the amount of kernel system ticks to convert into millieseconds

Returns
  converted value in system ticks

uint32_t pal_osKernelSysTick | ( | void |  | ) |

Get the RTOS kernel system timer counter.

Note
  this counter will wrap around very often (e.g. once every 42 sec for 100Mhz)

Returns
  the RTOS kernel system timer counter

uint64_t pal_osKernelSysTick64 | ( | void |  | ) |

Get the RTOS kernel system timer counter.

Returns
  the RTOS kernel system timer counter

uint64_t pal_osKernelSysTickFrequency | ( | void |  | ) |

Get the system tick frequency

Returns
  the system tick frequency

uint64_t pal_osKernelSysTickMicroSec | ( | uint64_t | microseconds | ) |

Converts value from microseconds to kernel sys tick

Parameters

  [in] | microseconds | the amount of microseconds to convert into system ticks

Returns
  converted value in system ticks

palStatus_t pal_osMessageGet | ( | palMessageQID_t | messageQID,
|  | uint32_t | timeout,
|  | uint32_t * | messageValue
| ) |  |

Get a Message or Wait for a Message from a Queue.

Parameters

  [in] | messageQID | the handle for the memory pool
  [in] | timeout | timeout in milliseconds
  [out] | event | the data to send

Returns
  the function returns the status in the form of palStatus_t which will be PAL_SUCCESS(0) in case of success and one of the following error codes in case of failure: PAL_ERR_RTOS_RESOURCE - in case semaphore was not available but not due to time out. PAL_ERR_RTOS_TIMEOUT - no message arrived during the timeout period. PAL_ERR_RTOS_RESOURCE - no message received and there was no timeout

palStatus_t pal_osMessagePut | ( | palMessageQID_t | messageQID,
|  | uint32_t | info,
|  | uint32_t | timeout
| ) |  |

Put a Message to a Queue.

Parameters

  [in] | messageQID | the handle for the memory pool
  [in] | info | the data to send
  [in] | timeout | timeout in milliseconds

Returns
  the function returns the status in the form of palStatus_t which will be PAL_SUCCESS(0) in case of success and another negative value indicating a specific error code in case of failure

palStatus_t pal_osMessageQueueCreate | ( | uint32_t | messageQSize,
|  | palMessageQID_t * | messageQID
| ) |  |

Create and initialize a message queue.

Parameters

  [in] | messageQSize | size of the message queue.
  [out] | memoryPoolID | holds the created memory pool ID handle - zero value indecates an error.

Returns
  PAL_SUCCESS when message queue created successfully. PAL_ERR_NO_MEMORY: no memory resource available to create message queue object.

palStatus_t pal_osMessageQueueDestroy | ( | palMessageQID_t * | messageQID | ) |

Delete a message queue object.

Parameters

  [in,out] | messageQID | the handle for the message queue, in success:(*messageQID = NULL).

Returns
  the function returns the status in the form of palStatus_t which will be PAL_SUCCESS(0) in case of success and another negative value indicating a specific error code in case of failure

palStatus_t pal_osMutexCreate | ( | palMutexID_t * | mutexID | ) |

Create and initialize Mutex object

Parameters

  [out] | mutexID | holds the created mutex ID handle - zero value indecates an error.

Returns
  PAL_SUCCESS when mutex created successfully. PAL_ERR_NO_MEMORY: no memory resource available to create mutex object.

palStatus_t pal_osMutexDelete | ( | palMutexID_t * | mutexID | ) |

Delete a Mutex object.

Parameters

  [in,out] | mutexID | Mutex handle to delete, in success:(*mutexID = NULL).

Returns
  PAL_SUCCESS when mutex deleted successfully. PAL_ERR_RTOS_RESOURCE - mutex already released. PAL_ERR_RTOS_PARAMETER - mutex id is invalid. PAL_ERR_RTOS_ISR - cannot be called from interrupt service routines.

Note
  After this call the mutex_id is no longer valid and cannot be used.

palStatus_t pal_osMutexRelease | ( | palMutexID_t | mutexID | ) |

Release a Mutex that was obtained by osMutexWait.

Parameters

  [in] | mutexID | the handle for the mutex

Returns
  the function returns the status in the form of palStatus_t which will be PAL_SUCCESS(0) in case of success and another negative value indicating a specific error code in case of failure

palStatus_t pal_osMutexWait | ( | palMutexID_t | mutexID,
|  | uint32_t | millisec
| ) |  |

Wait until a Mutex becomes available.

Parameters

  [in] | mutexID | the handle for the mutex
  [in] | millisec | the timeout for the waiting operation if the timeout expires before the semaphore is released and error will be returned from the function, PAL_RTOS_WAIT_FOREVER can be used.

Returns
  the function returns the status in the form of palStatus_t which will be PAL_SUCCESS(0) in case of success and one of the following error codes in case of failure: PAL_ERR_RTOS_RESOURCE - mutex not avaialbe but no time out set. PAL_ERR_RTOS_TIMEOUT - mutex was not available until timeout expired. PAL_ERR_RTOS_PARAMETER - mutex id is invalid PAL_ERR_RTOS_ISR - cannot be called from interrupt service routines

void* pal_osPoolAlloc | ( | palMemoryPoolID_t | memoryPoolID | ) |

Allocate a single memory block from a memory pool.

Parameters

  [in] | memoryPoolID | the handle for the memory pool

Returns
  the function returns a pointer to a single allocated memory from the pool or NULL in case of failure.

void* pal_osPoolCAlloc | ( | palMemoryPoolID_t | memoryPoolID | ) |

Allocate a single memory block from a memory pool and set memory block to zero.

Parameters

  [in] | memoryPoolID | the handle for the memory pool

Returns
  the function returns a pointer to a single allocated memory from the pool or NULL in case of failure.

palStatus_t pal_osPoolCreate | ( | uint32_t | blockSize,
|  | uint32_t | blockCount,
|  | palMemoryPoolID_t * | memoryPoolID
| ) |  |

Create and initialize a memory pool.

Parameters

  [in] | blockSize | size of single block in bytes.
  [in] | blockCount | maximum number of blocks in memory pool.
  [out] | memoryPoolID | holds the created memory pool ID handle - zero value indecates an error.

Returns
  PAL_SUCCESS when memory pool created successfully. PAL_ERR_NO_MEMORY: no memory resource available to create memory pool object.

palStatus_t pal_osPoolDestroy | ( | palMemoryPoolID_t * | memoryPoolID | ) |

Delete a memory pool object.

Parameters

  [in,out] | memoryPoolID | the handle for the memory pool, in success:(*memoryPoolID = NULL).

Returns
  the function returns the status in the form of palStatus_t which will be PAL_SUCCESS(0) in case of success and another negative value indicating a specific error code in case of failure

palStatus_t pal_osPoolFree | ( | palMemoryPoolID_t | memoryPoolID,
|  | void * | block
| ) |  |

Return an memoryPoolID memory block back to a specific memory pool.

Parameters

  [in] | memoryPoolHandle | the handle for the memory pool
  [in] | block | the block to free

Returns
  the function returns the status in the form of palStatus_t which will be PAL_SUCCESS(0) in case of success and another negative value indicating a specific error code in case of failure

void pal_osReboot | ( | void |  | ) |

Initiates a system reboot

palStatus_t pal_osSemaphoreCreate | ( | uint32_t | count,
|  | palSemaphoreID_t * | semaphoreID
| ) |  |

Create and initialize a Semaphore object

Parameters

  [in] | count | number of available resources
  [out] | semaphoreID | holds the created semaphore ID handle - zero value indecates an error.

Returns
  PAL_SUCCESS when semaphore created successfully. PAL_ERR_NO_MEMORY: no memory resource available to create semaphore object.

palStatus_t pal_osSemaphoreDelete | ( | palSemaphoreID_t * | semaphoreID | ) |

Delete a Semaphore object

Parameters

  [in,out] | semaphoreID | Semaphore handle to delete, in success:(*semaphoreID = NULL).

Returns
  PAL_SUCCESS when semaphore deleted successfully. PAL_ERR_RTOS_RESOURCE - semaphore already released. PAL_ERR_RTOS_PARAMETER - semaphore id is invalid.

Note
  After this call the semaphore_id is no longer valid and cannot be used.

palStatus_t pal_osSemaphoreRelease | ( | palSemaphoreID_t | semaphoreID | ) |

Release a Semaphore token.

Parameters

  [in] | semaphoreID | the handle for the semaphore

Returns
  the function returns the status in the form of palStatus_t which will be PAL_SUCCESS(0) in case of success and another negative value indicating a specific error code in case of failure

palStatus_t pal_osSemaphoreWait | ( | palSemaphoreID_t | semaphoreID,
|  | uint32_t | millisec,
|  | int32_t * | countersAvailable
| ) |  |

Wait until a Semaphore token becomes available.

Parameters

  [in] | semaphoreID | the handle for the semaphore
  [in] | millisec | the timeout for the waiting operation if the timeout expires before the semaphore is released and error will be returned from the function, PAL_RTOS_WAIT_FOREVER can be used.
  [out] | counteresAvailable | the number of semaphore available at the call if semaphore is available, if semaphore was not available (timeout/error) zero is returned.

Returns
  the function returns the status in the form of palStatus_t which will be PAL_SUCCESS(0) in case of success and one of the following error codes in case of failure: PAL_ERR_RTOS_TIMEOUT - semaphore was not available until timeout expired. PAL_ERR_RTOS_PARAMETER - semaphore id is invalid.

palStatus_t pal_osThreadCreate | ( | palThreadFuncPtr | function,
|  | void * | funcArgument,
|  | palThreadPriority_t | priority,
|  | uint32_t | stackSize,
|  | uint32_t * | stackPtr,
|  | palThreadLocalStore_t * | store,
|  | palThreadID_t * | threadID
| ) |  |

Creates and starts thread function.

Parameters

  [in] | function | function pointer to the thread callback function.
  [in] | funcArgument | argument for the thread function.
  [in] | priority | priotity of the thread.
  [in] | stackSize | the stack size of the thread can NOT be 0.
  [in] | stackPtr | pointer to the thread's stack can NOT be NULL.
  [in] | store | pointer to thread's local sotre, can be NULL.
  [out] | threadID | holds the created thread ID handle - zero value indecates an error.

Returns
  PAL_SUCCESS when thread created successfully. PAL_ERR_RTOS_PRIORITY : the given priority already used before in the system.

Note
  Each thread MUST be with unique priority.
  When the priority of the created thread function is higher than the current running thread, the created thread function starts instantly and becomes the new running thread.

palThreadID_t pal_osThreadGetId | ( | void |  | ) |

Get ID of the current thread

Returns
  the ID of the current thread - in case of error return PAL_MAX_UINT32

Note
  for thread with Real Time priority the function will always return PAL_MAX_UINT32

void* pal_osThreadGetLocalStore | ( | void |  | ) |

Get the storage of current thread

Returns
  the storage of the current thread

palStatus_t pal_osThreadTerminate | ( | palThreadID_t * | threadID | ) |

Terminates and free allocated data for the thread.

Parameters

  [in] | threadID | thread ID to stop and terminate.

Returns
  palStatus_t which will be PAL_SUCCESS(0) in case of success and another negative value indicating a specific error code in case of failure PAL_ERR_RTOS_RESOURCE: if the thread ID is not correct.

palStatus_t pal_osTimerCreate | ( | palTimerFuncPtr | function,
|  | void * | funcArgument,
|  | palTimerType_t | timerType,
|  | palTimerID_t * | timerID
| ) |  |

Creates a Timer.

Parameters

  [in] | function | function pointer to the timer callback function.
  [in] | funcArgument | funcArgument for the timer callback function.
  [in] | timerType | timer type to be created - (periodic or oneShot).
  [out] | timerID | holds the created timer ID handle - zero value indecates an error.

Returns
  PAL_SUCCESS when timer created successfully. PAL_ERR_NO_MEMORY: no memory resource available to create timer object.

Note
  the timer function runs according to the platform resources of stack-size and priority.

palStatus_t pal_osTimerDelete | ( | palTimerID_t * | timerID | ) |

Delete the timer object

Parameters

  [in,out] | timerID | the handle for the timer to delete, in success:(*timerID = NULL).

Returns
  PAL_SUCCESS when timer deleted successfully. PAL_ERR_RTOS_PARAMETER when timerID is incorrect.

palStatus_t pal_osTimerStart | ( | palTimerID_t | timerID,
|  | uint32_t | millisec
| ) |  |

Start or restart a timer.

Parameters

  [in] | timerID | the handle for the timer to start
  [in] | millisec | the amount of time in milliseconds to set the timer to.

Returns
  the function returns the status in the form of palStatus_t which will be PAL_SUCCESS(0) in case of success and another negative value indicating a specific error code in case of failure

palStatus_t pal_osTimerStop | ( | palTimerID_t | timerID | ) |

Stop a timer.

Parameters

  [in] | timerID | the handle for the timer to stop

Returns
  the function returns the status in the form of palStatus_t which will be PAL_SUCCESS(0) in case of success and another negative value indicating a specific error code in case of failure