TCP/IP Development Kit
Getting Started
PREV NEXT INDEX


3. Installing Dynamic C

To develop and debug programs for the TCP/IP Development Board (and for all other Z-World and Rabbit Semiconductor hardware), you must install and use Dynamic C. This chapter takes you through the installation of Dynamic C, and then provides a tour of its major features with respect to the TCP/IP Development Board.

3.1 An Overview of Dynamic C

Dynamic C integrates the following development functions into one program:

In fact, compiling, linking and loading are one function. Dynamic C does not use an In-Circuit Emulator; programs being developed are downloaded to and executed from the "target" system via an enhanced serial-port connection. Program development and debugging take place seamlessly across this connection, greatly speeding system development.

Other features of Dynamic C include:

3.2 System Requirements

To install and run Dynamic C, your system must be running one of the following operating systems:

3.2.1 Hardware Requirements

The PC on which you install Dynamic C should have the following hardware:

3.3 Installing Dynamic C

Insert the Dynamic C CD-ROM in the drive on your PC. If autorun is enabled, the CD installation will begin automatically.

If autorun is disabled or the installation otherwise does not start, use the Windows Start > Run menu or Windows Disk Explorer to launch SETUP.EXE from the root folder of the CD-ROM.

The installation program will guide you through the installation process. Most steps of the process are self-explanatory and not covered in this section. Selected steps that may be confusing to some users are outlined below. (Some of the installation utility screens may vary slightly from those shown.)

3.3.1 Program & Documentation File Location

Dynamic C's application, library and documentation files can be installed in any convenient location on your workstation's hard drives.


The default location, as shown in the example above, is in a folder named for the version of Dynamic C, placed in the root folder of the C: drive. If this location is not suitable, enter a different root path before clicking Next >. Files are placed in the specified folder, so do not set this location to a drive's root directory.

3.3.2 Installation Type

Dynamic C has two components that can be installed together or separately. One component is Dynamic C itself, with the development environment, support files and libraries. The other component is the documentation library in HTML and PDF formats, which may be left uninstalled to save hard drive space or installed elsewhere (on a separate or network drive, for example).


The installation type is selected in the installation menu shown above. The options are:

3.3.3 Select COM Port

Dynamic C uses a COM (serial) port to communicate with the target development system. The installation allows you to choose the COM port that will be used.


The default selection, as shown in the example above, is COM1. You may select any available port for Dynamic C's use. If you are not certain which port is available, select COM1. This selection can be changed later within Dynamic C.

NOTE The installation utility does not check the selected COM port in any way. Specifying a port in use by another device (mouse, modem, etc.) may cause temporary problems when Dynamic C is started.

3.3.4 Desktop Icons

Once your installation is complete, you will have up to three icons on your PC desktop, as shown below.


One icon is for Dynamic C, one opens the documentation menu, and the third is for the Rabbit Field Utility, a tool used to download precompiled software to a target system.

3.4 Starting Dynamic C

Once the TCP/IP Development Board is set up and connected as described in Chapter 2 and Dynamic C has been installed, start Dynamic C by double-clicking on the Dynamic C icon. Dynamic C should start, then look for the target system on the COM port you specified during installation (by default, COM1). Once detected, Dynamic C should go through a sequence of steps to cold-boot the module and compile the BIOS.

If you receive the message beginning "BIOS successfully compiled ..." you are ready to continue with the sample programs in the next chapter.

3.4.1 Communication Error Messages

If you receive the message "No Rabbit Processor Detected," the programming cable may be connected to a different COM port, a connection may be faulty, or the target system may not be powered up. First, check to see that the power supply is connected correctly. If it is, check both ends of the programming cable to ensure that it is firmly plugged into the PC and the TCP/IP Development Board's programming port.

If there are no faults with the hardware, select a different COM port within Dynamic C. From the Options menu, select Communications. The dialog shown should appear.


Select another COM port from the list, then click OK. Press <Ctrl-Y> to force Dynamic C to recompile the BIOS. If Dynamic C still reports it is unable to locate the target system, repeat the above steps until you locate the active COM port.

If Dynamic C appears to compile the BIOS successfully, but you then receive a communication error message, it is possible that your PC cannot handle the 115,200 bps baud rate. Try changing the baud rate to 57,600 bps as follows.

If you are using Dynamic C version 7.04 or earlier, modify the BIOS source code as follows. Skip these three steps if your version of Dynamic C is 7.05 or later.

1. Open the BIOS source code file named RABBITBIOS.C, which can be found in the BIOS directory.
2. Change the line 

#define USE115KBAUD 1   // set to 0 to use 57600 baud
to read as follows. 

#define USE115KBAUD 0   // set to 0 to use 57600 baud
3. Save the changes using File > Save.

Now press <Ctrl-Y>. You should receive the "BIOS successfully compiled ..." message indicating that the target is now ready to compile a program. You should then continue with the sample programs in the next chapter.

3.5 PONG.C

You are now ready to test your set-up by running a sample program.

Find the file PONG.C, which is in the Dynamic C SAMPLES folder. To run the program, open it with the File menu (if it is not still open), compile it using the Compile menu, and then run it by selecting Run in the Run menu. The STDIO window will open and will display a small square bouncing around in a box.

This program does not test the TCP/IP part of the board, but does ensure that the board is functional. The sample program in the next chapter tests the TCP/IP portion of the board.

3.6 Sample Programs

Other 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 ICOM and TCPIP folders provide sample programs specific to the TCP/IP Development Board. Let's take a look at the TCPIP folder.


The various folders contain sample programs to illustrate the topics associated with the TCP/IP Development Board. See An Introduction to TCP/IP for more information on these topics.

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

3.6.1 Running Sample Program DEMOBRD1.C

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

Before running this sample program, you will have to connect the Demonstration Board from the TCP/IP Development Kit to the TCP/IP Development Board. Proceed as follows.

1. Use the wires included in the TCP/IP Development Kit to connect header J1 on the Demonstration Board to header J7 on the TCP/IP Development Board. The connections are shown in Figure 4.

2. Make sure that your TCP/IP Development Board is connected to your PC and that the power supply is connected to the TCP/IP Development Board and plugged in as described in Section 2.2.


Figure 4. Connections Between TCP/IP Development Board and Demonstration Board

Now, open the file DEMOBRD1.C, which is in the Samples/ICOM 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 DEMOBRD1.C

To run the program DEMOBRD1.C, load it with the File menu, compile it using the Compile menu, and then run it by selecting Run in the Run menu. LED1 and LED2 on the Demonstration Board should start going on and off if everything went well. If this doesn't work, review the following points.

3.6.2 Single-Stepping

Compile or re-compile DEMOBRD1.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.

3.6.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.

3.6.2.2 Break Point

Move the cursor to the start of the statement: 


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

To set a break point on this statement, type F2 or select 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. The break point will start flashing both red and green colors. Note that LED1 on the Demonstration Board is now solidly turned on. This is because we have passed the statement turning on LED1.

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 LED1 should be flashing again because 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.

3.6.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 20000 in the for (.. statement to 10000. Then use the F9 key to recompile and run the program. The LEDs will start flashing, but it will flash much faster than before because you have changed the loop counter terminal value from 20000 to 10000.

3.6.2.4 Watching Variables Dynamically

Go back to edit mode (select edit) and load the program DEMOBRD2.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 DEMOBRD2.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.

3.6.2.5 Summary of Features

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

3.6.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 a different 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 DEMOBRD3.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 DEMOBRD3.C sample program has two independent tasks. The first task flashes LED2 once a second. The second task uses button SW1 on the Demonstration Board to toggle the logical value of a virtual switch, vswitch, and flash LED1 each time the button is pressed. This task also debounces button SW1.

Note that the Demonstration Board has to be connected to the TCP/IP Development Board as described in Section 3.6.1 to be able to run DEMOBRD3.C. 


main() {
    int vswitch;        // state of virtual switch controlled by button S1

    WrPortI(PDDDR, &PDDDRShadow, 0x03); // set port D bits 0-1 as outputs
    WrPortI(PDDCR, &PDDCRShadow, 0x00); // set port D to not open drain mode
    vswitch = 0;                        // initialize virtual switch as off

(1)  while (1) {                         // endless loop
        
        // First task will flash LED4 for 200 ms once per second.

(2)      costate {
            BitWrPortI(PDDR, &PDDRShadow, 0xFF, 1);    // turn LED on
(3)          waitfor(DelayMs(200));                     // wait 200 ms
            BitWrPortI(PDDR, &PDDRShadow, 0x00, 1);    // turn LED off
            waitfor(DelayMs(800));                     // wait 800 ms
(4)     }

        // Second task - debounce SW1 and toggle vswitch

        costate {
(5)          if (!BitRdPortI(PDDR, 2)) abort; // if button not down skip out
            waitfor(DelayMs(50));            // wait 50 ms
            if(!BitRdPortI(PDDR, 2))  abort; // if button not still down exit

            vswitch = !vswitch;       // toggle since button was down 50 ms

            while (1) {
                waitfor(!BitRdPortI(PDDR, 2));  // wait for button to go up
                waitfor(DelayMs(200));          // wait additional 200 ms
                if (!BitRdPortI(PDDR, 2))
                    break;    // if button still up break out of while loop
            }
        }                     // end of costate

        // make LED1 agree with vswitch

(6)      BitWrPortI(PDDR, &PDDRShadow, vswitch, 0);

(7)  }   // end of while loop
}       // end of main

The numbers in the left margin are reference indicators, and are not a part of the code. Load and run the program. Note that LED2 flashes once per second. Push button SW1 several times and note how LED1 is toggled.

The flashing of LED2 is performed by the costatement starting at the line marked (2). Costatements need to be executed regularly, often at least every 25 ms. To accomplish this, the costatements are enclosed in a while 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 while loop starts at (1) and ends at (7).

The statement at (3) waits for a time delay, in this case 200 ms. The costatement is being executed on each pass through the big loop. When a waitfor 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 (4), 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. Once 200 ms has passed, the statement after the waitfor is executed. 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.

The second costatement in the program debounces the switch and maintains the variable vswitch. Debouncing is performed by making sure that the switch is either on or off for a long enough period of time to ensure that high-frequency electrical hash generated when the switch contacts open or close does not affect the state of the switch. The abort statement is illustrated at (5). If executed, the internal statement pointer is set back to the first statement within the costatement, and a jump to the closing brace of the costatement is made.

At (6) a use for a shadow register is illustrated. 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. In this case a test is made to see the state of the LED and make it agree with the state of vswitch. This test is not strictly necessary, the output register could be set every time to agree with vswitch, but it is placed here to illustrate the concept of a shadow register.

To illustrate the use of snooping, use the watch window to observe vswitch while the program is running. Add the variable vswitch to the list of watch expressions. Then toggle vswitch and the LED. Then type <Ctrl-U> to observe vswitch again.

3.6.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 a device caused slicing that is further described in the Dynamic C Premier User's Manual.

Rabbit Semiconductor
http://www.rabbitsemiconductor.com
Voice: (530) 757-8400
FAX: (530) 757-8402
sales@rabbitsemiconductor.com
PREV NEXT INDEX