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 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.
A pended task that has been suspended with
OSTaskSuspend() can obtain the semaphore. However, the task remains suspended until it is resumed by calling
OSSemPend() also returns if the pend is aborted or, the semaphore is deleted.
is a pointer to the semaphore.
allows the task to resume execution if a semaphore is not posted within the specified number of clock ticks. A timeout value of 0 indicates that the task waits forever for the semaphore. The timeout value is not synchronized with the clock tick. The timeout count begins decrementing on the next clock tick, which could potentially occur immediately.
specifies whether the call is to block if the semaphore is not available, or not block.
to block the caller until the semaphore is available or a timeout occurs.
If the semaphore is not available,
OSSemPend() will not block but return to the caller with an appropriate error code.
is a pointer to a variable that will receive a timestamp of when the semaphore was posted, pend aborted, or deleted. Passing a
NULL pointer is valid and indicates that a timestamp is not required.
A timestamp is useful when the task must know when the semaphore was posted or, how long it took for the task to resume after the semaphore was posted. In the latter case, call
OS_TS_GET() and compute the difference between the current value of the timestamp and
*p_ts. In other words:
delta = OS_TS_GET() - *p_ts;
is a pointer to a variable used to hold an error code:
If the semaphore is available.
If the semaphore was deleted.
OS_CFG_ARG_CHK_EN is set to
p_sem is a
OS_CFG_OBJ_TYPE_CHK_EN is set to
p_sem is not pointing to a semaphore.
OS_CFG_ARG_CHK_EN is set to
opt is not
OS_CFG_INVALID_OS_CALLS_CHK_EN is set to
os_cfg.h: if µC/OS-III is not running yet.
if the pend was aborted
OS_CFG_CALLED_FROM_ISR_CHK_EN set to
if this function is called from an ISR.
if this function is called as specified
OS_OPT_PEND_NON_BLOCKING, and the semaphore was not available.
If calling this function when the scheduler is locked.
If the pend status has an invalid value.
If the semaphore is not signaled within the specified timeout.
The new value of the semaphore count.
OS_CFG_SEM_EN must be enabled in
os_cfg.h. Refer to µC-OS-III Configuration Manual.
- Semaphores must be created before they are used.