1.07 Example #1

The first example is found in \SOFTWARE\uCOS-II\EX1_x86L and basically consists of 13 tasks (including µC/OS-II’s idle task). µC/OS-II creates two ‘internal’tasks: the idle task and a task that determines CPU usage. Example #1 creates 11 other tasks. The TaskStart() task is created by main() and its function is to create the other tasks and display the following statistics on the screen:

1)the number of task switches in one second,

2)the CPU usage in %,

3)the number of context switches,

4)the current date and time, and

5)µC/OS-II’s version.

The TaskStart() task also checks to see if you pressed the ESCAPE key indicating your desire to exit the example and return to DOS.

The other 10 tasks are based on the same code, i.e. the function Task(). Each of the 10 tasks displays a number (each task has its own number from 0 to 9) at random locations on the screen.

1.07.01 Example #1, main()

Example #1 does basically the same thing as the first example provided in the first edition of µC/OS, however, I cleaned up some of the code and output to the screen is in color. Also, I decided to use the old data types (i.e. UBYTE, UWORD etc.) to show that µC/OS-II is backward compatible.

A µC/OS-II application looks just like any other DOS application. You compile and link your code just as if you would do a single threaded application running under DOS. The .EXE file that you create is loaded and executed by DOS, and execution of your application starts from main().

main() starts by clearing the screen to ensure we don’t have any characters left over from the previous DOS session L1.5(1). Note that I specified to use white letters on a black background. Since the screen will be cleared, I could have simply specified to use a black background and not specify a foreground. If I did this, and you decided to return to DOS then you would not see anything on the screen! It’s always better to specify a visible foreground just for this reason.

Listing 1.5, main()

A requirement of µC/OS-II is that you callOSInit() L1.5(2) 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.

The current DOS environment is then saved by callingPC_DOSSaveReturn() L1.5(3). This allows us to return to DOS as if we had never started µC/OS-II. A lot happens inPC_DOSSaveReturn() so you may need to look at the code in listing 1.6 to follow along. PC_DOSSaveReturn() starts by setting the flag PC_ExitFlag to FALSE L1.6(1) indicating that we are not returning to DOS. Then, PC_DOSSaveReturn() initializes OSTickDOSCtr to 1 L1.6(2) because this variable will be decremented in OSTickISR(). A value of 0 would have caused this value to wrap around to 255 when decremented by OSTickISR(). PC_DOSSaveReturn() then saves DOS’s tick handler in a

free vector table L1.6(3)-(4) entry so it can be called by µC/OS-II’s tick handler. Next, PC_DOSSaveReturn() calls setjmp() L1.6(5), which captures the state of the processor (i.e., the contents of all its registers) into a structure called PC_JumpBuf. Capturing the processor's context will allow us to return to PC_DOSSaveReturn() and execute the code immediately following the call to setjmp(). Because PC_ExitFlag was initialized to FALSE L1.6(1), PC_DOSSaveReturn() skips the code in the if statement (i.e. L1.6(6) -(9)) and returns to the caller (i.e. main()). When you want to return to DOS, all you have to do is call PC_DOSReturn() (see listing 1.7) which sets PC_ExitFlag to TRUE L1.7(1) and execute a longjmp() L1.7(2). This brings the processor back in PC_DOSSaveReturn() (just after the call to setjmp()) L1.6(5). This time, however, PC_ExitFlag is TRUE and the code following the if statement is executed. PC_DOSSaveReturn() changes the tick rate back to 18.2 Hz L1.6(6), restores the PC’s tick ISR

handler L1.6(7), clears the screen L1.6(8) and returns to the DOS prompt through the exit(0) function L1.6(9).

Listing 1.6, Saving the DOS environment.

Listing 1.7, Setting up to return to DOS.

Now we can go back to main() in listing 1.5. main() then calls PC_VectSet() L1.5(4) to install µC/OS-II’s context switch handler. Task level context switching is done 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.

A binary semaphore is then created L1.5(5) to guard access to the random number generator provided by the Borland C/C++ library. I decided to use a semaphore because I didn’t know whether or not this function was reentrant. I assumed it was not. Because I initialized the semaphore to 1, I am indicating that only one task can access the random number generator at any time.

Before starting multitasking, I create one task L1.5(6) called TaskStart(). It is very important that you create at least one task before starting multitasking through OSStart() L1.5(7). Failure to do this will certainly make your application crash. In fact, you may always want to only create a single task if you

are planning on using the CPU usage statistic task. µC/OS-II’s statistic task assumes that no other task is running for a whole second. If, however, you need to create additional tasks before starting multitasking, you must ensure that your task code will monitor the global variable OSStatRdy and delay execution (i.e. call OSTimeDly()) until this variable becomes TRUE. This indicates that µC/OS-II has collected its data for CPU usage statistics.

1.07.02 Example #1, TaskStart()

A major portion of the work in example #1 is done byTaskStart(). The pseudo-code for this function is shown in listing 1.8. The task starts by displaying a banner on top of the screen identifying this as example #1 L1.8(1). Next, we disable interrupts to change the tick ISR (Interrupt Service Routine) vector so that it now points to µC/OS-II’s tick handler L1.8(2) and, change the tick rate from the default DOS 18.2 Hz to 200 Hz L1.8(3). We sure don’t want to be interrupted while in the process of changing an interrupt vector! Note that main() purposely didn't set the interrupt vector to µC/OS-II's tick handler because you don't want a tick interrupt to occur before the operating system is fully initialized and running. If you run code in an embedded application, you should always enable the ticker (as I have done here) from within the first task.

for (;;) {

Display the number of tasks created; Display the % of CPU used;

Display the number of task switches in 1 second; Display uC/OS-II’s version number

if (key was pressed) {

if (key pressed was the ESCAPE key) { PC_DOSReturn();

}

}

Delay for 1 Second;

}

}

Listing 1.8, Task that creates the other tasks.

Before we create any other tasks, we need to determine how fast you particular PC is. This is done by calling OSStatInit() L1.8(4). OSStatInit() is shown in listing 1.9 and starts by delaying itself for

two clock ticks so that it can be synchronized to the tick interrupt L1.9(1). Because of this, OSStatInit() MUST occur after the ticker has been installed otherwise, your application will crash! When µC/OS-II returns control to OSStatInit(), a 32-bit counter called OSIdleCtr is cleared L1.9(2) and another delay is initiated, which again suspends OSStatInit(). At this point, µC/OS-II

doesn't have anything else to execute and thus decides to run the Idle Task (internal to µC/OS-II). The idle task is an infinite loop that increments OSIdleCtr. The idle task gets to increment this counter for one

full second L1.9(3). After one second, µC/OS-II resumes OSStatInit(), which saves OSIdleCtr in a variable called OSIdleCtrMax L1.9(4). OSIdleCtrMax now contains the largest value that OSIdleCtr can ever reach. When you start adding application code, the idle task will get less of the processor's time and thus, OSIdleCtr will not be allowed to count as high (assuming we will reset OSIdleCtr every second). CPU utilization is computed by a task provided b y µC/OS-II called OSStatTask() which executes every second.

OS_EXIT_CRITICAL();

}

Listing 1.9, Determining the PC’s speed.

1.07.03 Example #1, TaskN()

OSStatInit() returns back to TaskStart() and we can now create 10 identical tasks (all running the same code) L1.8(5). TaskStart() will create all the tasks and no context switch will occur because TaskStart() has a priority of 0 (i.e. the highest priority). When all the tasks are created, TaskStart() enters the infinite loop portion of the task and continuously displays statistics on the screen, checks to see if the ESCAPE key was pressed and then delay for one second before starting the loop again. If you press the escape key, TaskStart() calls PC_DOSReturn() and we gracefully return back to the DOS prompt.

The task code is shown in listing 1.10. When the task gets to execute, it tries to acquire a semaphore L1.10(1) so that we can call the Borland C/C++ library function random() L1.10(2). I assumed here that the random function is non-reentrant so, each of the 10 tasks must have exclusive access to this code in order to proceed. We release the semaphore when both X and Y coordinates are obtained L1.10(3). The task displays a number (between ‘0’and ‘9’) which is passed to the task when it is created L1.10(4). Finally, each task delays itself for one tick L1.10(5) and thus, each task will execute 200 times per second! With the 10 task this means that µC/OS-II will context switch between these tasks 2000 per second.