Description
Used when a task wants exclusive access to a resource, needs to synchronize its activities with an ISR or task, or is waiting until an event occurs.
When the semaphore is used for resource sharing, if a task calls OSSemPend() and the value of the semaphore is greater than 0, OSSemPend() decrements the semaphore and returns to its caller. However, if the value of the semaphore is 0, OSSemPend() places the calling task in the waiting list for the semaphore. The task waits until the owner of the semaphore (which is always a task in this case) releases the semaphore by calling OSSemPost(), or the specified timeout expires. If the semaphore is signaled before the timeout expires, µC/OS-III resumes the highest-priority task waiting for the semaphore.
When the semaphore is used as a signaling mechanism, the calling task waits until a task or an ISR signals the semaphore by calling OSSemPost(), or the specified timeout expires. If the semaphore is signaled before the timeout expires, µC/OS-III resumes the highest-priority task waiting for the semaphore.
A pended task that has been suspended with OSTaskSuspend() can obtain the semaphore. However, the task remains suspended until it is resumed by calling OSTaskResume().
OSSemPend() also returns if the pend is aborted or, the semaphore is deleted.
Files
os.h/os_sem.c
Prototype
| Code Block |
|---|
OS_SEM_CTR OSSemPend (OS_SEM *p_sem,
OS_TICK timeout,
OS_OPT opt,
CPU_TS *p_ts,
OS_ERR *p_err) |
Arguments
p_sem
is a pointer to the semaphore.
...
If OS_CFG_ARG_CHK_EN is set to 1 in DEF_ENABLED in os_cfg.h: if p_sem is a NULL pointer.
...
If OS_CFG_OBJ_TYPE_CHK_EN is set to 1 in DEF_ENABLED in os_cfg.h: if p_sem is not pointing to a semaphore.
...
If OS_CFG_ARG_CHK_EN is set to 1 in DEF_ENABLED in os_cfg.h: if opt is not OS_OPT_PEND_NON_BLOCKING or OS_OPT_PEND_BLOCKING.
OS_ERR_OS_NOT_RUNNING
If OS_CFG_INVALID_OS_CALLS_CHK_EN is set to DEF_ENABLED in os_cfg.h: if µC/OS-III is not running yet.
OS_ERR_PEND_ABORT
if the pend was aborted
...
If OS_CFG_CALLED_FROM_ISR_CHK_EN set to 1 in DEF_ENABLED in os_cfg.h: if this function is called from an ISR.
...
If calling this function when the scheduler is locked.
OS_ERR_STATUS_INVALID
If the pend status has an invalid value.
OS_ERR_TIMEOUT
If the semaphore is not signaled within the specified timeout.
Returned Value
The new value of the semaphore count.
Required Configuration
OS_CFG_SEM_EN must be enabled in os_cfg.h. Refer to uCµC-OS-III Configuration Manual.
Callers
Application.
Notes/Warnings
- Semaphores must be created before they are used.
Example Usage
| Code Block | ||
|---|---|---|
| ||
OS_SEM SwSem;
void DispTask (void *p_arg)
{
OS_ERR err;
CPU_TS ts;
OS_SEM_CTR ctr;
(void)&p_arg;
while (DEF_ON) {
:
:
ctr = OSSemPend(&SwSem,
0,
OS_OPT_PEND_BLOCKING,
&ts,
&err);
/* Check "err" */
:
:
}
} |