3. Software Reference

Dynamic C Premier is an integrated development system for writing embedded software. It runs on an IBM-compatible PC and is designed for use with Z-World controllers and other controllers based on the Rabbit microprocessor. Chapter 3 provides the libraries, function calls, and sample programs related to the RCM2100.

3.1 More About Dynamic C

Dynamic C has been in use worldwide since 1989. It is specially designed for programming embedded systems, and features quick compile and interactive debugging in the real environment. A complete reference guide to Dynamic C is contained in the Dynamic C Premier User's Manual.

Dynamic C for Rabbit 2000^TM processors uses the standard Rabbit programming interface. This is a 10-pin connector that connects to the Rabbit 2000 serial port A. It is possible to reset and cold-boot a Rabbit processor via the programming port. No software needs to be present in the target system. More details are available in the Rabbit 2000 Microprocessor User's Manual.

Dynamic C cold-boots the target system and compiles the BIOS. The BIOS is a basic program of a few thousand bytes in length that provides the debugging and communication facilities that Dynamic C needs. Once the BIOS has been compiled, the user can compile his own program and test it. If the user program stops running, a new cold boot and BIOS compile can be done at any time.

Dynamic C does not use include files, rather it has libraries that are used for the same purpose, that is, to supply functions and function prototypes to programs before they are compiled.

Dynamic C supports assembly language, either as separate functions or as fragments embedded in C programs. Interrupt routines may be written in Dynamic C or in assembly language.

3.1.1 Operating System Framework

Dynamic C does not include an operating system in the usual sense of a complex software system that is resident in memory. The user has complete control of what is loaded as a part of his program, other than those routines that support loading and debugging (which are inactive at embedded run time). However, certain routines are very basic and normally should always be present and active.

• Periodic interrupt routine. This interrupt routine is driven by the Rabbit periodic interrupt facility, and when enabled creates an interrupt every 16 ticks of the 32.768 kHz oscillator, or every 488 µs. This routine drives three long global variables that keep track of the time: SEC_TIMER, MS_TIMER, and TICK_TIMER that respectively count seconds, milliseconds, and 488 µs ticks. These variables are needed by some functions that measure time. The SEC_TIMER is set to seconds elapsed since 1 Jan 1980, and thus also keeps track of the time and date. The periodic interrupt routine must be disabled when the microprocessor enters sleepy mode and the processor clock is operating at 32.768 kHz. The interrupt routine cannot complete at this slow speed before the next tick of the periodic interrupt. In this situation, the hardware real-time clock can be read directly to provide the time.
• The periodic interrupt function also hits the hardware watchdog timer. Software or "virtual" watchdog timers are available in Dynamic C. See the Dynamic C Premier User's Manual for more information.

3.1.2 Using Dynamic C

You have a choice of doing your software development in the flash memory or in the static RAM. There are 512K or 256K bytes of flash memory and 512K or 128K bytes of SRAM. The advantage of working in RAM is to save wear on the flash, which is limited to about 100,000 writes.

NOTE	Note that an application can be developed in RAM, but cannot run standalone from RAM after the programming cable is disconnected. All applications can only run from flash memory.
NOTE	Do not depend on the flash memory sector size or type. Due to the volatility of the flash memory market, the RCM2100 and Dynamic C were designed to accommodate flash devices with various sector sizes.

The disadvantage of using flash memory when debugging a program is that interrupts must be disabled for approximately 5 ms to 20 ms whenever a break point is set in the program. This can crash fast interrupt routines that are running while you stop at a break point or single-step the program.

Flash memory or RAM is selected with the Dynamic C Options > Compiler menu.

3.2 Dynamic C Libraries

With Dynamic C running, click File > Open, and select Lib. The following list of Dynamic C libraries will be displayed.

There is no unique library that is specific to the RCM2100. The functions in the above libraries are described in the Dynamic C Premier User's Manual.

3.2.1 I/O

The RCM2100 was designed to interface with other systems, and so there are no drivers written specifically for the I/O. The general Dynamic C read and write functions allow you to customize the parallel I/O to meet your specific needs. For example, use

WrPortI(PEDDR, &PEDDRShadow, 0x00);

to set all the port E bits as inputs, or use

WrPortI(PEDDR, &PEDDRShadow, 0xFF);

to set all the port E bits as outputs.

The sample programs in the Dynamic C SAMPLES/RCM2100 directory provide further examples.

3.2.1.1 PCLK Output

The PCLK output is controlled by bits 7 and 6 of the Global Output Register (GOCR) on the Rabbit 2000 microprocessor, and so can be enabled or disabled in software. Starting with Dynamic C v 7.02, the PCLK output is disabled by default at compile time to minimize radiated emissions; the PCLK output is enabled in earlier versions of Dynamic C.

Use the following code to set the PCLK output as needed.

PCLK output driven with peripheral clock:

	 WrPortI(GOCR, &GOCRShadow, (GOCRShadow&~0xc0));

PCLK output driven with peripheral clock ÷ 2:

	 WrPortI(GOCR, &GOCRShadow, ((GOCRShadow&~0xc0)| 0x40));	 

PCLK output off (low):

	 WrPortI(GOCR, &GOCRShadow, ((GOCRShadow&~0xc0)| 0x80));

PCLK output on (high):

	 WrPortI(GOCR, &GOCRShadow, (GOCRShadow | 0xc0));

3.2.2 Serial Communication Drivers

Library files included with Dynamic C provide a full range of serial communications support. The RS232.LIB library provides a set of circular-buffer-based serial functions. The PACKET.LIB library provides packet-based serial functions where packets can be delimited by the 9th bit, by transmission gaps, or with user-defined special characters. Both libraries provide blocking functions, which do not return until they are finished transmitting or receiving, and nonblocking functions, which must be called repeatedly until they are finished. For more information, see the Dynamic C Premier User's Manual and Technical Note 213, Rabbit 2000 Serial Port Software.

3.2.3 TCP/IP Drivers

The TCP/IP drivers are located in the TCPIP directory.

Complete information on these libraries and the TCP/IP functions is provided in the Dynamic C TCP/IP User's Manual.

3.3 Sample Programs

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. For example, the sample program PONG.C demonstrates the output to the Dynamic C STDIO window.

Two folders contain sample programs that illustrate features unique to the RabbitCore RCM2100.

• RCM2100--Demonstrates the basic operation and the Ethernet functionality of the RabbitCore RCM2100.
• TCPIP--Demonstrates more advanced TCP/IP programming for Z-World's Ethernet-enabled Rabbit-based boards.

Follow the instructions included with the sample program to connect the RabbitCore RCM2100 and the other hardware identified in the instructions.

To run a sample 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 RCM2100 must be in Program Mode (see Section 2.5, "Programming Cable") and must be connected to a PC using the programming cable.

More complete information on Dynamic C is provided in the Dynamic C Premier User's Manual.

3.4 Upgrading Dynamic C

Dynamic C patches that focus on bug fixes are available from time to time. Check the Web sites

• www.zworld.com/support/supportcenter.html

or

• www.rabbitsemiconductor.com/support.html

for the latest patches, workarounds, and bug fixes.

The default installation of a patch or bug fix is to install the file in a directory (folder) different from that of the original Dynamic C installation. Z-World recommends using a different directory so that you can verify the operation of the patch without overwriting the existing Dynamic C installation. If you have made any changes to the BIOS or to libraries, or if you have programs in the old directory (folder), make these same changes to the BIOS or libraries in the new directory containing the patch. Do not simply copy over an entire file since you may overwrite a bug fix; of course, you may copy over any programs you have written. Once you are sure the new patch works entirely to your satisfaction, you may retire the existing installation, but keep it available to handle legacy applications.

3.4.1 Upgrades

A special edition of Dynamic C, Dynamic C SE, is included on the CD that comes with the RabbitCore RCM2100 Development Kit, and has been customized with all the libraries and features needed to develop and run an application on the RCM2100.

More advanced users who may need upgrades and additional capabilities for other Z-World products in the future are encouraged to consider the standard edition of Dynamic C Premier, which Z-World plans to fully supported with upgrades now and into the future.