OSSemCreate

Description

Initializes a semaphore. Semaphores are used when a task wants exclusive access to a resource, needs to synchronize its activities with an ISR or a task, or is waiting until an event occurs. You would use a semaphore to signal the occurrence of an event to one or multiple tasks, and use mutexes to guard share resources. However, technically, semaphores allow for both.

Files

os.h/os_sem.c

Prototype

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

Arguments

p_sem

is a pointer to the semaphore control block. It is assumed that storage for the semaphore will be allocated in the application. In other words, you need to declare a “global” variable as follows, and pass a pointer to this variable to OSSemCreate():

OS_SEM  MySem;

p_name

is a pointer to an ASCII string used to assign a name to the semaphore. The name can be displayed by debuggers or µC/Probe.

cnt

specifies the initial value of the semaphore.

If the semaphore is used for resource sharing, you would set the initial value of the semaphore to the number of identical resources guarded by the semaphore. If there is only one resource, the value should be set to 1 (this is called a binary semaphore). For multiple resources, set the value to the number of resources (this is called a counting semaphore).

If using a semaphore as a signaling mechanism, you should set the initial value to 0.

p_err

is a pointer to a variable used to hold an error code:

OS_ERR_NONE

If the call is successful and the semaphore has been created.

OS_ERR_CREATE_ISR

If OS_CFG_CALLED_FROM_ISR_CHK_EN set to DEF_ENABLED in os_cfg.h: if you attempted to create a semaphore from an ISR.

OS_ERR_ILLEGAL_CREATE_RUN_TIME

If OS_SAFETY_CRITICAL_IEC61508 is defined: you called this after calling OSStart() and thus you are no longer allowed to create additional kernel objects.

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.

Returned Value

None

Required Configuration

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

Callers

Application.

Notes/Warnings

1. Semaphores must be created before they are used.

Example Usage

          OS_SEM  SwSem;
           
           
          void main (void)
          {
              OS_ERR  err;
           
           
              :
              OSInit(&err);                 /* Initialize µC/OS-III             */
              :  
              :
              OSSemCreate(&SwSem,           /* Create Switch Semaphore          */
                          "Switch Semaphore",
                           0,
                          &err);
              /* Check "err" */
              :
              :
              OSStart(&err);                /* Start Multitasking              */
          }