Maestro Audio Framework  v 1.0
NXP Semiconductors
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

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

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
attrAttribute structure. This will be initialized and returned as output.
Return values
ERRCODE_NO_ERRORAttribute structure successfully initialized.
ERRCODE_OUT_OF_MEMORYNo memory available.

◆ osa_thread_attr_destroy()

void osa_thread_attr_destroy ( OsaThreadAttr attr)

Free memory for a thread attribute structure.

Parameters
attrAttribute 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
attrA valid thread attribute object
sizeThe maximum stack size
Return values
ERRCODE_NO_ERRORFunction succeeded
ERRCODE_INVALID_ARGUMENTInvalid 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
attrA valid thread attribute object
sizeAn output parameter that will store the stack size
Return values
ERRCODE_NO_ERRORFunction succeeded
ERRCODE_INVALID_ARGUMENTInvalid 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
attrA valid thread attribute object
policyThe scheduling policy
Return values
ERRCODE_NO_ERRORFunction succeeded
ERRCODE_INVALID_ARGUMENTInvalid 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
attrA valid thread attribute object
policyAn output parameter that will store the policy
Return values
ERRCODE_NO_ERRORFunction succeeded
ERRCODE_INVALID_ARGUMENTInvalid 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
attrA valid thread attribute object
priorityThe scheduling policy
Return values
ERRCODE_NO_ERRORFunction succeeded
ERRCODE_INVALID_ARGUMENTInvalid 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
attrA valid thread attribute object
priorityAn output parameter that will store the priority
Return values
ERRCODE_NO_ERRORFunction succeeded
ERRCODE_INVALID_ARGUMENTInvalid 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
attrA valid thread attribute object
intervalThe scheduling interval, in milliseconds
Return values
ERRCODE_NO_ERRORFunction succeeded
ERRCODE_INVALID_ARGUMENTInvalid 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
attrA valid thread attribute object
intervalAn output parameter that will store the interval
Return values
ERRCODE_NO_ERRORFunction succeeded
ERRCODE_INVALID_ARGUMENTInvalid 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
attrA valid thread attribute object
nameName for the thread (max of OSA_MAX_THREAD_NAME_LENGTH)
Return values
ERRCODE_NO_ERRORFunction succeeded
ERRCODE_INVALID_ARGUMENTInvalid 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
threadOutput argument that is returned to the caller that represents the ID of the newly-created thread.
functionThe entry function for the new thread
attrA valid thread attribute object or NULL
argThe argument to be passed to the new thread entry point
Return values
ERRCODE_NO_ERRORFunction succeeded
ERRCODE_OUT_OF_MEMORYOut of memory
ERRCODE_INVALID_ARGUMENTInvalid input parameters. Thread attributes could be invalid.
ERRCODE_TRY_AGAINExceeded system limits for threads.
ERRCODE_GENERAL_ERRORUnexpected system error.

◆ osa_thread_destroy()

int osa_thread_destroy ( OsaThread  thread)
Parameters
threadThe thread represented with this object will be destroyed.
Return values
ERRCODE_NO_ERRORFunction succeeded
ERRCODE_OUT_OF_MEMORYOut of memory
ERRCODE_INVALID_ARGUMENTInvalid input parameters. Thread attributes could be invalid.
ERRCODE_TRY_AGAINExceed system limits for threads
ERRCODE_GENERAL_ERRORUnexpected 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
threadThe thread to wait on for termination.
valueNot currently used, will be set to zero.
Return values
ERRCODE_NO_ERRORFunction succeeded
ERRCODE_INVALID_ARGUMENTInvalid input parameters
ERRCODE_DEADLOCKTwo threads attempted to join with each other
ERRCODE_GENERAL_ERRORUnexpected 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
valueData 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
threadA valid thread object
tidOutput parameter holding the thread id
Return values
ERRCODE_NO_ERRORFunction succeeded
ERRCODE_INVALID_ARGUMENTInvalid thread parameter

◆ osa_sched_set_policy()

int osa_sched_set_policy ( OsaThread  thread,
OsaSchedPolicy  policy 
)

Set the scheduling policy for a thread.

Parameters
threadA valid thread object
policyThe scheduling policy
Return values
ERRCODE_NO_ERRORFunction succeeded
ERRCODE_INVALID_ARGUMENTInvalid 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
threadA valid thread object
policyOutput parameter to store the scheduling policy
Return values
ERRCODE_NO_ERRORFunction succeeded
ERRCODE_INVALID_ARGUMENTInvalid 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
threadA valid thread object
priorityThe scheduling priority
Return values
ERRCODE_NO_ERRORFunction succeeded
ERRCODE_INVALID_ARGUMENTInvalid 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
threadA valid thread object
priorityOutput parameter to store the scheduling priority
Return values
ERRCODE_NO_ERRORFunction succeeded
ERRCODE_INVALID_ARGUMENTInvalid 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
threadA valid thread object
intervalThe scheduling interval in milliseconds. The task will execute for this much time before yielding the processor.
Return values
ERRCODE_NO_ERRORFunction succeeded
ERRCODE_INVALID_ARGUMENTInvalid thread object or interval out of range
ERRCODE_NOT_SUPPORTEDNot 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
threadA valid thread object
intervalOutput parameter used to store the scheduling interval
Return values
ERRCODE_NO_ERRORFunction succeeded
ERRCODE_INVALID_ARGUMENTInvalid thread object or interval out of range
ERRCODE_NOT_SUPPORTEDNot 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
threadA valid thread object
namename string
Return values
ERRCODE_NO_ERRORFunction succeeded
ERRCODE_INVALID_ARGUMENTInvalid thread object or invalid name
ERRCODE_NOT_FOUNDNo 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
threadA valid thread object
namename string
Return values
ERRCODE_NO_ERRORFunction succeeded
ERRCODE_INVALID_ARGUMENTInvalid thread object or invalid name
ERRCODE_NOT_FOUNDNo name string (MQX only)