Getting Started with µC/OS-II

(1) First, you will notice that there is only a single #include statement. That’s because I like to place all my header files in a ‘master’ header file called INCLUDES.H. Each source file always references this single include file and thus, I never need to worry about determining which headers I need; they all get included via INCLUDES.H. You can use your code editor to view the contents of INCLUDES.H which is also found in the SOURCE directory.

I will get back to Listing 1.1 later as needed. Like most C programs, we need a main() as shown in Listing 1.2.

(1) µC/OS-II is a multitasking kernel and allows you to have up to 255 application tasks. µC/OS-II decides when to switch from one task to the other based on information you provide to µC/OS-II. One of the items you must tell µC/OS-II is the priority of your tasks. Changing between tasks is called a context switch.

main() starts by clearing the screen to ensure that no characters are left over from the previous DOS session. The function PC_DispClrScr() is found in a file called PC.C (see Chapter 18, PC Services for details). PC.C contains functions that provides services if you are running in a DOS environment (or a window under the Windows 95, 98, Me, NT, 2000 or XP operating systems). The PC_ prefix allows you to easily determine the name of the file where the function comes from; in this case, PC.C. You should note that I specified white letters on a black background. Since the screen will be cleared, I simply could have specified a black background and not specified a foreground. If I did this, and you decided to return to the DOS prompt, you would not see anything on the screen! It’s always better to specify a visible foreground just for this reason.

(2) A requirement of µC/OS-II is that you call OSInit() before you invoke any of its other services. OSInit() creates two tasks: an idle task, which executes when no other task is ready to run, and a statistic task, which computes CPU usage.

(3) The current DOS ‘environment’ is saved by calling PC_DOSSaveReturn(). This allows you to return to DOS as if you had never started µC/OS-II. You can refer to Chapter 18, PC Services for a description of what PC_DOSSaveReturn() does.

(4) main() calls PC_VectSet() (see Chapter 18, PC Services) to install the µC/OS-II context switch handler. Task-level context switching will be done by µC/OS-II by issuing an 80x86 INT instruction to this vector location. I decided to use vector 0x80 (i.e., 128) because it’s not used by either DOS or the BIOS.

(5) A binary semaphore is created to guard access to the random number generator function provided by the Borland C/C++ library. A semaphore is an object provided by the kernel to prevent multiple tasks from accessing the same resource (in this case a function) at the same time. I decided to use a semaphore because I didn’t know whether or not the random generator function was reentrant; I assumed it was not. By initializing the semaphore to 1, I’m telling µC/OS-II to only allow one task to access the random generator function at any given time. A semaphore must be ‘created’ before it can be used. This is done by calling OSSemCreate() and specifying its initial value. OSSemCreate() returns a ‘handle’ (see Listing 1.1(6)) to the semaphore which must be used to reference this particular semaphore.

(6) Before starting multitasking, you have to create at least one task. For this example, I called this task TaskStart(). You ‘create’ a task because you want to tell µC/OS-II to manage the task. The OSTaskCreate() function receives four arguments. The first argument is a pointer to the task’s address, in this case TaskStart(). The second argument is a pointer to data that you want to pass to the task when it first starts. In this case, there is nothing to pass and thus, I passed a NULL pointer but it could have been anything. I’ll discuss the use of this argument in Example #4. The third argument is the task’s top-of-stack (TOS). With µC/OS-II, as with most preemptive kernels, each task requires its own stack space. Each task in µC/OS-II can have a different size but, for simplicity, I made them all the same. On the 80x86 CPU, the stack grows downwards and thus, we must pass the highest most ‘valid’ TOS address to OSTaskCreate(). In this case, the stack is called TaskStartStk[] and is allocated at compile time. A stack must be declared having a type OS_STK (see Listing 1.1(4)). The size of the stack is declared in Listing 1.1(2). For the 80x86, an OS_STK is a 16-bit value and thus, the size of the stack is 1024 bytes. Finally, we must specify the priority of the task being created. The lower the priority number the higher the priority (i.e. its importance).

As previously mentioned, µC/OS-II allows you to create up to 255 tasks. However, each task must have a unique priority number between 0 and 254. You’re the one that actually decides what priority to give your tasks based on your application requirements. Priority level 0 is the highest priority.

(7) OSStart() is then called to start multitasking and give control to µC/OS-II. It is very important that you create at least one task before calling OSStart(). Failure to do this will certainly make your application crash. In fact, you may always want to create only one task if you are planning on using the CPU usage statistic task.

OSStart()’s job is to determine which, of all the tasks created, is the most important one (highest priority), and start executing this task. In our case, µC/OS-II created two low priority tasks: the idle task and the statistic task. main() created TaskStart() with a priority of 0. As I mentioned, priority 0 is the highest priority, and thus, OSStart() will start executing TaskStart().

You should note that OSStart() doesn’t return back to main(). However, if you call PC_DOSReturn(), multitasking would be halted and your application would return back to DOS (but not main()). In an embedded system, there is no need for an equivalent function to PC_DOSReturn() because you would most likely not be returning to anything!

(1) TaskStart() begins by setting pdata to itself. I do this because some compilers would complain (error or warning) if pdata is not referenced. In other words, I ‘fake’ the usage of pdata! pdata is a pointer passed to your task, when the task is created. The second argument passed in OSTaskCreate() is none other that the argument pdata of a task (see L1.2(6)). Because I passed a NULL pointer (again see L1.2(6)), I am not passing anything to TaskStart().

(2) TaskStart() then calls TaskStartDispInit() to initialize the display as shown in Figure 1.2. TaskStartDispInit() makes 25 consecutive calls to PC_DispStr() (see Chapter 18, PC Services) to fill the 25 lines of text of a typical DOS window.

(3) TaskStart() then invokes the macro OS_ENTER_CRITICAL() . OS_ENTER_CRITICAL() is basically a processor-specific macro and its used to disable interrupts (see Chapter 13, Porting µC/OS-II ).

(4) µC/OS-II, like all kernel, requires a time source to keep track of delays and timeouts. In real mode, the PC offers such a time source which occurs every 54.925 ms (18.20648 Hz) and is called a tick. PC_VectSet() allows us to replace the address where the PC goes to service the DOS tick with one that will be used by µC/OS-II. However, µC/OS-II will still call the DOS tick handler every 54.925 ms. This technique is called chaining and is setup by PC_DOSSaveReturn() (see Chapter 18, PC Services).

(5) We then change the tick rate rate from 18.2 Hz to 200 Hz. I selected 200 Hz because it’s almost an exact multiple of 18.2 Hz (i.e. 11 times faster). I never quite understood why IBM selected 18.2 Hz instead of 20 Hz as the tick rate on the original PC. Instead of setting up the 82C54 timer to divide the timer input frequency by 59,659 to obtain a nice 20 Hz, it appears that they left the 16-bit timer overflow every 65,536 pulses! Changing the tick rate is handled by another PC service called PC_SetTickRate() and is passed the desired tick rate (OS_TICKS_PER_SEC is set to 200 in OS_CPU.H).

(6) We then invoke the macro OS_EXIT_CRITICAL(). OS_EXIT_CRITICAL() is basically a processor-specific macro and its used to reenable interrupts (see Chapter 13, Porting µC/OS-II). OS_ENTER_CRITICAL() and OS_EXIT_CRITICAL() must be used in pair.

(7) OSStatInit() is called to determine the speed of your CPU (see Chapter 3, Kernel Structure). This allows µC/OS-II to know what percentage of the CPU is actually being used by all the tasks.

(8) TaskStart() then calls TaskStartCreateTasks() to let µC/OS-II manage more tasks. Specifically, we will be adding N_TASKS identical tasks (see Listing 1.1(2)). TaskStartCreateTasks() is shown in Listing 1.4.

(1) An array is initialized to contain the ASCII characters ‘0’ to ‘9’ (see also Listing 1.1(5)).

(2) The loop will initialize N_TASKS identical tasks called Task(). Task() will be responsible for placing an ASCII character at a random location on the screen. In fact, each instance of Task() will place a different character.

(3) Each of these task will receive a pointer to the array of ASCII characters. Each task will in fact receive a pointer to a different character.

(4) Again, each task requires its own stack space (see Listing 1.1(3)).

(5) With µC/OS-II, each task must have a unique priority. Since priority number 0 is already used by TaskStart(), I decided to create tasks with priorities 1 through 10.

As each task is created, µC/OS-II determines whether the created task is more important than the creator. If the created task had a higher priority then µC/OS-II would immediately run the created task. However, since TaskStart() has the highest priority (priority 0), none of the created tasks will execute just yet.

We can now resume discussion of Listing 1.3.

(9) With µC/OS-II, each task must be an infinite loop.

(10) TaskStartDisp() is called to display information at the bottom of the DOS window (see Figure 1.1). Specifically, TaskStartDisp() will print the number of tasks created, the current CPU usage in percentage, the number of context switches, the version of µC/OS-II and finally, whether your processor has a Floating-Point Unit (FPU) or not.

(11) TaskStart() then checks to see if you pressed a key by calling PC_GetKey().

(12) & (13) TaskStart() determines whether you pressed the ‘ESC’ key on your keyboard and if so, calls PC_DOSReturn() to exit this example and return back to the DOS prompt. You can find out how this is done by refering to Chapter 18, PC Services.

(14) If you didn’t press the ‘Esc’ key, the global variable OSCtxSwCtr (the context switch counter) is cleared so that we can display the number of context switches in one second.

(15) Finally, TaskStart() is suspended (will not run) for one complete second by calling OSTimeDlyHMSM(). The HMSM stands for Hours, Minutes, Seconds and Milliseconds and corresponds to the arguments passed to OSTimeDlyHMSM(). Because TaskStart() is suspended for one second, µC/OS-II will start exeuting the next most important task, in this case Task() at priority 1. You should note that without OSTimeDlyHMSM() (or other similar functions), TaskStart() would be a true infinite loop and other tasks would never get a chance to run.

(1) As I previously mentioned, a µC/OS-II task is typically an infinite loop.

(2) The task starts by acquiring the semaphore which guards access to the Borland compiler random number generator function. This is done by calling OSSemPend() and passing it the ‘handle’ (see L1.1(6)) of the semaphore which was created to guard access to the random number generator function. The second argument of OSSemPend() is used to specify a timeout. A value of 0 means that this task will wait forever for the semaphore. Because the semaphore was initialized with a count of one and no other task has requested the semaphore, Task() is allowed to continue execution. If the semaphore was ‘owned’ by another task, µC/OS-II would have suspended this task, and executed the next most important task.

(3) The random number generator function is called and a value between 0 and 79 (inclusively) is returned. This happens to be the ‘X’ coordinate where we want to display the character ‘0’ (for this task) on the screen.

(4) Again, the random number generator is called and returns a number between 0 and 15 (inclusively). This value will be used to determine the ‘Y’ position of the character to display.

(5) The semaphore is released by calling OSSemPost(). Here we simply need to specify the semaphore ‘handle’.

(6) We can now display the character that was passed to Task() when Task() was created. For the first instance of Task(), the character would be ‘0’ and the last instance, it’s ‘9’. I added an offset of 5 lines from the top so that I don’t overwrite the header at the top of the display (see Figure 1.1).

(7) Finally, Task() calls OSTimeDly() to tell µC/OS-II that it’s done executing and to give other tasks a chance to run. The value of 1 means that I want this task to delay for one clock tick or, 5 ms since the tick rate is 200 Hz. When OSTimeDly() is called, µC/OS-II suspends the calling function and executes the next most important task. In this case, it would be another instance of Task() which would display ‘1’. This process goes on for all instances of Task() and thus, that’s why Figure 1.1 looks the way it does.

Based on what you learned in Example #1, you should recognize:

(1) INCLUDES.H as the master include file.

(2) The size of each task stacks (TASK_STK_SIZE). Again, I made all stack sizes the same for simplicity but with µC/OS-II, the stack size for each task can be different.

(5) The storage for the task stacks.

(1) main() calls PC_ElapsedInit() to initialize the elapsed time measurement function that will be used to measure the execution time of OSTaskStkChk(). This function basically measures the execution time (i.e. overhead) of two functions: PC_ElapsedStart() and PC_ElapsedStop(). By measuring this time, we can determine fairly precisely how long it takes to execute code that’s wrapped between these two calls.

(2) & (3) TaskStart() in example #2 will be invoking the floating-point emulation library instead of making use of the Floating-Point Unit (FPU) which is present on 80486 and higher-end PCs. The Borland compiler defaults to use its emulation library if an FPU is not detected. In other words, if you were to run TEST.EXE on a DOS based machine equiped with an Intel 80386EX (without an 80387 coprocessor) then, the floating-point unit would be emulated. The emulation library is unfortunately non-reentrant and we have to ‘trick’ it in order to allow multiple tasks to do floating-point math. For now, let me just say that we have to modify the task stack to accommodate the floating-point emulation library. This is accomplished by calling OSTaskStkInit_FPE_x86() (see Chapter 14, 80x86 Port). You will notice from Figure 1.3 that the stack size reported for TaskStart() is 624 instead of 1024. That’s because OSTaskStkInit_FPE_x86() reserves the difference for the floating-point emulation library.

(4) Instead of calling OSTaskCreate() to create TaskStart(), we must call OSTaskCreateExt() (the extended version of OSTaskCreate()) because we modified the stack and also because we want to check the stack size at run-time (described later).

(5) OSTaskStkInit_FPE_x86() modifies the top-of-stack pointer so we must pass the new pointer to OSTaskCreateExt().

(6) Instead of passing a hard-coded priority (as I did in example #1), I created a #define symbol (see L1.6(4)).

(7) OSTaskCreateExt() requires that you pass a task identifier (ID). The actual value can be anything since this field is not actually used by µC/OS-II at this time.

(8) OSTaskStkInit_FPE_x86() modifies the bottom-of-stack pointer so we must pass the new pointer to OSTaskCreateExt().

(9) OSTaskStkInit_FPE_x86() also modifies the size of the stack so we must pass the new size to OSTaskCreateExt().

(10) One of OSTaskCreateExt()‘s argument is a Task Control Block (TCB) extension pointer. This argument is not used in example #2 so we simply pass a NULL pointer.

(11) Finally, the last argument to OSTaskCreateExt() is a set of options (i.e. bits) that tell OSTaskCreateExt() that we will be doing stack size checking and that we want to clear the stack when the task is created.

(1) Although the function call is identical TaskStartDispInit() initializes the display as shown in Figure 1.4.

(2) µC/OS-II allows you to have tasks or ISRs send messages to other tasks. In example #2, I will have task #4 send a message to task #5 and, task #5 will respond back to task #4 with an acknowledgement message (described later). For this purpose, we need to create two kernel objects that are called mailboxes. A mailbox allows a task or an ISR to send a ‘pointer’ to another task. The mailbox only has room for a single pointer. What the pointer points to is application specific and of course, both the sender and the receiver need to agree about the contents of the message.

(3) TaskStartCreateTasks() creates six tasks using OSTaskCreateExt(). These tasks will not be doing floating-point operations and thus, there is no need to call OSTaskStkInit_FPE_x86() to modify the stacks. However, I will be doing stack checking on these tasks so I call OSTaskCreateExt() with the proper options set.

(4) In example #1, I called OSTimeDlyHMSM() to delay TaskStart() for one second. I decided to use OSTimeDly(OS_TICKS_PER_SEC) to show you that you can use either method. However, OSTimeDly() is slightly faster than OSTimeDlyHMSM().

(1) & (3) The execution time of OSTaskStkChk() is measured by wrapping OSTaskStkChk() with calls to PC_ElapsedStart() and PC_ElapsedStop(). PC_ElapsedStop() returns the time difference in microseconds.

(2) OSTaskStkChk() is a service provided by µC/OS-II to allow your code to determine the actual stack usage of a task. You call OSTaskStkChk() by passing it the task priority of the task you want to check. The second argument to the function is a pointer to a data structure that will hold information about the task’s stack. Specifically, OS_STK_DATA contains the number of bytes used and the number of bytes free. OSTaskStkChk() returns an error code that indicates whether the call was successful. It would not be successful if I had passed the priority number of a task that didn’t exist.

(4) & (5) The information retrieved by OSTaskStkChk() is formatted into a string and displayed.

(6) I decided to execute this task 10 times per second but in an actual product or application, you would most likely run stack checking every few seconds or so. In other words, it might not make sense to consume valuable CPU processing time to determine worst case stack growth.

(1) Task4() sends a message (an ASCII character) to Task5() by posting the message to the TxMbox.

(2) Task4() then waits for an acknowledgement from Task5() by waiting on the AckMbox. The second argument to the OSMboxPend() call specifies a timeout and I specified to wait forever because I passed a value of 0. By specifying a non-zero value, Task4() would have given up waiting after the specified timeout. The timeout is specified as an integral number of clock ticks.

(3) The message is changed when Task5() acknowledges the previous message.

(4) When Task5() starts execution, it immediately waits (forever) for a message to arrive through the mailbox TxMbox.

(5) When the message arrives, Task5() displays it on the screen.

(6) & (7) Task5() then waits for one second before acknowledging Task4(). I decided to wait for one second so that you could see it change on the screen. In fact, there must either be a delay in Task5() or one in Task4() otherwise, all lower priority tasks would not be allowed to run!

(1) A data structure is created to hold additional information about a task. Specifically, the data structure allows you to add a name to a task (µC/OS-II doesn’t directly provide this feature), keep track of how many times a task has executed, how long a task takes to execute and finally, the total time a task has executed.

(2) An array of the TASK_USER_DATA is allocated to hold information about each task created (except the idle and statistic task).

(3) µC/OS-II provides another message passing mechanism called a message queue. A message queue is like a mailbox except that instead of being able to send a single pointer, a queue can hold more than one message (i.e. pointers). A message queue thus allows your tasks or ISRs to send messages to other tasks. What each of the pointers point to is application specific and of course, both the sender and the receiver need to agree about the contents of the messages. Two elements are needed to create a message queue: an OS_EVENT structure and an array of pointers. The depth of the queue is determined by the number of pointers allocated in the pointer array. In this case, the message queue contains 20 entries.

(1) Before a task is created, we assign a name to the task using the ANSI C library function strcpy(). The name is stored in the data structure (see L1.13(1)) assigned to the task.

(2) TaskStart() is created using OSTaskCreateExt() and passed a pointer to its user data structure. The Task Control Block (TCB) of each task in µC/OS-II can store a pointer to a user provided data structure (see Chapter 3, Kernel Structure for details). This allows you to extend the functionality of µC/OS-II as you will see shortly.

(1) Not much has been added except the creation of the message queue that will be used by Task1(), Task2(), Task3() and Task4().

(2) Like with Example #2, TaskStartCreateTasks() create 6 tasks. The difference is that each task is assigned an entry in the TaskUserData[] array. As each task is created, it’s assigned a name just like I did when I created TaskStart() (see L1.14(1)).

(1) Task1() waits forever for a message to arrive through a message queue.

(2) When a message arrives, it is displayed on the screen.

(3) The task is delayed for 100 ms to allow you to see the message received.

(4) Task2() sends the message "Task 2" to Task1() through the message queue.

(5) Task2() waits for half a second before sending another message.

(6) & (7) Task3() and Task4() sends their message and also waits half a second between messages.

(1) A timer on the PC obtains the execution time of the task being ‘switched out’ through PC_ElapsedStop().

(2) It is assumed that the timer was started by calling PC_ElapsedStart() when the task was ‘switched in’. The first context switch will probably read an incorrect value, but this is not really critical.

(3) When OSTaskSwHook() is called, the global pointer OSTCBCur points to the TCB of the current task while OSTCBHighRdy points to the TCB of the new task. In this case, however, we don’t use OSTCBHighRdy. OSTaskSwHook() retrieves the pointer to the TCB extension that was passed in OSTaskCreateExt().

(4) We then check to make sure we don’t deference a NULL pointer. In fact, some of the tasks in this example do not contain a TCB extension pointer: the idle task and the statistic task.

(5) We increment a counter that indicates how many times the task has executed. This counter is useful to determine if a particular task is running.

(6) The measured execution time (in microseconds) is stored in the TCB extension.

(7) The total execution time (in microseconds) of the task is also stored in the TCB extension. This allows you to determine the percent of time each task takes with respect to other tasks in an application (will be discussed shortly).

(1) The total execution time of all the tasks (except the statistic task) is computed.

(2) Individual statistics are displayed at the proper location on the screen by DispTaskStat(), which takes care of converting the values into ASCII. In addition, DispTaskStat() also displays the name of each task.

(3) & (4) The percent execution time is computed for each task and displayed.

(1) Because µC/OS-II doesn’t allow multiple tasks at the same priority, I offset the priority of the identical tasks by 1 since task priority #0 is assigned to TaskStart().

(2) The task priority of each task is placed in an array.

(3) µC/OS-II allows you to pass an argument to a task when the task is first started. This argument is a pointer, and I generally call it pdata (pointer to data). The task priority saved in the array is actually passed as the task argument, pdata.

(4) Each of the tasks will be doing floating point calculations and we want to tell the port (see Chapter 15) to save the floating-point registers during a context switch.

(1) The argument pdata points to an 8-bit integer containing the task priority. To make each task calculate different angles (not that it really matters), I decided to offset each task by 36 degrees.

(2) sin() and cos() assumes radians instead of degrees and thus the conversion.

(3) Each task is delayed by 1 clock tick (i.e. 50 milliseconds) and thus, each task will execute 200 times per second.