Page Comparison

...

• The stack must be declared with the CPU_STK type.
• A task must always invoke one of the services provided by µC/OS-III to wait for time to expire, suspend the task, or wait on an object (wait on a message queue, event flag, mutex, semaphore, a signal or a message to be sent directly to the task). This allows other tasks to gain control of the CPU.
• You should not use task priorities 0, 1, OS_CFG_PRIO_MAX-2 and OS_CFG_PRIO_MAX-1 because they are reserved for use by µC/OS-III.

Example Usage

OSTaskCreate() can be called from main() (in C), or a previously created task.

(1) In order to create a task, you need to allocate storage for a TCB and pass a pointer to this TCB to OSTaskCreate().

(2) You can assign an ASCII name to the task by passing a pointer to an ASCII string. The ASCII string may be allocated in code space (i.e., ROM), or data space (i.e., RAM). In either case, it is assumed that the code can access that memory. The ASCII string must be NUL terminated.

(3) You pass the address of the task to OSTaskCreate(). In C, the address of a function is simply the name of that function.

(4) To provide additional data to MyTask(), you can pass a pointer to such data. In this case, MyTask() did not need such data and therefore, a NULL pointer is passed.

(5) The user must assign a priority to the task. The priority specifies the importance of this task with respect to other tasks. A low-priority value indicates a high priority. Priority 0 is the highest priority (reserved for an internal task) and a priority up to OS_CFG_PRIO_MAX-3 can be specified (see os_cfg.h). Note that OS_CFG_PRIO_MAX-1 is also reserved for an internal task, the idle task.

(6) The next argument specifies the “base address” of the task’s stack. In this case, it is simply the base address of the array MyTaskStk[]. Note that it is possible to simply specify the name of the array. I prefer to make it clear by writing &MyTaskStk[0].

(7) This argument sets the watermark limit for stack growth. If the processor port does not use this field then you can set this value to 0.

(8) µC/OS-III also needs to know the size of the stack for the task. This allows µC/OS-III to perform stack checking at run time. This argument represents the number of CPU_STK elements, not the number of bytes.

(9) µC/OS-III allows tasks or ISRs to send messages directly to a task. This argument specifies how many such messages can be received by this task.

(10) This argument specifies how much time (in number of ticks) this task will run on the CPU before µC/OS-III will force the CPU away from this task and run the next task at the same priority (if there are more than one task at the same priority that is ready-to-run).

(11) µC/OS-III allows the user to “extend” the capabilities of the TCB by allowing passing a pointer to some memory location that could contain additional information about the task. For example, there may be a CPU that supports floating-point math and the user would likely need to save the floating-point registers during a context switch. This pointer could point to the storage area for these registers.

(12) When creating a task, options must be specified. Specifically, such options as, whether the stack of the task will be cleared (i.e., filled with 0x00) when the task is created (OS_OPT_TASK_STK_CLR), whether µC/OS-III will be allowed to check for stack usage (OS_OPT_TASK_STK_CHK), whether the CPU supports floating-point math, and whether the task will make use of the floating-point registers and therefore need to save and restore them during a context switch (OS_OPT_TASK_SAVE_FP). The options are additive.

(13) Most of µC/OS-III’s services return an error code indicating the outcome of the call. The error code is always returned as a pointer to a variable of type OS_ERR. The user must allocate storage for this variable prior to calling OSTaskCreate().

(14) It is highly recommended that the user examine the error code whenever calling a µC/OS-III function. If the call is successful, the error code will always be OS_ERR_NONE. If the call is not successful, the returned code will indicate the reason for the failure (see OS_ERR_??? in os.h).