FileX Best Practices

FileX footprint and performance optimization

This section provides guidelines to tune FileX build-time options to reduce memory footprint while keeping acceptable performance. The recommendations below describe a low-footprint profile that can be adapted depending on application needs.

File name length and path configuration

FX_MAX_LONG_NAME_LEN

  • Goal: reduce RAM usage in resource‑constrained systems by limiting long file name support.

  • How to configure: - For low-footprint profiles, set FX_MAX_LONG_NAME_LEN to 32 or 16. - Increase this value only if the application really requires very long file names.

  • Impact on FileX internals: - Controls the maximum length of long file names. - Directly impacts the size of the FX_PATH, FX_MEDIA and FX_FILE structures.

  • Default value: 256

FX_MAX_LAST_NAME_LEN

  • Goal: keep path handling robust even with deep directory hierarchies.

  • How to configure: - For most low-footprint profiles, keep the default value (256). - Avoid reducing this parameter unless the maximum directory depth is well controlled by the application.

  • Impact on FileX internals: - Defines the size of the buffer storing the last component of a path inside FX_MEDIA. - Reducing this parameter provides limited memory savings but can increase the risk of issues with deeply nested directories.

  • Default value: 256

Sector and FAT cache configuration

FX_MAX_SECTOR_CACHE

  • Goal: balance RAM usage and throughput for cached sector access.

  • How to configure: - If FX_DISABLE_CACHE is enabled, you can ignore this parameter (the sector cache is disabled). - If the cache remains enabled, limit FX_MAX_SECTOR_CACHE to at most 64 in low-footprint builds, with a typical value of 16.

  • Impact on FileX internals: - Controls the number of sectors kept in the FileX sector cache (inside FX_MEDIA). - A larger value improves performance but increases RAM usage; a smaller value reduces memory at the cost of more frequent media accesses.

  • Default value: 256

FX_FAT_MAP_SIZE

  • Goal: keep FAT management efficient without increasing RAM usage unnecessarily.

  • How to configure: - For most low-footprint profiles, keep FX_FAT_MAP_SIZE at its default value. - Change this parameter only if profiling shows a clear benefit for specific workloads.

  • Impact on FileX internals: - Defines the size of the FAT map used inside FX_MEDIA. - Reducing this parameter provides only small memory savings and may degrade FAT handling efficiency.

  • Default value: 128

FX_MAX_FAT_CACHE

  • Goal: provide a reasonable trade‑off between FAT access performance and memory footprint.

  • How to configure: - For typical applications, keep FX_MAX_FAT_CACHE at its default value. - Adjust this parameter only when detailed performance measurements justify the change.

  • Impact on FileX internals: - Controls the number of FAT entries cached by FileX. - Changing this value has limited impact on footprint but can influence performance in some scenarios.

  • Default value: 16

Global cache and search cache

FX_DISABLE_CACHE

  • Goal: minimize RAM usage by removing the global FileX sector cache.

  • How to configure: - For low-footprint profiles, enable FX_DISABLE_CACHE by default to reduce memory usage. - Provide a configuration option so that end users can clear this flag (keep the cache enabled) when they need higher throughput for large data transfers.

  • Impact on FileX internals: - When FX_DISABLE_CACHE is enabled, many cache-related members of FX_MEDIA are removed and several functions (for example

    fx_media_open(), fx_utility_logical_sector_read(), fx_utility_logical_sector_write(), fx_utility_logical_sector_cache_entry_read(), fx_utility_logical_sector_flush()) use fewer local variables on the stack.

    • This significantly reduces RAM usage, but disabling the cache can degrade performance for large or frequent data transfers.

  • Default value: disabled

FX_MEDIA_DISABLE_SEARCH_CACHE

  • Goal: reduce RAM usage by disabling the directory search cache.

  • How to configure: - Enable FX_MEDIA_DISABLE_SEARCH_CACHE for low-footprint profiles. - Allow users to disable this flag when they need improved directory search performance (for example, frequent directory traversal or a large number of files in the same directory).

  • Impact on FileX internals: - Disables the caching mechanisms used to speed up directory lookups. - Removes several members from FX_MEDIA and reduces local variable usage in directory functions such as

    fx_directory_next_entry_find(), fx_directory_next_full_entry_find(), and fx_directory_search().

  • Default value: disabled

Statistics, error checking and update policies

FX_MEDIA_STATISTICS_DISABLE

  • Goal: save RAM by removing runtime statistics that are not required in production.

  • How to configure: - Enable FX_MEDIA_STATISTICS_DISABLE for production or resource-constrained builds where detailed statistics are not needed. - Disable this flag in debug or profiling builds that require runtime counters.

  • Impact on FileX internals: - When enabled, multiple statistic counters (ULONG members) are removed from FX_MEDIA. - This reduces RAM usage without changing the functional behavior of the file system.

  • Default value: disabled

FX_DISABLE_ERROR_CHECKING

  • Goal: reduce code size and slightly reduce RAM usage by removing extended error checks.

  • How to configure: - Enable FX_DISABLE_ERROR_CHECKING in production low-footprint configurations that have already been thoroughly validated. - Disable this flag in debug builds to benefit from additional safety checks and easier troubleshooting.

  • Impact on FileX internals: - When enabled, FileX calls the core fx_ APIs instead of the extended fxe_ APIs that include error checking. - This reduces code size and can slightly reduce RAM usage, but removes internal parameter checks.

  • Default value: disabled

FX_DONT_UPDATE_OPEN_FILES

  • Goal: reduce overhead by limiting metadata updates for open files.

  • How to configure: - Enable FX_DONT_UPDATE_OPEN_FILES when the application does not depend on frequently updated metadata for open files (for example, file timestamps or size while the file remains open). - Leave this flag disabled in applications that require up-to-date file information while files are still open.

  • Impact on FileX internals: - Some functions allocate fewer local variables and FileX performs fewer metadata updates for open files. - This can reduce CPU usage and stack consumption, at the cost of less frequent metadata refresh.

  • Default value: disabled

FX_DISABLE_FAT_ENTRY_REFRESH

  • Goal: reduce stack usage and code size related to FAT entry refresh operations.

  • How to configure: - Enable FX_DISABLE_FAT_ENTRY_REFRESH for low-footprint builds where stack usage must be minimized. - Keep this option disabled if the application requires the most robust FAT refresh behavior.

  • Impact on FileX internals: - Reduces stack usage and code related to FAT entry refresh, mainly in fx_utility_FAT_entry_read().

  • Default value: disabled

Miscellaneous flags

The following flags have a small impact on memory footprint compared with the options above. For most applications it is recommended to keep the default configuration:

  • FX_DISABLE_BUILD_OPTIONS

  • FX_DISABLE_FILE_CLOSE

  • FX_SINGLE_OPEN_LEGACY

  • FX_DISABLE_FAST_OPEN

  • FX_DISABLE_FORCE_MEMORY_OPERATION

  • FX_DISABLE_CONSECUTIVE_DETECT

  • FX_DISABLE_ONE_LINE_FUNCTION

  • FX_DRIVER_USE_64BIT_LBA

  • FX_RENAME_PATH_INHERIT

Fault-tolerance options

Fault-tolerance support increases both code size and RAM usage. Enable these options only when the application explicitly requires fault‑tolerant behavior (for example, recovery after unexpected resets during write operations).

  • FX_ENABLE_FAULT_TOLERANT

    • Goal: enable the FileX fault-tolerant layer to protect against media corruption after unexpected resets.

    • How to configure: - Keep this option disabled by default in low-footprint profiles. - Enable it only when the application requires fault‑tolerant operation (for example, safety‑critical or high‑reliability systems).

    • Impact on FileX internals: - Activates the fault-tolerant journal and additional data structures used to maintain media consistency. - Increases both code size and RAM usage.

    • Default value: disabled

  • FX_FAULT_TOLERANT and FX_FAULT_TOLERANT_DATA

    • Goal: provide internal definitions required when fault tolerance is enabled.

    • How to configure: - These options are automatically enabled when FX_ENABLE_FAULT_TOLERANT is defined. No manual tuning is required.

    • Impact on FileX internals: - Control the inclusion of fault‑tolerant support code and data structures.

  • FX_FAULT_TOLERANT_BOOT_INDEX

    • Goal: adjust the location of the fault-tolerant boot area on the media when needed.

    • How to configure: - Keep the default value in most applications. - Change this parameter only when the media layout requires a different boot index.

    • Impact on FileX internals: - Has no significant impact on footprint when kept within its typical range.

    • Default value: 116

No-OS / RTOS-specific flags

Some flags are automatically enabled in no-OS mode:

  • FX_SINGLE_THREAD

  • FX_NO_LOCAL_PATH

  • FX_NO_TIMER

These options do not need manual tuning for low-footprint profiles, as they are automatically selected according to the underlying integration.

Low-footprint profile summary

For a typical low-footprint FileX profile, the following configuration is recommended:

  • Reduce FX_MAX_LONG_NAME_LEN (for example 16 or 32).

  • Keep FX_MAX_LAST_NAME_LEN, FX_FAT_MAP_SIZE and FX_MAX_FAT_CACHE at their default values.

  • If acceptable for the application, enable:

    • FX_DISABLE_CACHE

    • FX_MEDIA_DISABLE_SEARCH_CACHE

    • FX_MEDIA_STATISTICS_DISABLE

    • FX_DISABLE_ERROR_CHECKING

    • FX_DONT_UPDATE_OPEN_FILES

    • FX_DISABLE_FAT_ENTRY_REFRESH

  • Keep fault-tolerance options disabled unless they are explicitly required.

Performance-oriented configuration

The previous sections focus on a low-footprint profile, where several FileX cache mechanisms are disabled. This section provides generic recommendations for cases where throughput and latency have a higher priority than memory savings.

Impact of cache configuration on performance

In general, the configuration of FileX cache options has the following effects on performance:

  • Global cache (``FX_DISABLE_CACHE``)

    • Enabling FX_DISABLE_CACHE (therefore disabling the global FileX cache) degrades performance for large data transfers, since each access requires more physical operations on the storage media.

    • Keeping the global cache enabled (FX_DISABLE_CACHE = disabled) improves throughput at the cost of higher memory consumption.

  • Search cache (``FX_MEDIA_DISABLE_SEARCH_CACHE``)

    • Enabling FX_MEDIA_DISABLE_SEARCH_CACHE disables the caching mechanisms used to speed up directory lookups.

    • This option mainly impacts applications that frequently traverse directories or handle a large number of files in the same directory tree.

  • Direct data read cache fill (``FX_DISABLE_DIRECT_DATA_READ_CACHE_FILL``)

    • The configuration of FX_DISABLE_DIRECT_DATA_READ_CACHE_FILL can influence performance when the application performs many small, and possibly repeated, read operations on the same sectors.

    • Its impact is generally less significant than that of the global cache, but it can become noticeable for specific access patterns.

Recommendations for a performance-oriented profile

For a performance-oriented configuration , the following settings can be used as a baseline:

  • Keep the global cache enabled:

    • FX_DISABLE_CACHE = disabled

  • Keep the directory search cache enabled when the application performs many navigation or file search operations:

    • FX_MEDIA_DISABLE_SEARCH_CACHE = disabled

  • Use a sufficiently large sector cache:

    • Keep FX_MAX_SECTOR_CACHE at its default value or increase it if memory resources allow, in order to reduce physical accesses to the storage media.

  • Keep error checking disabled in production for better performance:

    • FX_DISABLE_ERROR_CHECKING = enabled in release builds,

    • and disabled in debug builds to ease troubleshooting and debugging.

The final configuration must always be validated on the target platform and adjusted to the actual access pattern of the application in order to find the best trade-off between performance and resource usage.