Appendix C.  Security Software & Utility Programs

This appendix documents several useful and easy to use utility programs available from Rabbit.

This appendix documents the security software and utility programs available for Rabbit-based systems.

C.1    Dynamic C Utilities

There are several utilities bundled with Dynamic C.

C.0.1 Rabbit I/O LIB Utility

This utility is provided for configuring a Rabbit 4000 or 5000 board. All register bit assignments for the Rabbit 4000 and many register bit assignments for the Rabbit 5000 are transformed from cryptic hex num­bers into an easy-to-use GUI. You can also open a window that lets you view the corresponding register values as you make changes via the GUI.

Double-click on /Utilities/IOConfig.exe to run the utility.

When a configuration is saved, the utility will generate a library that contains a function that will execute the necessary statements to produce the selected configuration. The name of the function and the name and path of the library are chosen by the user in the “Save Configuration” dialog. If the library is saved where your “lib.dir” file can find it, then the newly created function and library can be found with Ctrl+H when running Dynamic C. The utility-generated function and library are used in application code as follows:

#use mylib.lib
main(){
   BoardInit();
   ...
}

The Rabbit I/O LIB Utility allows you to configure the following Rabbit features:

• Parallel Ports - includes configuring slave port and auxiliary I/O bus use, pin data direction and alter­nate functions.

• Serial Ports - includes configuring transfer mode, hardware pin assignment for Tx and Rx, baud rate and other serial port parameters.

• PWM - includes configuring the interrupt priority, period, duty cycle, spread function and prescaler for each PWM channel. You can also select parallel port pins for the PWM output.

• Timers - includes configuration of timers A, B and C. Includes configuring interrupt priority.

• External Interrupts - includes configuring priority level and whether interrupts occur on the rising edge, falling edge or both.

• Input Capture - includes configuring priority levels, choosing between normal and counter operation, determining trigger latch, trigger condition pin and start/stop conditions.

• External I/O - includes configuring wait states, signal polarity, selecting type of strobe signals, transac­tion timing and whether or not to enable handshaking.

• DMA - includes configuring parallel port pin assignments for triggering external DMA requests and transfer mode.

• Quadrature Decoder - includes configuring interrupt priority level, counter width (8 or 10 bits), assign­ing parallel port pins for quadrature decoder inputs and determining PCLK prescaler and timer A10 divisor.

• Slave Port - includes configuring interrupt priority level, enabling/disabling the slave port and the exter­nal I/O bus.

C.0.2 Library File Encryption

The Library File Encryption Utility, Encrypt.exe, allows distribution of sensitive runtime library files.

The encrypted library files compile normally, but cannot be read with an editor. The files will be automati­cally decrypted during Dynamic C compilation, but users of Dynamic C will not be able to see any of the decrypted contents except for function descriptions for which a public interface is given. An optional user-defined copyright notice is put at the beginning of an encrypted file.

To use this utility, double-click on the program name, Encrypt.exe. The following window will appear:

Complete instructions are available by clicking on the Help button in the upper righthand corner of the program window. Context-sensitive help is accessed by positioning the cursor over the desired subject and then pressing <F1>.

C.0.2.1 Add Files to Encrypt

There are two ways to select files to encrypt.

1. Type the path and filename in the lower window.

2. Click the Add Files to Encrypt button to bring up a file open dialog box and browse for the desired file.

The list of files to be encrypted may be edited if desired. Notice that if anything is entered in the lower window, a new button named “Encrypt” appears. Two entries in the window change it to “Encrypt All”. Clicking this button causes the utility to encrypt the file(s) listed in the lower window.

C.0.2.2 File Extension

Encrypted files will be saved with the same pathname but with the extension supplied. Dynamic C will use encrypted and non-encrypted files seamlessly, so the choice of extension is for one’s own file manage­ment.

C.0.2.3 Optional Text Area

The upper window is a text window of up to 4k bytes in length. Any text entered will appear in all files in the list appearing in the lower window. If two files are to be given unique headers, they should be encrypted separately.

This area can be used for copyright information, instructions, disclaimers, warnings, or anything else rele­vant to viewers of the file.

C.0.3 File Compression Utility

Dynamic C has a compression utility feature. The default utility implements an LZSS style compression algorithm. Support libraries to decompress files achieve a throughput of 10 KB/s to 20 KB/s (number of bytes in uncompressed file/time to decompress entire file using ReadCompressedFile()) depending upon file size and compression ratio.

The #zimport() compiler directive performs a standard #ximport, but compresses the file by invoking the compression utility before emitting the file to the target. Support libraries allow the compressed file to be decompressed on-the-fly. Compression ratios of 50% or more for text files can be achieved, thus freeing up valuable xmem space. The compression library is thread safe.

For details on compression ratios, memory usage and performance, please see Technical Note 234, “File Compression (Using #zimport)” available on our website, at www.rabbit.com.

C.0.3.1 Using the File Compression Utility

The utility is invoked by Dynamic C during compile time when #zimport is used. The keyword #zimport will compress any file. Of course some files are already in a compressed format, for example jpeg files, so trying to compress them further is not useful and may even cause the resulting compressed file to be larger than the original file. (The original file is not modified by the compression utility nor by the support libraries.) The compression of FS2 files is a special case. Instead of using #zimport, #ximport is used along with the function CompressFile().

Compressed files are decompressed on-the-fly using ReadCompressedFile(). Compressed FS2 files may also be decompressed on-the-fly by using ReadCompressedFile(). In addition, an FS2 file may be decompressed into a new FS2 file by using DecompressFile().

There are 3 sample programs to illustrate the use of file compression

• Samples/zimport/zimport.c: demonstrates #zimport

• Samples/zimport/zimport_fs2.c: demonstrates file compression in combination with the file system

• Samples/tcpip/http/zimport.c: demonstrates file compression support using the http server

C.0.3.2 File Compression/Decompression API

The file compression API consists of 7 functions, 3 of which are of prime importance:

OpenInputCompressedFile() - open a compressed file for reading or open an uncompressed #ximport file for compression.

CloseInputCompressedFile() - close input file and deallocate memory buffers.

ReadCompressedFile() - perform on-the-fly decompression.

The remaining 4 functions are included for compression support for FS2 files:

OpenOutputCompressedFile() - open FS2 file for use with CompressFile().

CloseOutputCompressedFile() - close file and deallocate memory buffers.

CompressFile() - compress an FS2 file, placing the result in a second FS2 file.

DecompressFile() - decompress an FS2 file, placing the result in a second FS2 file.

Complete descriptions are available for these functions in the Dynamic C Function Reference Manual and also via the Function Lookup facility (Ctrl+H or Help menu).

There are several macros associated with the file compression utility:

• ZIMPORT_MASK - Used to determine if the imported file is compressed (#zimport) or not (#ximport).

• OUTPUT_COMPRESSION_BUFFERS (default = 0) - Number of 24K buffers for compression (com­pression also requires a 4K input buffer, which is allocated automatically for each output buffer that is defined).

• INPUT_COMPRESSION_BUFFERS (default = 1) Number of 4KB internal buffers (in RAM) used for decompression.

Each compressed file has an associated file descriptor of type ZFILE. All fields in this structure are used internally and must not be changed by an application program.

C.0.3.3 Replacing the File Compression Utility

Users can use their own compression utility, replacing the one provided. If the provided compression util­ity is replaced, the following support libraries will also need to be replaced: zimport.lib, lzss.lib and bitio.lib. They are located in lib\..\zimport\. The default compression utility, Zcompress.exe, is located in Dynamic C’s root directory. The utility name is defined by a key in the current project file:

[Compression Utility]

Zimport External Utility=Zcompress.exe

To replace Zcompress.exe as the utility used by Dynamic C for compression, open your project file and edit the filename.

The compression utility must reside in the same directory as the Dynamic C compiler executable. Dynamic C expects the program to behave as follows:

• Take as input a file name relative to the Dynamic C installation directory or a fully qualified path.

• Produce an output file of the same name as the input file with the extension .DCZ at the end. E.g., test.txt becomes test.txt.dcz.

• Exit with zero on success, non-zero on failure.

If the utility does not meet these criteria, or does not exist, a compile-time error will be generated.

C.0.4 Font and Bitmap Converter Utility

The Font and Bitmap Converter converts Windows fonts and monochrome bitmaps to a library file format compatible with Rabbit’s Dynamic C applications and graphical displays. Non-Roman characters may also be converted by applying the monochrome bitmap converter to their bitmaps.

Double-click on the fmbcnvtr.exe file in the Utilities folder where you installed Dynamic C. Select and convert existing fonts or bitmaps. Complete instructions are available by clicking on the Help button within the utility.

When complete, the converted file is displayed in the editing window. Editing may be done, but probably won’t be necessary. Save the file as name_me.lib: the name of your choice.

Add the file to applications with the statement:

#use name_me.lib         // remember to add this filename to “lib.dir” file

or by cut and pasting from name_me.lib directly into the application file.

C.0.5 Rabbit Field Utility Module

The Rabbit Field Utility (RFU) will load a binary file created with Dynamic C to a Rabbit-based board. The RFU can be used to load a binary file without Dynamic C present on the host computer, and without recompiling the program each time it is loaded to a controller.

The Dynamic C installation created a desktop icon for the RFU. The executable file, rfu.exe, can be found in the subdirectory named “Utilities” where Dynamic C was installed. Complete instruc­tions are available by clicking on the Help button within the utility. The Help document details setup information, the file menu options and BIOS requirements.

The RFU executable that comes with the Dynamic C distribution is branded as a product, as seen in the “About” screenshot shown here. You can brand the RFU or customize its functionality to suit your needs. Please contact technical support for the source file needed for customization:

www.rabbit.com/support/questionSubmit.shtml

The RFU enables those without Dynamic C to update their Rabbit-based board with a few files installed on the computer and the appropriate connection to the target board.

The necessary files are included with Dynamic C. They are: the executable (Rfu.exe), the cold loader, the pilot BIOS, and a couple of files used to determine information about the mem­ory device being used.

The default files used for the cold loader, etc., can be seen by selecting “File Locations...” from the Setup menu. We strongly recommend that the default files be used. They are needed internally by the RFU and improper operation of the utility will result if a replacement file does not contain the expected code or informa­tion.

Rfu.exe and its ancillary files are freely distributable.

The RFU communicates with the tar­get using a serial connection. This connection requires a programming cable.

C.0.5.1 Command Line RFU

There is also a command line version of the RFU. On the command line specify:

clRFU SourceFilePathName [options]

where SourceFilePathName is the path name of the .bin file to load to the connected target. The options are as follows:

-s port:baudrate

--v

-cl ColdLoaderPathName

 -pb PilotBiosPathName

 -fi Flash.ini PathName

 -vp+

 -vp-

 -usb+

-usb-