| Kinetis SDK API Reference Manual 1.0.0-beta Freescale Semiconductor, Inc.

- Introduction
- Related Pages
- API Usage

All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Groups Pages
Modules | Macros | Enumerations
OS Abstraction Layer (OSA)

The Kinetis SDK provides the abstraction layer for real-time operating systems. More...

## Modules
| Bare Metal Abstraction Layer
| The Kinetis SDK provides the bare metal abstraction layer for synchronization, mutual exclusion, message queue, etc.
| FreeRTOS Abstraction Layer
| The Kinetis SDK provides the FreeRTOS Abstraction Layer for synchronization, mutual exclusion, message queue, etc.
| Freescale MQX™ RTOS Abstraction Layer
| The Freescale MQX™ RTOS OSA layer provides the OSA services mapped to the MQX software services.
| µC/OS-II Abstraction Layer
| The Kinetis SDK provides the µC/OS-II Abstraction Layer for synchronization, mutual exclusion, message queue, etc.
| µC/OS-III Abstraction Layer
| The Kinetis SDK provides the µC/OS-III for synchronization, mutual exclusion, message queue, etc.

## Macros
#define | __FSL_RTOS_MSGQ_COPY_MSG__ 1

## Enumerations
enum | fsl_rtos_status { kSuccess = 0, kError, kTimeout, kIdle }
| Status values to be returned by functions. More...
enum | event_status { kFlagNotSet = 0, kFlagSet }
| The event flags are set or not. More...
enum | event_clear_type { kEventAutoClr = 0, kEventManualClr }
| The event flags are cleared automatically or manually. More...

## Synchronization
fsl_rtos_status | sync_create (sync_object_t *obj, uint8_t initValue)
| Initialize a synchronization object to a given state. More...
fsl_rtos_status | sync_wait (sync_object_t *obj, uint32_t timeout)
| Wait for the synchronization object. More...
fsl_rtos_status | sync_poll (sync_object_t *obj)
| Checks a synchronization object's status. More...
fsl_rtos_status | sync_signal (sync_object_t *obj)
| Signal for someone waiting on the synchronization object to wake up. More...
fsl_rtos_status | sync_signal_from_isr (sync_object_t *obj)
| Signal for someone waiting on the synchronization object to wake up. More...
fsl_rtos_status | sync_destroy (sync_object_t *obj)
| Destroy a previously created synchronization object. More...

## Resource locking
fsl_rtos_status | lock_create (lock_object_t *obj)
| Initialize a locking object. More...
fsl_rtos_status | lock_wait (lock_object_t *obj, uint32_t timeout)
| Wait for the object to be unlocked and lock it. More...
fsl_rtos_status | lock_poll (lock_object_t *obj)
| Checks if a locking object can be locked and locks it if possible. More...
fsl_rtos_status | lock_release (lock_object_t *obj)
| Unlock a previously locked object. More...
fsl_rtos_status | lock_destroy (lock_object_t *obj)
| Destroy a previously created locking object. More...

## Event signaling
fsl_rtos_status | event_create (event_object_t *obj, event_clear_type clearType)
| Initializes the event object. More...
fsl_rtos_status | event_wait (event_object_t *obj, uint32_t timeout, event_group_t *setFlags)
| Wait for any event flags to be set. More...
fsl_rtos_status | event_set (event_object_t *obj, event_group_t flags)
| Set one or more event flags of an event object. More...
fsl_rtos_status | event_set_from_isr (event_object_t *obj, event_group_t flags)
| Set one or more event flags of an event object. More...
fsl_rtos_status | event_clear (event_object_t *obj, event_group_t flags)
| Clear one or more events of an event object. More...
event_status | event_check_flags (event_object_t *obj, event_group_t flag)
| Check the flags are set or not. More...
fsl_rtos_status | event_destroy (event_object_t *obj)
| Destroy a previously created event object. More...

## Thread management
fsl_rtos_status | __task_create (task_t task, uint8_t *name, uint16_t stackSize, task_stack_t *stackMem, uint16_t priority, void *param, bool usesFloat, task_handler_t *handler)
| Create a task. More...
fsl_rtos_status | task_destroy (task_handler_t handler)
| Destroy a previously created task. More...

## Message queues
msg_queue_handler_t | msg_queue_create (msg_queue_t *queue, uint16_t number, uint16_t size)
| Initialize the message queue. More...
fsl_rtos_status | msg_queue_put (msg_queue_handler_t handler, msg_queue_item_t item)
| Introduce an element at the tail of the queue. More...
fsl_rtos_status | msg_queue_get (msg_queue_handler_t handler, msg_queue_item_t *item, uint32_t timeout)
| Read and remove an element at the head of the queue. More...
fsl_rtos_status | msg_queue_flush (msg_queue_handler_t handler)
| Discards all elements in the queue and leaves the queue empty. More...
fsl_rtos_status | msg_queue_destroy (msg_queue_handler_t handler)
| Destroy a previously created queue. More...

## Memory Management
void * | mem_allocate (size_t size)
| Reserves the requested amount of memory in bytes. More...
void * | mem_allocate_zero (size_t size)
| Reserves the requested amount of memory in bytes and initializes it to 0. More...
fsl_rtos_status | mem_free (void *ptr)
| Releases the memory previously reserved. More...

## Time management
void | time_delay (uint32_t delay)
| Delays execution for a number of milliseconds. More...

## Interrupt management
fsl_rtos_status | interrupt_handler_register (int32_t irqNumber, void(*handler)(void))
| Install interrupt handler. More...

### OS Abstraction Layer

# Overview

Operating System Abstraction layer (OSA) provides a common set of services for drivers and applications so that they can work with or without the operating system. OSA provides services that abstract most of the OS kernel functionality. These services can either be mapped to the target OS functions directly, or implemented by OSA when no OS is used (bare metal) or when the service does not exist in the target OS. Freescale Kinetis SDK implements the OS abstraction layer for the Freescale MQX RTOS, FreeRTOS, µC/OS, and for no OS usage (bare metal). The bare metal OS abstraction implementation is selected as the default option.
OSA provides these services: task management, semaphore, mutex, event, message queue, memory allocator, critical section, and time delay.

# Task Management

With OSA, applications can create and destroy tasks dynamically. These services are mapped to the task functions of RTOSes. For bare metal, a function poll mechanism is used to simulate a task.
To create a task, use the FSL_RTOS_TASK_DEFINE() to declare the task statically. Then, use the task_create() to create the task.
This is an example code to creating and destroying a task:
// Define the task with entry function task_func.
FSL_RTOS_TASK_DEFINE(task_func, stackSize, taskName, FALSE);
void main(void)
{
// Define the task handler.
task_handler_t handler;
// Create the task.
task_create(task_func, priority, param, &handler);
task_destroy(&handler);
// ...
}

# Semaphore

OSA provides the drivers and applications with a counting semaphore. It can be used either to synchronize tasks or to synchronize a task and an ISR.
To use the semaphore, use the sync_object_declare() and the sync_create() to create it. The object can be created with an initial value.
Depending on the target OS, the sync_object_declare() may either define or declare the object to be used by the sync_create(). When the sync_object_declare() defines the object with the memory allocated, the memory has be to available for the entire lifespan of the object. It is recommended to declare objects in places where the memory allocated has the desired scope. When the sync object is not used any more, use the sync_destroy() to destroy it.
This is an example code to create and destroy a sync object:
// Declare the object.
sync_object_declare(my_sync);
// Create the object with initial value.
sync_create(&my_sync, initValue);
// Destroy the object.
sync_destory(&my_sync);
There are two ways to wait for the sync object.

1. The first way to wait for the sync object involves using the function, fsl_rtos_status sync_wait,(sync_object_t *obj, uint32_t timeout). This function waits for a timeout in milliseconds. Setting a parameter timeout as the kSyncWaitForever causes the thread to wait infinitely if the object can't be obtained. Note that the parameter timeout must not be 0.
2. The second way to wait for the sync object involves using the function, fsl_rtos_status sync_poll(sync_object_t *obj), as a non-blocking interface.

To post the object, use either the sync_signal() or the sync_signal_from_isr().

# Mutex

A mutex is used for mutual exclusion of the tasks when they access a shared resource.
Depending on the target OS, the lock_object_declare() may either define or declare the object to be used by the lock_create(). When the lock_object_declare() defines the object with memory allocated, the memory has be to available for the entire lifespan of the object. It is recommended to declare objects in places where the memory allocated has the desired scope. You should use the lock_object_declare() and the lock_create() to create the object, and the lock_destroy() to destroy it. When the lock object is created, it is in an unlocked state.This is example code to create and destroy a lock object:
// Declare the object.
lock_object_declare(my_lock);
// Create the object.
lock_create(&my_lock);
// Destroy the object.
lock_destroy(&my_lock);
There are two ways to wait for the lock object.

1. The first way to wait for the lock object involves the function fsl_rtos_status lock_wait(lock_object_t *obj, uint32_t timeout). This function waits for the timeout in milliseconds. Setting a parameter timeout as the kSyncWaitForever makes the thread wait infinitely if the lock can't be obtained. Note that the parameter timeout must not be 0.
2. The other way to wait for the lock object involves the function, fsl_rtos_status lock_poll(lock_object_t *obj), as a non-blocking interface.

To unlock the object, use the lock_release().

# Event

An event is supported with a single consumer and multi-producers.
The function fsl_rtos_status event_create(event_object_t *obj, event_clear_type clearType) creates two types of event objects, auto-clear and manual-clear.

1. An auto-clear event means that the event flags are cleared automatically.
2. A manual-clear event means that applications must clear the flags manually.

The function fsl_rtos_status event_wait(event_object_t *obj, uint32_t timeout, event_group_t *setFlags) waits for a timeout in milliseconds if the event flags are not set. Passing the kSyncWaitForever causes it to wait forever. The event flags which are set can be obtained by the parameter setFlags. This interface does not have the parameter to specify which flags to wait for and will wait for any flag.
The functions fsl_rtos_status event_set(event_object_t *obj, event_group_t flags) and fsl_rtos_status event_set_from_isr(event_object_t *obj, event_group_t flags) set the event flags.
The function fsl_rtos_status event_clear(event_object_t *obj, event_group_t flags) clears specified flags manually.
The function event_status event_check_flags(event_object_t *obj, event_group_t flag) checks whether any of the specified flags are set.
When the event object is not used any more, use the event_destory to destroy it.

# Message Queue

A message queue transfers messages between tasks. OSA provides two types of message queue.

1. The first message queue occurs when only the pointer to the message is stored in the queue. The senders put pointer to the message in the queue and the receivers get the message through the pointer. This type of message queue is more efficient because it does not need to copy memories. Applications and drivers must ensure that the message is always valid until receivers get it. If not, use the second message queue type.
2. The second message queue type occurs when entities are copied to the internal memory of the queue. Even though this is a safer approach, it slows down the performance.

Configure the macro __FSL_RTOS_MSGQ_COPY_MSG__ to determine which mode is used.
To create a message queue, use the MSG_QUEUE_DECLARE() and the msg_queue_create() like this:
// Declare the message queue.
MSG_QUEUE_DECLARE(my_message, msg_num, msg_size);
void main(void)
{
msg_queue_handler_t handler;
handler = msg_queue_create(&my_message, msg_num, msg_size);
// ...
}
The function fsl_rtos_status msg_queue_put(msg_queue_handler_t handler, msg_queue_item_t item) puts the message to the queue. Depending on the target OS, the MSG_QUEUE_DECLARE() may either define or declare the message queue to be used by the msg_queue_create(). When the MSG_QUEUE_DECLARE() defines the message queue with memory allocated, the memory has be to available for the entire lifespan of the message queue. It is recommended to declare the message queue in places where the memory allocated has the desired scope. If the queue is full, an error returns.
The function fsl_rtos_status msg_queue_get(msg_queue_handler_t handler, msg_queue_item_t *item, uint32_t timeout) waits for a timeout to get the message if the queue is empty. Passing 0 causes it to return immediately and passing the kSyncWaitForever causes it to wait forever.
The function fsl_rtos_status msg_queue_flush(msg_queue_handler_t handler) cleans all messages in the queue.
If the queue is not used any more, use the msg_queue_destroy() to destroy it.

# Critical Section

The rtos_enter_critical() and rtos_exit_critical() functions ensure that code is not pre-empted.

# Dynamic Memory Allocation

The void *mem_allocate(size_t size) function allocates memory with specified size. The void *mem_allocate_zero(size_t size) function allocates and cleans the memory. The fsl_rtos_status mem_free(void *ptr) function frees the memory. For RTOSes that have internal memory manager, such as the Freescale MQX RTOS, OSA maps these functions directly. For other RTOSes or for bare metal, the standard functions malloc/calloc/free are used.

# Time Delay

The function void time_delay(uint32_t delay) delays specified time in milliseconds.

## Enumeration Type Documentation

enum fsl_rtos_status

Enumerator
kSuccess | Functions work correctly.
kError | Functions work failed.
kTimeout | Timeout occurs while waiting for an object.
kIdle | Can not get the object in non-blocking mode.

enum event_status

Enumerator
kFlagNotSet | The flags checked are set.
kFlagSet | The flags checked are not set.

enum event_clear_type

Enumerator
kEventAutoClr | The flags of the event will be cleared automatically.
kEventManualClr | The flags of the event will be cleared manually.

## Function Documentation

fsl_rtos_status sync_create | ( | sync_object_t * | obj,
|  | uint8_t | initValue
| ) |  |

Parameters

  obj | The sync object to initialize.
  initValue | The initial value the object will be set to.

Return values

  kSuccess | The object was successfully created.
  kError | Invalid parameter or no more objects can be created.

fsl_rtos_status sync_wait | ( | sync_object_t * | obj,
|  | uint32_t | timeout
| ) |  |

This function checks the sync object's counting value, if it is positive, decreases it and returns kSuccess, otherwise, timeout will be used for wait.

Parameters

  obj | Pointer to the synchronization object.
  timeout | The maximum number of milliseconds to wait for the object to be signalled. Pass the kSyncWaitForever constant to wait indefinitely for someone to signal the object. A value of 0 should not be passed to this function. Instead, use sync_poll for a non blocking check.

Return values

  kSuccess | The object was signalled.
  kTimeout | A timeout occurred.
  kError | An incorrect parameter was passed.
  kIdle | The object has not been signalled.

Note
  There could be only one process waiting for the object at the same time.

fsl_rtos_status sync_poll | ( | sync_object_t * | obj | ) |

This function is used to poll a sync object's status. If the sync object's counting value is positive, decrease it and return kSuccess. If the object's counting value is 0, the function will return kIdle immediately

Parameters

  obj | The synchronization object.

Return values

  kSuccess | The object was signalled.
  kIdle | The object was not signalled.
  kError | An incorrect parameter was passed.

fsl_rtos_status sync_signal | ( | sync_object_t * | obj | ) |

This function should not be called from an ISR.

Parameters

  obj | The synchronization object to signal.

Return values

  kSuccess | The object was successfully signaled.
  kError | The object can not be signaled or invalid parameter.

fsl_rtos_status sync_signal_from_isr | ( | sync_object_t * | obj | ) |

This function should only be called from an ISR.

Parameters

  obj | The synchronization object to signal.

Return values

  kSuccess | The object was successfully signaled.
  kError | The object can not be signaled or invalid parameter.

fsl_rtos_status sync_destroy | ( | sync_object_t * | obj | ) |

Parameters

  obj | The synchronization object to destroy.

Return values

  kSuccess | The object was successfully destroyed.
  kError | Object destruction failed.

fsl_rtos_status lock_create | ( | lock_object_t * | obj | ) |

Parameters

  obj | The lock object to initialize.

Return values

  kSuccess | The lock is created successfully.
  kError | Tke lock creation failed.

fsl_rtos_status lock_wait | ( | lock_object_t * | obj,
|  | uint32_t | timeout
| ) |  |

This function will wait for some time or wait forever if could not get the lock.

Parameters

  obj | The locking object.
  timeout | The maximum number of milliseconds to wait for the mutex. Pass the kSyncWaitForever constant to wait indefinitely for someone to unlock the object. A value of 0 should not be passed to this function. Instead, use lock_poll for a non blocking check.

Return values

  kSuccess | The lock was obtained.
  kTimeout | A timeout occurred.
  kError | An incorrect parameter was passed.

fsl_rtos_status lock_poll | ( | lock_object_t * | obj | ) |

This function returns instantly if could not get the lock.

Parameters

  obj | The locking object.

Return values

  kSuccess | The lock was obtained.
  kIdle | The lock could not be obtained.
  kError | An incorrect parameter was passed.

Note
  There could be only one process waiting for the object at the same time. For RTOSes, wait for a lock recursively by one task is not supported.

fsl_rtos_status lock_release | ( | lock_object_t * | obj | ) |

Parameters

  obj | The locking object to unlock.

Return values

  kSuccess | The object was successfully unlocked.
  kError | The object can not be unlocked or invalid parameter.

fsl_rtos_status lock_destroy | ( | lock_object_t * | obj | ) |

Parameters

  obj | The locking object to destroy.

Return values

  kSuccess | The object was successfully destroyed.
  kError | Object destruction failed.

fsl_rtos_status event_create | ( | event_object_t * | obj,
|  | event_clear_type | clearType
| ) |  |

When the object is created, the flags is 0.

Parameters

  obj | Pointer to the event object to initialize.
  clearType | The event is auto-clear or manual-clear.

Return values

  kSuccess | The object was successfully created.
  kError | Incorrect parameter or no more objects can be created.

fsl_rtos_status event_wait | ( | event_object_t * | obj,
|  | uint32_t | timeout,
|  | event_group_t * | setFlags
| ) |  |

This function will wait for some time or wait forever if no flags are set. Any flags set will wake up the function.

Parameters

  obj | The event object.
  timeout | The maximum number of milliseconds to wait for the event. Pass the kSyncWaitForever constant to wait indefinitely. A value of 0 should not be passed to this function.
  setFlags | Pointer to receive the flags that were set.

Return values

  kSuccess | An event was set.
  kTimeout | A timeout occurred.
  kError | An incorrect parameter was passed.

fsl_rtos_status event_set | ( | event_object_t * | obj,
|  | event_group_t | flags
| ) |  |

This function should not be called from an ISR.

Parameters

  obj | The event object.
  flags | Event flags to be set.

Return values

  kSuccess | The flags were successfully set.
  kError | An incorrect parameter was passed.

Note
  There could be only one process waiting for the event.

fsl_rtos_status event_set_from_isr | ( | event_object_t * | obj,
|  | event_group_t | flags
| ) |  |

This function should only be called from an ISR.

Parameters

  obj | The event object.
  flags | Event flags to be set.

Return values

  kSuccess | The flags were successfully set.
  kError | An incorrect parameter was passed.

fsl_rtos_status event_clear | ( | event_object_t * | obj,
|  | event_group_t | flags
| ) |  |

This function should not be called from an ISR.

Parameters

  obj | The event object.
  flags | Event flags to be clear.

Return values

  kSuccess | The flags were successfully cleared.
  kError | An incorrect parameter was passed.

event_status event_check_flags | ( | event_object_t * | obj,
|  | event_group_t | flag
| ) |  |

Parameters

  obj | The event object.
  flag | The flag to check.

Return values

  kFlagsSet | The flags checked are set.
  kFlagsNotSet | The flags checked are not set or got an error.

fsl_rtos_status event_destroy | ( | event_object_t * | obj | ) |

Parameters

  obj | The event object to destroy.

Return values

  kSuccess | The object was successfully destroyed.
  kError | Event destruction failed.

fsl_rtos_status __task_create | ( | task_t | task,
|  | uint8_t * | name,
|  | uint16_t | stackSize,
|  | task_stack_t * | stackMem,
|  | uint16_t | priority,
|  | void * | param,
|  | bool | usesFloat,
|  | task_handler_t * | handler
| ) |  |

This function is wrapped by the macro task_create. Generally, this function is for internal use only, applications must use FSL_RTOS_TASK_DEFINE to define resources for task statically then use task_create to create task. If applications have prepare the resouces for task dynamically, they can use this function to create the task.

Parameters

  task | The task function.
  name | The name of this task.
  stackSize | The stack size in byte.
  stackMem | Pointer to the stack. For bare metal, Freescale MQX RTOS, and FreeRTOS, this could be NULL.
  priority | Initial priority of the task.
  param | Pointer to be passed to the task when it is created.
  usesFloat | This task will use float register or not.
  handler | Pointer to the task handler.

Return values

  kSuccess | The task was successfully created.
  kError | The task could not be created.

Note
  Different tasks can not use the same task function.

fsl_rtos_status task_destroy | ( | task_handler_t | handler | ) |

Note
  Depending on the RTOS, task resources may or may not be automatically freed, and this function may not return if the current task is destroyed.

Parameters

  handler | The handler of the task to destroy. Returned by the task_create function.

Return values

  kSuccess | The task was successfully destroyed.
  kError | Task destruction failed or invalid parameter.

msg_queue_handler_t msg_queue_create | ( | msg_queue_t * | queue,
|  | uint16_t | number,
|  | uint16_t | size
| ) |  |

This function will initialize the message queue that declared previously. Here is an example demonstrating how to use:

msg_queue_handler_t handler;
MSG_QUEUE_DECLARE(my_message, msg_num, msg_size);
handler = msg_queue_create(&my_message, msg_num, msg_size);

Parameters

  queue | The queue declared through the MSG_QUEUE_DECLARE macro.
  number | The number of elements in the queue.
  size | Size of every elements in words.

Return values

  Handler | to access the queue for put and get operations. If message queue created failed, return 0.

fsl_rtos_status msg_queue_put | ( | msg_queue_handler_t | handler,
|  | msg_queue_item_t | item
| ) |  |

Parameters

  handler | Queue handler returned by the msg_queue_create function.
  item | Pointer to the element to be introduced in the queue.

Return values

  kSuccess | Element successfully introduced in the queue.
  kError | The queue was full or an invalid parameter was passed.

fsl_rtos_status msg_queue_get | ( | msg_queue_handler_t | handler,
|  | msg_queue_item_t * | item,
|  | uint32_t | timeout
| ) |  |

Parameters

  handler | Queue handler returned by the msg_queue_create function.
  item | Pointer to store a pointer to the element of the queue.
  timeout | In case the queue is empty, the number of milliseconds to wait for an element to be introduced into the queue. Use 0 to return immediately or kSyncWaitForever to wait indefinitely.

Return values

  kSuccess | Element successfully obtained from the queue.
  kTimeout | If a timeout was specified, the queue remained empty after timeout.
  kError | The queue was empty or the handler was invalid.
  kIdle | The queue was empty and the timeout has not expired.

Note
  There should be only one process waiting on the queue.

fsl_rtos_status msg_queue_flush | ( | msg_queue_handler_t | handler | ) |

Parameters

  handler | Queue handler returned by the msg_queue_create function.

Return values

  kSuccess | Queue successfully emptied.
  kError | Emptying queue failed.

fsl_rtos_status msg_queue_destroy | ( | msg_queue_handler_t | handler | ) |

Parameters

  handler | Queue handler returned by the msg_queue_create function.

Return values

  kSuccess | The queue was successfully destroyed.
  kError | Message queue destruction failed.

void* mem_allocate | ( | size_t | size | ) |

Parameters

  size | Amount of bytes to reserve.

Return values

  Pointer | to the reserved memory. NULL if memory could not be allocated.

void* mem_allocate_zero | ( | size_t | size | ) |

Parameters

  size | Amount of bytes to reserve.

Return values

  Pointer | to the reserved memory. NULL if memory could not be allocated.

fsl_rtos_status mem_free | ( | void * | ptr | ) |

Parameters

  ptr | Pointer to the start of the memory block previously reserved.

Return values

  kSuccess | Memory correctly released.

void time_delay | ( | uint32_t | delay | ) |

Parameters

  delay | The time in milliseconds to wait.

fsl_rtos_status interrupt_handler_register | ( | int32_t | irqNumber,
|  | void(*)(void) | handler
| ) |  |

Parameters

  irqNumber | IRQ number of the interrupt.
  handler | The interrupt handler to install.

Return values

  kSuccess | Handler is installed successfully.
  kSuccess | Handler could not be installed.