Rabbit 2000 User manual

Rabbit 2000™
Microprocessor Development Kit
Getting Started
010118 - D

Rabbit 2000 Development Kit
Rabbit 2000 Development Kit Getting Started Manual
Part Number 019-0068 • 010118 - D • Printed in U.S.A.
Copyright
© 1999 Rabbit Semiconductor • All rights reserved.
Rabbit Semiconductor reserves the right to make changes and improvements to its prod-
ucts without providing notice.
Trademarks
•Dynamic C®is a registered trademark of Z-World, Inc.
•Windows®is a registered trademark of Microsoft Corporation
•Jackrabbit™is a trademark of Z-World, Inc.
•Rabbit 2000™is a trademark of Rabbit Semiconductor
Notice to Users
When a system failure may cause serious consequences, protecting life and property
against such consequences with a backup system or safety device is essential. The buyer
agrees that protection against consequences resulting from system failure is the buyer’s
responsibility.
This device is not approved for life-support or medical systems.
All Rabbit Semiconductor products are 100 percent functionally tested. Additional testing
may include visual quality control inspections or mechanical defects analyzer inspections.
Specifications are based on characterization of tested sample units rather than testing over
temperature and voltage of each unit. Rabbit Semiconductor may qualify components to
operate within a range of parameters that is different from the manufacturer’s recom-
mended range. This strategy is believed to be more economical and effective. Additional
testing or burn-in of an individual unit is available by special arrangement.
Company Address
Rabbit Semiconductor
2932 Spafford Street
Davis, California 95616-6800
USA
Telephone: [phone]
Facsimile: [phone]
Web site: http://www.rabbitsemiconductor.com

Getting Started Manual
Table of Contents
About This Manual
1. Introduction.....................................................................................................................1
1.1 Kit Contents.................................................................................................................................1
1.2 Documentation ............................................................................................................................1
1.3 An Overview of Dynamic C for the Rabbit ................................................................................2
2. Detailed Installation Instructions....................................................................................5
2.1 Software Installation ...................................................................................................................5
2.2 Getting Hooked Up .....................................................................................................................5
2.2.1 Prototyping Board......................................................................................................6
2.2.2 Jackrabbit Board ........................................................................................................7
2.3 Starting Dynamic C.....................................................................................................................8
3. Sample Programs............................................................................................................9
3.1 Running Sample Program DEMOJR1.C...................................................................................10
3.2 Single-Stepping.........................................................................................................................11
3.2.1 Watch Expression.....................................................................................................11
3.2.2 Break Point ..............................................................................................................11
3.2.3 Editing the Program.................................................................................................12
3.2.4 Watching Variables Dynamically.............................................................................12
3.2.5 Summary of Features...............................................................................................12
3.3 Cooperative Multitasking..........................................................................................................13
3.4 Advantages of Cooperative Multitasking..................................................................................15
4. Software Reference.......................................................................................................17
4.1 More About Dynamic C............................................................................................................17
4.1.1 Operating System Framework.................................................................................17
4.2 I/O Drivers.................................................................................................................................18
4.2.1 Initialization.............................................................................................................18
4.2.2 Digital Output ..........................................................................................................18
4.2.3 Analog Output..........................................................................................................19
4.2.4 Analog Input............................................................................................................21
4.3 Serial Communication Drivers..................................................................................................22
4.3.1 Open and Close Functions.......................................................................................22
4.3.2 Non-Cofunction Blocking Input Functions .............................................................23
4.3.3 Non-Cofunction Blocking Output Functions...........................................................24
4.3.4 Single-User Cofunction Input Functions.................................................................25
4.3.5 Single-User Cofunction Output Functions ..............................................................26
4.3.6 Circular Buffer Functions........................................................................................27
Appendix A. Specifications..............................................................................................29
Schematics

Rabbit 2000 Development Kit

Getting Started Manual
About This Manual
This manual provides instructions for installing, testing, configuring, and interconnecting
the Rabbit 2000 microprocessor using the Jackrabbit controller and the Jackrabbit Devel-
opment board.
Assumptions
Assumptions are made regarding the user’s knowledge and experience in the following
areas:
•Understanding of the basics of operating a software program and editing files under
Windows on a PC.
•Knowledge of basic assembly language and architecture for controllers.
For a full treatment of C, refer to the following texts:
The C Programming Language by Kernighan and Ritchie (published by Prentice-
Hall).
and/or
C: A Reference Manual by Harbison and Steel (published by Prentice-Hall).
Pin Number 1
A black square indicates pin 1 of all headers.
Measurements
All diagram and graphic measurements are in inches followed by millimeters enclosed in
parenthesis.
J1
Pin 1

Getting Started Manual 1
1. Introduction
The Rabbit 2000 a a new and powerful microprocessor. Both hardware and software
design are easy with the Rabbit.
This kit has the essentials that you need to design your own a microprocessor-based sys-
tem, and includes a complete software development system (Dynamic C). This Develop-
ment Kit contains a powerful single-board computer (the Jackrabbit board). With this kit
you will be able to write and test complex software. You will be able to prototype circuits
that interface to a Rabbit 2000 microprocessor.
1.1 Kit Contents
The items in the kit and their use is as follows:
•CD-ROM with Dynamic C software and Rabbit 2000 documentation. You may install
this software by inserting the disk into your CD-ROM drive. If it doesn’t start automat-
ically, click on “setup.exe.”This software runs under Windows ‘95, ‘98 and Windows
NT. We suggest taking the option to load the documentation to your hard disk. The
documentation is in HTML or Adobe PDF format, and may be viewed with a browser.
•Jackrabbit controller board. This is a complete controller board that includes a Rabbit
2000 processor, 128K of flash memory and 128K of RAM (Random Access Memory).
You can use this board to demonstrate the use of the Rabbit 2000.
•Prototyping Board. The Jackrabbit board can be plugged into this board. The Prototyp-
ing Board includes various accessories such as pushbutton switches, LEDs, and a
beeper. In addition, you can add your own circuitry.
•Programming cable. This is a cable that is used to connect your PC serial port to the
Jackrabbit board to write and debug C programs that run on the Jackrabbit board.
•Loose parts kit. This bag of parts contains parts that you can solder to the Prototyping
Board for various demonstrations.
•Wall transformer. This is used to power the Jackrabbit board. The wall transformer is
supplied only for Development Kits sold for the North American market.
The Jackrab-
bit board in the Development Kit can also be powered from any DC voltage source
between 9 V and 15 V. Higher voltages can be used, but may make the regulator rather hot.
1.2 Documentation
Our documentation is provided in paperless form on the CD-ROM included in the Devel-
opment Kit. (A paper copy of this “Getting Started”manual is included.) Most documents
are provided in two formats: HTML and PDF. HTML documents can be viewed with an
internet browser, either Netscape Navigator or Internet Explorer. HTML documents are
very convenient because all the documents are hyperlinked together, and it is easy to navi-
gate from one place to another. PDF documents can be viewed using the Adobe Acrobat
reader, which is automatically invoked from the browser. The PDF format is best suited
for documents requiring high resolution, such as schematics, or if you want to print the
document. Don’t print a hardcopy from the HTML manuals because they have no page

2Rabbit 2000 Development Kit
numbers and the cross-references and table of contents links only work if viewed on line.
The PDF versions contain page number references to allow navigation when reading a
paper version of the manual. To view the online documentation with a browser, open the
file default.htm in the docs folder. When you open the default.htm file with your
browser, you will see a page similar to that shown below.
1.3 An Overview of Dynamic C for the Rabbit
The Rabbit 2000 is programmed using Z-World’s Dynamic C, an integrated development
environment that includes an editor, a C compiler, and a debugger. Library functions pro-
vide an easy-to-use interface for the Jackrabbit board included with the Development Kit.
The Jackrabbit board included with the Development Kit is a powerful board that includes
a complete Rabbit microprocessor system. A Prototyping Board that includes pushbutton
switches, LEDs, and a beeper can be plugged into the Jackrabbit board. By writing pro-
grams that run on the Jackrabbit board, you can flash the LEDs, beep the beeper, and oth-
erwise demonstrate the capabilities of the Rabbit. Schematics for both boards are included
on the CD-ROM in PDF format.
The Jackrabbit board has a standard Rabbit programming connector, which is a 10-pin,
2 mm header. A programming cable is used to connect a PC serial port (COM port) to the
Jackrabbit board. The programming cable has a level converter board in the middle of the
cable since the programming connector supports CMOS logic levels, and not the RS-232
levels that are used by PC serial ports. When the programming cable is connected,
Dynamic C running on the PC can hard reset the Jackrabbit board and cold boot it. The
cold boot includes compiling and downloading a BIOS program that stays resident while
you work. If you crash the target, Dynamic C will automatically reboot and recompile the
BIOS if it senses that a target communication error occurred.

Getting Started Manual 3
You have a choice of doing your software development in the flash memory or in the static
RAM included on the Jackrabbit board. There are 128K in each memory. Versions of the
Jackrabbit board are available that support only 32K of static RAM. If you use one of
these boards, you must do development in flash memory. The advantage of working in
RAM is to save wear on the flash, which is limited to about 100,000 writes. Note that an
application can only be developed in RAM, but cannot run standalone from RAM after the
programming cable is disconnected. All applications can only run from flash.
When using flash, the compile to a file is followed by a download to the flash. The disad-
vantage of using flash is that interrupts must be disabled for approximately 5 ms whenever
a break point is set in the program. This can crash fast interrupt routines that are running
while you stop at a breakpoint or single-step the program. Flash or RAM is selected on the
Options-Compiler menu.
Dynamic C provides a number of debugging features. You can single-step your program,
either in C, statement by statement, or in assembly language, instruction by instruction.
You can set breakpoints, where the program will stop, on any statement. You can evaluate
watch expressions. A watch expression is any C expression that can be evaluated in the
context of the program. If the program is at a breakpoint, a watch expression can view any
expression using local or external variables. If the program is running and a call to the
debugger is included in the user’s code (runwatch();), it is possible to evaluate watch
expressions using global variables only while the target program continues to run, slowed
down only by the need to refresh a display in response to a <ctrl-U> command.

4Rabbit 2000 Development Kit

Getting Started Manual 5
2. Detailed Installation Instructions
Chapter 2 contains detailed instructions for installing the software on your PC and for con-
necting the Jackrabbit board to your PC in order to run sample programs.
2.1 Software Installation
You will need approximately 10 megabytes of free space on your hard disk. The software
can be installed on your C drive or any other convenient drive.
2.2 Getting Hooked Up
Figure 1 below shows an overview of how the serial and power connections are made to
Jackrabbit board, the Prototyping Board, and to your PC.
Figure 1. Jackrabbit Hookup Connections
9-pin DE9
PC COM
port
10-pin
2 mm PROG
CMOS to RS-232
Converter
Jackrabbit
Board
Prototyping Board
Wall Transformer
Your PC
Beeper
plug
Level
connector

6Rabbit 2000 Development Kit
2.2.1 Prototyping Board
To attach the Jackrabbit board to the Prototyping Board, turn the Jackrabbit board over so
that the battery is facing up. Plug headers J4 and J5 into the sockets on the Prototyping
Board as indicated in Figure 2.
Figure 2. Attaching Jackrabbit Board to Prototyping Board
+
S5 RESET
DS1
DS6
DS7
DS8
PWR R3
Buzzer
DS2
DS3DS4
DS5
S1S2S3S4
JACKRABBIT DEVELOPMENT BOARD
VCC
RXB
TXB
PC0 PC2 PC4 PC6 AD0 DA0 PD0 PD2 PD4 PD6
GND
485
VCC
SM0
IOBEN
GND
/RST
GND RXC TXC PC1 PC3 PC5 PC7 AGND DA1 PD1 PD3 PD5 PD7 GND 485 VCC SM1 STAT VBAT
GND
Z-World, Inc.
GND
PA0 PA2 PA4 PA6
GND
PB0 PB2 PB4 PB6
WDO
GND
PE6 PE4 PE2 PE0
HV0 HV2
K
GND
VCC PA1 PA3 PA5 PA7 GND PB1 PB3 PB5 PB7 PCLK PE7 PE5 PE3 PE1 GND HV1 HV3 RAW VCC
DS1 DS2 DS3 DS4 DS5 DS6 DS7 DS8
S1 S2 S3 S4
GND
PA0 PA1 PA2 PA3 PA4 PA5 PA6 PA7 PB2 PB3 PB4 PB5 GND
Battery
JACKRABBIT
GND PA0 PA2 PA4 PA6 GND PB0 PB2 PB4 PB6 WDO GND PE6 PE4 PE2 PE0 HV0 HV2 K GND
VCC
PA1 PA3 PA5 PA7
GND
PB1 PB3 PB5 PB7
PCLK
PE7 PE5 PE3 PE1
GND
HV1 HV3
RAW
VCC
GND
RXC
TXC
PC1 PC3 PC5 PC7
AGND
DA1 PD1 PD3 PD5 PD7
GND
485
VCC
SM1
STAT
VBAT
GND
VCC RXB TXB PC0 PC2 PC4 PC6 AD0 DA0 PD0 PD2 PD4 PD6 GND 485 VCC SM0 IOBEN GND /RST
J4

Getting Started Manual 7
2.2.2 Jackrabbit Board
1. Connect the 10-pin PROG connector of the programming cable to header J3 on the
Jackrabbit board as shown in Figure 3. (If your programming cable has only one unla-
beled 10-pin connector, attach that connector to header J3 on the Jackrabbit board.)
Connect the other end of the programming cable to a COM port on your PC. Note that
COM1 is the default COM port used by Dynamic C.
Figure 3. Power and Programming Cable Connections
to Jackrabbit Board
2. Hook up the connector from the wall transformer to header J1 on the Jackrabbit board
as shown in Figure 3. The orientation of this connector is not important since the VIN
(positive) voltage is the middle pin, and GND is available on both ends of the three-pin
header J1.
3. Plug in the wall transformer. The Jackrabbit board and the Prototyping Board are ready
to be used.
A RESET button isprovided on the Prototyping Board (see Figure 2) to allow a har-
ware reset.
PROTOTYPING BOARD
JACKRABBIT BOARD
JP1
U4
VIN GNDGND
RESET
JACKRABBIT Z-World, Inc.
GND
PA0
PA2
PA4
PA6
GND
PB0
PB2
PB4
PB6
WDO
GND
PE6
PE4
PE2
PE0
HV0
HV2
K
GND
VCC
PA1
PA3
PA5
PA7
GND
PB1
PB3
PB5
PB7
PCLK
PE7
PE5
PE3
PE1
GND
HV1
HV3
RAW
VCC
GND
RXC
TXC
PC1
PC3
PC5
PC7
AGND
DA1
PD1
PD3
PD5
PD7
GND
485
VCC
SM1
STAT
VBAT
GND
VCC
RXB
TXB
PC0
PC2
PC4
PC6
AD0
DA0
PD0
PD2
PD4
PD6
GND
485
VCC
SM0
IOBEN
GND
/RST
J5
U6
U5
U3
J4
U1
J1
J2
J3
Y3
Rabbit 2000
SRAM
RS-232
RS-485
Colored side
lines up with
pin 1
To
PC COM port
PROG
DIAG
Programming
connector
Diagnostic
connector
!

8Rabbit 2000 Development Kit
2.3 Starting Dynamic C
Once the Jackrabbit board is connected as described in Section 2.2, start Dynamic C by
double-clicking on the Dynamic C icon or by double-clicking on dwc.exe in the
Dynamic C directory.
Dynamic C assumes, by default, that you are using serial port COM1 on your PC. If you
are using COM1, then Dynamic C should detect the Jackrabbit board and go through a
sequence of steps to cold-boot the Jackrabbit board and to compile the BIOS. If an error
message appears, you have probably connected to a different PC serial port such as
COM2, COM3, or COM4. You can change the serial port used by Dynamic C with the
OPTIONS menu, then try to get Dynamic C to recognize the Jackrabbit board by selecting
Recompile BIOS on the Compile menu. Try the different COM ports in the OPTIONS
menu until you find the one you are connected to. If you can’t get Dynamic C to recognize
the target on any port, then the hookup may be wrong or the COM port is not working on
your PC.
If you receive the “BIOS successfully compiled …” message after pressing <ctrl-Y> or
starting Dynamic C, and this message is followed by “Target not responding,”it is possi-
ble that your PC cannot handle the 115,200 bps baud rate. Try changing the baud rate to
57,600 bps as follows.
1. Open the BIOS source code file RABBITBIOS.C 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. Locate the Serial options dialog in the Dynamic C Options menu. Change the baud
rate to 57,600 bps, then press <ctrl-Y>.
If you receive the “BIOS successfully compiled …” message and do not receive a “Target
not responding”message, the target is now ready to compile a user program.

Getting Started Manual 9
3. Sample Programs
A series of sample programs is provided in the Dynamic C Samples/JackRab folder.
You can load a sample program by using the File Open menu in Dynamic C. The sample
programs are listed in Table 1.
The first five sample programs provide a step-by-step introduction to the Jackrabbit board.
Additional sample programs illustrate more advanced topics.
Each sample program has comments that describe to the purpose and function of the pro-
gram.
Table 1. Jackrabbit Sample Programs
DEMOJR1.C
DEMOJR2.C
DEMOJR3.C
DEMOJR6.C
JRIOTEST.C
JRIO_COF.C
RABDB01.C
RABDB02.C

10 Rabbit 2000 Development Kit
3.1 Running Sample Program DEMOJR1.C
This sample program can be used to illustrate some of the functions of Dynamic C.
First, open the file DEMOJR1.C, which is in the Samples/JackRab folder. The program
will appear in a window, as shown in Figure 4 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 4. Sample Program DEMOJR1.C
To run the program DEMOJR1.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 Development
Board should start flashing if everything went well. If this doesn’t work review the follow-
ing 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.
main(){
WrPortI(SPCR,NULL,0x84);
WrPortI(PADR,&PADRShadow,0xff);
while(1) {
BitWrPortI(PADR,&PADRShadow,1,2);
for(j=0; j<25000; j++);
BitWrPortI(PADR,&PADRShadow,0,2);
for(j=0; j<1000; j++);
} // end while(1)
} // end of main
C programs begin with main
write to SPCR register to
initialize parallel port A
to turn off all LEDs
Start a loop
Set bit 2 to a “1”
LED DS3 off.
Time delay by counting
to 25,000.
Set bit 2 to a “0”
turning LED DS3 on
Count to 1000 for a shorter
time delay
End of the endless loop
Note: See Rabbit 2000 Microprocessor User’s Manual
(Software Chapter) for details on the routines that read and
write I/O ports.
NULL is a macro for a zero pointer
Write all 1’s to port A

Getting Started Manual 11
•A message reports that “No Rabbit processor detected”in cases where the Jackrabbit
and Prototyping Board are not connected together, the wall transformer is not con-
nected, or is not plugged in. (The red power LED lights whenever power is connected.)
•The programming cable must be connected to the Jackrabbit board. (The colored wire
on the programming cable is closest to pin 1 on header J3 on the Jackrabbit board, as
shown in Figure 3 on page 7.) The other end of the programming cable must be con-
nected to the PC serial port, possibly, using the 9- to 25-pin adapter if necessary. 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 one 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.
3.2 Single-Stepping
Compile or re-compile DEMOJR1.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.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 jadvances when the statement
j++ is executed.
3.2.2 Break Point
Move the cursor to the start of the statement:
for(j=0; j<1000; 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 run-
ning 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 jin the watch window has the value
25000. This is because the loop above terminated when jreached 25000.
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.

12 Rabbit 2000 Development Kit
You can set break points while the program is running by positioning the cursor to a state-
ment 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.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 recom-
pile 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.
3.2.4 Watching Variables Dynamically
Go back to edit mode (select edit) and load the program DEMOJR2.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 keach 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 DEMOJR2.C. Now type <ctrl-W> to open the watch
window and add the watch expression kto 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 kand k*5.
3.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 Com-
pile 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 state-
ment 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 pro-
gram 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.

Getting Started Manual 13
•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 com-
mand 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 run-
watch() command that is frequently executed. In this case, only expressions involv-
ing global variables can be evaluated, and the expression is evaluated as if it were in a
separate function with no local variables.
3.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. Coop-
erative 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 Reference Manual. The example below, sample program DEMOJR3.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 costate-
ments is in the Dynamic C Reference Manual. The DEMOJR3.C sample program has two
independent tasks. The first task flashes LED DS4 once a second. The second task uses
button S1 on the Prototyping Board to toggle the logical value of a virtual switch,
vswitch, and flash DS1 each time the button is pressed. This task also debounces button
S1.

14 Rabbit 2000 Development Kit
int vswitch; // state of virtual switch controlled by button S1
main(){ // begin main program
// set up parallel port A as output
WrPortI(SPCR,NULL,0x84);
WrPortI(PADR,&PADRShadow,0xff); // turn off all LEDs
vswitch=0; // initialize virtual switch off
(1) while (1) { // Endless loop
BigLoopTop(); // Begin a big endless loop
// first task flash LED DS4 every second for 200 milliseconds
(2) costate { // begin a costatement
BitWrPortI(PADR,&PADRShadow,0,3); // LED DS4 on
(3) waitfor(DelayMs(200)); // light on for 200 ms
BitWrPortI(PADR,&PADRShadow,1,3); // LED DS4 off
waitfor(DelayMs(800)); // light off for 800 ms
(4) }// end of costatement
// second task - debounce switch #1 and toggle virtual switch vswitch
// check button 1 and toggle vswitch on or off
costate {
(5) if(BitRdPortI(PBDR,2)) abort; // if button not down skip out
waitfor(DelayMs(50)); // wait 50 ms
if(BitRdPortI(PBDR,2)) abort; // if button not still down skip out
vswitch=!vswitch; // toggle virtual switch- button was down 50 ms
while (1) { // wait for button to be off 200 ms
waitfor(BitRdPortI(PBDR,2)); // wait for button to go up
waitfor(DelayMs(200)); // wait for 200 milliseconds
if(BitRdPortI(PBDR,2)) break;// if button up break
}// end of while(1)
}// end of costatement
// make LED agree with vswitch if vswitch has changed
(6) if( (PADRShadow & 1) == vswitch) {
BitWrPortI(PADR,&PADRShadow,!vswitch,0);
)
(7) }// end of while loop, go back to start
}// end of main, never come here
The numbers in the left margin are reference indicators and are not a part of the code.
Load and run the program. Note that LED DS4 flashes once per second. Push button S1
several times and note how LED DS1 is toggled.
The flashing of LED DS4 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 function BigLoopTop() is
used to collect some operations that are helpful to do once on every pass through the loop.
Place the cursor on this function name BigLoopTop() and hit <ctrl-H> to learn more.

Getting Started Manual 15
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 encoun-
tered, 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 Reference Man-
ual 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 state-
ment 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 regis-
ter could be set every time to agree with vswitch, but it is placed here to illustrate the con-
cept 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.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 differ-
ent 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 Reference Manual.