4. Sample Programs

To help familiarize you with the RCM2000 modules, several sample Dynamic C programs have been included. Loading, executing and studying these programs will give you a solid hands-on overview of the RCM2000's capabilities, as well as a quick start with Dynamic C as an application development tool.

4.1 Sample Program Overview

Dynamic C comes with a large number of sample programs that illustrate many of its features. These programs are intended to serve as tutorials, but then can also be used as starting points or building blocks for your own applications.

NOTE	It is assumed in this section that you have at least an elementary grasp of ANSI C. If you do not, see the introductory pages of the Dynamic C Premier User's Manual for a suggested reading list.

Sample programs are provided in the Dynamic C Samples folder, which is shown below.

The various folders contain specific sample programs that illustrate the use of the corresponding Dynamic C libraries. The sample program PONG.c demonstrates the output to the STDIO window. The COREMODULE folder provides sample programs specific to the RCM2000. Let's take a look at the COREMODULE folder.

Each sample program has comments that describe the purpose and function of the program.

Before running any of these sample program, make sure that your RCM2000 is connected to the Prototyping Board and to your PC as described in the RabbitCore RCM2000 Getting Started manual.

4.1 Running Sample Program FLASHLED.C

This sample program will be used to illustrate some of the functions of Dynamic C.

First, open the file FLASHLED.C, which is in the SAMPLES/COREMODULE folder. The program will appear in a window, as shown in Figure 5 below (minus some comments). Use the mouse to place the cursor on the function name WrPortI in the program and type <ctrl-H>. This will bring up a documentation box for the function WrPortI. In general, you can do this with all functions in Dynamic C libraries, including libraries you write yourself. Close the documentation box and continue.

Figure 5. Sample Program FLASHLED.C

To run the program FLASHLED.C, load it with the File menu, compile it using the Compile menu, and then run it by selecting Run in the Run menu. The LED on the Prototyping Board should start flashing if everything went well. If this doesn't work review the following points.

• The target should be ready, which is indicated by the message "BIOS successfully compiled..." If you did not receive this message or you get a communication error, recompile the BIOS by typing <ctrl-Y> or select Recompile BIOS from the Compile menu.
• A message reports "No Rabbit Processor Detected" in cases where the RCM2000 and the Prototyping Board are not connected together, the wall transformer is not connected, or is not plugged in. (The red power LED lights whenever power is connected.)
• The programming cable must be connected to the RCM2000. (The colored wire on the programming cable is closest to pin 1 on header J3 on the RCM2000, as shown in Figure 4.) The other end of the programming cable must be connected to the PC serial port. The COM port specified in the Dynamic C Options menu must be the same as the one the programming cable is connected to.
• To check if you have the correct serial port, select Compile, then Compile BIOS, or type <ctrl-Y>. If the "BIOS successfully compiled ..." message does not display, try a different serial port using the Dynamic C Options menu until you find the serial port you are plugged into. Don't change anything in this menu except the COM number. The baud rate should be 115,200 bps and the stop bits should be 1.

4.2 Single-Stepping

Compile or re-compile FLASHLED.C by clicking the Compile button on the task bar. The program will compile and the screen will come up with a highlighted character (green) at the first executable statement of the program. Use the F8 key to single-step. Each time the F8 key is pressed, the cursor will advance one statement. When you get to the for(j=0, j< ... statement, it becomes impractical to single-step further because you would have to press F8 thousands of times. We will use this statement to illustrate watch expressions.

4.2.1 Watch Expression

Type <ctrl-W> or chose Add/Del Watch Expression in the Inspect menu. A box will come up. Type the lower case letter j and click on add to top and close. Now continue single-stepping with F8. Each time you step, the watch expression (j) will be evaluated and printed in the watch window. Note how the value of j advances when the statement j++ is executed.

4.2.2 Break Point

Move the cursor to the start of the statement:

   for(j=0; j<25000; j++);

To set a break point on this statement, type F2 or select Toggle Breakpoint from the Run menu. A red highlight will appear on the first character of the statement. To get the program running at full speed, type F9 or select Run on the Run menu. The program will advance until it hits the break point. Then the break point will start flashing and show both red and green colors. Note that LED DS3 is now solidly turned on. This is because we have passed the statement turning on LED DS3. Note that j in the watch window has the value 32000. This is because the loop above terminated when j reached 32000.

To remove the break point, type F2 or select Toggle Breakpoint on the Run menu. To continue program execution, type F9 or select Run from the Run menu. Now the LED should be flashing again since the program is running at full speed.

You can set break points while the program is running by positioning the cursor to a statement and using the F2 key. If the execution thread hits the break point, a break point will take place. You can toggle the break point off with the F2 key and continue execution with the F9 key. Try this a few times to get the feel of things.

4.2.3 Editing the Program

Click on the Edit box on the task bar. This will set Dynamic C into the edit mode so that you can change the program. Use the Save as choice on the File menu to save the file with a new name so as not to change the demo program. Save the file as MYTEST.C. Now change the number 25000 in the for (.. statement to 10000. Then use the F9 key to recompile and run the program. The LED will start flashing, but it will flash much faster than before because you have changed the loop counter terminal value from 25000 to 10000.

4.2.4 Watching Variables Dynamically

Go back to edit mode (select edit) and load the program FLASHLED2.C using the File menu Open command. This program is the same as the first program, except that a variable k has been added along with a statement to increment k each time around the endless loop. The statement:

runwatch();

has been added. This is a debugging statement that makes it possible to view variables while the program is running.

Use the F9 key to compile and run FLASHLED2.C. Now type <ctrl-W> to open the watch window and add the watch expression k to the top of the list of watch expressions. Now type <ctrl-U>. Each time you type <ctrl-U>, you will see the current value of k, which is incrementing about 5 times a second.

As an experiment, add another expression to the watch window:

k*5

Then type <ctrl-U> several times to observe the watch expressions k and k*5.

4.2.5 Summary of Features

So far you have practiced using the following features of Dynamic C.

• Loading, compiling and running a program. When you load a program it appears in an edit window. You can compile by selecting Compile on the task bar or from the Compile menu. When you compile the program, it is compiled into machine language and downloaded to the target over the serial port. The execution proceeds to the first statement of main where it pauses, waiting for you to command the program to run, which you can do with the F9 key or by selecting Run on the Run menu. If want to compile and start the program running with one keystroke, use F9, the run command. If the program is not already compiled, the run command will compile it first.
• Single-stepping. This is done with the F8 key. The F7 key can also be used for single-stepping. If the F7 key is used, then descent into subroutines will take place. With the F8 key the subroutine is executed at full speed when the statement that calls it is stepped over.
• Setting break points. The F2 key is used to turn on or turn off (toggle) a break point at the cursor position if the program has already been compiled. You can set a break point if the program is paused at a break point. You can also set a break point in a program that is running at full speed. This will cause the program to break if the execution thread hits your break point.
• Watch expressions. A watch expression is a C expression that is evaluated on command in the watch window. An expression is basically any type of C formula that can include operators, variables and function calls, but not statements that require multiple lines such as for or switch. You can have a list of watch expressions in the watch window. If you are single-stepping, then they are all evaluated on each step. You can also command the watch expression to be evaluated by using the <ctrl-U> command. When a watch expression is evaluated at a break point, it is evaluated as if the statement was at the beginning of the function where you are single-stepping. If your program is running you can also evaluate watch expressions with a <ctrl-U> if your program has a runwatch() command that is frequently executed. In this case, only expressions involving global variables can be evaluated, and the expression is evaluated as if it were in a separate function with no local variables.

4.3 Cooperative Multitasking

Cooperative multitasking is a convenient way to perform several different tasks at the same time. An example would be to step a machine through a sequence of steps and at the same time independently carry on a dialog with the operator via a human interface. Cooperative multitasking differs from another approach called preemptive multitasking. Dynamic C supports both types of multitasking. In cooperative multitasking each separate task voluntarily surrenders its compute time when it does not need to perform any more activity immediately. In preemptive multitasking control is forcibly removed from the task via an interrupt.

Dynamic C has language extensions to support multitasking. The major C constructs are called costatements, cofunctions, and slicing. These are described more completely in the Dynamic C Premier User's Manual. The example below, sample program FLASHLEDS2.C, uses costatements. A costatement is a way to perform a sequence of operations that involve pauses or waits for some external event to take place. A complete description of costatements is in the Dynamic C Premier User's Manual. The FLASHLEDS2.C sample program has two independent tasks. The first task flashes LED DS2 2.5 times a second. The second task flashes DS3 every 1.5 seconds.

#define DS2 0           // predefine for LED DS2
#define DS3 1           // predefine for LED DS3

//  This cofunction flashes LED on for ontime, then off for offtime
cofunc flashled[4](int led, int ontime, int offtime) {
    for(;;) {
        waitfor(DelayMs(ontime));                       // on delay
        WrPortI(PADR,&PADRShadow,(1<<led)|PADR);        // turn LED off
        waitfor(DelayMs(offtime);                       // off delay
        WrPortI(PADR,&PADRShadow,(1<<led)^0xff&PADR);   // turn LED on
    }
}

main {
    // Initialize ports
    WrPortI(SPCR,&SPCRShadow,0x84);    // Set Port A all outputs, LEDs on
    WrPortI(PEFR,&PEFRShadow,0x00);    // Set Port E normal I/O
    WrPortI(PEDDR,&PEDDRShadow,0x01);  // Set Port E bits 7...1 input, 0 output
    WrPortI(PECR,&PECRShadow,0x00);    // Set transfer clock as pclk/2

    for(;;) {                          // run forever
        costate {                      // start costatement
            wfd {                // use wfd (waitfordone) with cofunctions
              flashled[0](DS2,200,200); // flash DS2 on 200 ms, off 200 ms
              flashled[1](DS3,1000,500);// flash DS3 on 1000 ms, off 500 ms
            }
        }                               // end costatement
    }                                   // end for loop
}                                       // end of main, never come here

Load and run the program.

The flashing of the LEDs is performed by the costatement. Costatements need to be executed regularly, often at least every 25 ms. To accomplish this, the costatements are enclosed in a while loop or a for loop. The term while loop is used as a handy way to describe a style of real-time programming in which most operations are done in one loop.

The costatement is executed on each pass through the big loop. When a waitfor or a wfd condition is encountered the first time, the current value of MS_TIMER is saved and then on each subsequent pass the saved value is compared to the current value. If a waitfor condition is not encountered, then a jump is made to the end of the costatement, and on the next pass of the loop, when the execution thread reaches the beginning of the costatement, execution passes directly to the waitfor statement. The costatement has the property that it can wait for long periods of time, but not use a lot of execution time. Each costatement is a little program with its own statement pointer that advances in response to conditions. On each pass through the big loop, as little as one statement in the costatement is executed, starting at the current position of the costatement's statement pointer. Consult the Dynamic C Premier User's Manual for more details.

This program also illustrates a use for a shadow register. A shadow register is used to keep track of the contents of an I/O port that is write only - it can't be read back. If every time a write is made to the port the same bits are set in the shadow register, then the shadow register has the same data as the port register.

4.4 Advantages of Cooperative Multitasking

Cooperative multitasking, as implemented with language extensions, has the advantage of being intuitive. Unlike preemptive multitasking, variables can be shared between different tasks without having to take elaborate precautions. Sharing variables between tasks is the greatest cause of bugs in programs that use preemptive multitasking. It might seem that the biggest problem would be response time because of the big loop time becoming long as the program grows. Our solution for that is called slicing, which is further described in the Dynamic C Premier User's Manual.