 |
Synergy Software Package User's Manual
|
|
Synergy Software Package User's Manual
|
The purpose of this document is to provide an easy reference for the FileX source component in e2 studio. The properties are explained in greater detail than the footer comment supplied with each property. Context specific usage is included to help understand when to change the default values. This document should make it easier to use the FileX source component without having to cross reference with the Azure RTOS FileX User Guide, and help the developer become familiarized, more quickly, with FileX features.
Adding the FileX source component enables the developer in the Synergy configurator environment to customize the FileX library, change values from default settings, and enable or disable certain features. Otherwise, they must use the prebuilt FileX library. In most projects beyond the simplest, the developer will typically want to customize their FileX environment. Note that the ThreadX source component is automatically added whenever FileX is added as a higher-level source component.
Without adding the FileX source component, the e2 studio configurator will use a prebuilt library with the FileX default settings.
In the e2 studio configurator, add the ThreadX source component by selecting any thread from the Threads list and pressing the New Stack button and navigating the menu to X-Ware > FileX> FileX Source. Often the FileX source is available as an option when a high-level framework is created. For example, the FileX source module is available as an option for the FileX on USB Mass Storage framework module as seen in the below thread stack diagram.
After changing FileX property settings, the developer must click on the Generate Project Content button to update the project configurator in e2 studio and then the FileX library must be rebuilt (for example, rebuild the project). Simply changing a property (or applying a #define in the preprocessor list) without rebuilding the project will not affect any change since e2 studio will use the previously built library.
The default settings are often the choice needed for the most common use cases.
The properties of the FileX Source component are given in the order they appear in the properties window of the Synergy configurator.
Error Checking – default value enabled – Generally enabled during development and debugging phase, and disabled when a release version is being built. When enabled, FileX include error checking services that will check input and other parameters before calling the actual API. Some of the things it checks for are:
file_ptr -> fx_file_id != FX_FILE_ID // check the file instance structureThese last two checks guard against an application using a different version of the FileX library than the application is using.
Disabling the FileX error checking API results in improved performance (as much as 30%) and smaller code size.
Max Long Name Len – Maximum Long Name Length – default value not displayed, 33 characters is used – Defines the maximum size of long file names supported by FileX. The default value is 33. The minimum value is 13 and the maximum value is 256.
Max Last Name Len – Maximum Last Name Length – default value not displayed, 256 characters is used – Defines the maximum size of last opened file names supported by FileX. The default value is 256. The minimum value is 13 and the maximum value is 256. Must be as large as or larger than Max Long Name Len.
Max Sector Cache – Maximum Sector Cache Size - default value not displayed, 256 is used – Defines the maximum number of logical sectors that can be cached by FileX. The cache memory supplied to FileX at fx_media_open determines how many sectors can actually be cached. Minimum value is 2, all other values must be a power of 2.
Fat Map Size – FAT Map Size - default value not displayed, 128 is used – Defines the size in bytes of the bit map used to update the secondary FAT sectors. Larger the value result in fewer unnecessary secondary FAT sector writes. Minimum value is 1, no maximum value.
Max Fat Cache – Maximum FAT Cache - default value not displayed, 16 is used – Defines the number of entries in the internal FAT cache. The minimum value is 8, all values must be a power of 2.
Update Rate (seconds) - default value not displayed, 10 seconds used - Specifies rate at which the system time in FileX is adjusted. The default value 10 means that the FileX system time is updated every 10 seconds.
__Max exFAT Cache Size - default value not displayed, 512 is used. -__ Defines bitmat cache size for exFAT. Size should be minimum one sector size and maximum 4096. For applications using multiple media devices with varying sector size, the value should be set to the size of largest sector size.
No Timer – default value disabled – When enabled, FileX is built without update to the time parameters. 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.
Single Thread – default value disabled – When enabled, FileX is running in a single-threaded environment and does not need thread protection. 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.
Don't Update Open Files – default value disabled – When enabled, FileX does not update already opened files.
Media Search Cache – default value enabled – When enabled, a cache is used for optimization when searching for open media. Disabling this option will remove this optimization, reducing code size and memory footprint at the expense of performance.
Direct Data Read Cache Fill – default value enabled – When enabled, data sector reads are cached for faster access. Disabling this feature will reduce code size and memory footprint at the expense of performance.
Media Statistics – default value enabled – Determine if media statistics are kept and gathered. When disabled, no media statistics are available. This improves performance slightly and reduces code size; each instance of the FX_MEDIA_STRUCT structure is considerably smaller.
Single Open Legacy – default value disabled – When enabled, legacy single open logic for the same file is used. This may be necessary to make the fx_file_open behave in the same way as older versions of FileX, when migrating old FileX application code.
Rename Path Inherit – default value disabled – When enabled, renaming inherits path information. In other words, prepend the path in the new file name, then override the old file name with the new one on the renamed file.
No Local Path – default value disabled – When enabled, the local path logic is disabled. When disabled, a local path is kept for each thread; all operations performed with a relative path, will be relative to this local path.
Fault Tolerant Data – default value disabled – When enabled, data sector write requests are flushed immediately to the driver. This will increase the likelihood that data is not lost in case of power loss or a reset, but it will impact performance.
Fault Tolerant – default value disabled – When enabled, system sector write requests (including FAT and directory entry requests) are flushed immediately to the driver. This will increase the likelihood that data is not lost in case of power loss or a reset, but it will impact performance.
64-bit LBA – default value enabled – When enabled, 64-bits sector addresses are used in the I/O driver. This allows bigger media and bigger files.
Fault Tolerant Service – default value disabled – Enables or disables the FileX fault tolerant service. The FileX Fault Tolerant Module is designed to prevent file system corruption caused by interruptions during the file or directory update. For example, when appending data to a file, FileX needs to update the content of the file, the directory entry, and possibly the FAT entries. If this sequence of update is interrupted (such as by a power glitch, or if the media is ejected in the middle of the update), the file system is in an inconsistent state, which may affect the integrity of the entire file system, leading towards corruption of other files.
Fault Tolerant Boot Index – default is 16 – 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/exFAT specification.
Fault Tolerant Minimal Cluster Size – default is 3072 – Defines the requirement for minimal size of a cluster in bytes. It must be a multiple of the sector size. The default value is 3072, which works with the worst case for long file renaming.
exFAT Support – default value disabled – When enabled, the logic for handling the exFAT file system is enabled in FileX source code
Standalone enable – default value is disabled – When enabled, Filex will be used in standalone mode (without ThreadX).
Disable cache – default value is disabled – When enabled, cache is disabled.
Disable file close – default value is disabled – When enabled, file close is disabled.
Disable fast open – default value is disabled – When enabled, fast open is disabled.
Disable force memory operation – default value is disabled – When enabled, force memory operations are disabled.
Disable build option – default value is disabled – When enabled, build option is disabled.
Disable one line function – default value is disabled – When enabled, one line function is disabled.
Disable fat entry refresh – default value is disabled – When enabled, FAT entry refresh is disabled.
Disable consecutive detect – default value is disabled – When enabled, consecutive detect is disabled.
When an application writes data into a file, FileX updates both data clusters and system information. These updates must be completed as an atomic operation to keep information in the file system coherent. For example, when appending data to a file, FileX needs to find an available cluster in the media, update the FAT chain, update the length filed in the directory entry, and possibly update the starting cluster number in the directory entry. Either a power failure or media ejection can interrupt the sequence of updates, which will leave the file system in an inconsistent state. If the inconsistent state is not corrected, the data being updated can be lost, and because of damage to the system information, subsequent file system operation may damage other files or directories on the media.
The FileX Fault Tolerant Module works by journaling steps required to update a file before these steps are applied to the file system. If the file update is successful, these log entries are removed. However, if the file update is interrupted, the log entries are stored on the media. Next time the media is mounted, FileX will detect these log entries from the previous (unfinished) write operation. In such cases, FileX can recover from a failure by either rolling back the changes already made to the file system, or by reapplying the required changes to complete the previous operation. In this way, the FileX Fault Tolerant Module maintains file system integrity if the media loses power during an update operation.
After the FileX Fault Tolerant module protects a media, the media must not be mounted by anything other than FileX with Fault Tolerant enabled. Doing so can cause the log entries in the file system to be inconsistent with system information on the media. If the FileX Fault Tolerant module attempts to process log entries after the media is updated by another file system, the recovery procedure may fail, leaving the entire file system in an unpredictable state.
The FileX Fault Tolerant feature is available to all FAT file systems supported by FileX, including FAT12, FAT16, FAT32, and exFAT. To enable the fault tolerant feature, FileX must be built with the option "Fault
tolerant service" enabled. At run time, the application starts the fault tolerant service by calling fx_fault_tolerant_enable() immediately after the call to fx_media_open. After fault tolerant is enabled, all file write operations to the designated media are protected. By default, the fault tolerant module is not enabled.
The application needs to make sure the file system is not being accessed prior to fx_fault_tolerant_enable() being called. If application writes data to the file system prior to fault tolerant enable, the write operation could corrupt the media if prior write operations were not completed, and the file system.
The FileX fault tolerant log takes up one logical cluster in flash. The index to the starting cluster number of that cluster is recorded in the boot sector was not restored using fault tolerant log entries. For further details on the log format refer to the FileX user guide.
To enable the exFAT file system support in SSP, the user has to add the fileX source files to the project, and enable the “FileX Source" -> “exFAT support" option in the fileX source configurator properties, and re-build the FileX project.