<< Previous | Index | Next >>

> ## Appendix C. Security Software & Utility Programs

> This appendix documents the many useful and easy to use add-on modules and utility programs available from Rabbit.

> This appendix documents the security software and utility programs available for Rabbit-based systems. The security software is called the Rabbit Embedded Security Pack. It is summarized in Section C.1. There are several Dynamic C utilities, each one described in Section C.2.

> ### C.1 Rabbit Embedded Security Pack

> The Rabbit Embedded Security Pack is composed of AES and SSL functionality. It is available for purchase on the Rabibt website:

>     www.rabbit.com/products/dc/index.shtml

> Documentation for the security pack is also available online:

>     www.rabbit.com/products/dc/docs.shtml

> Currently the Rabbit Embedded Security Pack is the only Dynamic C add-on module available. Prior to Dynamic C 10.21, there were a number of add-on modules (FAT, µC/OS-II, etc.) that are now part of the regular Dynamic C distribution.

> A brief reference to the Rabbit Embedded Security Pack functionality follows. For complete documentation, please follow the link given above.

> #### C.1.1 AES

> Advanced Encryption Standard (AES) is an implementation of the Rijndael Advanced Encryption Standard cipher with 128 bit key. This is useful for encrypting sensitive data to be sent over unsecured network paths.

> #### C.1.2 SSL

> Secure Sockets Layer (SSL) is a security protocol that transforms a typical reliable transport protocol (such as TCP) into a secure communications channel for conducting sensitive transactions. The SSL protocol defines the methods by which a secure communications channel can be established--it does not indicate which cryptographic algorithms to use. SSL supports many different algorithms, and serves as a framework whereby cryptography can be used in a convenient and distributed manner.

> ### C.2 Dynamic C Utilities

> There are several utilities bundled with Dynamic C.

> #### C.2.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 numbers 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 alternate 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, transaction 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), assigning 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 external I/O bus.

> #### C.2.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 automatically 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.2.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.

> 1. 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.2.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 management.

> ##### C.2.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 relevant to viewers of the file.

> #### C.2.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.2.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.2.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 (compression 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.2.3.3 Replacing the File Compression Utility

> Users can use their own compression utility, replacing the one provided. If the provided compression utility 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.2.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.2.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 instructions 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:

>     http://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 memory device being used.

> The default files used for the cold loader, etc., can be seen by selecting "File Locations..." from the Setup menu.

> `Rfu.exe` and its ancillary files are freely distributable.

> The RFU communicates with the target using a serial connection. This connection requires a programming cable.

> 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

> ###

> ###  | Description: | Select the comm port and baud rate for the serial connection.
> ###  | Default: | COM1 and 115,200 bps
> ###  | RFU GUI Equivalent: | From the Setup | Communications dialog box, choose values from the Baud Rate and Comm Port drop-down menus.
> ###  | Example: | clRFU myProgram.bin -s 2:115200

> ### --v

> ###

> ###  | Description: | Causes the RFU version number and additional status information to be displayed.
> ###  | Default: | Only error messages are displayed.
> ###  | RFU GUI Equivalent: | Status information is displayed by default and there is no option to turn it off.
> ###  | Example: | clRFU myProgram.bin -v

> ### -cl ColdLoaderPathName

> ###

> ###  | Description: | Select a new initial loader.
> ###  | Default: | `\bios\coldload.bin`
> ###  | RFU GUI Equivalent: | From the "Choose File Locations..." dialog box, visible by selecting the menu option Setup | File Locations,, type in a pathname or click on the ellipses radio button to browse for a file.
> ###  | Example: | clRFU myProgram.bin -cl myInitialLoader.c

> ### -pb PilotBiosPathName

> ###

> ###  | Description: | Select a new secondary loader.
> ###  | Default: | `\bios\pilot.bin`
> ###  | RFU GUI Equivalent: | From the "Choose File Locations..." dialog box, visible by selecting the menu option Setup | File Locations, type in a pathname or click on the ellipses radio button to browse for a file.
> ###  | Example: | clRFU myProgram.bin -pb mySecondaryLoader.c

> ### -fi Flash.ini PathName

> ###

> ###  | Description: | Select a new file that Dynamic C will use to externally define flash.
> ###  | Default: | `flash.ini`
> ###  | RFU GUI Equivalent: | From the "Choose File Locations..." dialog box, visible by selecting the menu option Setup | File Locations, type in a pathname or click on the ellipses radio button to browse for a file.
> ###  | Example: | clRFU myProgram.bin -fi myflash.ini

> ### -vp+

> ###

> ###  | Description: | Verify the presence of the processor by using the DSR line of the PC serial connection.
> ###  | Default: | The processor is verified.
> ###  | RFU GUI Equivalent: | From the "Communications Options" dialog box, visible by selecting Setup | Communications, check the "Enable Processor Detection" option.
> ###  | Example: | clRFU myProgram.bin -vp+

> ### -vp-

> ###

> ###  | Description: | Do not verify the presence of the processor.
> ###  | Default: | The processor is verified.
> ###  | RFU GUI Equivalent: | From the "Communications Options" dialog box, visible by selecting Setup | Communications, uncheck the "Enable Processor Detection" option.
> ###  | Example: | clRFU myProgram.bin -vp-

> ### -usb+

> ###

> ###  | Description: | Enable use of USB to serial converter.
> ###  | Default: | The use of the USB to serial converter is disabled.
> ###  | RFU GUI Equivalent: | From the "Communications Options" dialog box, visible by selecting Setup | Communications, check the "Use USB to Serial Converter" option.
> ###  | Example: | clRFU myProgram.bin -usb+

> ### -usb-

> ###

> ###  | Description: | Disable use of USB to serial converter.
> ###  | Default: | The use of the USB to serial converter is disabled.
> ###  | RFU GUI Equivalent: | From the "Communications Options" dialog box, visible by selecting Setup | Communications, uncheck the "Use USB to Servile Converter" option.
> ###  | Example: | clRFU myProgram.bin -usb-

Dynamic C User's Manual | << Previous | Index | Next>> | rabbit.com