FATFS Module System Application Guide

the Fatfs version used in this article is: v0.12b (released September 2016 4)
1. How to migrate1.1 first to considerThe Fatfs module migration is based on the following hypothetical conditions:

• ANSI C: compilers should follow ANSI C. The Fatfs module is a middleware software written in the ANSI C (C89 Standard) language and does not rely on any hardware platform, as long as the corresponding compiler supports ANSI C.

• Shaping type size: The Fatfs module assumes that the Char/short/long type variable size is 8/16/32 bits, assuming that the INT type variable is 16 or 32 bits. These are defined in file integer.h, and for most compilers, there is no problem with the default Definition. If there is a conflict with the current definition, you must be careful to resolve it in this File.

1.2 System Organizational StructureFigure 1-1 shows the typical relationship dependency graph of the embedded system fatfs module. The figure assumes that the SPI interface is used to access the SD card, the blue area represents the Fatfs module, and note that the Fatfs module does not contain or care about the underlying disk IO layer of the green ZONE. For applications that use the SPI to access the SD card, there are routines in the FATFS website that use hardware SPI and analog Spi.
Figure 1-1:fatfs Relationship Dependency graphIf you have only one disk device, and you use the disk interface provided by fatfs, you do not need other modules, just write the application, as shown in 1-2 (a). If you use many different interfaces, you need to write another layer of software to translate commands and data flows between the drive and the fatfs, as shown in 1-2 (b).
Note that the gray part of Figure 1-2 belongs to the underlying disk I/O layer, and Fatfs never cares how this layer is implemented!
Figure 1-2: Single device and multiple device systems 1.3 functions that must be implemented by porting
You only need to provide the underlying disk I/O functions required by the Fatfs module, and none of the others are Required. Most functions are not required, for example, a disk write function is not required when it is configured as Read-only Mode. Table 1-1 shows whether the function needs to be related to configuration Options.
Table 1-1: List of functions required for porting
2. Restrictions

• Supported file system types: FAT12, FAT16, FAT32 (r0.0), and exFAT (r1.0, starting from version R0.12 support)
• Number of open Files: unlimited (depending on available Memory)
• Number of volumes: maximum of 10
• Volume size: 2TB maximum (512 bytes/sector)
• Single file size: fat volume up to 4gb,exfat volume almost unlimited (theoretical 16*1024*1024tb)
• Cluster size: FAT volume up to 128 sectors, exFAT volume Max 16MB
• Sector size: 512, 1024, 2048, 4096 bytes

What is exfat?

exFAT (Extended file Allocation Table file system, extended Fat) is a flash-appropriate file system that Microsoft introduced in Windows Embeded 5.0 and Above. In order to solve the FAT32 file system does not support a single file greater than or equal to 4GB launched.

volumes, clusters, and sectors?

a volume (logical drive) is a file system that is proposed to manage physical disks. A physical disk can have multiple volumes, and multiple physical disks can also be mapped to 1 volumes. We often say that the drive is divided into 4 zones, and in fact it manages 4 volumes for a file System.

a

cluster can be simply understood as a set of sectors, which is the smallest unit of the file System Management disk data area, and a file, even if it is 0 bytes, is bound to occupy a cluster. When the disk is formatted, there is an "allocation unit size" option, with the default selection of 4096 bytes, which is the size of the Cluster.

the

sector is the smallest unit of the physical disk, which is determined at the time of manufacture, typically 512 bytes for USB drives and SD CARDS.

3. Memory UsageThe size of the memory usage depends on the configuration options, and table 3-1 shows the ROM and RAM usage under a specific configuration (there are more platforms on the FATFS official website for reference, and the most popular platforms are intercepted here). Before doing this, let's look at the configuration options and abbreviations that are encountered in table 3-1.
in table 3-1:

• v indicates the value defined by the macro _volumes (number of volumes);
• F indicates the number of open Files.
• The macro _fs_readonly represents a read-write limit, 0 means reading/writing (r/w), and 1 is read-only (r/o);
• Macro _fs_minimize is used for function clipping, 0 for full-featured version, and 3 for minimum function (min);
• Macro _fs_tiny is used for mode configuration, 0 for normal mode, and 1 for micro Mode.

Table 3-1: FATFS module ROM and ram consumption reference for different platforms, different configurations
4. Function ClippingTable 4-1 lists all the API functions for FATFS and how the functions are clipped under different configurations. Table 4-1:API functions and configuring macro relationships
5. Long File namesthe Fatfs module supports long file names starting from version 0.07. In addition to the function F_readdir function, other functions of the Fatfs module are transparent to the short name (SFN) and the long file name (LFN). By default, long filenames are Forbidden. To enable long filenames, you need to set the macro _USE_LFN to 1, 2, or 3, and you need to add the file option/unicode.c to the Project. LFN requires some extra cache, and the size of the cache is set by the macro _max_lfn. Long filenames can take up to 255 characters, so you need to allocate at least 255 bytes of buffer to fully conform to the long file name Feature. If the allocated buffer is not sufficient to drop the file name, the file function returns a fr_invalid_name error Value. When the long file name attribute is enabled and the Reentrant feature (macro _fs_reentrant==1) is enabled, the _USE_LFN must be set to 2 or 3. In this scenario, the file function accesses the file name in the workspace cache bit domain stack or in the HEAP. Working buffer Occupancy (_max_lfn+1) * 2 bytes, If enabled exFAT file system, additional 608 byte cache is Required.
table 5-1 lists the ROM sizes that are added to different internal code tables in the CORTEX-M3 hardware platform, the GCC compiler environment, and the use of long filenames.


when the LFN feature is enabled, the growth of the ROM size depends on the internal code table Used. The table above shows the ROM growth size corresponding to several internal code tables using the LFN feature. When you use japanese, chinese, and chinese, There are thousands of Characters. unfortunately, They need a huge oem-unicode bidirectional conversion table, which increases the size of the module substantially, as shown in the Table. therefore, the long file name attribute of the Fatfs double-byte character set is unrealistic for most 8-bit Microcontrollers. (this is why the author has not been interested in realizing the LFN feature for a long time.)
note: The long filenames feature in the FAT file system is Microsoft's Patent. When enabling LFN in a commercial application, you may need to apply for a license from microsoft.
6.Unicode APIby default, Fatfs's API functions use the ANSI/OEM code set, even in the case of enabling long Filenames. however, Fatfs can also switch to the UNICODE code set, requiring only _lfn_unicode==1. When using the Ansi/oem code set, the string data type uses char, and when the Unicode code set is used, the string data type uses WCHAR (UTF-16). The article "fatfs path name rules" provides more detailed information about Unicode.
7.exFAT File SystemExFAT (microsoft's Extended file Allocation Table) filesystem was developed by Microsoft to replace the FAT file system in a widely used embedded operating System. It has been adopted by SDA (SD card Association) and is recommended for use in high-capacity SD cards (>32g). So exFAT is about to become a standard file system for removable Storage.
for FAT32 systems, A single file is limited to a maximum of 4GB, but a single file size of exFAT file system can exceed 256tb! In addition, compared to the FAT file system, the exFAT file system has reduced file system overhead, especially file allocation delay, and can improve file write Efficiency. however, There is also a problem with the current version of Fatfs software, which is not as large as the FAT file system throughput when the file write sector is not aligned. You can use the F_expand function to pre-allocate a contiguous block to avoid this problem.
Note exFAT belongs to Microsoft patent! The exFAT function of the Fatfs module is based on Us. Pat. App. Pub. No. 2009/0164440 A1 to Achieve. You can configure macros to enable or disable the exFAT feature. When enabling EXFAT functionality on commercial products, you need to apply for a license from microsoft.
It is important to note that after enabling exfat, the C89 is no longer compatible because it requires a 64-bit shaping type.
8. Re-entry Accessibilityfile operations on different volumes are always reentrant (with the exception of a long file name and the use of a static work buffer) and can work at the same time. file operations on the same volume are non-reentrant, but you can also use thread protection by configuring the _fs_reentrant Option. In this case, the synchronization object control function of the OS is required, and the functions ff_cre_syncobj, ff_del_syncobj, ff_req_grant, and ff_rel_grant must be added to the Project.
When a volume is used by a task, if another task calls the file function, then the access is blocked waiting until the task leaves the file Function. If the wait exceeds the time defined by macro _timeout, the file function call terminates and returns FR_TIMEOUT. The timeout feature may not be supported under some rtos.
functions f_mount, f_mkfs, and F_fdisk are an exception. These volume management functions are always non-reentrant on the same volume or physical disk. When using these functions, other tasks are to avoid accessing this Volume.
Note: This paragraph simply describes the reentrant nature of the Fatfs module itself, and does not assume that the underlying disk I/O modules are Reentrant.
9. Duplicate Access files (duplicated file Access)by default, Fatfs does not support repeating open files in Read/write mode, allowing you to repeatedly open files as Read-only. It is forbidden to repeatedly open files in write mode, prevent renaming, delete files that have already been opened, or the FAT structure on the volume will Crash. also, The current directory cannot be Deleted.
file Lock control can be enabled via macro _fs_lock > 1. The value defined by this macro indicates how many files and subdirectories can be opened at the same time under file lock Control. In this case, any illegal operations on open objects (such as removal, Renaming) are rejected and return the fr_locked error code, and the functions F_open and F_opendir are special cases, and they fail to return fr_too_many_open_files error Codes.
10. High-performance File AccessIn a small embedded system, for better read and write file performance, application programming should consider how to handle the Fatfs Module. The F_read function reads the file data on the disk according to the sequence in:
 Figure 10-1: Read data, sector misaligned (small piece of Data)Figure 10-2: Read data, sector misaligned (chunk Data)Figure 10-3: Read data, sector alignmentThe file I/O buffers are used to read and write partial sector Data. The file I/O buffer can be a private sector cache for each file object, or it can be a sector cache that shares the entire file system Object. Macro _fs_tiny is used to determine whether a file I/O buffer uses a file object cache or a file system object Cache. When _fs_tiny==1 is used, the file system cache is used to indicate the use of micro-mode, files I/O buffers to share file system object caches, file Data transfer, and Fat/directory access. This allows each file object to reduce _max_ss bytes of data memory. The disadvantage of this small memory configuration is that fat data cached in the file I/O buffers will be lost during file data transfer and reloaded at the boundary of each cluster (meaning longer execution time). In any case, this is suitable for most applications where a small amount of memory consumption is required to achieve good performance.
Figure 10-1 depicts partial sector data in a file that is not aligned in a fan is passed through the file I/O cache. The bulk data transfer is shown in Figure 10-2, where one or more sector data transfers in the middle part of figure 10-2 are directly using the application Cache. Figure 10-3 describes the data transfer by sector Alignment. In this scenario, the file I/O cache is not Used. Direct transfer, through the Disk_read function, reads as many sectors as possible at a time, but multi-sector data transmissions never cross the cluster boundary, even if they are contiguous.
therefore, as far as possible to read and write to ensure sector alignment, avoid the transfer of cached data, so as to improve read and write Performance. In addition to this, the use of sector-aligned read and write, in the configuration of small memory mode, when the file is transferred, the cached fat data will not be flushed out, so that the same performance and normal mode while having a small memory consumption.
11. Considerations for using Flash memorywhen using flash memory, such as SDC and cfc, to achieve maximum write performance, you must consider their characteristics.
11.1 using multi-sector writeFigure 11-1: Multi-sector/single-sector Comparisonwhen using Flash memory, the write of one sector of a sector is most affected by the throughput rate at which the data is Written. If you write to more than one sector at a time, you will greatly increase the throughput rate of writing data, as shown in 11-1. The faster the memory interface clock, the greater the impact, and the usual throughput rate will increase by more than 10 times Times. Figure 11-2 shows this relationship, where the memory interface rate is the same, such as using the 8GB SDHC type of SD card, each write 16K (32 sector) than 100 bytes per write (1 Sector) throughput rate is 38.8 times times higher. The number of write events will affect the life of the memory, when the use of small data blocks, you may access the same sector multiple times, such as 100 bytes per write, write 5~6 times to write a sector full, so from the protection of memory life, as much as possible to use large chunks of Data.
 Figure 11-2: Relationship between Read-write throughput and write block size, memory interface ratetherefore, The application should make the data a large chunk of data and write it as much as Possible. The ideal way to write is that each write is sector aligned, and the write data size equals the multiple of the sector, preferably a cluster size. of course, the application layer to the media layer must support multi-sector write features, but most open-source disk drivers are missing this block.
note: the Fatfs module and its routines disk driver support Multi-sector read and Write.
12. Force Erase Memorywhen a file is removed through the F_unlink function, fatfs marks the cluster data space occupied by the file as "empty" in the fat table, but does not do any erasure on the sector that contains the file data, so the file data still Exists. If you want to force the file data to be removed when the file is removed, the free blocks on the storage increase. This will allow you to skip the internal erase operation the next time you write data to this block of Data. This may improve write performance. To enable this feature, set _use_trim to 1. Note: This feature is expected by the flash memory internal handler. Most applications do not require this feature, and the F_unlink function may take a long time to remove large files.
13. Critical Sectionwhen writing a fat volume, if the write operation is interrupted due to an unexpected failure, such as a sudden power outage, an incorrect removal of the disk, and an unrecoverable disk error, the FAT structure may Crash. Figure 13-1 and figure 13-2 illustrate the critical section of the Fatfs Application.
 Figure 13-1: Long Critical ZoneFigure 13-2: Minimized critical sectionthe red zone code above is executed unexpectedly and the object changes that are being executed may be lost. When the yellow area code above is executed unexpectedly, one or more of the following lists may occur:

• The file data being overwritten is corrupted
• The added file reverts to its original state
• Missing new files
• The newly created file or overwrite content is missing
• Disk performance drops due to loss of cluster chain

This is not the case if you open the file in Read-only Mode. In order to minimize the risk of data loss, the critical section should be as short as possible, and the appropriate use of the F_sync function can shorten the critical section, as shown in 13-2.

FATFS Module System Application Guide