Chapter 3

Kernel Structure

This chapter describes some of the structural aspects of µC/OS-II. You will learn:

∙How µC/OS-II handles access to critical sections of code,

∙What a task is, and how µC/OS-II knows about your tasks,

∙How tasks are scheduled,

∙How µC/OS-II can determine how much of CPU your application is using,

∙How do to write Interrupt Service Routines (ISRs),

∙What a clock tick is and how µC/OS-II handles it,

∙How to initialize µC/OS-II and,

∙How to start multitasking.

This chapter also describes the following application services:

∙OS_ENTER_CRITICAL() and OS_EXIT_CRITICAL(),

∙OSInit(),

∙OSStart(),

∙OSIntEnter() and OSIntExit(),

∙OSSchedLock() and OSSchedUnlock() and,

∙OSVersion().

3.00Critical Sections

µC/OS-II like all real-time kernels need to disable interrupts in order to access critical sections of code, and re-enable interrupts when done. This allows µC/OS-II to protect critical code from being entered simultaneously from either multiple tasks or ISRs. The interrupt disable time is one of the most important specifications that a real -time kernel vendor can provide because it affects the responsiveness of your system to real-time events. µC/OS-II tries to keep the interrupt disable time to a minimum but, with µC/OS-II, interrupt disable time is largely dependent on the processor architecture, and the quality of the code generated by the compiler. Every processor generally provides instructions to disable/enable interrupts and your C compiler must have a mechanism to perform these operations directly from C. Some compilers will allow you to insert in -line assembly language statements in your C source code. This makes it quite easy to insert processor instructions to enable and disable interrupts. Other compilers will actually contain language extensions to enable and disable interrupts directly from C. To hide the implementation method chosen by the compiler manufacturer, µC/OS-II defines two macros to disable and enable interrupts: OS_ENTER_CRITICAL() and OS_EXIT_CRITICAL(), respectively. Because these macros are processor specific, they are found in a file called OS_CPU.H. Each processor port will thus have its own OS_CPU.H file.

Chapters 8, Porting µC/OS -II and chapter 9, 80x86, Large Model Port provide additional details with regards to these two macros.

3.01 Tasks

OSTaskCreateExt() is an ‘extended’version of OSTaskCreate() and provides additional features. These two functions are explained in Chapter 4, Task Management.

3.02 Task States

Figure 3-1 shows the state transition diagram for tasks under µC/OS-II. At any given time, a task can be in any one of five states.

WAITING

OSTaskDel()

Figure 3-1, Task States

The DORMANT state corresponds to a task (see Listing 3.1 or Listing 3.2) which resides in program space (ROM or

RAM) but has not been made available to µC/OS-II. A task is made available to µC/OS-II by calling either OSTaskCreate() or OSTaskCreateExt(). When a task is created, it is made READY to run. Tasks may be created before multitasking starts or dynamically by a running task. When created by a task, if the created task has a

higher priority than its creator, the created task is immediately given control of the CPU. A task can return itself or another task to the dormant state by calling OSTaskDel().

Multitasking is started by calling OSStart(). OSStart() runs the highest priority task that is READY to run. This task is thus placed in the RUNNING state. Only one task can be running at any given time. A ready task will not run until all higher priority tasks are either placed in the wait state or are deleted.

The running task may delay itself for a certain amount of time by either calling OSTimeDly() or OSTimeDlyHMSM(). This task is thus WAITING for some time to expire and the next highest priority task that is ready-to-run is immediately given control of the CPU. The delayed task is made ready to run by OSTimeTick() when the desired time delay expires (see Section 3.11, Clock Tick ).

The running task may also need to wait until an event occurs, by calling either OSSemPend(), OSMboxPend() or OSQPend(). The task is thus WAITING for the occurrence of the event. When a task pends on an event, the next

highest priority task is immediately given control of the CPU. The task is made ready when the event occurs. The occurrence of an event may be signaled by either another task or an ISR.

A running task can always be interrupted, unless the task or µC/OS-II disables interrupts. The task thus enters the ISR state. When an interrupt occurs, execution of the task is suspended and the ISR takes control of the CPU. The ISR may make one or more tasks ready to run by signaling one or more events. In this case, before returning from the ISR, µC/OS-II determines if the interrupted task is still the highest priority task ready to run. If a higher priority task is made ready to run by the ISR then the new highest priority task is resumed. Otherwise, the interrupted task is resumed.

When all tasks are either waiting for events or for time to expire then µC/OS-II executes the idle task,

OSTaskIdle().

3.03 Task Control Blocks (OS_TCBs)

When a task is created, it is assigned a Task Control Block, OS_TCB (see Listing 3.3). A task control block is a data

structure that is used by µC/OS-II to maintain the state of a task when it is preempted. When the task regains control of the CPU the task control block allows the task to resume execution exactly where it left off. All OS_TCBs reside in RAM. You will notice that I organized the fields in OS_TCB to allow for data structure packing while maintaining a logical grouping of members. An OS_TCB is initialized when a task is created (see Chapter 4, Task Management). Below is a description of each field in the OS_TCB data structure.

typedef struct os_tcb {

struct os_tcb *OSTCBNext; struct os_tcb *OSTCBPrev;

#if (OS_Q_EN && (OS_MAX_QS >= 2)) || OS_MBOX_EN || OS_SEM_EN OS_EVENT *OSTCBEventPtr;

#endif

#if (OS_Q_EN && (OS_MAX_QS >= 2)) || OS_MBOX_EN void *OSTCBMsg;

#endif

Listing 3.3, µC/OS-II’s Task Control Block

OSTCBStkPtr contains a pointer to the current top of stack for the task. µC/OS-II allows each task to have

its own stack but just as important, each stack can be of any size. Some commercial kernels assume that all stacks are the same size unless you write complex hooks. This limitation wastes RAM when all tasks have different stack requirements, because the largest anticipated stack size has to be allocated for all tasks. OSTCBStkPtr is the only field in the OS_TCB data structure accessed from assembly language code (from the context switching code). Placing OSTCBStkPtr at the first entry in the structure makes accessing this field easier from assembly language code.

OSTCBExtPtr is a pointer to a user definable task control block extension. This allows you or the user of

µC/OS -II to extend the task control block without having to change the source code for µC/OS-II. OSTCBExtPtr is only used by OSTaskCreateExt() and thus, you will need to set

OS_TASK_CREATE_EXT_EN to 1 to enable this field. You could create a data structure that contains the name of each task, keep track of the execution time of the task, the number of times a task has been switched-in and more (see Example #3). Note that I decided to place this pointer immediately after the stack pointer in case you need to access this field from assembly language. This makes calculating the offset from the beginning of the data structure easier.

OSTCBStkBottom is a pointer to the task’s stack bottom. If the processor’s stack grows from high memory locations to low memory locations then OSTCBStkBottom will point at the lowest valid memory

location for the stack. Similarly, if the processor’s stack grows from low memory locations to high memory locations then OSTCBStkBottomwill point at the highest valid stack address. OSTCBStkBottom is used by OSTaskStkChk()to check the size of a task’s stack at run-time. This allows you determine the amount

of free stack space available for each stack. Stack checking can only occur if you created a task with OSTaskCreateExt() and thus, you will need to set OS_TASK_CREATE_EXT_EN to 1 to enable this field.

OSTCBStkSize is a variable that holds the size of the stack in number of elements instead of bytes. This means that if a stack contains 1000 entries and each entry is 32-bit wide then the actual size of the stack is 4000 bytes. Similarly, a stack where entries are 16-bit wide would contain 2000 bytes for the same 1000 entries. OSTCBStkSize is used by OSTaskStkChk(). Again, this field is valid only if you set

OS_TASK_CREATE_EXT_EN to 1.

OSTCBOpt is a variable that holds ‘options’that can be passed to OSTaskCreateExt(). Because of this, this field is valid only if you set OS_TASK_CREATE_EXT_EN to 1. µC/OS-II currently only defines three options (see uCOS_II.H): OS_TASK_OPT_STK_CHK, OS_TASK_OPT_STK_CLR and, OS_TASK_OPT_SAVE_FP. OS_TASK_OPT_STK_CHK is used to specify to OSTaskCreateExt() that stack checking is enabled for the task being created. OS_TASK_OPT_STK_CLR indicates that the stack

needs to be cleared when the task is created. The stack only needs to be cleared if you intend to do stack checking. If you do not specify OS_TASK_OPT_STK_CLR and you create and delete tasks then, the stack

checking will report incorrect stack usage. If you never delete a task once it’s created and your startup code clears all RAM then, you can save valuable execution time by NOT specifying this option. Passing OS_TASK_OPT_STK_CLR will increase the execution time of OSTaskCreateExt() because it will clear the content of the stack. The larger you stack, the longer it will take. Finally, OS_TASK_OPT_SAVE_FP tells OSTaskCreateExt() that the task will be doing floating-point computations and, if the processor provides hardware assisted floating -point capability then, the floating-point registers will need to be saved for the task being created and during a context switch.

OSTCBId is a variable that is used to hold an identifier for the task. This field is currently not used and has only been included for future expansion.