OSSemPost

Description

A semaphore is signaled by calling OSSemPost(). If the semaphore value is 0 or more, it is incremented, and OSSemPost() returns to its caller. If tasks are waiting for the semaphore to be signaled, OSSemPost() removes the highest-priority task pending for the semaphore from the waiting list and makes this task ready-to-run. The scheduler is then called to determine if the awakened task is now the highest-priority task that is ready-to-run.

Files

os.h/os_sem.c

Prototype

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

Arguments

p_sem

is a 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 the semaphore.

OS_OPT_POST_ALL

Post to all tasks waiting on the semaphore. You should only use this option if the semaphore is used as a signaling mechanism and never when the semaphore is used to guard a shared resource. It does not make sense to tell all tasks that are sharing a resource that they can all access the resource.

OS_OPT_POST_NO_SCHED

This option indicates that the caller does not want the scheduler to be called after the post. This option can be used in combination with one of the two previous options.

You should use this option if the task (or ISR) calling OSSemPost() will be doing additional posting and, the user does not want to reschedule until all done, and multiple posts are to take effect simultaneously.

p_err

is a pointer to a variable that holds an error code:

OS_ERR_NONE

If no tasks are waiting on the semaphore. In this case, the return value is also 0.

OS_ERR_OBJ_PTR_NULL

If OS_CFG_ARG_CHK_EN is set to DEF_ENABLED in os_cfg.h: if p_sem is a NULL pointer.

OS_ERR_OBJ_TYPE

If OS_CFG_OBJ_TYPE_CHK_EN is set to DEF_ENABLED in os_cfg.h: if p_sem is not pointing to a semaphore.

OS_ERR_OPT_INVALID

If OS_CFG_ARG_CHK_EN is set to DEF_ENABLED in os_cfg.h: if a valid option is not specified.

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_SEM_OVF

If the post would have caused the semaphore counter to overflow.

Returned Value

The current value of the semaphore count

Required Configuration

OS_CFG_SEM_EN must be enabled in os_cfg.h. Refer to µC-OS-III Configuration Manual.

Callers

Application and ISRs.

Notes/Warnings

1. Semaphores must be created before they are used.
2. You can also post to a semaphore from an ISR but the semaphore must be used as a signaling mechanism and not to protect a shared resource.

Example Usage

          OS_SEM  SwSem;
           
           
          void  TaskX (void  *p_arg)
          {
              OS_ERR      err;
              OS_SEM_CTR  ctr;
           
           
              (void)&p_arg;
              while (DEF_ON) {
                  :
                  :
                  ctr = OSSemPost(&SwSem,
                                   OS_OPT_POST_1 + OS_OPT_POST_NO_SCHED,
                                  &err);
                  /* Check "err" */
                  :
                  :
              }
          }