File System Configuration#
To configure the Micrium OS File System, there are two groups of configuration parameters:
This section explains how to setup these configuration groups.
File System Compile-Time Configuration#
The Micrium OS File System is configurable at compile time through a set of #defines located in fs_core_cfg.h and fs_storage_cfg.h. Through these #defines, the Micrium OS File System feature set can be tailored to match your application's requirements while keeping ROM and RAM footprints as low as possible.
We recommend that you begin the configuration process with the default configuration values, which are shown in bold in the next sections.
The sections below are organized following the order in Micrium OS File System template configuration files, fs_core_cfg.h and fs_storage_cfg.h.
Core Configuration#
The Core layer options are found in the file fs_core_cfg.h.
Generic Options#
Table - Generic Options#
Constant | Description | Possible values |
|---|---|---|
FS_CORE_CFG_FAT_EN | Enables or disables support for the FAT file system driver.Since FAT is the only file system driver currently supported, this option must be enabled. | DEF_ENABLED or DEF_DISABLED |
FS_CORE_CFG_POSIX_EN | Enables or disables support for the POSIX compatibility layer. | DEF_ENABLED or DEF_DISABLED |
FS_CORE_CFG_DIR_EN | Enables or disables support for directories. If this option is disabled, only files residing in a volume's root directory can be accessed. Furthermore, no entries can be created outside of a volume's root directory. All code paths dealing with directories are thus excluded. | DEF_ENABLED or DEF_DISABLED |
FS_CORE_CFG_FILE_BUF_EN | Enables or disables support for file buffers. Disabling this option removes all code paths and data structures related to file buffers handling.This option must be enabled when FS_CORE_CFG_POSIX_EN is enabled. | DEF_ENABLED or DEF_DISABLED |
FS_CORE_CFG_FILE_LOCK_EN | Enables or disables support for file locks. | DEF_ENABLED or DEF_DISABLED |
FS_CORE_CFG_PARTITION_EN | Enables or disables support for partitions. If this option is disabled, only the first partition can be accessed and partition table creation in the Master Boot Record (MBR) is disabled. | DEF_ENABLED or DEF_DISABLED |
FS_CORE_CFG_TASK_WORKING_DIR_EN | Enables or disables support for task bound working directories.This feature can be enabled only if the kernel abstraction layer implementation (KAL) being used provides task registers (see the subsection Task Registers in the Task Management Kernel Services section). | DEF_ENABLED or DEF_DISABLED |
FS_CORE_CFG_UTF8_EN | Enables or disables support for entry names containing UTF-8 characters. If this option is disabled, only ASCII characters may be used in an entry name. | DEF_ENABLED or DEF_DISABLED |
FS_CORE_CFG_THREAD_SAFETY_EN | Enables or disables thread safety at the core level. When disabled, this option may result in improved CPU time, RAM and ROM usage.It is not safe to disable this option when the file system is accessed by concurrent tasks. When in doubt, leave this option to its default value (DEF_ENABLED). | DEF_ENABLED or DEF_DISABLED |
FS_CORE_CFG_ORDERED_WR_EN | Enables or disables ordered write operations. If this option is enabled, write operations will be performed on the underlying media in a known order (typically one that does not jeopardize file system integrity in case of an untimely power failure). This option can be safely disabled when caches being used have only one block.It is not safe to disable this option when at least one cache instance has more than one block. When in doubt, leave this option to its default value (DEF_ENABLED). | DEF_ENABLED or DEF_DISABLED |
FS_CORE_CFG_FILE_COPY_EN | Enables or disables file copy. If this option is enabled, a dedicated API is provided for copying files. While it is possible to perform a copy using File System Compile-Time Configuration and File System Compile-Time Configuration API functions, this approach requires more RAM: one buffer for reading / writing and at least one cache block, as opposed to only one cache block in the case of File System Compile-Time Configuration. | DEF_ENABLED or DEF_DISABLED |
FS_CORE_CFG_RD_ONLY_EN | Enables or disables the read-only mode. If this option is enabled, all write operations are disallowed, and all the associated code paths and data structures are excluded. | DEF_ENABLED or DEF_DISABLED |
FS_CORE_CFG_POSIX_PUTCHAR | Configures the putchar()-like callback that is used internally by the perror() function to output an error message. The provided function must have the following prototype: int my_putchar_func(int c). If FS_CORE_CFG_POSIX_PUTCHAR is not defined, the perror() function will not be available. | Any putchar()-like function (default is putchar) |
FS_CORE_CFG_MAX_VOL_NAME_LEN | Configures the maximum number of characters contained in a volume name (e.g., the name given to File System Compile-Time Configuration) not including the terminating null character. | Must be > 1 (default is 20) |
FS_CORE_CFG_DBG_MEM_CLR_EN | Enables or disables the memory clear debug feature. | DEF_ENABLED or DEF_DISABLED |
FS_CORE_CFG_CTR_STAT_EN | Enables or disables core statistics counters. | DEF_ENABLED or DEF_DISABLED |
FS_CORE_CFG_CTR_ERR_EN | Enables or disables core error counters. | DEF_ENABLED or DEF_DISABLED |
FAT-Specific Options
Table - FAT-Specific Options#
Constant | Description | Possible values |
|---|---|---|
FS_FAT_CFG_LFN_EN | Enables or disables the long file name support. If this option is disabled, LFN entries cannot be accessed nor created. | DEF_ENABLED or DEF_DISABLED |
FS_FAT_CFG_FAT12_EN | Enables or disables the FAT12 file system driver. | DEF_ENABLED or DEF_DISABLED |
FS_FAT_CFG_FAT16_EN | Enables or disables the FAT16 file system driver. | DEF_ENABLED or DEF_DISABLED |
FS_FAT_CFG_FAT32_EN | Enables or disables the FAT32 file system driver. | DEF_ENABLED or DEF_DISABLED |
FS_FAT_CFG_JOURNAL_EN | Enables or disables the FAT journaling module. | DEF_ENABLED or DEF_DISABLED |
Storage Configuration#
The Storage layer options are found in the file fs_storage_cfg.h.
Generic Options#
Table - Generic Options#
Constant | Description | Possible values |
|---|---|---|
FS_STORAGE_CFG_DBG_WR_VERIFY_EN | Enables or disables the written data check. If this option is enabled, a write access to the media is verified by reading back the written data integrity by performing a CRC check. | DEF_ENABLED or DEF_DISABLED |
FS_STORAGE_CFG_CTR_STAT_EN | Enables or disables storage statistics counters. | DEF_ENABLED or DEF_DISABLED |
FS_STORAGE_CFG_CTR_ERR_EN | Enables or disables storage error counters. | DEF_ENABLED or DEF_DISABLED |
FS_STORAGE_CFG_MEDIA_POLL_TASK_EN | Enables or disables media polling task. | DEF_ENABLED or DEF_DISABLED |
FS_STORAGE_CFG_RD_ONLY_EN | Enables or disables the read-only mode. If this option is enabled, all write operations are disallowed, and all the associated code paths and data structures are excluded. | DEF_ENABLED or DEF_DISABLED |
FS_STORAGE_CFG_CRC_OPTIMIZE_ASM_EN | Enables or disables CRC calculation assembler optimization. | DEF_ENABLED or DEF_DISABLED |
NAND-Specific Options
Table - NAND-Specific Options#
Constant | Description | Possible values |
|---|---|---|
FS_NAND_CFG_AUTO_SYNC_EN | Determines, for each operation on the device (i.e., each call to the device's API), if the metadata should be synchronized. Synchronizing at the end of each operation is safer; it ensures the device can be remounted and appear exactly as it should. Disabling automatic synchronization will result in a large write speed increase, as the metadata won't be committed automatically, unless done in the application. If a power down occurs between a device operation and a sync operation, the device will appear as it was in a prior state when remounted. Device synchronization can be forced with a call to FSBlkDev_Sync().Note that using large write buffers will reduce the metadata synchronization performance hit, as fewer calls to the device API will be needed. | DEF_ENABLED or DEF_DISABLED |
FS_NAND_CFG_UB_META_CACHE_EN | Determines, for each update block, if the metadata will be cached. Enabling this will allow searching for a specific updated sector through data in RAM instead of accessing the device, which would require additional read page operations. More RAM will be consumed if this option is enabled, but write/read speed will be improved. RAM usage = (<Nbr update blks> x (log2(<Max associativity>) + log2(<Nbr secs per blk>)) / 8) octets (rounded up). | DEF_ENABLED or DEF_DISABLED |
FS_NAND_CFG_DIRTY_MAP_CACHE_EN | Determines if the dirty blocks map will be cached. With this feature enabled, a copy of the dirty blocks map on the device is cached. It is possible then to determine if the state "dirty" of a block is committed on the device without the need to actually read the device.With this feature enabled, overall write and read speed should be improved. Also, robustness will be improved for specific cases. However, more RAM will be consumed. RAM usage = (<Nbr of blks on device> / 8) octets (rounded up) | DEF_ENABLED or DEF_DISABLED |
FS_NAND_CFG_UB_TBL_SUBSET_SIZE | Controls the size of the subsets of sectors pointed by each entry of the update block tables. The value must be a power of 2 (or 0). If, for example, the value is 4, each time a specific updated sector is requested, the NAND Flash Translation layer must find the sector from a group of 4 sectors. Thus, if the cache is disabled, 4 sectors must be read from the device. Otherwise, the 4 entries will be searched in the cache. If the value is set to 0, the table will be disabled completely, meaning that all sectors of the block might have to be be read before the specified sector is found. If the value is 1, the table completely specifies the location of the sector, and thus no search must be performed. In that case, enabling the update blocks metadata cache will yield to no performance benefit. RAM usage = (<Nbr update blks> x (log2(Nbr secs per blk>) - log2(<Subset size>) x <Max associativity> / 8) octets (rounded up). | Any power of 2 or 0 (default is 1) |
FS_NAND_CFG_RSVD_AVAIL_BLK_CNT | Indicates the number of blocks in the available blocks table that are reserved for metadata block folding. Since this operation is critical and must be done before adding blocks to the available blocks table, the driver needs enough reserved blocks to make sure at least one of them is not bad so that the metadata can be folded successfully. When set to 3, probability for the metadata folding operation to fail is low. This value should be sufficient for most applications. | Must be > 1 (default is 3) |
FS_NAND_CFG_MAX_RD_RETRIES | Indicates the maximum number of retries performed when a read operation fails. It is recommended by most manufacturers to retry reading a page if it fails, as successive read operations might be successful. This number should be at least set to 2 for smooth operation, but might be set higher to improve reliability. | Must be > 2 (default is 10) |
FS_NAND_CFG_MAX_SUB_PCT | Indicates the maximum number of update blocks that can be sequential update blocks (SUB). This value is set as a percentage of the total number of update blocks. | Integer between 0 and 100 (default is 30) |
FS_NAND_CFG_DUMP_SUPPORT_EN | Enables or disables support for the NAND dump facility. | DEF_ENABLED or DEF_DISABLED |
NOR-Specific Options
Table - NOR-Specific Options#
Constant | Description | Possible values |
|---|---|---|
FS_NOR_CFG_WR_CHK_EN | Enables or disables checking for data writes. When enabled, all NOR operations implying a write operation such as page program or block erase are verified by reading back the data from the NOR chip and comparing it to the data written. When erasing a block, the check ensures that the read data bits are all one because after an erase operation, the bits are all set to one. This configuration is useful during the development phase and should not be left enabled as it impacts the write performances. | DEF_ENABLED or DEF_DISABLED |
SD-Specific Options#
Table - SD-Specific Options#
Constant | Description | Possible values |
|---|---|---|
FS_SD_SPI_CFG_CRC_EN | Enables or disables CRC and checking for data writes and reads. When enabled, a CRC will be generated for data written to the card, and the CRC of received data will be checked. When disabled, no CRC will be generated for data written to the card, and the CRC received data will not be checked. | DEF_ENABLED or DEF_DISABLED |
File System Run-Time Configuration#
This section describes the Micrium OS File System run-time configurations. These configurations are optional and can usually be ignored until the very late stages of an application design.
Core Configuration#
Optional Pre-Init Configuration#
To perform pre-init configuration, you must call the dedicated configuration functions before calling FSCore_Init(). If no explicit pre-init configuration is performed, default values will be used. These default values are stored in FSCore_InitCfgDflt defined in fs_core.c.
Memory Segment#
Configures the memory segment where the core internal data structures will be allocated.
Type | Function to call | Default | Field from default configuration structure |
|---|---|---|---|
MEM_SEG* | FSCore_ConfigureMemSeg() | .MemSegPtr |
Maximum Number of Core Objects#
Configures the maximum number of file system driver-agnostic core objects.
Type | Function to call | Default | Field from default configuration structure |
|---|---|---|---|
FS_CORE_CFG_MAX_OBJ_CNT | FSCore_ConfigureMaxObjCnt() | Unlimited number of objects | .MaxCoreObjCnt.WrkDirCnt .MaxCoreObjCnt.RootDirDescCnt |
Maximum Number of FAT Objects#
Configures the maximum number of FAT objects.
Type | Function to call | Default | Field from default configuration structure |
|---|---|---|---|
FS_CORE_CFG_MAX_FAT_OBJ_CNT | FSCore_ConfigureMaxFatObjCnt() | Unlimited number of objects | .MaxFatObjCnt.FileDescCnt |
FS_CORE_CFG_MAX_FAT_OBJ_CNT | FSCore_ConfigureMaxFatObjCnt() | Unlimited number of objects | .MaxFatObjCnt.FileNodeCnt |
FS_CORE_CFG_MAX_FAT_OBJ_CNT | FSCore_ConfigureMaxFatObjCnt() | Unlimited number of objects | .MaxFatObjCnt.DirDescCnt |
FS_CORE_CFG_MAX_FAT_OBJ_CNT | FSCore_ConfigureMaxFatObjCnt() | Unlimited number of objects | .MaxFatObjCnt.DirNodeCnt |
FS_CORE_CFG_MAX_FAT_OBJ_CNT | FSCore_ConfigureMaxFatObjCnt() | Unlimited number of objects | .MaxFatObjCnt.VolCnt |
Storage Configuration#
Optional Pre-Init Configuration#
To perform pre-init configuration, you must call the dedicated configuration functions before calling FSStorage_Init(). If no explicit pre-init configuration is performed, default values will be used. These default values are stored in FSStorage_InitCfgDflt defined in fs_storage.c.
Memory Segment#
Configures the memory segment where the storage sub-module's internal data structures will be allocated.
Type | Function to call | Default | Field from default configuration structure |
|---|---|---|---|
MEM_SEG* | FSStorage_ConfigureMemSeg() | .MemSegPtr |
Media Connection Callbacks#
Configures the media connection and disconnection callbacks.
Type | Function to call | Default | Field from default configuration structure |
|---|---|---|---|
FS_MEDIA_CONN_CB | FSStorage_ConfigureMediaConnCallback() | DEF_NULL | .OnConn |
FS_MEDIA_CONN_CB | FSStorage_ConfigureMediaConnCallback() | DEF_NULL | .Disconn |
Media Poll Task Stack#
Configures the size and the start address of the Media Poll task stack.
Type | Function to call | Default | Field from default configuration structure |
|---|---|---|---|
CPU_INT32U | FSStorage_ConfigureMediaPollTaskStk() | A stack of 512 elements allocated on Common 's memory segment | .PollTaskStkSizeElements |
void * | FSStorage_ConfigureMediaPollTaskStk() | A stack of 512 elements allocated on Common 's memory segment | .PollTaskStkPtr |
Maximum Number of SCSI Logical Units#
Configures the maximum number of SCSI logical units that may co-exist at a given time.
Type | Function to call | Default | Field from default configuration structure |
|---|---|---|---|
CPU_SIZE_T | FSStorage_ConfigureMaxSCSILogicalUnitCnt() | Unlimited | .MaxSCSILuCnt |
Optional Post-Init Configuration#
This section describes the configurations that can be set at any time during execution after FSStorage_Init() has been called. These configurations are optional. If you do not set them in your application, the default configurations will apply.
Media Poll Task Period#
Configures the interval of time (in milliseconds) between two media polls.
Type | Function to call | Default |
|---|---|---|
CPU_INT32U | FSStorage_PollTaskPeriodSet() | 500 |
Media Poll Task Priority#
Configures the priority of the Media Poll task.
Type | Function to call | Default |
|---|---|---|
RTOS_TASK_PRIO | FSStorage_PollTaskPrioSet() |
File System Run-time Configuration Details for Core#
The FS_CORE_CFG_MAX_OBJ_CNT structure allows you to configure the number of objects needed by the Core layer.
Table - FS_CORE_CFG_MAX_OBJ_CNT Configuration Structure in the File System Run-time Configuration Details for Core page describes each configuration field available in this configuration structure.
Table - FS_CORE_CFG_MAX_OBJ_CNT Configuration Structure#
Field | Description |
|---|---|
.WrkDirCnt | The maximum number of working directories. A working directory object is allocated each time a working directory is opened with FSWrkDir_Open(). |
.RootDirDescCnt | The maximum number of root directory descriptors. A root directory descriptor object is allocated e ach time a directory is opened with FSDir_Open() . |
File System Run-time Configuration Details for FAT#
The FS_CORE_CFG_MAX_FAT_OBJ_CNT structure allows you to configure the number of objects needed by the FAT sub-module of the Core layer.
Table - FS_CORE_CFG_MAX_FAT_OBJ_CNT Configuration Structure in the File System Run-time Configuration Details for FAT page describes each configuration field available in this configuration structure.
Table - FS CORE CFG MAX FAT OBJ CNT Configuration Structure#
Field | Description |
|---|---|
.FileDescCnt | The maximum number of file descriptors. A file descriptor object is allocated each time a file is opened with FSFile_Open(), |
.FileNodeCnt | The maximum number of file nodes. A file node object is allocated for each different file opened with FSFile_Open(). If the same file is opened several times with FSFile_Open(), only one file node is created. Refer to the section Core Objects for more details about file descriptors versus file nodes. |
.DirDescCnt | The maximum number of directory descriptors. Each time a directory is opened with FSWrkDir_Open() , a directory descriptor object is allocated. |
.DirNodeCnt | The maximum number of directory nodes. A directory node object is allocated for each different directory opened with FSDir_Open(). If the same directory is opened several times with FSDir_Open(), only one directory node is created. Refer to the section Core Objects for more details about directory descriptors versus directory nodes. |
.VolCnt | The maximum number of volumes. A volume object is allocated each time a volume is opened with FSVol_Open(). |