Kernel Semaphore API#

OSSemCreate()
OSSemDel()
OSSemPend()
OSSemPendAbort()
OSSemPost()
OSSemSet()

OSSemCreate()#

Description#

Creates a semaphore.

Files#

os.h/os_sem.c

Prototype#

void  OSSemCreate (OS_SEM      *p_sem,
                   CPU_CHAR    *p_name,
                   OS_SEM_CTR   cnt,
                   RTOS_ERR    *p_err)

Arguments#

p_sem

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

p_name

Pointer to the name to assign to the semaphore.

cnt

The initial value for the semaphore.

If used to share resources, you should initialize to the number of resources available.
If used to signal the occurrence of event(s), you should initialize to 0.

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.

OSSemDel()#

Description#

Deletes a semaphore.

Files#

os.h/os_sem.c

Prototype#

OS_OBJ_QTY  OSSemDel (OS_SEM    *p_sem,
                      OS_OPT     opt,
                      RTOS_ERR  *p_err)

Arguments#

p_sem

Pointer to the semaphore to delete.

opt

Determines delete options as follows:

OS_OPT_DEL_NO_PEND Deletes the semaphore ONLY if there are no pending tasks.
OS_OPT_DEL_ALWAYS Deletes the semaphore even if tasks are waiting. In this case, all the 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 were no tasks waiting on the semaphore, or upon error.
> 0 If one or more tasks waiting on the semaphore that are now readied and informed.

Notes / Warnings#

Use this function with care. Tasks that would normally expect the presence of the semaphore MUST check the return code of OSSemPend().
Because ALL tasks pending on the semaphore will be readied, be careful with applications where the semaphore is used for mutual exclusion because the resource(s) will no longer be guarded by the semaphore.

OSSemPend()#

Description#

Waits for a semaphore.

Files#

os.h/os_sem.c

Prototype#

OS_SEM_CTR  OSSemPend (OS_SEM    *p_sem,
                       OS_TICK    timeout,
                       OS_OPT     opt,
                       CPU_TS    *p_ts,
                       RTOS_ERR  *p_err)

Arguments#

p_sem

Pointer to the semaphore.

timeout

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

opt

Determines whether the user wants to block if the semaphore 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 receives the timestamp of when the semaphore was posted or pending aborted or the semaphore 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_OS_OBJ_DEL
RTOS_ERR_WOULD_BLOCK
RTOS_ERR_OS_SCHED_LOCKED
RTOS_ERR_ABORT
RTOS_ERR_TIMEOUT

Returned Value#

The current value of the semaphore counter, or 0 if not available.

Notes / Warnings#

None.

OSSemPendAbort()#

Description#

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

Files#

os.h/os_sem.c

Prototype#

OS_OBJ_QTY  OSSemPendAbort (OS_SEM    *p_sem,
                            OS_OPT     opt,
                            RTOS_ERR  *p_err)

Arguments#

p_sem

Pointer to the semaphore.

opt

Determines the type of ABORT performed:

OS_OPT_PEND_ABORT_1 ABORT waits for a single task (HPT) waiting on the semaphore.
OS_OPT_PEND_ABORT_ALL ABORT waits for ALL tasks that are waiting on the semaphore.
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 no tasks were waiting on the semaphore, or upon error.
> 0 If one or more tasks waiting on the semaphore are now readied and informed.

Notes / Warnings#

None.

OSSemPost()#

Description#

Signals a semaphore.

Files#

os.h/os_sem.c

Prototype#

OS_SEM_CTR  OSSemPost (OS_SEM    *p_sem,
                       OS_OPT     opt,
                       RTOS_ERR  *p_err)

Arguments#

p_sem

Pointer to the semaphore.

opt

Determines the type of POST performed:

OS_OPT_POST_1 POST and ready only the highest priority task waiting on semaphore (if tasks are waiting).
OS_OPT_POST_ALL POST to ALL tasks that are waiting on the semaphore.
OS_OPT_POST_NO_SCHED Do not call the scheduler.

Note(s):

OS_OPT_POST_NO_SCHED can be added with one of the other options.

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

Returned Value#

The current value of the semaphore counter or 0 upon error.

Notes / Warnings#

None.

OSSemSet()#

Description#

Sets the semaphore count to the value specified as an argument. Typically this value would be 0, but you can set the semaphore to any value.

Files#

os.h/os_sem.c

Prototype#

void  OSSemSet (OS_SEM      *p_sem,
                OS_SEM_CTR   cnt,
                RTOS_ERR    *p_err)

Arguments#

p_sem

Pointer to the semaphore.

cnt

The new value for the semaphore count. You would pass 0 to reset the semaphore count.

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_TASK_WAITING

Returned Value#

None.

Notes / Warnings#

None.