The Compact-Flash Wildcard and
CF Card Software Package User Guide
<< Previous | Next>>
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_id's 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 5. 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; for example, the root directory of a 10 Megabyte card can contain a maximum of 512 files. Only DOS- and Windows 3.xx 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. 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 were no errors, and equals a bit-mapped error code if some failure occurred. The error code returned by the latest file function is also bit-wise OR'd with the prior error parameter, and saved in a system variable associated with the specified file that can be accessed using the File_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; if the result is nonzero, the specified error occurred. To clear the error flag associated with a specified open file, call Clear_Error or 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 Wildcard 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 top 16 Kbytes of page 3 RAM (this implies that you must operate in the STANDARD.MAP to run this code). The function locates the fat_info structure pointed to by FI at 0x4000 to 0x417F on page 3, and declares a heap for use by the CF Software at 0x4180 to 0x7FFF on page 3. (Note that "0x" in front of a number means that the number is shown in hexadecimal base.) It specifies a maximum of max 5 open files with a 1 Kbyte user buffer per file. Up to 5 open files at a time are supported, and a 1 Kilobyte File_Contents buffer is dimensioned in the page 3 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 top 16 Kbytes of page 3 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.
File processing is a powerful feature that lets you reconfigure, upgrade or exchange data with a 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 Wildcard 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.
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.
<< Previous | Next>>
| 
