Page Comparison

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 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.

...

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

OS_ERR_ILLEGAL_OBJCREATE_PTRRUN_NULLTIME

If If OS_CFGSAFETY_ARG_CHK_EN is set to 1 in os_cfg.h: if p_sem is a NULL pointerCRITICAL_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_TYPENULL

If OS_CFG_OBJ_TYPEARG_CHK_EN is set to 1 in DEF_ENABLED in os_cfg.h: if p_sem has been initialized to a different object type.

OS_ERR_ILLEGAL_CREATE_RUN_TIME

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

is a NULL pointer.

Returned Value

None

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

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              */
          }