This chapter contains an introduction to FileX and a description of installation conditions, procedures, and use.
Embedded development is usually performed on Windows or Linux (Unix) host computers. After the application is compiled, linked, and located on the host, it is downloaded to the target hardware for execution.
Usually the target download is done from within the development tool’s debugger. After download, the debugger is responsible for providing target execution control (go, halt, breakpoint, etc.) as well as access to memory and processor registers.
Most development tool debuggers communicate with the target hardware via on-chip debug (OCD) connections such as JTAG (IEEE 1149.1) and Background Debug Mode (BDM). Debuggers also communicate with target hardware through In-Circuit Emulation (ICE) connections. Both OCD and ICE connections provide robust solutions with minimal intrusion on the target resident software.
The source code for FileX is delivered in ASCII format and requires approximately 500 KBytes of space on the host computer’s hard disk
FileX requires between 6 KBytes and 30 KBytes of Read-Only Memory (ROM) on the target. Another 100 bytes of the target’s Random Access Memory (RAM) are required for FileX global data structures. Each opened media also requires 1.5 KBytes of RAM for the control block in addition to RAM for storing data for one sector (typically 512 bytes).
For date/time stamping to function properly, FileX relies on ThreadX timer facilities. This is implemented by creating a FileX-specific timer during FileX initialization. FileX also relies on ThreadX semaphores for multiple thread protection and I/O suspension.
FileX can be obtained from our public source code repository at https://github.com/eclipse-threadx/filex/.
The following is a list of several important files in the repository:
Important: All file names are in lower-case. This naming convention makes it easier to convert the commands to Linux (Unix) development platforms.
FileX is installed by cloning the GitHub repository to your local machine. The following is typical syntax for creating a clone of the FileX repository on your PC:
git clone https://github.com/eclipse-threadx/filex
Alternatively you can download a copy of the repository using the download button on the GitHub main page.
You will also find instructions for building the FileX library on the front page of the online repository.
Important: Application software needs access to the FileX library file (usually called* usually fx.a or fx.lib) *and the C include files fx_api.h and fx_port.h. This is accomplished either by setting the appropriate path for the development tools or by copying these files into the application development area.
Using FileX is easy. Basically, the application code must include fx_api.h during compilation and link with the FileX run-time library fx.a (or fx.lib). Of course, the ThreadX files, namely tx_api.h and tx.a (or tx.lib), are also required.
Important: When using FileX in Standalone mode (FX_STANDALONE_ENABLE must be defined), ThreadX files/libraries are not required.
Assuming you are already using ThreadX, there are four steps required to build a FileX application:
Initialize the FileX system by calling fx_system_initialize from the tx_application_define function or an application thread.
Important: When using FileX in Standalone mode, fx_system_initialize should be directly called from application code.
Add one or more calls to fx_media_open to set up the FileX media. This call must be made from the context of an application thread.
Important: Remember that the fx_media_open call requires enough RAM to store data for one sector.
Each FileX port is delivered with a demonstration application. It is always a good idea to get the demonstration system running first—either on the target hardware or a specific demonstration environment.
If the demonstration system does not work, try the following things to narrow the problem:
There are several configuration options when building the FileX library and the application using FileX. The options below can be defined in the application source, on the command line, or within the fx_user.h include file.
Important: Options defined in fx_user.h are applied only if the application and ThreadX library are built with *FX_INCLUDE_USER_DEFINE_FILE defined.* When using FileX in Standalone mode (FX_STANDALONE_ENABLE must be defined), ThreadX files/libraries are not required.
The following list describes each configuration option in detail:
| Define | Meaning |
|---|---|
| FX_MAX_LAST_NAME_LEN | This value defines the maximum file name length, which includes full path name. By default, this value is 256. |
| FX_DONT_UPDATE_OPEN_FILES | Defined, FileX does not update already opened files. |
| FX_MEDIA_DISABLE_SEARCH_CACHE | Defined, the file search cache optimization is disabled. |
| FX_MEDIA_DISABLE_SEARCH_CACHE | Defined, the file search cache optimization is disabled. |
| FX_DISABLE_DIRECT_DATA_READ_CACHE_FILL | Defined, the direct read sector update of cache is disabled. |
| FX_MEDIA_STATISTICS_DISABLE | Defined, gathering of media statistics is disabled. |
| FX_SINGLE_OPEN_LEGACY | Defined, legacy single open logic for the same file is enabled. |
| FX_RENAME_PATH_INHERIT | Defined, renaming inherits path information. |
| FX_DISABLE_ERROR_CHECKING | Removes the basic FileX error checking API and results in improved performance (as much as 30%) and smaller code size. |
| FX_MAX_LONG_NAME_LEN | Specifies the maximum file name size for FileX. The default value is 256, but this can be overridden with a command-line define. Legal values range between 13 and 256. |
| FX_MAX_SECTOR_CACHE | Specifies the maximum number of logical sectors that can be cached by FileX. The actual number of sectors that can be cached is lesser of this constant and how many sectors can fit in the amount of memory supplied at fx_media_open. The default value is 256. All values must be a power of 2. |
| FX_FAT_MAP_SIZE | Specifies the number of sectors that can be represented in the FAT update map. The default value is 256, but this can be overridden with a command-line define. Larger values help reduce unneeded updates of secondary FAT sectors. |
| FX_MAX_FAT_CACHE | Specifies the number of entries in the internal FAT cache. The default value is 16, but this can be overridden with a command-line define. All values must be a power of 2. |
| FX_FAULT_TOLERANT | When defined, FileX immediately passes write requests of all system sectors (boot, FAT, and directory sectors) to the media’s driver. This potentially decreases performance, but helps limit corruption to lost clusters. Note that enabling this feature does not automatically enable FileX Fault Tolerant Module, which is enabled by defining |
| FX_FAULT_TOLERANT_DATA | When defined, FileX immediately passes all file data write requests to the media’s driver. This potentially decreases performance, but helps limit lost file data. Note that enabling this feature does not automatically enable FileX Fault Tolerant Module, which is enabled by defining FX_ENABLE_FAULT_TOLERANT |
| FX_NO_LOCAL_PATH | Removes local path logic from FileX, resulting in smaller code size. |
| FX_NO_TIMER | Eliminates the ThreadX timer setup to update the FileX system time and date. Doing so causes default time and date to be placed on all file operations. |
| FX_UPDATE_RATE_IN_SECONDS | Specifies rate at which system time in FileX is adjusted. By default, value is 10, specifying that the FileX system time is updated every 10 seconds. |
| FX_UPDATE_RATE_IN_TICKS | Specifies the same rate as FX_UPDATE_RATE_IN_SECONDS (see above), except in terms of the underlying ThreadX timer frequency. The default is 1000, which assumes a 10ms ThreadX timer rate and a 10 second interval. |
| FX_SINGLE_THREAD | Eliminates ThreadX protection logic from the FileX source. It should be used if FileX is being used only from one thread or if FileX is being used without ThreadX. |
| FX_DRIVER_USE_64BIT_LBA | When defined, enables 64-bit sector addresses used in I/O driver. By default this option is not defined. |
| FX_ENABLE_FAULT_TOLERANT | When defined, enables FileX Fault Tolerant Module. Enabling Fault Tolerant automatically defines the symbol FX_FAULT_TOLERANT and FX_FAULT_TOLERANT_DATA. By default this option is not defined. |
| FX_FAULT_TOLERANT_BOOT_INDEX | Defines byte offset in the boot sector where the cluster for the fault tolerant log is. By default this value is 116. This field takes 4 bytes. Bytes 116 through 119 are chosen because they are marked as reserved by FAT 12/16/32 specification. |
| FX_FAULT_TOLERANT_MINIMAL_CLUSTER | This symbol is deprecated. It is no longer being used by FileX Fault Tolerant. |
| FX_STANDALONE_ENABLE | Defined, enables FileX to be used in standalone mode (without Eclipse ThreadX). By default this symbol is not defined. |
Important: When FX_STANDALONE_ENABLE is defined, Local path logic and ThreadX timer setup are disabled.
The current version of FileX is available both to the user and the application software during run-time. The programmer can obtain the FileX version from examination of the fx_port.h file. In addition, this file also contains a version history of the corresponding port. Application software can obtain the FileX version by examining the global string _fx_version_id.