OS Interface (OSIF)

Detailed Description

OS Interface Layer (OSIF)

The OSIF layer is a minimal wrapper layer for common RTOS services, intended to be used by SDK drivers and middlewares. I can be used by the user application, but it is not recommended. The operations supported by OSIF:

OSIF currently comes in two variants: bare-metal and FreeRTOS. Steps to use each one are described below.

FreeRTOS

To integrate the FreeRTOS OSIF variant, two steps are necessary:

FreeRTOSConfig.h dependencies

FreeRTOS configuration file needs to have these options activated:

Hardware resources

FreeRTOS OSIF uses the FreeRTOS API and services, does not use any additional hardware or software resources.

FreeRTOS supported platforms

The SDK platforms supported by FreeRTOS can be found in the following table. If a platform is supported by FreeRTOS, both osif variants, bare-metal and freertos, are supported. If the platform is not supported by FreeRTOS, only osif bare-metal variant is applicable:

Platform FreeRTOS support
S32K11x No
S32K14x Yes
MPC5746C Yes
MPC5748G Yes
MPC5744P Yes

Bare-metal

To integrate the bare-metal OSIF variant:

Mutex operations are dummy operations (always return success) and semaphore is implemented as a simple counter.

Hardware resources

Bare-metal OSIF uses a hardware timer to accurately measure time. The timer and channel used are platform-dependent, are chosen to be the same as the FreeRTOS implementation if possible.

The table below shows which timers and channels are used on each platform:

Platform Timer Channel
S32K11x Systick N/A
S32K14x Systick N/A
MPC5746C PIT 15
MPC5748G PIT 15
MPC5744P PIT 3

Bare-metal timing limitations

For bare-metal OSIF, the timer is initialized at the first call in OSIF that needs timing. That is either OSIF_TimeDelay, OSIF_MutexLock or OSIF_SemaWait (functions with timeout). The timer configuration, but not the counter, is updated at each subsequent call to these functions.

Do not assume OSIF_GetMilliseconds will return a global value since system initialization. It will return the global value since the very first timer initialization, mentioned above.

Macros

#define OSIF_WAIT_FOREVER   0xFFFFFFFFu
 

Functions

void OSIF_TimeDelay (const uint32_t delay)
 Delays execution for a number of milliseconds. More...
 
uint32_t OSIF_GetMilliseconds (void)
 Returns the number of miliseconds elapsed since starting the internal timer or starting the scheduler. More...
 
status_t OSIF_MutexLock (const mutex_t *const pMutex, const uint32_t timeout)
 Waits for a mutex and locks it. More...
 
status_t OSIF_MutexUnlock (const mutex_t *const pMutex)
 Unlocks a previously locked mutex. More...
 
status_t OSIF_MutexCreate (mutex_t *const pMutex)
 Create an unlocked mutex. More...
 
status_t OSIF_MutexDestroy (const mutex_t *const pMutex)
 Destroys a previously created mutex. More...
 
status_t OSIF_SemaWait (semaphore_t *const pSem, const uint32_t timeout)
 Decrement a semaphore with timeout. More...
 
status_t OSIF_SemaPost (semaphore_t *const pSem)
 Increment a semaphore. More...
 
status_t OSIF_SemaCreate (semaphore_t *const pSem, const uint8_t initValue)
 Creates a semaphore with a given value. More...
 
status_t OSIF_SemaDestroy (const semaphore_t *const pSem)
 Destroys a previously created semaphore. More...
 

Macro Definition Documentation

#define OSIF_WAIT_FOREVER   0xFFFFFFFFu

Definition at line 65 of file osif.h.

Function Documentation

uint32_t OSIF_GetMilliseconds ( void  )

Returns the number of miliseconds elapsed since starting the internal timer or starting the scheduler.

Returns
the number of miliseconds elapsed

Definition at line 230 of file osif_baremetal.c.

status_t OSIF_MutexCreate ( mutex_t *const  pMutex)

Create an unlocked mutex.

Parameters
[in]pMutexreference to the mutex object
Returns
One of the possible status codes:
  • STATUS_SUCCESS: mutex created
  • STATUS_ERROR: mutex could not be created

Definition at line 278 of file osif_baremetal.c.

status_t OSIF_MutexDestroy ( const mutex_t *const  pMutex)

Destroys a previously created mutex.

Parameters
[in]pMutexreference to the mutex object
Returns
One of the possible status codes:
  • STATUS_SUCCESS: mutex destroyed

Definition at line 292 of file osif_baremetal.c.

status_t OSIF_MutexLock ( const mutex_t *const  pMutex,
const uint32_t  timeout 
)

Waits for a mutex and locks it.

Parameters
[in]pMutexreference to the mutex object
[in]timeouttime-out value in milliseconds
Returns
One of the possible status codes:
  • STATUS_SUCCESS: mutex lock operation success
  • STATUS_ERROR: mutex already owned by current thread
  • STATUS_TIMEOUT: mutex lock operation timed out

Definition at line 248 of file osif_baremetal.c.

status_t OSIF_MutexUnlock ( const mutex_t *const  pMutex)

Unlocks a previously locked mutex.

Parameters
[in]pMutexreference to the mutex object
Returns
One of the possible status codes:
  • STATUS_SUCCESS: mutex unlock operation success
  • STATUS_ERROR: mutex unlock failed

Definition at line 264 of file osif_baremetal.c.

status_t OSIF_SemaCreate ( semaphore_t *const  pSem,
const uint8_t  initValue 
)

Creates a semaphore with a given value.

Parameters
[in]pSemreference to the semaphore object
[in]initValueinitial value of the semaphore
Returns
One of the possible status codes:
  • STATUS_SUCCESS: semaphore created
  • STATUS_ERROR: semaphore could not be created

Definition at line 384 of file osif_baremetal.c.

status_t OSIF_SemaDestroy ( const semaphore_t *const  pSem)

Destroys a previously created semaphore.

Parameters
[in]pSemreference to the semaphore object
Returns
One of the possible status codes:
  • STATUS_SUCCESS: semaphore destroyed

Definition at line 402 of file osif_baremetal.c.

status_t OSIF_SemaPost ( semaphore_t *const  pSem)

Increment a semaphore.

Parameters
[in]pSemreference to the semaphore object
Returns
One of the possible status codes:
  • STATUS_SUCCESS: semaphore post operation success
  • STATUS_ERROR: semaphore could not be incremented

Definition at line 357 of file osif_baremetal.c.

status_t OSIF_SemaWait ( semaphore_t *const  pSem,
const uint32_t  timeout 
)

Decrement a semaphore with timeout.

Parameters
[in]pSemreference to the semaphore object
[in]timeouttime-out value in milliseconds
Returns
One of the possible status codes:
  • STATUS_SUCCESS: semaphore wait operation success
  • STATUS_TIMEOUT: semaphore wait timed out

Definition at line 306 of file osif_baremetal.c.

void OSIF_TimeDelay ( const uint32_t  delay)

Delays execution for a number of milliseconds.

Parameters
[in]delayTime delay in milliseconds.

Definition at line 205 of file osif_baremetal.c.