5. Software Reference

RabbitCore RCM3900
User's Manual

5. Software Reference

Dynamic C is an integrated development system for writing embedded software. It runs on an IBM-compatible PC and is designed for use with Rabbit controllers and other controllers based on the Rabbit microprocessor. Chapter 5 describes the libraries and function calls related to the RCM3900.

5.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. A complete reference guide to Dynamic C is contained in the Dynamic C User's Manual.

You have a choice of doing your software development in the flash memory or in the static SRAM included on the RCM3900. The flash memory and SRAM options are selected with the Options > Program Options > Compiler menu.

The advantage of working in RAM is to save wear on the flash memory, which is limited to about 100,000 write cycles. The disadvantage is that the code and data might not both fit in RAM.

NOTE An application should be run from the program execution SRAM after the serial programming cable is disconnected. Your final code must always be stored in flash memory for reliable operation. RCM3900 modules have a fast program execution SRAM that is not battery-backed. Select Code and BIOS in Flash, Run in RAM from the Dynamic C Options > Project Options > Compiler menu to store the code in flash and copy it to the fast program execution SRAM at run-time to take advantage of the faster clock speed. This option optimizes the performance of RCM3900 modules running at 44.2 MHz.
NOTE Do not depend on the flash memory sector size or type in your program logic. The RCM3900 and Dynamic C were designed to accommodate flash devices with various sector sizes in response to the volatility of the flash-memory market.

Developing software with Dynamic C is simple. Users can write, compile, and test C and assembly code without leaving the Dynamic C development environment. Debugging occurs while the application runs on the target. Alternatively, users can compile a program to an image file for later loading. Dynamic C runs on PCs under Windows 2000 and later—see Rabbit's Technical Note TN257, Running Dynamic C® With Windows Vista®, for additional information if you are using a Dynamic C release prior to v. 9.60 under Windows Vista. Programs can be downloaded at baud rates of up to 460,800 bps after the program compiles.

Dynamic C has a number of standard features.

Full-feature source and/or assembly-level debugger, no in-circuit emulator required.

Royalty-free TCP/IP stack with source code and most common protocols.

Hundreds of functions in source-code libraries and sample programs:

u Exceptionally fast support for floating-point arithmetic and transcendental functions.

u RS-232 and RS-485 serial communication.

u Analog and digital I/O drivers.

u I2C, SPI, GPS, file system.

u LCD display and keypad drivers.

Powerful language extensions for cooperative or preemptive multitasking

Loader utility program to load binary images into Rabbit targets in the absence of Dynamic C.

Provision for customers to create their own source code libraries and augment on-line help by creating "function description" block comments using a special format for library functions.

Standard debugging features:

u Breakpoints—Set breakpoints that can disable interrupts.

u Single-stepping—Step into or over functions at a source or machine code level, µC/OS-II aware.

u Code disassembly—The disassembly window displays addresses, opcodes, mnemonics, and machine cycle times. Switch between debugging at machine-code level and source-code level by simply opening or closing the disassembly window.

u Watch expressions—Watch expressions are compiled when defined, so complex expressions including function calls may be placed into watch expressions. Watch expressions can be updated with or without stopping program execution.

u Register window—All processor registers and flags are displayed. The contents of general registers may be modified in the window by the user.

u Stack window—shows the contents of the top of the stack.

u Hex memory dump—displays the contents of memory at any address.

u STDIO window—printf outputs to this window and keyboard input on the host PC can be detected for debugging purposes. printf output may also be sent to a serial port or file.

5.1.1 Developing Programs Remotely with Dynamic C

Dynamic C is an integrated development environment that allows you to edit, compile, and debug your programs. Dynamic C has the ability to allow programming over the Internet or local Ethernet. This is accomplished in one of two ways.

Via the Rabbit RabbitLink, which allows a Rabbit-based target to have programs downloaded to it and debugged with the same ease as exists when the target is connected directly to a PC.

Dynamic C provides sample programs to illustrate the use of a download manager. The DLM_TCP.C and DLP_TCP.C sample programs found in the Dynamic C SAMPLES\DOWN_LOAD folder, are intended to be compiled to the program flash memory (which is a parallel flash memory). Custom applications based on these sample programs may use the NAND flash for data storage.

5.2 Dynamic C Functions

5.2.1 Digital I/O

The RCM3900 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.

When using the external I/O bus on the Rabbit 3000 chip, add the line
#define PORTA_AUX_IO    // required to enable auxiliary I/O bus
to the beginning of any programs using the auxiliary I/O bus.

The sample programs in the Dynamic C SAMPLES/RCM3900 folder provide further examples.

5.2.2 SRAM Use

The RCM3900 has a battery-backed data SRAM and a program-execution SRAM. Dynamic C provides the protected keyword to identify variables that are to be placed into the battery-backed SRAM. The compiler generates code that creates a backup copy of a protected variable before the variable is modified. If the system resets while the protected variable is being modified, the variable's value can be restored when the system restarts.

The sample code below shows how a protected variable is defined and how its value can be restored.
protected nf_device nandFlash;
int main() {
   ...
   _sysIsSoftReset();    // restore any protected variables
The bbram keyword may be used instead if there is a need to store a variable in battery-backed SRAM without affecting the performance of the application program. Data integrity is not assured when a reset or power failure occurs during the update process.

Additional information on bbram and protected variables is available in the Dynamic C User's Manual.

5.2.3 Serial Communication Drivers

Library files included with Dynamic C provide a full range of serial communications support. The LIB\Rabbit3000\RS232.LIB library provides a set of circular-buffer-based serial functions. The LIB\Rabbit3000\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, allowing other functions to be performed between calls. For more information, see the Dynamic C Function Reference Manual and Technical Note TN213, Rabbit Serial Port Software.

5.2.4 TCP/IP Drivers

The TCP/IP drivers are located in the LIB\Rabbit3000\TCPIP folder. Complete information on these libraries and the TCP/IP functions is provided in the Dynamic C TCP/IP User's Manual.

5.2.5 NAND Flash Drivers

The Dynamic C LIB\Rabbit3000\NANDFlash\NFLASH.LIB library is used to interface to NAND flash memory devices on the RCM3900. The function calls were written specifically to work with industry-standard flash devices with a 528-byte page program and 16896-byte block erase size. The NAND flash function calls are designed to be closely cross-compatible with the newer serial flash function calls found in the LIB\Rabbit3000\SFLASH.LIB library. These function calls use an nf_device structure as a handle for a specific NAND flash device. This allows multiple NAND flash devices to be used by an application.

More information on these function calls is available in the Dynamic C Function Reference Manual.

The NAND flash is ideally suited to store files with a directory structure. The Dynamic C FAT file system module provides support for a file system for use in a Rabbit-based system. The supporting documentation for the Dynamic C FAT File System and the sample programs in the SAMPLES\FileSystem\FAT folder illustrate the use of the Dynamic C FAT file system.

5.2.6 miniSD™ Card Drivers

The Dynamic C LIB\SDflash\SDFLASH.LIB library is used to interface to miniSD™ Card memory devices on an SPI bus. More information on these function calls is available in the Dynamic C Function Reference Manual.

Application developers are cautioned against modifying the BIOS code to insert application-specific external I/O (IOE) instructions before the GOCR register and its shadow are initialized by the standard BIOS code. Such IOE code will cause the miniSD™ Card select to toggle, possibly interfering with the miniSD™ Card operation.

The miniSD™ Card is ideally suited to store files with a directory structure. The Dynamic C FAT file system included with Dynamic C provides support for a file system and for formatting the miniSD™ Card for use in a Rabbit-based system. This allows files to be read and written in a PC-compatible manner. The supporting documentation for the Dynamic C FAT File System and the sample programs in the SAMPLES\FileSystem\FAT folder illustrate the use of the Dynamic C FAT file system.

NOTE Dynamic C has a utility for partitioning storage devices. Rabbit recommends that you do not partition the miniSD™ Card since doing so would make it not PC-compatible.

5.2.7 Prototyping Board Function Calls

The functions described in this section are for use with the Prototyping Board features. The source code is in the Dynamic C SAMPLES\RCM3900\RCM39xx.LIB library if you need to modify it for your own board design.

Other generic functions applicable to all devices based on Rabbit microprocessors are described in the Dynamic C Function Reference Manual.

5.2.7.1 Board Initialization

brdInit

void brdInit (void);

Description

Call this function at the beginning of your program. This function initializes Parallel Ports A through G for use with the Prototyping Board.
This function call is intended for demonstration purposes only, and can be modified for your applications.
Summary of Initialization
1. I/O port pins are configured for Prototyping Board operation.

2. Unused configurable I/O are set as tied inputs or outputs.

3. The external I/O bus is enabled.

4. The LCD/keypad module is disabled.

5. RS-485 is not enabled.

6. RS-232 is not enabled.

7. LEDs are off.

8. Ethernet select is disabled.

9. Motor control is disabled.

10. The relay is set to normally closed positions.

Return Value

None.

5.2.7.2 Digital I/O

digIn

int digIn(int channel);

Description

Reads the input state of a digital input on headers J5 and J6 on the Prototyping Board.
Do not use this function call if you configure these pins for alternate use after brdInit() is called.
A runtime error will occur if brdInit() has not been called first.

Parameter

channel
the channel number corresponding to the digital input channel:
0—IN0
1—IN1
2—IN2
3—IN3
4—QD1B
5—QD1A
6—QD2B
7—QD2A

Return Value

The logic state (0 or 1) of the input. A run-time error will occur if the channel parameter is out of range.

See Also
brdInit
digOut

void digOut(int channel, int value);

Description

Writes a value to an output channel on Prototyping Board header J10. Do not use this function if you have installed the stepper motor chips at U2 and U3.

Parameters

channel
output channel 0–7 (OUT00–OUT07).

value
value (0 or 1) to output.

Return Value

None.

See Also
brdInit
5.2.7.3 Switches, LEDs, and Relay

switchIn

int switchIn(int swin);

Description

Reads the state of a switch input.
A runtime error will occur if brdInit() has not been called first or if the swin parameter is invalid.

Parameters

swin
switch input to read:
2—S2
3—S3

Return Value

State of the switch input:
1 = open
0 = closed

See Also
brdInit
ledOut

void ledOut(int led, int value);

Description

Controls LEDs on the Prototyping Board and on the RCM3900.
A runtime error will occur if brdInit() has not been called first.

Parameters

led
the LED to control:
0 = red BSY LED on RCM3900
3 = DS3 on Prototyping Board
4 = DS4 on Prototyping Board
5 = DS5 on Prototyping Board
6 = DS6 on Prototyping Board

value
the value used to control the LED:
0 = off
1 = on

RETURN VALUE

None.

SEE ALSO
brdInit
relayOut

void relayOut(int relay, int value);

Description

Sets the position for the relay common contact. The default position is for normally closed contacts.
A runtime error will occur if brdInit() has not been called first.

Parameters

relay
the one relay (1)

value
the value used to connect the relay common contact:
0 = normally closed positions (NC1 and NC2)
1 = normally open positions (NO1 and NO2)

Return Value

None.

See Also
brdInit
5.2.7.4 Serial Communication

ser485Tx

void ser485Tx(void);

Description

Enables the RS-485 transmitter. Transmitted data are echoed back into the receive data buffer. The echoed data may be used as an indicator for disabling the transmitter by using one of the following methods:
Byte mode—disable the transmitter after the same byte that is transmitted is detected in the receive data buffer.

Block data mode—disable the transmitter after the same number of bytes transmitted are detected in the receive data buffer.

Remember to call the serXopen() function before running this function.

Return Value

None.

SEE ALSO
ser485Rx
ser485Rx

void ser485Rx(void);

Description

Disables the RS-485 transmitter. This puts the device into the listen mode, which allows it to receive data from the RS-485 interface.
Remember to call the serXopen() function before running this function.

Return Value

None.

SEE ALSO
ser485Tx
5.3 Upgrading Dynamic C

Dynamic C patches that focus on bug fixes are available from time to time. Check the Web site www.rabbit.com/support/ for the latest patches, workarounds, and bug fixes.

5.3.1 Extras

Dynamic C installations are designed for use with the board they are included with, and are included at no charge as part of our low-cost kits.

Starting with Dynamic C version 9.60, which is included with the RCM3900 Development Kit, Dynamic C includes the popular µC/OS-II real-time operating system, point-to-point protocol (PPP), FAT file system, RabbitWeb, and other select libraries. Rabbit also offers for purchase the Rabbit Embedded Security Pack featuring the Secure Sockets Layer (SSL) and a specific Advanced Encryption Standard (AES) library.

In addition to the Web-based technical support included at no extra charge, a one-year telephone-based technical support subscription is also available for purchase.

Visit our Web site at www.rabbit.com for further information and complete documentation.

Rabbit—A Digi International Brand
www.rabbit.com