The Compact-Flash Wildcard and
CF Card Software Package User Guide

<< Previous | Next>>

How To Create and Use an AUTOEXEC.QED File

The CF Card Software facilitates in-the-field software upgrades. A small AUTOEXEC.QED file can copy the image of upgraded software page-by-page into the memory of the Mosaic controller. The operating system can be configured to look for and automatically execute such a file named AUTOEXEC.QED each time the system starts up. This means that an upgrade can be performed by simply plugging a pre-configured CF card into its socket.

The most common uses for the automated processing capability are to image the QED memory into files, and transfer the contents of files to memory. Two powerful functions named Page_To_File and File_To_Page have been designed to make things easy. Each of these functions accepts a single parameter that specifies a 32 Kbyte page of memory, and accesses a binary file. The filename is fixed as PAGEpp.BIN, where pp is the 2-digit hexadecimal representation of the specified page. Page_To_File creates a 32 Kbyte file whose contents equal the contents of the specified page. File_To_Page reads a 32 Kbyte file and stores the contents to the specified page in memory.

To perform a software upgrade, we will see how to:

1. compile a program into flash memory;
2. create a set of files that contain the desired images of the flash pages; and
3. transfer the contents of the image files to a target system’s memory in the field.

Compile a Program into Flash Memory

Pages 4, 5, and 6 of memory typically contain the program code of an application. These pages are flash memory in the Standard.Map as described in the Mosaic controller documentation. The top-level function of a C application is called "main", and this is located on page 4 in QED memory. The top-level function of a QED-Forth program can be located on page 4, 5 or 6.

To take advantage of automated file processing, include two statements in your top-level function: the first is a call to Set_CF_Module, and the second invokes the Do_Autoexec function. Note that parameter passed to the Set_CF_Module funtion must match the hardware jumper settings described in Table 2 above. Let’s assume that the CF Wildcard is configured as module number 0. In C, the following two statements should be in the top-level function:
    Set_CF_Module( 0 );
    Do_Autoexec( );
In Forth, the required statements are:
    0 Set_CF_Module
    Do_Autoexec

In a typical application, the top-level function is configured as a "Priority Autostart" routine. The Priority Autostart vector is stored near the top of page 4 flash memory. For example, the function named "main" is made to automatically execute upon each startup or restart by the declaration:
    CFA.FOR main PRIORITY.AUTOSTART
which is typically typed at the terminal. This statement causes an autostart vector to be written to the top of page 4, causing the specified function to be automatically executed at startup.

Create a Set of Image Files

After compiling the application and declaring the flash-based Autostart vector, we are ready to make a set of image files named PAGE04.BIN, PAGE05.BIN, and PAGE06.BIN. All we need to do is use a PC to store a proper version of the AUTOEXEC.QED file on a CF Card, install the CF Card into its socket on the CF Wildcard, and restart the board. After the restart (which can be invoked from the terminal by typing WARM or ABORT), there will be a delay, then you will see the echoed report of the file processing.

Listing 1 shows the contents of the required file, which is provided in the PAGE2FILE directory of the CF Wildcard code distribution.

Listing 1. Page-to-File Version of AUTOEXEC.QED

\ This AUTOEXEC.QED file is executed at startup
\ if the autostart routine calls Set_CF_Module and Do_Autoexec.
\ It creates a set of 32 Kbyte files, one per page for the specified pages.

\ Comment out the following line to suppress echoing to the serial port:
cfa.for emit1 uemit x! \ Vector output to the primary serial port

The file listing starts with some comments delimited by the \ (backslash plus space) comment character. The first executable line vectors the "emit" serial output primitive to the default primary serial port so that the progress of the upgrade can be monitored at the serial terminal. If this line is commented out by placing a backslash and a space at the start of the line, the serial output is suppressed during processing of the file. It is recommended that serial output be enabled, as the Page_To_File routine prints useful diagnostic information while it runs.

The standard.map directive ensures that we are in the standard memory map (pages 4, 5, and 6 are flash). The hex directive means that all numbers (in this case, the page numbers) are interpreted in hexadecimal base. This directive can be changed to decimal if you prefer. Do not use the prefix "0x" to denote hex numbers in the AUTOEXEC.QED file.

The next three executable lines specify that pages 4, 5, and 6 are to be imaged into files named PAGE04.BIN, PAGE05.BIN, and PAGE06.BIN, respectively. Note that there must be at least one space between the page number and the function name. You can comment out any lines that refer to pages you do not want to image, and you can add additional lines if necessary. If these Page_To_File commands are executed after software has been loaded into flash memory, then the files contain the information required to perform a software upgrade, including setting up a revised Priority Autostart vector.

Any page can be imaged, including RAM pages 1, 2, and 3, and writeable flash pages 7 and 0x0D (decimal thirteen). If you are using a Wildcard Carrier Board with installed memory, then RAM is present starting at page 0x40, and flash is present starting at page 0x50 (check the board specifications to determine how much memory is available).

You can also create the image files by executing a program that calls Set_CF_Module, calls Init_File_System, and invokes the Page_To_File function for each page to be imaged.

Note to experts: You can also use the File_Open and File_Write functions called from a runtime C or Forth program to save memory contents to files. This gives you the option of specifying custom file names and the address ranges imaged into the files. In this case, however, you cannot use File_To_Page to store the file contents to memory; rather, you would use customized functions that you write.

Transfer the Image File Contents into Memory

Now let’s assume that you want to create a CF card that will automatically install into a field instrument the software images contained in PAGE04.BIN, PAGE05.BIN, and PAGE06.BIN. We also assume that the Autostart routine running the the controller calls Set_CF_Module and Do_Autoexec as described above. All we need to do is use the PC to replace the AUTOEXEC.QED file on the CF card with a file that contains the proper File_To_Page commands, install the CF Card into its socket on the CF Wildcard, and restart the board. Listing 2 shows the contents of the required file, which is provided in the FILE2PAGE directory of the CF Wildcard code distribution.

Listing 2. File-to-Page Version of AUTOEXEC.QED

\ This AUTOEXEC.QED file is executed at startup
\ if the autostart routine calls Set_CF_Module and Do_Autoexec.
\ It copies the contents of a set of 32 Kbyte files into memory (RAM or Flash).
\ There must be one file named PAGEpp.BIN per page, where pp is the (hex) page.

\ comment out the lines for any pages you do not want to update:
4 File_To_Page
5 File_To_Page
6 File_To_Page
\ you may remove the following line if you are not updating the autostart routine:
End_Update

The file listing starts with some comments delimited by the \ (backslash plus space) comment character. The first executable line vectors the "emit" serial output primitive to the default primary serial port so that the progress of the upgrade can be monitored at the serial terminal. If this line is commented out by placing a backslash and a space at the start of the line, the serial output is suppressed during processing of the file. It is recommended that serial output be enabled, as the File_To_Page routine prints useful diagnostic information while it runs.

The standard.map directive ensures that we are in the standard memory map (pages 4, 5, and 6 are flash). The hex directive means that all numbers (in this case, the page numbers) are interpreted in hexadecimal base. This directive can be changed to decimal if you prefer. Do not use the prefix "0x" to denote hex numbers in the AUTOEXEC.QED file.

The next three executable lines specify that the contents of files PAGE04.BIN, PAGE05.BIN, and PAGE06.BIN are to be transferred to memory pages 4, 5, and 6, respectively. You can comment out any lines that refer to pages you do not want to store, and you can add additional lines to update other pages that were imaged into properly named binary files. These operations perform the software upgrade.

The last line of the file handles the tricky situation that develops when one attempts to upgrade software that is running while the upgrade is in progress. In this case, the top-level Priority Autostart routine (for example, "main") invoked the Do_Autoexec function that started the upgrade process. If we’re not very careful, the processor could try to continue executing a function that has been changed by the upgrade process! This could cause a software crash. To avoid this problem, End_Update prints the message:
    Update complete, please remove CF Card...
and waits until the CF card is removed before allowing execution to proceed beyond the end of the End_Update function. When the CF card is removed, End_Update executes ABORT to restart the controller. If you are sure that no executing functions are affected by the File_To_Page directives, the End_Update function may be commented out. If present, End_Update must be the last function in the file.

At the completion of processing this AUTOEXEC.QED file, the software upgrade is done. As far as the field user was concerned, all that was required was to insert a CF Card, reboot the board (via reset or power cycle), wait for the upgrade to finish, and remove the CF card.

Note to experts: The contents of the AUTOEXEC.QED file must be capable of being processed (interpreted and executed) at runtime by the QED-Forth interpreter. The Page_To_File, File_To_Page, and End_Update functions are always recognized by the file interpreter, even if the programmer is using C and has not loaded the Forth-style CF Card Software headers to the Mosaic controller.

Restrictions on Software Upgrades

Overwriting the page that contains the CF Wildcard driver code is not allowed during a software upgrade. This is because the CF Wildcard code is executing during the upgrade, and flash-resident code cannot in general modify itself while it is running. The CF Wildcard driver code is supplied as a "kernel extension" and generally resides in page 0x0D (decimal page thirteen), but it may reside in page 7 in some systems. If you have any questions, please contact Mosaic Industries for technical support.

Likewise, the data structures used by the CF WIldcard driver code cannot be modified during an upgrade. The top 16 Kbytes of page 3 are the default location for these data structures; see the glossary entry for Init_File_System. Thus, unless you relocate these data structures, File_To_Page should not be used to write to page 3.

Recovering from Buggy AUTOSTART.QED Files

If an error occurs during the automated processing of the AUTOEXEC.QED file at startup, the operating system will continue trying to process the file contents until the card is removed or until a "factory cleanup" operation is performed. This implies two things. First, all AUTOEXEC.QED files should be carefully debugged before attempting to automatically load them into a Mosaic controller. Second, if your AUTOEXEC.QED file does have a bug in it, remove the CF Card from the socket (or perform a factory cleanup using the DIP switches) to regain control of the computer, and then repair the file and re-post the Autostart or Priority Autostart function.

<< Previous | Next>>