Overview ¶

FileX is an open-source library part of Eclipse ThreadX. project maintained by the Eclipse foundation. It is a fully compliant FAT library for media storage and file system management. It supports the usual filesystem operation like media formatting, file access, and directory management. FileX is designed in a modular way that facilitate the integration of any media storage. It supports both RTOS and BareMetal modes. Designed for seamless integration into STM32 projects, FileX offers reliable data retention and significant endurance improvements. For detailed documentation, visit the FileX GitHub page doc.

Features ¶

FileX offers the common filesystem features along with a set of unique ones. Below are the most important ones:

Storage media management: this includes, opening, closing, formatting and checking the media storage status. FileX supports FAT16, FAT32 and formats.

Note: extFAT support is no longer available, in the FileX open-source library, as it must be licensed from MSFT.

File services: FileX offers a set of APIs to deal with files. It offers a set of APIs to create, delete, open in read/write modes, seek and set properties for files.
Directory Services: alongside file services, FileX also provides APIs to deal with directories. it is possible to create, delete, rename, and list the content of directories.
Unicode and LFN support: FileX supports UTF-8 and Unicode encoding formats for file names, and long file name features to ensure filesystem shareability between MCUs and modern PCs.
Fault tolerance: FileX helps preserve filesystem integrity through a fail-safe feature. This is useful for flash memories where power loss may corrupt data and the filesystem.

Overall architecture ¶

The FileX ecosystem on STM32 is organized in a layered architecture, as illustrated in the figure above:

Application layer ¶

The user application accesses the file system exclusively through the FileX API . It calls high-level services to create, open, read, write and delete files and directories, without dealing with the underlying storage technology.

FileX core services ¶

The FileX core provides:

File services (file creation, deletion, read/write, seek, attributes, …)
Directory services (directory creation, traversal, rename, …)
Media storage services (mounting, formatting, caching, sector I/O)
Fault-tolerance services (recovery after power loss, journal/log handling)

These services are RTOS-agnostic and independent from the physical media.

Low-level interfaces ¶

Below the core, a set of low-level interfaces adapts FileX to each storage device.

For SD and eMMC media, FileX directly accesses the block device through a dedicated low-level driver (no additional library is required).
For NOR and NAND Flash, FileX relies on the LevelX wear-levelling library. In this case, the FileX media layer calls the LevelX low-level interface, which handles bad-block management and wear-levelling on top of the raw Flash.

HAL / part drivers ¶

These interfaces are implemented on top of the STM32 HAL and part-specific drivers . They provide the actual communication with each memory device (SDMMC peripheral for SD/eMMC, NOR/NAND, etc.).

Notes:

Before configuring or enabling any low-level interfaces ensure that the target hardware platform supports the selected features.

Incorrect configuration can cause hardware malfunctions or unexpected behavior.

Some low-level interfaces require additional hardware modules, drivers, or firmware components.

Verify that all required dependencies are installed and properly configured.
Check for software or hardware conflicts that can affect interface operation.
Consult the documentation for instructions on installing and updating dependencies.
Failure to resolve dependencies can result in incomplete functionality or system errors.

Physical storage media ¶

At the bottom of the stack are the physical memory devices such as USB mass-storage keys, microSD cards, NOR Flash and NAND Flash. Each device is accessed through its corresponding communication interface and, when required (NOR/NAND), through the LevelX wear-levelling layer.

Folder Structure ¶

The FileX original folder structure is updated to:

Make FileX RTOS agnostic.
Provide low-level interfaces for supported storage media.

FileX folder_structure — FileX Folder Structure ¶

Common ¶

This folder contains FileX source code and main headers file. It is split into two subfolders:

src: This folder contains all the FileX source code. Each file implements a single API. File names start with a prefix specific to each FileX feature. For example, files with the fx_media_ prefix implement media-related APIs.
inc: This folder contains the main header files.

Ports ¶

In the FileX source tree, the ports directory contains the OS- and platform-specific adaptations of FileX. The highlighted folders have the following roles:

freertos: Provides the FileX port for FreeRTOS. This directory contains the glue code that integrates FileX with the FreeRTOS kernel (thread management, mutexes, critical sections, timers, etc.). It is used when FileX is configured to run in FreeRTOS mode in the STM32 project.
threadx: Provides the FileX port for ThreadX. In this configuration, FileX relies on ThreadX services for scheduling, synchronization, and resource management.
user_defined: Contains a template for a custom FileX port to any other RTOS or execution environment. Developers can implement the required primitives here (threading, locking, timing) to integrate FileX on a platform that is not supported out of the box (proprietary RTOS, specific real-time OS, etc.).
generic: Provides the generic (No-OS) port of FileX. This directory contains the implementation used when FileX runs without any RTOS (standalone mode). In this configuration, FileX does not rely on an operating system for thread scheduling or synchronization; instead, it uses simple generic stubs or application-controlled calls, making it suitable for bare-metal / no-OS STM32 projects.

Interfaces ¶

This folder contains a set of ready-to-use low-level interfaces that let FileX access storage media:

sd: A subfolder that provides different SD interface variants (polling, dma_no_os, dma_os) to communicate with microSD devices.
mmc: Similar to the sd subfolder, but dedicated to eMMC storage media.
nor: A generic interface based on the LevelX NOR API to communicate with NOR memories.
nand: A generic interface based on the LevelX API to communicate with NAND flash memories.

FileX Interfaces folder_structure — FileX Interfaces folder structure ¶