File System Troubleshooting#

• When calling FSBlkDev Open(), I get an error.

• When calling FSVol Open(), I get an error.

• When calling FSFile Open() / FSDir Open() / FSWrkDir Open() / FSFile Write() / FSDir Truncate(), I get an error.

• I want to partition my media, which options do I have?

• I am creating a cache instance, which parameters values should I choose for the cache configuration?

  • One Cache Per Block Device Type

  • One Cache for Multiple Block Devices

• When writing a few files of a few KB in size in a RAM disk, I get the error RTOS ERR VOL FULL.

• I want to open a file or directory on a default volume, can I still do it?

When calling FSBlkDev_Open(), I get an error.#

When opening a block device, you may encounter these typical errors:

• RTOS_ERR_SEG_OVF: some internal resources could not be allocated on a given memory segment. Increase the memory segment size. By default the File System Core and Storage layers use the heap region as a default memory segment. In that case, the heap size is increased using LIB_MEM_CFG_HEAP_SIZE. If the heap size is too low, this error is more likely to happen with a NAND or NOR media. Both of these media need a certain quantity of RAM to allocate internal resources for the proper operation of the Flash Translation Layer (FTL).

• RTOS_ERR_BLK_DEV_FMT_INVALID and RTOS_ERR_BLK_DEV_CORRUPTED: these errors indicate that the low-level format is invalid and the block device metadata is corrupted, respectively. They are only returned by NAND and NOR media when a low-level mounting is performed. These errors mean that the FTL was not able to use the metadata retrieved from the physical media. You need to low-level format the media in order to recover from these errors by using FSMedia_LowFmt(). Refer to section Low-Level Formatting a Media for more details.

• RTOS_ERR_BLK_DEV_FMT_INCOMPATIBLE: the device low-level format is incompatible with the user configuration. This error applies only to NAND media. It occurs because the NAND FTL configuration read from the flash block metadata does not match the user configuration. This error may arise in two situations regarding how the NAND FTL configuration is specified. The first situation is that you have manually specified the NAND FTL configuration using the function FS_NAND_FTL_ConfigureLowParams(). In that case, verify your FS_NAND_FTL_CFG structure parameters. The second situation is that the automatic NAND FTL configuration has not worked, and you did not specify a valid NAND FTL configuration. In that case it might be a low-level corruption issue. You need to investigate further to confirm the possible corruption and the solution may imply to low-level format the NAND chip with FSMedia_LowFmt().

• RTOS_ERR_IO: a communication error has occurred with the media. This error mostly applies to removable media such as SD and does not really apply to fixed media such as NAND and NOR. The main reason is that the SD card was not inserted when calling FSBlkDev_Open(). Ensure that the SD card is inserted or use the Media Poll task to detect the SD card insertion and open the device with FSBlkDev_Open() after the detection.

When calling FSVol_Open(), I get an error.#

When opening a volume, you may encounter these typical errors:

• RTOS_ERR_VOL_FMT_INVALID: the volume format information of the file system type is invalid. For a FAT volume, the boot sector signature is invalid, some parameters of the BIOS Parameter Block are invalid, etc. This error usually indicates a volume format corruption and you have to high-level format the volume to recover from it. The high-level format is done with FS_FAT_Fmt(). Refer to section Formatting an Existing Partition for more details.

• RTOS_ERR_PARTITION_INVALID: the partition is invalid (for instance, the first sector signature is incorrect or the partition type is not recognized). The partition on which the volume is open is certainly corrupted. You need to high-level format with FS_FAT_Fmt().

• RTOS_ERR_VOL_CORRUPTED: the volume is corrupted because the file system metadata cannot be understood correctly or is invalid. For a FAT volume, the only situation this error occurs is when the FAT journal module (cf. Optional FAT Journaling ) is not able to replay after a power-failure in order to restore the FAT metadata in a known state. In that case, you need to high-level format with FS_FAT_Fmt(). Refer to section Formatting an Existing Partition for more details.

Please note that you will loose your files and directories when performing a high-level format. You may take some extra precautions to try recovering your data before proceeding with a high-level format:

• If the media is removable such as SD and SCSI devices: you can connect the removable media to a computer and try to use any data recovery tools. Indeed, a corrupted volume does not necessarily mean that your data has been completely wiped out or lost. Some or all of your data may still be on the media, but invisible to the Micrium OS File System.

• If the media is fixed such as NAND or NOR: you may use the debug utility function called FS_NAND_Dump() to take a NAND image snapshot for further analysis of the high-level corruption root cause before high-level formatting. NOR does not offer for the moment an image dump utility function.

When calling FSFile_Open() / FSDir_Open() / FSWrkDir_Open() / FSFile_Write() / FSDir_Truncate(), I get an error.#

When calling one of these functions, you may encounter these typical errors:

• RTOS_ERR_VOL_CORRUPTED: the volume is corrupted because the file system metadata cannot be understood correctly or is invalid. For a FAT volume, the FAT is corrupted and some cluster chains cannot be followed or allocated for a file or directory; a directory table is corrupted, and the essential "dot dot" entry cannot be found. In that case, you can consider the file or directory as corrupted. You may delete the file or directory entry using FSEntry_Del(). This file and its content will be deleted. For a directory all files and sub-directories, are also deleted.

• RTOS_ERR_IO: a communication error has occurred with the media (for instance, NAND, SD, etc.). In that case, you may retry the file or directory operation if the communication error is temporary.

I want to partition my media, which options do I have?#

The MBR is usually the first sector found on partitioned medium. It holds the information on how the logical partitions, containing file systems, are organized (that is presence of a partitions table) on that medium. If you need to partition your media, you have three options:

1. My medium has only one unique partition and no Master Boot Record (MBR) sector is present. In that case, use FSPartition_Init() to create your unique partition and the MBR sector.

2. My medium has only one unique partition and a Master Boot Record (MBR) sector is present. In that case, use FS_FAT_Fmt() to create and format your unique partition containing a FAT file system without an MBR sector.

3. My medium has more than one partition and a Master Boot Record (MBR) sector is necessarily present. In that case, use a combination of FSPartition_Init() and FSPartition_Add() to create the first partition and add any subsequent partitions (usually up to a maximum of four partitions) to the partitions table of the MBR sector.

For all these options, refer to Creating and Formatting Partitions for more details.

I am creating a cache instance, which parameters values should I choose for the cache configuration?#

When creating a cache instance, you need to provide a cache configuration (structure FS_CACHE_CFG) composed of:

• a memory segment (.BlkMemSegPtr)

• a cache buffer alignment (.Align)

• a maximum logical block size (.MinLbSize)

• a minimum logical block size (.MaxLbSize)

• a number of cache blocks (.MinBlkCnt)

You need to consider two use cases in order to choose the configuration values:

1. There is one cache instance per block device type. In that situation, the values of .MinLbSize, .MaxLbSize and .MinBlkCnt can be tightly coupled to the block device capacities.

2. There is one unique cache instance shared by multiple block devices. In that situation, the values for .MaxLbSize and .MinBlkCnt shall take into account all block device capacities and the number of block devices.

The tables below present some typical values according to the two situations listed above.

One Cache Per Block Device Type#

FSCache_DfltAssign() can be used to ease the configuration in this case.

One Cache for Multiple Block Devices#

Refer to Creating and Assigning a Cache for more details.

When writing a few files of a few KB in size in a RAM disk, I get the error RTOS_ERR_VOL_FULL.#

This error may occur because your RAM disk zone is too small. In that case, increase the number of sectors composing your RAM disk to fit the files' size you need to write. A RAM disk is created using the function FS_RAM_Disk_Add(). This function takes a parameter of type FS_RAM_DISK_CFG to describe the RAM disk size in terms of number of sectors and sector size. The main reason why a RAM disk is too small is because the RAM disk has a certain number of sectors reserved for the FAT file system formatting information (FAT metadata). This number of reserved sectors for FAT is subtracted from the total size of the RAM disk specified by FS_RAM_DISK_CFG.LbCnt. Consequently, the number of useful sectors to write your file data is limited. Let's assume a RAM disk volume formatted in FAT12. FAT12 allows you to define a disk with a maximum size of 32 MB, which fits most of the time on the internal or external RAM of an embedded system using the File System module's RAM disk media driver. In that case, the number of sectors reserved for FAT metadata is about 36 sectors. Thus you need at least 18432 bytes (that is 36 sectors * 512 bytes per sector) just for the FAT metadata. In this example, your RAM disk size must be greater than 36 sectors to allow for a few files of a few KB.

Refer to the section RAM Disk for more details about the creation of a RAM disk zone.

I want to open a file or directory on a default volume, can I still do it?#

In µC/FS, it was possible to open a file or directory on a default volume by using the back slash "\" or forward slash "/" at the beginning of the absolute path as presented below:

Listing - Open a file or directory on a default volume#

p_file = fs_fopen("\\file.txt", "w");
p_file = fs_opendir("\\")

The default volume is not supported anymore with Micrium OS File System. You must specify the volume name on which the file or directory is opened. Refer to the section File and Directory Names and Paths for more details about the absolute path with Micrium OS File System.