Description
Create and initialize a mutex. A mutex is used to gain exclusive access to a resource.
Files
os.h/os_mutex.c
Prototype
Code Block |
---|
void OSMutexCreate (OS_MUTEX |
...
*p_mutex, |
...
CPU_CHAR |
...
*p_name, |
...
OS_ERR |
...
*p_err) |
...
File
...
Called from
...
Code enabled by
...
os_mutex.c
...
...
OS_CFG_MUTEX_EN
OSMutexCreate()
is used to create and initialize a mutex. A mutex is used to gain exclusive access to a resource.
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 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.
...
is a pointer to a variable that is used to hold an error code:
OS_ERR_NONE
if
If the call is successful and the mutex has been created.
OS_ERR_CREATE_ISR
if
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
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_
...
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.
Returned Value
NoneMUTEX_EN
must be enabled in os_cfg.h
. Refer to µC-OS-III Configuration Manual.
Callers
Application.
Notes/Warnings
- Mutexes must be created before they are used.
Example Usage
Code Block | ||
---|---|---|
| ||
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 */
} |