| Maestro Audio Framework v 1.0 NXP Semiconductors

Data Structures | Macros | Enumerations | Functions
osa_thread.h File Reference

Contains thread function prototypes for libosa. More...

## Data Structures
struct | OsaThreadAttr
| Thread Attributes. More...

## Macros
#define | OSA_MAX_THREAD_NAME_LENGTH 40

## Enumerations
enum | OsaSchedPriority { OSA_SCHED_PRIORITY_LOW = 0 , OSA_SCHED_PRIORITY_NORMAL , OSA_SCHED_PRIORITY_HIGH , OSA_SCHED_PRIORITY_URGENT }
| Scheduler Priority Enumeration of possible priorities for thread scheduling. More...
enum | OsaSchedPolicy { OSA_SCHED_POLICY_FIFO = 0 , OSA_SCHED_POLICY_RR , OSA_SCHED_POLICY_OTHER }
| Scheduler Policy Enumeration of scheduling policies for threads. More...

## Functions
int | osa_thread_attr_init (OsaThreadAttr *attr)
| Initialize a thread attribute structure. More...
void | osa_thread_attr_destroy (OsaThreadAttr *attr)
| Destroy a thread attribute structure. More...
int | osa_thread_attr_set_stack_size (OsaThreadAttr *attr, size_t size)
| Set thread attribute maximum stack size. More...
int | osa_thread_attr_get_stack_size (const OsaThreadAttr *attr, size_t *size)
| Get thread attribute maximum stack size. More...
int | osa_thread_attr_set_sched_policy (OsaThreadAttr *attr, OsaSchedPolicy policy)
| Set thread attribute scheduling policy. More...
int | osa_thread_attr_get_sched_policy (const OsaThreadAttr *attr, OsaSchedPolicy *policy)
| Get thread attribute scheduling policy. More...
int | osa_thread_attr_set_sched_priority (OsaThreadAttr *attr, OsaSchedPriority priority)
| Set thread attribute scheduling priority. More...
int | osa_thread_attr_get_sched_priority (const OsaThreadAttr *attr, OsaSchedPriority *priority)
| Get thread attribute scheduling priority. More...
int | osa_thread_attr_set_sched_interval (OsaThreadAttr *attr, uint32_t interval)
| Set thread attribute scheduling interval. More...
int | osa_thread_attr_get_sched_interval (const OsaThreadAttr *attr, uint32_t *interval)
| Get thread attribute scheduling interval. More...
int | osa_thread_attr_set_name (OsaThreadAttr *attr, const char *name)
| Set thread name attribute. More...
int | osa_thread_create (OsaThread *thread, const OsaThreadAttr *attr, void(*function)(void *), void *arg)
| Create a new thread. More...
int | osa_thread_destroy (OsaThread thread)
| Destroy a thread. More...
OsaThread | osa_thread_self (void)
| Obtain ID of the calling thread. More...
int | osa_thread_join (OsaThread thread, void **value)
| Join with a terminated thread. More...
void | osa_thread_yield (void)
| Yield a thread. More...
void | osa_thread_exit (void *value)
| Terminate a thread. More...
int | osa_thread_get_id (OsaThread thread, uint32_t *tid)
| Return an ID for a thread. More...
int | osa_sched_set_policy (OsaThread thread, OsaSchedPolicy policy)
| Set thread scheduling policy. More...
int | osa_sched_get_policy (OsaThread thread, OsaSchedPolicy *policy)
| Get thread scheduling policy. More...
int | osa_sched_set_priority (OsaThread thread, OsaSchedPriority priority)
| Set thread scheduling priority. More...
int | osa_sched_get_priority (OsaThread thread, OsaSchedPriority *priority)
| Get thread scheduling priority. More...
int | osa_sched_set_rr_interval (OsaThread thread, uint32_t interval)
| Set thread scheduling interval. More...
int | osa_sched_get_rr_interval (OsaThread thread, uint32_t *interval)
| Get thread scheduling interval. More...
int | osa_thread_get_name (OsaThread thread, char **name)
| Get thread name. More...
int | osa_thread_set_name (OsaThread thread, const char *name)
| Set thread name. More...

## Enumeration Type Documentation

## ◆ OsaSchedPriority

enum OsaSchedPriority

Enumerator
OSA_SCHED_PRIORITY_LOW | Low priority.
OSA_SCHED_PRIORITY_NORMAL | Normal priority.
OSA_SCHED_PRIORITY_HIGH | High priority.
OSA_SCHED_PRIORITY_URGENT | Urgent priority.

## ◆ OsaSchedPolicy

enum OsaSchedPolicy

Warning
  OSA_SCHED_POLICY_OTHER is only valid for Linux.

Enumerator
OSA_SCHED_POLICY_FIFO | FIFO policy.
OSA_SCHED_POLICY_RR | Round-robin policy.
OSA_SCHED_POLICY_OTHER | Other policy (non-real-time)

## Function Documentation

## ◆ osa_thread_attr_init()

int osa_thread_attr_init | ( | OsaThreadAttr * | attr | ) |

Allocate memory for a thread attribute structure and initialize the parameters to default values.

Parameters

  attr | Attribute structure. This will be initialized and returned as output.

Return values

  ERRCODE_NO_ERROR | Attribute structure successfully initialized.
  ERRCODE_OUT_OF_MEMORY | No memory available.

## ◆ osa_thread_attr_destroy()

void osa_thread_attr_destroy | ( | OsaThreadAttr * | attr | ) |

Free memory for a thread attribute structure.

Parameters

  attr | Attribute structure. The memory initialized in osa_thread_attr_init will be freed.

## ◆ osa_thread_attr_set_stack_size()

int osa_thread_attr_set_stack_size | ( | OsaThreadAttr * | attr,
|  | size_t | size
| ) |  |

Set the stack size for a thread attribute object.

Parameters

  attr | A valid thread attribute object
  size | The maximum stack size

Return values

  ERRCODE_NO_ERROR | Function succeeded
  ERRCODE_INVALID_ARGUMENT | Invalid attribute object or stack size outside of limits

## ◆ osa_thread_attr_get_stack_size()

int osa_thread_attr_get_stack_size | ( | const OsaThreadAttr * | attr,
|  | size_t * | size
| ) |  |

Retrieve the stack size for a thread attribute object.

Parameters

  attr | A valid thread attribute object
  size | An output parameter that will store the stack size

Return values

  ERRCODE_NO_ERROR | Function succeeded
  ERRCODE_INVALID_ARGUMENT | Invalid attribute object or NULL size pointer

## ◆ osa_thread_attr_set_sched_policy()

int osa_thread_attr_set_sched_policy | ( | OsaThreadAttr * | attr,
|  | OsaSchedPolicy | policy
| ) |  |

Set the scheduling policy for a thread attribute object.

Parameters

  attr | A valid thread attribute object
  policy | The scheduling policy

Return values

  ERRCODE_NO_ERROR | Function succeeded
  ERRCODE_INVALID_ARGUMENT | Invalid attribute object or policy

## ◆ osa_thread_attr_get_sched_policy()

int osa_thread_attr_get_sched_policy | ( | const OsaThreadAttr * | attr,
|  | OsaSchedPolicy * | policy
| ) |  |

Retrieve the scheduling policy for a thread attribute object.

Parameters

  attr | A valid thread attribute object
  policy | An output parameter that will store the policy

Return values

  ERRCODE_NO_ERROR | Function succeeded
  ERRCODE_INVALID_ARGUMENT | Invalid attribute object or NULL policy pointer

## ◆ osa_thread_attr_set_sched_priority()

int osa_thread_attr_set_sched_priority | ( | OsaThreadAttr * | attr,
|  | OsaSchedPriority | priority
| ) |  |

Set the scheduling policy for a thread attribute object.

Parameters

  attr | A valid thread attribute object
  priority | The scheduling policy

Return values

  ERRCODE_NO_ERROR | Function succeeded
  ERRCODE_INVALID_ARGUMENT | Invalid attribute object or priority

## ◆ osa_thread_attr_get_sched_priority()

int osa_thread_attr_get_sched_priority | ( | const OsaThreadAttr * | attr,
|  | OsaSchedPriority * | priority
| ) |  |

Retrieve the scheduling priority for a thread attribute object.

Parameters

  attr | A valid thread attribute object
  priority | An output parameter that will store the priority

Return values

  ERRCODE_NO_ERROR | Function succeeded
  ERRCODE_INVALID_ARGUMENT | Invalid attribute object or NULL priority pointer

## ◆ osa_thread_attr_set_sched_interval()

int osa_thread_attr_set_sched_interval | ( | OsaThreadAttr * | attr,
|  | uint32_t | interval
| ) |  |

Set the scheduling interval for a thread attribute object.

Parameters

  attr | A valid thread attribute object
  interval | The scheduling interval, in milliseconds

Return values

  ERRCODE_NO_ERROR | Function succeeded
  ERRCODE_INVALID_ARGUMENT | Invalid attribute object or interval

## ◆ osa_thread_attr_get_sched_interval()

int osa_thread_attr_get_sched_interval | ( | const OsaThreadAttr * | attr,
|  | uint32_t * | interval
| ) |  |

Retrieve the scheduling interval for a thread attribute object.

Parameters

  attr | A valid thread attribute object
  interval | An output parameter that will store the interval

Return values

  ERRCODE_NO_ERROR | Function succeeded
  ERRCODE_INVALID_ARGUMENT | Invalid attribute object or NULL interval pointer

## ◆ osa_thread_attr_set_name()

int osa_thread_attr_set_name | ( | OsaThreadAttr * | attr,
|  | const char * | name
| ) |  |

Set the name to represent a thread in the attribute structure

Parameters

  attr | A valid thread attribute object
  name | Name for the thread (max of OSA_MAX_THREAD_NAME_LENGTH)

Return values

  ERRCODE_NO_ERROR | Function succeeded
  ERRCODE_INVALID_ARGUMENT | Invalid attribute object or NULL interval pointer

## ◆ osa_thread_create()

int osa_thread_create | ( | OsaThread * | thread,
|  | const OsaThreadAttr * | attr,
|  | void(*)(void *) | function,
|  | void * | arg
| ) |  |

Create a new thread of execution starting at the given function as an entry point. The new thread properties will be defined in 'attr'. Passing in NULL will use default properties. 'arg' is passed as the function argument to the new thread. The new thread may or may not be scheduled immediately.

Parameters

  thread | Output argument that is returned to the caller that represents the ID of the newly-created thread.
  function | The entry function for the new thread
  attr | A valid thread attribute object or NULL
  arg | The argument to be passed to the new thread entry point

Return values

  ERRCODE_NO_ERROR | Function succeeded
  ERRCODE_OUT_OF_MEMORY | Out of memory
  ERRCODE_INVALID_ARGUMENT | Invalid input parameters. Thread attributes could be invalid.
  ERRCODE_TRY_AGAIN | Exceeded system limits for threads.
  ERRCODE_GENERAL_ERROR | Unexpected system error.

## ◆ osa_thread_destroy()

int osa_thread_destroy | ( | OsaThread | thread | ) |

Parameters

  thread | The thread represented with this object will be destroyed.

Return values

  ERRCODE_NO_ERROR | Function succeeded
  ERRCODE_OUT_OF_MEMORY | Out of memory
  ERRCODE_INVALID_ARGUMENT | Invalid input parameters. Thread attributes could be invalid.
  ERRCODE_TRY_AGAIN | Exceed system limits for threads
  ERRCODE_GENERAL_ERROR | Unexpected system error

## ◆ osa_thread_self()

OsaThread osa_thread_self | ( | void |  | ) |

Returns
  The ID of the calling thread. This function always succeeds.

## ◆ osa_thread_join()

int osa_thread_join | ( | OsaThread | thread,
|  | void ** | value
| ) |  |

Wait for a given thread to terminate before continuing execution.

Parameters

  thread | The thread to wait on for termination.
  value | Not currently used, will be set to zero.

Return values

  ERRCODE_NO_ERROR | Function succeeded
  ERRCODE_INVALID_ARGUMENT | Invalid input parameters
  ERRCODE_DEADLOCK | Two threads attempted to join with each other
  ERRCODE_GENERAL_ERROR | Unexpected system error

## ◆ osa_thread_yield()

void osa_thread_yield | ( | void |  | ) |

Force the currently running thread to yield the processor. This will cause another ready thread to be scheduled.

## ◆ osa_thread_exit()

void osa_thread_exit | ( | void * | value | ) |

Force the currently running thread to exit. This differs from osa_exit in that the OS/process does not exit on MQX/Linux, only the calling thread.

Parameters

  value | Data to pass back upon exit

## ◆ osa_thread_get_id()

int osa_thread_get_id | ( | OsaThread | thread,
|  | uint32_t * | tid
| ) |  |

Return a unique identifier for a specific thread.

Parameters

  thread | A valid thread object
  tid | Output parameter holding the thread id

Return values

  ERRCODE_NO_ERROR | Function succeeded
  ERRCODE_INVALID_ARGUMENT | Invalid thread parameter

## ◆ osa_sched_set_policy()

int osa_sched_set_policy | ( | OsaThread | thread,
|  | OsaSchedPolicy | policy
| ) |  |

Set the scheduling policy for a thread.

Parameters

  thread | A valid thread object
  policy | The scheduling policy

Return values

  ERRCODE_NO_ERROR | Function succeeded
  ERRCODE_INVALID_ARGUMENT | Invalid thread object or policy

## ◆ osa_sched_get_policy()

int osa_sched_get_policy | ( | OsaThread | thread,
|  | OsaSchedPolicy * | policy
| ) |  |

Get the scheduling policy for a thread.

Parameters

  thread | A valid thread object
  policy | Output parameter to store the scheduling policy

Return values

  ERRCODE_NO_ERROR | Function succeeded
  ERRCODE_INVALID_ARGUMENT | Invalid thread object or policy

## ◆ osa_sched_set_priority()

int osa_sched_set_priority | ( | OsaThread | thread,
|  | OsaSchedPriority | priority
| ) |  |

Set the scheduling priority for a thread.

Parameters

  thread | A valid thread object
  priority | The scheduling priority

Return values

  ERRCODE_NO_ERROR | Function succeeded
  ERRCODE_INVALID_ARGUMENT | Invalid thread object or priority

## ◆ osa_sched_get_priority()

int osa_sched_get_priority | ( | OsaThread | thread,
|  | OsaSchedPriority * | priority
| ) |  |

Get the scheduling priority for a thread.

Parameters

  thread | A valid thread object
  priority | Output parameter to store the scheduling priority

Return values

  ERRCODE_NO_ERROR | Function succeeded
  ERRCODE_INVALID_ARGUMENT | Invalid thread object or priority

## ◆ osa_sched_set_rr_interval()

int osa_sched_set_rr_interval | ( | OsaThread | thread,
|  | uint32_t | interval
| ) |  |

Set the scheduling interval for a thread. This is only valid if the scheduling policy of the thread is set to round robin and the OS is MQX. It's not policy to adjust RR interval on Linux.

Parameters

  thread | A valid thread object
  interval | The scheduling interval in milliseconds. The task will execute for this much time before yielding the processor.

Return values

  ERRCODE_NO_ERROR | Function succeeded
  ERRCODE_INVALID_ARGUMENT | Invalid thread object or interval out of range
  ERRCODE_NOT_SUPPORTED | Not supported (Linux only)

## ◆ osa_sched_get_rr_interval()

int osa_sched_get_rr_interval | ( | OsaThread | thread,
|  | uint32_t * | interval
| ) |  |

Get the scheduling interval for a thread.

Parameters

  thread | A valid thread object
  interval | Output parameter used to store the scheduling interval

Return values

  ERRCODE_NO_ERROR | Function succeeded
  ERRCODE_INVALID_ARGUMENT | Invalid thread object or interval out of range
  ERRCODE_NOT_SUPPORTED | Not supported (Linux only)

## ◆ osa_thread_get_name()

int osa_thread_get_name | ( | OsaThread | thread,
|  | char ** | name
| ) |  |

Get the thread name string for a thread.

Parameters

  thread | A valid thread object
  name | name string

Return values

  ERRCODE_NO_ERROR | Function succeeded
  ERRCODE_INVALID_ARGUMENT | Invalid thread object or invalid name
  ERRCODE_NOT_FOUND | No name string (MQX only)

## ◆ osa_thread_set_name()

int osa_thread_set_name | ( | OsaThread | thread,
|  | const char * | name
| ) |  |

Set the thread name string for a thread.

Parameters

  thread | A valid thread object
  name | name string

Return values

  ERRCODE_NO_ERROR | Function succeeded
  ERRCODE_INVALID_ARGUMENT | Invalid thread object or invalid name
  ERRCODE_NOT_FOUND | No name string (MQX only)