Compact Flash Wildcard Users Guide

This user guide provides all the necessary information to program and use the Compact Flash Wildcard.

The Compact Flash Wildcard expands the data storage capabilities of Mosaic embedded controllers by providing a plug-in interface to large-capacity removable flash data storage. Flash is solid-state nonvolatile read/write memory that maintains its contents even in the absence of applied power. The Compact Flash Wildcard is ideal for applications that require large amounts of memory, the convenience of removable storage, and file-based data exchange with a PC. Consider this Wildcard when you are doing remote acquisition, unattended instrumentation, or logging data from an instrument over long periods of time.

This Wildcard allows you to plug in widely available Compact Flash memory cards that measure only 1.5" by 1.7" and hold many megabytes of nonvolatile data. CF cards up to 2GB implementing PC Card Mode are supported by the Compact Flash Wildcard. We recommend Transcend CF200I CF cards, and known compatible CF cards may be purchased from Mosaic Industries.

This tiny 2" by 2.5" board is a member of the Wildcard series of Modular I/O Boards that connect to Mosaic embedded controllers.

This document reviews the CF Wildcard hardware jumper settings, and describes the driver software that provides a simple API for applications on the host Mosaic Controller. This software is referred to as the "CF Card Software".

Driver software running on the host Mosaic controller implements C file manipulation functions and supports a standard FAT16 (File Allocation Table) file system, allowing files to be created on a PC and read via the CF Wildcard, or visa versa. An automated file processing capability facilitates fool-proof software upgrades and data exchanges. The CF Card Software is installed automatically with C applications compiled for the PDQ Board, and is available as a kernel extension for earlier Mosaic controllers.

A comprehensive set of file management functions modeled on the ANSI C file library lets you create, open, close, read, write, rename, copy and delete files. Other software features include directory listing commands that behave like the DOS DIR command, printing and file capture commands, and a powerful redirection capability that allows any function to take its input from a specified file and send its output to a specified file in the same manner it would using a serial port, including standard C library functions like printf(). This set of functions allows files to be managed from within the Mosaic controller and/or the PC environment.

Fool-proof software upgrades are facilitated by the automated file processing feature. You can specify one or more files to be automatically loaded to or from the Mosaic Controller’s memory at startup. This powerful capability enables field software upgrades that are accomplished by simply inserting a pre-configured CF Card into the CF Wildcard socket.

The CF Wildcard comprises a Wildcard bus header, digital interface chips, module address selection jumpers, and a CF Card Socket. The CF Card Software transparently controls the hardware interface to the CF Card.

To connect the CF Wildcard to the Wildcard Bus on the controller board, follow these simple steps:

With the power off, connect the female 24-pin side of the stacking go-through Wildcard bus header on the bottom of the CF Wildcard to Wildcard Port 0 or Wildcard Port 1 on the controller or its mating Docking Panel. The corner mounting holes on the Wildcard should line up with the standoffs on the controller board. The Wildcard ports are labeled on the silkscreen of the controller board. Note that the CF Wildcard headers are configured to allow direct stacking onto the controller board, even if other Wildcards are also installed. Do not use ribbon cables to connect the CF Wildcard to the Wildcard bus.

CAUTION: The Wildcard bus on the controller board does not have keyed connectors. Be sure to insert the Wildcard so that all pins are connected. The Wildcard bus and the CF Wildcard can be permanently damaged if the connection is done incorrectly.

Once you have connected the CF Wildcard to the Mosaic controller, you must set the address of the wildcard using jumper shunts across J1 and J2.

The Wildcard Select Jumpers, labeled J1 and J2, select a 2-bit code that sets a unique address on the wildcard port of the Mosaic controller. Each wildcard port on the Mosaic controller accommodates up to 4 wildcards. Wildcard Port 0 on the Mosaic controller provides access to wildcards 0-3 while Wildcard Port 1 provides access to wildcards 4-7. Two wildcards on the same port cannot have the same address (jumper settings). The following table shows the possible jumper settings and the corresponding addresses.

CF Cards come preformatted, but you should reformat a card if you need a maximum file size greater than the default size listed in the following table. You may use CF cards in size up to 2 GB, with the cards formatted to use the FAT12 or FAT16 file system. We recommend using the FAT16 file system, which is what you get if you format the cards as "FAT" under Windows.

You can reformat the card using "Disk Management" under Windows. This is done under Windows XP by right-clicking "My Computer", and choosing Manage→ Disk Management. You can also get there by starting with the Start menu and going to Settings→ Control Panel→ Administrative Tools→ Compute Management→ Disk Management. In Windows 7 you may also type Disk Management into the Start Menu search box.

In the Disk Management wizard, right-click the CF card, and choose Format with the allocation size (also called its cluster size) you want. You must also choose "FAT" file format, rather than "FAT32" format. Note that simply choosing Format by right clicking within a file dialog box or under the Windows Explorer program does not allow you to choose the cluster size; instead, the Disk Management utility must be used.

The above table shows the cluster sizes in KB you can choose, and the approximate maximum file size for each cluster size. The maximum file size is always exactly 384 times the cluster size. Entries in bold show the default cluster size used when a card is formatted under Windows XP if formatted from a file folder or Windows Explorer. When formatting using Disk Management you have more control; you can specify the cluster size to be any of those in the table above. While Windows will allow you to use a small cluster size on a large card, choosing too small a cluster size will not you access the entire memory on the CF card. Consequently, you should choose only from the values shown in the above table to get the full use of the card. For example, when a 256 MB CF card is formatted, its cluster size usually may be chosen to range from 4 KB (the Windows default) to 32 KB corresponding to a maximum file size from 1½ MB to 12 MB. Even though Windows will allow you to choose the smaller cluster sizes of 1K and 2K, don’t do it because even when you have the maximum number of files on a card you won’t be using the entire card; use sizes from 4K up, as shown in the table.

Irrespective of how you format the card or its size, the maximum number of files you may have on a card is 511, and they must all be in the root folder; i.e., you can not create any folders or subdirectories on the CF card.

Install a Compact Flash Card into the socket on the CF Wildcard. These cards are designed to fit into the sockets only one way. Damage may occur to the CF card or the socket if the card is forced into the socket in an incorrect orientation.

Once the hardware and software are properly configured, files on the CF Card can be created, read, written, and manipulated by the pre-coded high-level driver routines, as described in the following section.

The rest of this document describes the Compact Flash (CF) Card Software Package. This package is shipped as a kernel extension that is easily loaded onto the host controller. The software enables a product containing a host controller and a CF Wildcard to read from and write to vast amounts of flash memory on convenient removable media. The software supports the standard FAT16 file system, allowing files to be created on a PC and read by the host controller, or visa versa. An automated file processing facility facilitates software upgrades or data exchanges.

Flash is a memory technology that is programmable yet nonvolatile: it maintains its contents even in the absence of power. Compact Flash Cards implementing PC Card Mode can be read or written from the CF Wildcard and computers with a low-cost USB adapter. They adhere to the ATA standard for disk drives, a widespread software and hardware interface. "ATA" stands for "AT Attachment", an interface developed for the IBM PC AT. ATA Flash cards can also be operated in a "True IDE" mode that makes them behave as a standard IDE hard drive such as those found in every PC.

The CF Card device driver software is provided as a pre-coded modular runtime library, known as a "kernel extension" because it enhances the on-board kernel's capabilities. The library functions are accessible from C and Forth.

Instructions for PDQ

Instructions for QED/Q-line

The C demo is located in your installation directory. It is also provided here for reference.

Instructions for PDQ

#include <mosaic/allqed.h>
#include <wcfm.h>

Instructions for QED/Q-line

#include "library.c"

 
#include "library.h"

The Forth demo is located in your installation directory. It is also provided here for reference.

Instructions for PDQ

MosaicPDQ\forth\demos\Compact_Flash_Wildcard\cfmdemo_loader.4TH

startup

Instructions for QED/Q-line

WHICH.MAP 0=
IFTRUE 4 PAGE.TO.RAM  \ if in standard.map...
       5 PAGE.TO.RAM
       6 PAGE.TO.RAM
      DOWNLOAD.MAP
ENDIFTRUE

4 PAGE.TO.FLASH
5 PAGE.TO.FLASH
6 PAGE.TO.FLASH
STANDARD.MAP
SAVE

The CF Software Package comprises four layers. The first two are essentially invisible to the end user, and the latter two provide high level capabilities:

• The ATA/IDE software driver layer enables drive identification and read/write operations using standard ATA commands.
• The FAT layer implements a DOS-compatible FAT (File Allocation Table) file interface to track the placement of files on a pre-formatted ATA flash card in a PC-compatible format. Both FAT12 and FAT16 formats are supported by the CF Card Software, and the FAT16 format is supported by all common operating systems. Maximum CF card size is 2 Gigabytes. The key restrictions are that files must be in the root directory (which holds a maximum of 511 files), and filenames are limited to the "8+3" scheme: up to 8 characters in the filename, and up to 3 characters in the file extension. The maximum size of each file is determined when the CF card is formatted. Formatting sets the "cluster size" on the card, and there is a maximum of 384 clusters per file. For example, with an 8 Kbyte cluster size, any given file on the CF card can contain up to 3 Megabytes of data. You should format CF cards under Windows to have 8Kbyte cluster sizes for 512 MB cards and 16K cluster sizes for 1 GB cards.
• The file management layer includes a set of user-callable commands modeled on the ANSI C file manipulation functions that enable the programmer to create, open, close, read, write, rename, copy and delete files in the root directory. Other software features include directory listing commands that report information similar to the DOS DIR command, a File_Type command that prints the contents of a specified file to the active serial port, and a File_Capture function to capture text sent from a terminal into a specified file. This set of functions allows files to be managed from within the QED environment and/or the PC environment. Files can be created on one platform and read and modified on the other.
• The automated file processing and redirection layer enables the programmer to specify a file to be automatically processed by the QED-Forth interpreter/compiler at startup. The software searches the root directory of a detected CF card for a file named AUTOEXEC.QED and, if it is found, interprets and executes the commands in the file. Two easy-to-use functions named Page_To_File() and File_To_Page() can be invoked in AUTOEXEC.QED to store memory contents in a file, or transfer file contents to memory. This enables software upgrades to be performed in the field by simply plugging in a CF card that contains the proper update files. Finally, a powerful redirect function allows any function to take its input from a specified file, and/or send its output to a specified file in the same manner as it would a serial port, including C standard library functions like printf().

This section lists all of the keywords (functions, constants and variables) in the ATA Flash Card Software Package. Functions include C-style parameter lists: the returned data type is shown before the function name, and a comma-delimited list between parentheses shows the type and a descriptive name for each input parameter.

This section discusses some important concepts that will help you use the file system software. The next section provides additional information about how to perform software upgrades using the automated file processing capability. The programming examples at the end of this document also provide lots of information that is useful when crafting your application.

The sample entry for File_Open() brings up some commonly used terms which we now describe. The file_id parameter returned by File_Open() is a file identifier that is passed to many of the file manipulation functions to specify which open file should be operated upon. Valid file_ids are small non-negative integers assigned by the File_Open() function. The first file to be opened is assigned file_id = 0, the next is assigned 1, etc. The maximum number of files that may be open at one time is set by Init_File_IO(); the default set by Init_File_System() is 4. A file's file_id is recycled (made available) when the file is closed. The file_id returned by File_Open() should be saved by the user's program to enable accessing and closing of the file.

The character string containing the name is handled slightly differently in each of the two programming languages. In C, the starting address and page of the string are passed in as two separate parameters. Typically, C programmers will pass the address of a character string or buffer as the name_addr, and will pass the macro THIS_PAGE as the name_page. THIS_PAGE resolves at runtime to the current page, and works well for strings that are compiled in the .strings area in ROM (this is the default place that strings are located by the C compiler and linker), or for string buffers in common RAM. To signal to the function that this is a null-terminated string, C programmers must pass -1 as the name_count.

In Forth, the starting extended address (that is, the 32-bit address of the first character of the string) is passed as name_xaddr, and the count is passed as name_count. Typically, these parameters are obtained by defining the string using double quotes, then using COUNT to unpack the counted string; see the definition of COUNT in the main QED-Forth glossary.

All files are opened with a specified access_mode parameter. The access mode determines whether the file has read-only privileges, write-only privileges, is append-only, or some combination of these. Consult the complete glossary entry for File_Open for a description of the meaning of these modes. The access modes are modeled on ANSI-C: C's "r" is our R_MODE (read-only mode), C's "a+" is our APLUS_MODE (append mode with read privileges), etc.

This file system software does not support directories. That is, only files in the "root directory" of the ATA flash card are recognized. This limits the number of files on the flash card to 511. Only DOS- and Windows "8+3" style names are supported: filenames must have 8 or fewer characters in the main part of the name, with an optional period and filename extension of up to 3 characters. All characters in the filenames are converted to upper case. "Long filenames" are not supported. See the glossary entry for Max_File_Size for a description of the filesize limitation. The maximum size of each file is determined when the CF card is formatted. Formatting sets the "cluster size" on the card, and there is a maximum of 384 clusters per file. For example, with an 8 Kbyte cluster size, any given file on the CF card can contain up to 3 Megabytes of data. Please keep these restrictions in mind if you are using a PC to create files that are to be accessed via the CF Wildcard.

Random access within an open file can be accomplished using any of the read or write functions, including File_Getc, File_Gets, File_Putc, File_Put_CRLF, File_Puts, File_Read, File_To_Memory, and File_Write. Each of these accesses an open file (specified by a file_id) starting at the current file position. When a file is first opened, its file position equals zero. The first character that is read from the file is the one located at the file position (in this case, at the start of the file), and the file position indicator is automatically incremented with each character read. If we open a file and immediately start writing to it, the characters are written starting at the current file position (in this case, at the start of the file) unless the append mode (A_MODE or APLUS_MODE) is active in which case the file position indicator is automatically moved to the end of the file. Again, the file position indicator is automatically incremented with each character written.

A program can modify the file position indicator using the functions File_Seek, File_Set_Pos, or File_Rewind. To find out the current file position, call the function File_Tell_Pos. Read the glossary entry of File_Seek for a brief but comprehensive overview of how the file position indicator works.

Many of the file system functions return an error parameter. This integer equals zero if there are no errors, and equals a bit-mapped error code if some failure occurs. The error code returned by the latest file function is also bit-wise OR'd with the prior error parameter, and saved in a 16-bit system variable associated with the specified file that can be accessed using the File_Error function. If the error occurs during a File_Open operation, it is bit-wise OR'd with any prior file_open error, and saved in a 16-bit system variable that is returned by the File_Open_Error function. Each error condition is represented by a named constant that starts with "ERR_"; see their glossary entries for details. If your program needs to test for a particular type of error, perform at bit-wise AND operation between the relevant ERR_ code and the error parameter returned by File_Error or File_Open_Error; if the result is nonzero, the specified error occurred. To clear the error flags associated with a specified file, see the glossary entries for Clear_File_Error and File_Rewind.

Often a program must test for the end of file (EOF) condition. While the procedure described above can be used (via the ERR_EOF constant), it may be easier to call the pre-coded File_EOF function which returns a true (-1) flag if an end of file has been encountered.

To print an error message summarizing the error conditions that have occurred, use Report_File_Errors. To print a message summarizing errors that occurred while trying to open a file, use Report_File_Open_Errors. See their glossary entries for details.

A set of failure codes is associated with the low-level ATA driver routines. While these are typically not used, they are available for special applications. See the glossary entry for ATA_Fail for more details.

If a battery-backed real-time clock is available on the host controller board, then the directory entries of all writeable files that are created or modified by the file system will be properly marked with DOS-compatible time and date information. This can make it easier to manage files. The time and date information is reported by the Dir and Dir_Open functions.

A CF Card must be plugged into its socket to perform an initialization of the CF Software. The most commonly used initialization function is Init_File_System.

This convenient function does not require or return any parameters. Before calling it, the function

Set_CF_Module 

must be called with a parameter equal to the module number as specified by the jumper settings and module port (see the section titled "Selecting the Module Address" and Table 1, above). For example, if both jumper shunts are installed and the CF Wildcard is plugged into module port 1, then Set_CF_Module must be called with a parameter of 7 before calling Init_File_System.

Init_File_System sets up a default set of RAM-based data structures. In the kernel V4.xx products (QED Board, QCard, QScreen, QVGA Controller) these data structures are located in the top 16 Kbytes of page 3 RAM; this implies that you must operate in the STANDARD.MAP to run this code. In the kernel V6.xx products (PDQ Board, PDQ Screen, QVue, and TFT Handheld) these data structures are located in page 0x17 RAM. (Note that "0x" in front of a number means that the number is shown in hexadecimal base.) The Init_File_System function locates the fat_info structure pointed to by FI, and declares a heap for use by the CF Software. Up to 4 open files at a time are supported, and a 1 Kilobyte File_Contents buffer is dimensioned in the heap for each open file. This File_Contents buffer is available to the programmer; see the File_Contents glossary entry for details.

Init_File_System calls a subsidiary function named Init_File_IO that accepts a set of parameters that allow the programmer to customize the memory map. If your application uses the reserved RAM described in the prior paragraph for other purposes, use Init_File_System to set up the CF Software with an appropriate memory map. It lets you specify the location of the fat_info structure, the location and size of the heap that contains all of the file system data structures, the maximum number of open files, and the size of the File_Contents buffers. The designated heap can span multiple pages of RAM, so large numbers of open files and/or large buffers can be accommodated. If you do customize your memory use, you must reserve enough heap memory for your open files. In addition to the file contents buffer, each open file requires 1864 bytes in the heap, and an additional 2.5K is reserved as scratchpad. Thus the total heap size must be greater than 2.5K + NumOpenFiles*[File_Contents_Buffer + 1864 bytes].

File processing is a powerful feature that lets you reconfigure, upgrade or exchange data with Mosaic embedded controller-based instrument by inserting a CF Card and invoking the file processing function. This section provides an overview of these features; for more details consult the following section and see the glossary entries for Process_File, Process_Autoexec, and Do_Autoexec.

The most comprehensive initialization and file processing function is

Do_Autoexec

This function does not require or return any parameters. Before calling it, the function

Set_CF_Module 

must be called with a parameter equal to the module number as specified by the jumper settings and module port (see the section titled "Selecting the Module Address" and Table 1, above. If a CF Card is installed, the Do_Autoexec function calls Init_File_System (described above) and then calls Process_Autoexec which looks for a file named AUTOEXEC.QED and executes it if it is found.

To configure an individual Mosaic controller for automatic initialization and file processing, craft a Priority Autostart routine that calls Set_CF_Module and then calls Do_Autoexec. Even if you do not plan to use the AUTOEXEC.QED file feature, this approach yields automatic initialization of the file system if a CF Card is detected at powerup or restart.

Simple files can perform memory imaging and automated software upgrades. Sample files are included at the end of this document, and the next section describes how to set up these files.

For those familiar with Forth, additional flexibility is available. Any executable Forth code can be handled during file processing. Files can cause other files to be processed. That is, recursive nesting is allowed (although End_Update halts recursion; see its glossary entry). The key restriction is that the Forth headers of any function that is referenced must be loaded. Forth programmers will typically load the library.4th file that declares the CF Wildcard Forth headers, so that the file operations can be referenced during file processing.

Due to the memory protection feature of the PDQ line, attention should be taken with the File_To_Memory and File_To_Page functions. These functions copy a file from the CF card into memory. If the memory region is write protected, the file copy will fail so it's important to ensure that the WriteEnable function is used to allow writes to the correct memory region.

Another set of functions to be aware of are: File_Copy, File_Rename, and File_Remove. The files used with these functions should not be opened before using these functions on the files.

The Link_File_IO function is no longer needed and should never be called. If called, it would load the headers for the obsolete MIB software in the QED V4.xx kernel. Note that the Arm_Autoexec and Disarm_Autoexec functions are no longer implemented. Moreover, because the CF Card Software is not a built-in part of the QED-Forth kernel, the allowed contents of the AUTOSTART.QED file may be restricted, depending on how the CF Card Software was loaded into memory. The recommended approach to creating a file for run-time processing is described in the following section. A more detailed upgrade notice is presented after the glossary.

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 controller 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 page of memory (32 Kbytes/page on V4.xx kernel products, or 16Kbytes/page on V6.xx kernel products), 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 binary file whose contents equal the contents of the specified page. File_To_Page reads a binary 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.

The following subsections describe how to perform a CF-card-based software upgrade.on a kernel V4.xx product (QED Board, QCard, or QScreen). On the PDQ Board kernel V6.xx, a similar approach can be used; simply adjust the memory map to correspond to the PDQ memory architecture (use 16K pages, typically starting at page 0, etc.)

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 flash. 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.

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
 
standard.map  \ in the standard map, pages 4,5,6 are flash
HEX  \ interpret numbers in hexadecimal base
 
\ comment out the lines for any pages you do not want to image into a file:
4 Page_To_File
5 Page_To_File
6 Page_To_File

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.

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.

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 following line to suppress echoing to the serial port:
cfa.FOR emit1 UEMIT x!  \ Vector output to the primary serial port
 
standard.map   \ in the standard map, pages 4,5,6 are flash
HEX  \ interpret numbers in hexadecimal base
 
\ 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.

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 on kernel V4.xx products (QED Board, QCard, QScreen); 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.

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.

The predecessor to the CF Wildcard was the Memory Interface Board (MIB) which hosts a PCMCIA PC Card using software that is built into the QED Kernel Flash. This software was linked (made accessible to interactive calls) by calling Link_File_IO, and set up its data structures on dedicated RAM resident on the MIB itself. The Do_Autoexec function was embedded as part of the kernel’s startup procedure, and so did not have to be explicitly included in a Priority Autostart function. Also, there was no "module number" to keep track of. The C library calls were declared and defined in the \fabius\include\mosaic\ataflash directory, in files ataflash.c and ataflash.h. These files cannot be used with the CF Wildcard.

Programmers should follow the instructions presented in the section titled "How to Install the CF Software" presented above.

While most of the MIB/ATA software is unchanged from the programmer’s point of view, the following changes have been made:

These functions are no longer needed and have been deleted:

• Arm_Autoexec
• Disarm_Autoexec
• Link_File_IO
• PCC_Offset_To_Xaddr
• PCC_bank
• Slow_Fetch
• Slow_Store
• Sectors_Per_Track

The variable

• xfat_info_save

has been deleted. Its value can be accessed using the FI function.

These functions have been added:

• Hidden_Sectors
• Do_Autoexec
• Read_CF_Module
• Set_CF_Module

The Link_File_IO function is no longer needed and should never be called. If called, it would load the headers for the obsolete MIB software in the QED V4.xx kernel. Note that the Arm_Autoexec and Disarm_Autoexec functions are no longer implemented. Moreover, because the CF Card Software is not a built-in part of the QED-Forth kernel, the allowed contents of the AUTOSTART.QED file may be restricted, depending on whether the CF Card Software Forth headers in library.4th are loaded into memory.

Init_File_System now locates the required data structures in the top 16 Kbytes of page 3, instead of in the RAM located on the MIB itself.

See also →

• Compact Flash C Demo
• Compact Flash Forth Demo
• Compact Flash Glossary