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
Code Block |
---|
void OSSemCreate (OS_SEM *p_sem, |
...
CPU_CHAR *p_name, |
...
OS_SEM_CTR cnt, |
...
OS_ERR *p_err |
...
File | Called from | Code enabled by |
---|---|---|
| Task or startup code |
|
...
) |
...
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.
...
is a pointer to a variable used to hold an error code:
OS_ERR_NONE
if If the call is successful and the semaphore has been created.
OS_ERR_CREATE_ISR
if 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_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 1
in DEF_ENABLED
in os_cfg.h
: if p_sem
is a NULL
pointer.
OS_ERR_OBJ_TYPE
...
Returned Value
None
Required Configuration
OS_CFG_
...
SEM_
...
EN
must be enabled in os_cfg.h
...
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.
Returned Value
None
. Refer to µC-OS-III Configuration Manual.
Callers
Application.
Notes/Warnings
- Semaphores must be created before they are used.
Example Usage
Code Block | ||
---|---|---|
| ||
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 */
} |