µC/OS-II API Reference

This section provides a user’s guide to µC/OS-II services. Each of the user-accessible kernel services is presented in alphabetical order and the following information is provided for each of the services.

A brief description
The function prototype
The filename of the source code
The #define constant needed to enable the code for the service
A description of the arguments passed to the function
A description of the return value(s)
Specific notes and warnings on using the service
One or two examples of how to use the function

1 OS_ENTER_CRITICAL()
2 OS_EXIT_CRITICAL()
3 OSFlagAccept()
4 OSFlagCreate()
5 OSFlagDel()
6 OSFlagPend()
7 OSFlagPost()
8 OSFlagQuery()
9 OSInit()
10 OSIntEnter()
11 OSIntExit()
12 OSMboxAccept()
13 OSMboxCreate()
14 OSMboxDel()
15 OSMboxPend()
16 OSMboxPost()
17 OSMboxPostOpt()
18 OSMboxQuery()
19 OSMemCreate()
20 OSMemGet()
21 OSMemPut()
22 OSMemQuery()
23 OSMutexAccept()
24 OSMutexCreate()
25 OSMutexDel()
26 OSMutexPend()
27 OSMutexPost()
28 OSMutexQuery()
29 OSQAccept()
30 OSQCreate()
31 OSQDel()
32 OSQFlush()
33 OSQPend()
34 OSQPost()
35 OSQPostFront()
36 OSQPostOpt()
37 OSQQuery()
38 OSSchedLock()
39 OSSchedUnlock()
40 OSSemAccept()
41 OSSemCreate()
42 OSSemDel()
43 OSSemPend()
44 OSSemPost()
45 OSSemQuery()
46 OSStart()
47 OSStatInit()
48 OSTaskChangePrio()
49 OSTaskCreate()
50 OSTaskCreateExt()
51 OSTaskDel()
52 OSTaskDelReq()
53 OSTaskQuery()
54 OSTaskResume()
55 OSTaskStkChk()
56 OSTaskSuspend()
57 OSTimeDly()
58 OSTimeDlyHMSM()
59 OSTimeDlyResume()
60 OSTimeGet()
61 OSTimeSet()
62 OSTimeTick()
63 OSTmrCreate()
64 OSTmrDel()
65 OSTmrNameGet()
66 OSTmrRemainGet()
67 OSTmrSignal()
68 OSTmrStart()
69 OSTmrStateGet()
70 OSTmrStop()
71 OSVersion()

OS_ENTER_CRITICAL()

File	Called From	Code Enabled By

File	Called From	Code Enabled By
`OS_CPU.H`	Task or ISR	N/A

OS_ENTER_CRITICAL() and OS_EXIT_CRITICAL() are macros used to disable and enable, respectively, the processor’s interrupts.

Arguments

None

Returned Value

None

Notes/Warnings

These macros must be used in pairs.

If OS_CRITICAL_METHOD is set to 3, your code is assumed to have allocated local storage for a variable of type OS_CPU_SR called cpu_sr as follows:

#if OS_CRITICAL_METHOD == 3      /* Allocate storage for CPU status register */
    OS_CPU_SR  cpu_sr;
#endif

Example

void TaskX(void *pdata)
{
#if OS_CRITICAL_METHOD == 3
      OS_CPU_SR   cpu_sr;
 #endif
      for (;;) {
         .
         .
         OS_ENTER_CRITICAL();    /* Disable interrupts     */
         .
         .                       /* Access critical code   */
         .
         OS_EXIT_CRITICAL();     /* Enable  interrupts     */
         .
         .
      }
}

OS_EXIT_CRITICAL()

File	Called From	Code Enabled By

File	Called From	Code Enabled By
`OS_CPU.H`	Task or ISR	N/A

OS_ENTER_CRITICAL() and OS_EXIT_CRITICAL() are macros used to disable and enable, respectively, the processor’s interrupts.

Arguments

None

Returned Value

None

Notes/Warnings

These macros must be used in pairs.

If OS_CRITICAL_METHOD is set to 3, your code is assumed to have allocated local storage for a variable of type OS_CPU_SR called cpu_sr as follows:

#if OS_CRITICAL_METHOD == 3      /* Allocate storage for CPU status register */
    OS_CPU_SR  cpu_sr;
#endif

Example

void TaskX(void *pdata)
{
#if OS_CRITICAL_METHOD == 3
      OS_CPU_SR   cpu_sr;
 #endif
      for (;;) {
         .
         .
         OS_ENTER_CRITICAL();    /* Disable interrupts     */
         .
         .                       /* Access critical code   */
         .
         OS_EXIT_CRITICAL();     /* Enable  interrupts     */
         .
         .
      }
}

OSFlagAccept()

OS_FLAGS OSFlagAccept(OS_FLAG_GRP *pgrp, 
                      OS_FLAGS     flags,
                      INT8U        wait_type, 
                      INT8U       *err);

File	Called From	Code Enabled By

File	Called From	Code Enabled By
`OS_FLAG.C`	Task	`OS_FLAG_EN` and `OS_FLAG_ACCEPT_EN`

OSFlagAccept() allows you to check the status of a combination of bits to be either set or cleared in an event flag group. Your application can check for ANY bit to be set/cleared or ALL bits to be set/cleared. This function behaves exactly as OSFlagPend() except that the caller will NOT block if the desired event flags are not present.

Arguments

pgrp

is a pointer to the event flag group. This pointer is returned to your application when the event flag group is created (see OSFlagCreate()).

flags

is a bit pattern indicating which bit(s) (i.e., flags) you wish to check. The bits you want are specified by setting the corresponding bits in flags . word

wait_type

specifies whether you want ALL bits to be set/cleared or ANY of the bits to be set/cleared. You can specify the following argument:

OS_FLAG_WAIT_CLR_ALL

You will check ALL bits in 'flags ' to be clear (0)

OS_FLAG_WAIT_CLR_ANY

You will check ANY bit in 'flags ' to be clear (0)

OS_FLAG_WAIT_SET_ALL

You will check ALL bits in 'flags ' to be set (1)

OS_FLAG_WAIT_SET_ANY

You will check ANY bit in 'flags ' to be set (1)

You can add OS_FLAG_CONSUME if you want the event flag(s) to be ‘consumed’ by the call. For example, to wait for ANY flag in a group and then clear the flags that are present, set wait_type to:

OS_FLAG_WAIT_SET_ANY + OS_FLAG_CONSUME

err

is a pointer to an error code and can be:

OS_NO_ERR

No error

OS_ERR_EVENT_TYPE

You are not pointing to an event flag group

OS_FLAG_ERR_WAIT_TYPE

You didn't specify a proper 'wait_type ' argument.

OS_FLAG_INVALID_pgrp

You passed a NULL pointer instead of the event flag handle.

OS_FLAG_ERR_NOT_RDY

The desired flags you are waiting for are not available.

Returned Value

The state of the flags in the event flag group.

Notes/Warnings

The event flag group must be created before it is used.
This function does NOT block if the desired flags are not present.

Example

#define  ENGINE_OIL_PRES_OK   0x01
#define  ENGINE_OIL_TEMP_OK   0x02
#define  ENGINE_START         0x04
 
OS_FLAG_GRP *EngineStatus;
 
void Task (void *pdata)
{
    INT8U     err;
    OS_FLAGS  value;
    pdata = pdata;
    for (;;) {
        value = OSFlagAccept(EngineStatus,
                             ENGINE_OIL_PRES_OK + ENGINE_OIL_TEMP_OK,
                             OS_FLAG_WAIT_SET_ALL,
                             &err);
        switch (err) {
            case OS_NO_ERR:
                 /* Desired flags are available         */
                 break;
            case OS_FLAG_ERR_NOT_RDY:
                 /* The desired flags are NOT available */
                 break;
        }
        .
        .
    }
}

OSFlagCreate()

OS_FLAG_GRP *OSFlagCreate (OS_FLAGS flags, INT8U *err);

File	Called From	Code Enabled By

File	Called From	Code Enabled By
`OS_FLAG.C`	Task or startup code	`OS_FLAG_EN`

OSFlagCreate() is used to create and initialize an event flag group.

Arguments

flags

contains the initial value to store in the event flag group.

err

is a pointer to a variable which will be used to hold an error code. The error code can be one of the following:

OS_NO_ERR

if the call was successful and the event flag group was created.

OS_ERR_CREATE_ISR

if you attempted to create an event flag group from an ISR.

OS_FLAG_GRP_DEPLETED

if there are no more event flag groups available. You will need to increase the value of OS_MAX_FLAGS in OS_CFG.H .

Returned Value

A pointer to the event flag group if a free one is available. If no event flag group is available, OSFlagCreate() will return a NULL pointer.

Notes/Warnings

Event flag groups must be created by this function before they can be used by the other services.

Example

OS_FLAG_GRP *EngineStatus;
 
void main (void)
{
    INT8U  err;
    .
    .
    OSInit();                /* Initialize µC/OS-II                                         */
    .
    .
                             /* Create a flag group containing the engine's status          */
    EngineStatus = OSFlagCreate(0x00, &err);    .
    .
    OSStart();               /* Start Multitasking                                          */
}

OSFlagDel()

OS_FLAG_GRP *OSFlagDel(OS_FLAG_GRP *pgrp, 
                             INT8U  opt,
                             INT8U *err);

File	Called From	Code Enabled By

File	Called From	Code Enabled By
`OS_FLAG.C`	Task	`OS_FLAG_EN` and `OS_FLAG_DEL_EN`

OSFlagDel() is used to delete an event flag group. This is a dangerous function to use because multiple tasks could be relying on the presence of the event flag group. You should always use this function with great care. Generally speaking, before you would delete an event flag group, you would first delete all the tasks that access the event flag group.

Arguments

pgrp

is a pointer to the event flag group. This pointer is returned to your application when the event flag group is created (see OSFlagCreate()).

opt

specifies whether you want to delete the event flag group only if there are no pending tasks (OS_DEL_NO_PEND) or whether you always want to delete the event flag group regardless of whether tasks are pending or not (OS_DEL_ALWAYS). In this case, all pending task will be readied.

err

is a pointer to a variable which will be used to hold an error code. The error code can be one of the following:

OS_NO_ERR

if the call was successful and the event flag group was deleted.

OS_ERR_DEL_ISR

if you attempted to delete an event flag group from an ISR.

OS_FLAG_INVALID_pgrp

if you passed a NULL pointer in pgrp .

OS_ERR_EVENT_TYPE

if pgrp is not pointing to an event flag group.

OS_ERR_INVALID_OPT

if you didn’t specify one of the two options mentioned above.

OS_ERR_TASK_WAITING

if one or more task were waiting on the event flag group and you specified OS_DEL_NO_PEND .

Returned Value

A NULL pointer if the event flag group is deleted, or pgrp if the event flag group was not deleted. In the latter case, you would need to examine the error code to determine the reason.

Notes/Warnings

You should use this call with care because other tasks may expect the presence of the event flag group.
This call can potentially disable interrupts for a long time. The interrupt disable time is directly proportional to the number of tasks waiting on the event flag group.

Example

OS_FLAG_GRP *EngineStatusFlags;
 
void Task (void *pdata)
{
    INT8U        err;
    OS_FLAG_GRP *pgrp
;
    pdata = pdata;
    while (1) {
        .
        .
        pgrp = OSFlagDel(EngineStatusFlags, OS_DEL_ALWAYS, &err);
        if (pgrp == (OS_FLAG_GRP *)0) {
            /* The event flag group was deleted */
        }
        .
        .
    }
}

OSFlagPend()

OS_FLAGS OSFlagPend(OS_FLAG_GRP *pgrp,
                    OS_FLAGS     flags,
                    INT8U        wait_type,
                    INT16U       timeout,
                    INT8U       *err);

File	Called From	Code Enabled By

File	Called From	Code Enabled By
`OS_FLAG.C`	Task only	`OS_FLAG_EN`

OSFlagPend() is used to have a task wait for a combination of conditions (i.e., events or bits) to be set (or cleared) in an event flag group. You application can wait for ANY condition to be set (or cleared) or, ALL conditions to be either set or cleared. If the events that the calling task desires are not available then, the calling task will be blocked until the desired conditions are satisfied or, the specified timeout expires.

Arguments

pgrp

is a pointer to the event flag group. This pointer is returned to your application when the event flag group is created (see OSFlagCreate()).

flags

is a bit pattern indicating which bit(s) (i.e., flags) you wish to check. The bits you want are specified by setting the corresponding bits in flags .

wait_type

specifies whether you want ALL bits to be set/cleared or ANY of the bits to be set/cleared. You can specify the following argument:

OS_FLAG_WAIT_CLR_ALL

You will check ALL bits in 'flags ' to be clear (0)

OS_FLAG_WAIT_CLR_ANY

You will check ANY bit in 'flags ' to be clear (0)

OS_FLAG_WAIT_SET_ALL

You will check ALL bits in 'flags ' to be set (1)

OS_FLAG_WAIT_SET_ANY

You will check ANY bit in 'flags ' to be set (1)

You can also specify whether the flags will be ‘consumed’ by adding OS_FLAG_CONSUME to the wait_type . For example, to wait for ANY flag in a group and then CLEAR the flags that satisfy the condition, set wait_type to:

OS_FLAG_WAIT_SET_ANY + OS_FLAG_CONSUME

err

is a pointer to an error code and can be:

OS_NO_ERR

No error

OS_ERR_PEND_ISR

You tried to call OSFlagPend from an ISR which is not allowed.

OS_FLAG_INVALID_pgrp

You passed a NULL pointer instead of the event flag handle.

OS_ERR_EVENT_TYPE

You are not pointing to an event flag group

OS_TIMEOUT

The flags were not available within the specified amount of time.

OS_FLAG_ERR_WAIT_TYPE

You didn't specify a proper 'wait_type ' argument.

Returned Value

The value of the flags in the event flag group after they are consumed (if OS_FLAG_CONSUME is specified) or, the state of the flags just before OSFlagPend() returns. OSFlagPend() returns 0 if a timeout occurs.

Notes/Warnings

The event flag group must be created before it’s used.

Example

#define  ENGINE_OIL_PRES_OK   0x01
#define  ENGINE_OIL_TEMP_OK   0x02
#define  ENGINE_START         0x04
 
OS_FLAG_GRP *EngineStatus;
 
void Task (void *pdata)
{
    INT8U     err;
    OS_FLAGS  value;
    pdata = pdata;
    for (;;) {
        value = OSFlagPend(EngineStatus,
                           ENGINE_OIL_PRES_OK   + ENGINE_OIL_TEMP_OK,
                           OS_FLAG_WAIT_SET_ALL + OS_FLAG_CONSUME,
                           10,
                           &err);
        switch (err) {
            case OS_NO_ERR:
                 /* Desired flags are available */
                 break;
            case OS_TIMEOUT:
                 /* The desired flags were NOT available before 10 ticks occurred */
                 break;
        }
        .
        .
    }
}

OSFlagPost()

OS_FLAGS OSFlagPost(OS_FLAG_GRP *pgrp,
                    OS_FLAGS     flags,
                    INT8U        opt,
                    INT8U       *err);

File	Called From	Code Enabled By

File	Called From	Code Enabled By
`OS_FLAG.C`	Task or ISR	`OS_FLAG_EN`

You set or clear event flag bits by calling OSFlagPost() . The bits set or cleared are specified in a ‘bit mask’. OSFlagPost() will ready each task that has it’s desired bits satisfied by this call. You can set or clear bits that are already set or cleared.

Arguments

pgrp

is a pointer to the event flag group. This pointer is returned to your application when the event flag group is created (see OSFlagCreate()).

flags

specifies which bits you want set or cleared. If opt (see below) is OS_FLAG_SET , each bit that is set in 'flags ' will set the corresponding bit in the event flag group. For example, to set bits 0, 4 and 5 you would set flags to 0x31 (note, bit 0 is least significant bit). If opt (see below) is OS_FLAG_CLR , each bit that is set in flags will CLEAR the corresponding bit in the event flag group. For example, to clear bits 0, 4 and 5 you would specify 'flags ' as 0x31 (note, bit 0 is least significant bit).

opt

indicates whether the flags will be set (OS_FLAG_SET) or cleared (OS_FLAG_CLR).

err

is a pointer to an error code and can be:

OS_NO_ERR

The call was successful

OS_FLAG_INVALID_pgrp

You passed a NULL pointer

OS_ERR_EVENT_TYPE

You are not pointing to an event flag group

OS_FLAG_INVALID_OPT

You specified an invalid option

Returned Value

The new value of the event flags.

Notes/Warnings

Event flag groups must be created before they are used.
The execution time of this function depends on the number of tasks waiting on the event flag group. However, the execution time is deterministic.
The amount of time interrupts are DISABLED also depends on the number of tasks waiting on the event flag group.

Example

#define  ENGINE_OIL_PRES_OK   0x01
#define  ENGINE_OIL_TEMP_OK   0x02
#define  ENGINE_START         0x04
 
OS_FLAG_GRP  *EngineStatusFlags;
 
void  TaskX (void *pdata)
{
    INT8U  err;
    pdata = pdata;
    for (;;) {
        .
        .
        err = OSFlagPost(EngineStatusFlags, ENGINE_START, OS_FLAG_SET, &err);
        .
        .
    }
}

OSFlagQuery()

OS_FLAGS OSFlagQuery (OS_FLAG_GRP *pgrp, 
                      INT8U       *err);

File	Called From	Code Enabled By

File	Called From	Code Enabled By
`OS_FLAG.C`	Task or ISR	`OS_FLAG_EN` and `OS_FLAG_QUERY_EN`

OSFlagQuery() is used to obtain the current value of the event flags in a group. At this time, this function does NOT return the list of tasks waiting for the event flag group.

Arguments

pgrp

is a pointer to the event flag group. This pointer is returned to your application when the event flag group is created (see OSFlagCreate()).

err

is a pointer to an error code and can be:

OS_NO_ERR

The call was successful

OS_FLAG_INVALID_pgrp

You passed a NULL pointer

OS_ERR_EVENT_TYPE

You are not pointing to an event flag group

Returned Value

The state of the flags in the event flag group.

Notes/Warnings

The event flag group to query must be created.
You can call this function from an ISR.

Example

OS_FLAG_GRP *EngineStatusFlags;
 
void Task (void *pdata)
{
    OS_FLAGS flags;
    INT8U    err;
    pdata = pdata;
    for (;;) {
        .
        .
        flags = OSFlagQuery(EngineStatusFlags, &err);
        .
        .
    }
}

OSInit()

void OSInit (void);

File	Called From	Code Enabled By

File	Called From	Code Enabled By
`OS_CORE.C`	Startup code only	N/A

OSInit() initializes µC/OS-II and must be called prior to calling OSStart() , which actually starts multitasking.

Arguments

None

Returned Value

None

Notes/Warnings

OSInit() must be called before OSStart() .

Example

void main (void)
{
      .
      .
      OSInit();      /* Initialize uC/OS-II */
      .
      .
      OSStart();     /* Start Multitasking  */
}

OSIntEnter()

void OSIntEnter (void);

File	Called From	Code Enabled By

File	Called From	Code Enabled By
`OS_CORE.C`	ISR only	N/A

OSIntEnter() notifies µC/OS-II that an ISR is being processed. This allows µC/OS-II to keep track of interrupt nesting. OSIntEnter() is used in conjunction with OSIntExit() .

Arguments

None

Returned Value

None

Notes/Warnings

This function must not be called by task-level code.

You can increment the interrupt nesting counter (OSIntNesting) directly in your ISR to avoid the overhead of the function call/return. It’s save to increment OSIntNesting in your ISR because interrupts are assumed to be disabled when OSIntNesting needs to be incremented.

You are allowed to nest interrupts up to 255 levels deep.

Example 1

(Intel 80x86, real mode, large model)

Use OSIntEnter() for backward compatibility with µC/OS.

    ISRx PROC   FAR
         PUSHA                          ; Save interrupted task's context
         PUSH   ES
         PUSH   DS
;
         MOV    AX, SEG(_OSIntNesting)  ; Reload DS
         MOV    DS, AX
;
         CALL   FAR PTR _OSIntEnter     ; Notify µC/OS-II of start of ISR
         .
         .
         POP    DS                      ; Restore processor registers
         POP    ES
         POPA
         IRET                           ; Return from interrupt
    ISRx ENDP

Example 2

(Intel 80x86, real mode, large model)

    ISRx    PROC   FAR
            PUSHA                          ; Save interrupted task's context
            PUSH   ES
            PUSH   DS
;
            MOV    AX, SEG(_OSIntNesting)  ; Reload DS
            MOV    DS, AX
;
            INC    BYTE PTR _OSIntNesting  ; Notify ?C/OS-II of start of ISR
            .
            .
            .
            POP    DS                      ; Restore processor registers
            POP    ES
            POPA
            IRET                           ; Return from interrupt
    ISRx    ENDP

OSIntExit()

void OSIntExit (void);

File	Called From	Code Enabled By

File	Called From	Code Enabled By
`OS_CORE.C`	ISR only	N/A

OSIntExit() notifies µC/OS-II that an ISR has completed. This allows µC/OS-II to keep track of interrupt nesting. OSIntExit() is used in conjunction with OSIntEnter() . When the last nested interrupt completes, OSIntExit() determines if a higher priority task has been made ready to run, in which case, the interrupt returns to the higher priority task instead of the interrupted task.

Arguments

None

Returned Value

None

Notes/Warnings

This function must not be called by task-level code. Also, if you decided to increment OSIntNesting, you still need to call OSIntExit() .

Example

(Intel 80x86, real mode, large model)
    ISRx    PROC    FAR
            PUSHA                      ; Save processor registers
            PUSH    ES
            PUSH    DS
            .
            .
            CALL    FAR PTR _OSIntExit ; Notify µC/OS-II of end of ISR
            POP     DS                 ; Restore processor registers
            POP     ES
            POPA
            IRET                       ; Return to interrupted task
    ISRx    ENDP

OSMboxAccept()

void *OSMboxAccept (OS_EVENT *pevent);

File	Called From	Code Enabled By

File	Called From	Code Enabled By
`OS_MBOX.C`	Task or ISR	`OS_MBOX_EN` and `OS_MBOX_ACCEPT_EN`

OSMboxAccept() allows you to see if a message is available from the desired mailbox. Unlike OSMboxPend() , OSMboxAccept() does not suspend the calling task if a message is not available. In other words, OSMboxAccept() is non-blocking. If a message is available, the message is returned to your application and the content of the mailbox is cleared. This call is typically used by ISRs because an ISR is not allowed to wait for a message at a mailbox.

Arguments

pevent

is a pointer to the mailbox from which the message is received. This pointer is returned to your application when the mailbox is created [see OSMboxCreate()].

Returned Value

A pointer to the message if one is available; NULL if the mailbox does not contain a message.

Notes/Warnings

Mailboxes must be created before they are used.

Example

OS_EVENT *CommMbox;
 
void Task (void *pdata)
{
    void *msg;
    pdata = pdata;
    for (;;) {
        msg = OSMboxAccept(CommMbox); /* Check mailbox for a message
*/
        if (msg != (void *)0) {
          .                           /* Message received, process
*/
          .
        } else {
          .                           /* Message not received, do ..
*/
          .                           /* .. something else
*/
        }
       .
       .
    }
}

OSMboxCreate()

OS_EVENT *OSMboxCreate (void *msg);