OSMutexCreate

Description

Create and initialize a mutex. A mutex is used to gain exclusive access to a resource.

Files

os.h/os_mutex.c

Prototype

void  OSMutexCreate (OS_MUTEX  *p_mutex,
                     CPU_CHAR  *p_name,
                     OS_ERR    *p_err)

Arguments

p_mutex

is a pointer to a mutex control block that must be allocated in the application. The user will need to declare a “global” variable as follows, and pass a pointer to this variable to OSMutexCreate():

OS_MUTEX  MyMutex;

p_name

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

p_err

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

OS_ERR_NONE

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

OS_ERR_CREATE_ISR

If OS_CFG_CALLED_FROM_ISR_CHK_EN set to DEF_ENABLED in os_cfg.h: if attempting to create a mutex 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_mutex is a NULL pointer.

Returned Value

None

Required Configuration

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

Callers

Application.

Notes/Warnings

1. Mutexes must be created before they are used.

Example Usage

          OS_MUTEX  DispMutex;
           
           
          void main (void)
          {
              OS_ERR  err;
            
           
              :
              OSInit(&err);                         /* Initialize µC/OS-III         */
              :
              :
              OSMutexCreate(&DispMutex,             /* Create Display Mutex         */
                            "Display Mutex",
                            &err);
              /* Check "err" */
           
              :
              :
              OSStart(&err);                        /* Start Multitasking           */
          }