Kernel Mutex API#

OSMutexCreate()#

Description#

Creates a mutex so that multiple program threads can take turns sharing the same resource.

Files#

os.h/os_mutex.c

Prototype#

void  OSMutexCreate (OS_MUTEX  *p_mutex,
                     CPU_CHAR  *p_name,
                     RTOS_ERR  *p_err)

Arguments#

p_mutex

Pointer to the mutex to initialize. Your application is responsible for allocating storage for the mutex.

p_name

Pointer to the name you would like to give the mutex.

p_err

Pointer to the variable that will receive one of the following error code(s) from this function:

  • RTOS_ERR_NONE

  • RTOS_ERR_OS_ILLEGAL_RUN_TIME

Returned Value#

None.

Notes / Warnings#

None.

OSMutexDel()#

Description#

Deletes a mutex and readies all tasks pending on the mutex.

Files#

os.h/os_mutex.c

Prototype#

OS_OBJ_QTY  OSMutexDel (OS_MUTEX  *p_mutex,
                        OS_OPT     opt,
                        RTOS_ERR  *p_err)

Arguments#

p_mutex

Pointer to the mutex to delete.

opt

Determines delete options as follows:

OS_OPT_DEL_NO_PEND Deletes the mutex ONLY if no tasks are pending. OS_OPT_DEL_ALWAYS Deletes the mutex even if tasks are waiting. In this case, all pending tasks will be readied.

p_err

Pointer to the variable that will receive one of the following error code(s) from this function:

  • RTOS_ERR_NONE

  • RTOS_ERR_OS_ILLEGAL_RUN_TIME

  • RTOS_ERR_OS_TASK_WAITING

Returned Value#

  • == 0 If there are no tasks waiting on the mutex, or upon error.

  • > 0 If there are one or more tasks waiting on the mutex that are now readied and informed.

Notes / Warnings#

  1. Use this function with care. Tasks that would normally expect the presence of the mutex MUST check the return code of OSMutexPend().

  2. Because ALL tasks pending on the mutex will be readied, be careful in applications where the mutex is used for mutual exclusion because the resource(s) will no longer be guarded by the mutex.

OSMutexPend()#

Description#

This function waits for a mutex.

Files#

os.h/os_mutex.c

Prototype#

void  OSMutexPend (OS_MUTEX  *p_mutex,
                   OS_TICK    timeout,
                   OS_OPT     opt,
                   CPU_TS    *p_ts,
                   RTOS_ERR  *p_err)

Arguments#

p_mutex

Pointer to the mutex.

timeout

Optional timeout period (in clock ticks). If non-zero, the task will wait for the resource up to the amount of time (in 'ticks') specified by this argument. If you specify 0, the task will wait forever at the specified mutex, or until the resource becomes available.

opt

Determines whether the feature to block if the mutex is available or not:

  • OS_OPT_PEND_BLOCKING Task will block.

  • OS_OPT_PEND_NON_BLOCKING Task will NOT block.

p_ts

Pointer to a variable that will receive the timestamp of when the mutex was posted or pend aborted or the mutex deleted. If you pass a NULL pointer (i.e., (CPU_TS *)0), you will not get the timestamp. In other words, passing a NULL pointer is valid and indicates that you don't need the timestamp.

p_err

Pointer to the variable that will receive one of the following error code(s) from this function:

  • RTOS_ERR_NONE

  • RTOS_ERR_WOULD_OVF

  • RTOS_ERR_OS_OBJ_DEL

  • RTOS_ERR_WOULD_BLOCK

  • RTOS_ERR_IS_OWNER (see note (1))

  • RTOS_ERR_OS_SCHED_LOCKED

  • RTOS_ERR_ABORT

  • RTOS_ERR_TIMEOUT

Returned Value#

None.

Notes / Warnings#

  1. A mutex can be nested, so RTOS_ERR_IS_OWNER error can be used as an indicator that you are nesting the mutex. If the correct number of Post is done the mutex will be released.

OSMutexPendAbort()#

Description#

Aborts and readies any tasks currently waiting on a mutex. Rather than signal the mutex via OSMutexPost(), use this function to fault-abort the wait on the mutex.

Files#

os.h/os_mutex.c

Prototype#

OS_OBJ_QTY  OSMutexPendAbort (OS_MUTEX  *p_mutex,
                              OS_OPT     opt,
                              RTOS_ERR  *p_err)

Arguments#

p_mutex

Pointer to the mutex.

opt

Determines the type of ABORT performed:

  • OS_OPT_PEND_ABORT_1 ABORT wait for a single task (HPT) waiting on the mutex.

  • OS_OPT_PEND_ABORT_ALL ABORT wait for ALL tasks that are waiting on the mutex.

  • OS_OPT_POST_NO_SCHED Do not call the scheduler.

p_err

Pointer to the variable that will receive one of the following error code(s) from this function:

  • RTOS_ERR_NONE

  • RTOS_ERR_NONE_WAITING

Returned Value#

  • == 0 If there were no tasks waiting on the mutex, or upon error.

  • > 0 If there were one or more tasks waiting on the mutex are now ready and informed.

Notes / Warnings#

None.

OSMutexPost()#

Description#

Signals a mutex.

Files#

os.h/os_mutex.c

Prototype#

void  OSMutexPost (OS_MUTEX  *p_mutex,
                   OS_OPT     opt,
                   RTOS_ERR  *p_err)

Arguments#

p_mutex

Pointer to the mutex.

opt

Option that alters the behavior of the post. The choices are:

  • OS_OPT_POST_NONE No special option selected.

  • OS_OPT_POST_NO_SCHED If you don't want the scheduler to be called after the post.

p_err

Pointer to the variable that will receive one of the following error code(s) from this function:

  • RTOS_ERR_NONE

  • RTOS_ERR_OWNERSHIP

  • RTOS_ERR_IS_OWNER

Returned Value#

None.

Notes / Warnings#

None.