Link here

Compact Flash Wildcard Users Guide

Overview

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

 

Specifications

Compact Flash Wildcard Specifications
Memory Sizes Available: Compact Flash cards of 16 Mbyte to 2 Gigabyte
Maximum Number of Files 511, all in the root directory. No subdirectories are allowed.
File Format: FAT-12 and FAT-16
Compatibility: File exchange with any computer using CF card reader.
Application Interface: C-like file manipulation functions including create, open, close, read, write, rename, copy and delete. Directory listing, file_type and file_capture commands
File Transfer: Files can be created, read, and modified on either the Mosaic or PC/Mac/Linux platforms.
Automated File Processing: Files may be automatically executed on startup, input/output piped from/to any file, and controller programs automatically upgraded.
Current: ~200 mA with CF card
Weight: 18 gram (~40 gram with CF card)
Size: 2" (~2.9" w/CF) x 2.5" x <0.5" (50.8mm (74.3 w/CF) x 63.5mm x 9.3mm)
 

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

 

File Management Functions

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.

 

Automated File Loading and Execution

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.

 

Hardware

Overview

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.

 

Connecting To the Wildcard Bus

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.

 

Selecting the Wildcard Address

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.

Address Jumper Settings
Wildcard Port Wildcard Address Installed Jumper Shunts
0 0 None
0 1 J1
0 2 J2
0 3 J1 and J2
1 4 None
1 5 J1
1 6 J2
1 7 J1 and J2
Note:<block indent>Address 0 is not available on the QScreen or Handheld. Use addresses 1 through 7 instead.</block>
 

Formatting a CF card

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.

CF Card Size Cluster Size Maximum File Size
64 MB 1 K 384 K
2 K 768 K
4 K 1.5 M
8 K 3 M
16 K 6 M
32 K 12 M
128 MB 2 K 768 K
4 K 1.5 M
8 K 3 M
16 K 6 M
32 K 12 M
256 MB 4 K 1.5 M
8 K 3 M
16 K 6 M
32 K 12 M
512 MB 8 K 3 M
16 K 6 M
32 K 12 M
1 GB 16 K 6 M
32 K 12 M
2 GB 32 K 12 M

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.

 

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

 

CF Card Software Package User Guide and Glossary

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.

 

How to Install the CF Card Software

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

 

Using the Driver Code with C

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

Instructions for PDQ

Instructions for QED/Q-line

 

Using the Driver Code with Forth

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

Instructions for PDQ

Instructions for QED/Q-line

 

CF Card Software

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().
 

Categorized List of Functions and Constants

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.

 

ATA Failure Codes

FAIL_ADDR FAIL_ARGS FAIL_BUSY
FAIL_CMD FAIL_DATAREQ FAIL_EXTERR
FAIL_ID_DRIVE FAIL_NO_CARD FAIL_READY
 

ATA Primitives

int ATA_Command( xaddr xbuf, ulong startsector, uint numsectors, int cmd, int xfer_type, int features)
int ATA_Fail( void )
int ATA_ID_Drive( xaddr xbuffer)
int ATA_Read( xaddr xbuf, ulong startsector, uint numsectors )
int ATA_Set_Features( int config_contents, int feature_contents )
int ATA_Write( xaddr xbuf, ulong startsector, uint numsectors )
int PCC_Present( void )
 

CF Card Information

ulong Card_Size( void ) Int Hidden_Sectors( void )
int Numsectors_Transferred( void ) SECTOR_SIZE
uint Volume_Label( char* string_addr, uint string_page )
 

Directory

DATE_DIR void Dir( void ) void Dir_Names( void )
EXTENSION_DIR FILENAME_DIR FILE_SIZE_DIR
xaddr File_Time( int file_id ) HOURS_DIR MINUTES_DIR
MONTH_DIR int Set_Filesize( ulong needed_filesize, int file_id )
void Dir_Open( void ) int Dir_To_Memory ( xaddr xbufbase, uint bufsize )
xaddr Dir_Record_Xaddr ( xaddr xbufbase, int record_index, int field_offset )
YEAR_DIR
 

File Access and Position Modes

A_MODE APLUS_MODE FROM_CURRENT
FROM_END FROM_START R_MODE
RPLUS_MODE W_MODE WPLUS_MODE
 

File I/O

END_CAPTURE (Forth only)
int File_Capture( int file_id )
int File_Close( int file_id )
xaddr File_Contents( uint file_position, int file_id )
int File_Copy( char* prior_name_addr, uint prior_name_page, int prior_count, char* new_name_addr, uint new_name_page, int new_count )
int File_Flush( int file_id )
int File_Getc( int file_id )
int File_Gets( char* dest_addr, uint dest_page, uint bufsize, int file_id )
int File_Open( char* name_addr, uint name_page, int name_count, int access_mode )
int File_Putc( char c, int file_id )
int File_Put_CRLF( int file_id )
int File_Puts( char* source_addr, uint source_page, uint maxchars, int file_id )
long File_Read( void* dest_addr, uint dest_page, ulong numbytes, int file_id )
int File_Remove( char* name_addr, uint name_page, int name_count )
int File_Rename( char* prior_name_addr, uint prior_name_page, int prior_count, char* new_name_addr, uint new_name_page, int new_count )
int File_Rewind( int file_id )
int File_Seek( int file_id, long offset, int mode )
int File_Set_Pos( int file_id, long offset )
ulong File_Size( int file_id )
long File_Tell_Pos( int file_id )
long File_To_Memory( void* dest_addr, uint dest_page, ulong numbytes, int file_id )
void File_Type( char* name_addr, uint name_page, int name_count )
int File_Ungetc( char c, int file_id )
long File_Write( void* source_addr, uint source_page, ulong numbytes, int file_id )
ulong Max_File_Size( void )
 

File Processing

void Do_Autoexec( void ) void File_Abort_Action( void )
int File_Ask_Key( void ) void File_Emit( char c )
void File_Interpreter( void ) uchar File_Key( void )
void File_To_Page( int page ) NO_ECHO_FILEID
void Page_To_File( int page ) int Process_Autoexec( int autoexec_echo )
void Process_File(int input_fileid, int output_fileid) void Put_Default_Serial( void )
void Redirect( int input_file_id, int output_file_id, void(*fn)(), uint fn_page )
 

File System Error Handling

void Clear_File_Error( int file_id )
ERR_ATA_READ ERR_ATA_WRITE
ERR_BAD_OR_UNOPEN_FILEID ERR_CANNOT_ADD_CLUSTER
ERR_CANNOT_TRUNCATE_FILE ERR_DISK_IS_FULL
ERR_EOF ERR_FAIL_ID_DRIVE
ERR_FILE_DOES_NOT_EXIST ERR_INVALID_SECTOR_NUMBER
ERR_NEGATIVE_FILE_POSN ERR_NOT_DOSFAT_DRIVE
ERR_READ_ACCESS_VIOLATION ERR_ROOT_DIR_FULL
ERR_TOO_MANY_FILES_OPEN ERR_WRITE_ACCESS_VIOLATION
int File_EOF( int file_id ) int File_Error( int file_id )
int File_Open_Error( void )
uint Report_File_Errors( int file_id, char* string_addr, uint string_page, uint maxbytes )
uint Report_File_Open_Errors( char* string_addr, uint string_page, uint maxbytes )
 

Initialization

xaddr FI( void)
int Init_File_Heap( uint maxopen_files, uint file_bufsize, xaddr xheap_start, xaddr xheap_end )
int Init_File_IO(uint maxopen_files, uint file_bufsize, xaddr xheap_start, xaddr xheap_end, xaddr xfat_info )
int Init_File_System( void )
void Link_File_IO( void )
int Read_CF_Module( void )
void Set_CF_Module( int module_num )
 

Using the File System Functions

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.

 

Commonly Used Terms

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.

 

String Parameters and the Use of THIS_PAGE

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.

 

Access Privileges

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.

 

Root Directory Only and File Name Restrictions

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.

 

File Position Indicator

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.

 

Error Handling

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.

 

Real-Time Clock on the Host Computer Enables Time/Date Marking of Files

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.

 

Initialization and Memory Use

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

 

Automatic Initialization and File Processing

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.

 

Usage note for PDQ line

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.

 

Upgrade note for former Memory Interface Board (MIB) Users

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.

 

How to Create and Use an AUTOEXEC.QED File on Kernel V4.xx Products

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

 

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

 

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

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

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

 

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.

 

Upgrade Notice for Prior Users of the Memory Interface Board

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.

 

CF Wildcard Hardware Schematic

This page is about: Embedded Compact Flash Interface, PC Interface, File Manipulation – Embedded CF Card reader provides data logging for easy upload to PC. CF Card, Compact Flash, data acquisition, data logging, kernel, software, C source code
 
 
Navigation