FatFS开发前首看官网的说明翻译

官网地址http://elm-chan.org/fsw/ff/00index_e.html

官网的应用笔记http://elm-chan.org/fsw/ff/en/appnote.html

How to Port  如何去移植

Basic considerations

The FatFs module is assuming following conditions on portability.

• ANSI C
  The FatFs module is a middleware written in ANSI C (C89). There is no platform dependence, so long as the compiler is in compliance with ANSI C.
• Size of integer types
  The FatFs module assumes that size of char/short/long are 8/16/32 bit andint is 16 or 32 bit. These correspondence are defined in integer.h. This will not be a problem on most compilers. When any conflict with existing definitions is occured, you must resolve it with care.

FatFs模块是用ANSI C编写的中间件，只要编译器遵循ANSI C，它都是平台无关的。只要编译器支持ANSI C即可。

FatFs假定char/short/long的长度为8/16/32位，而int为16位或32位，这些相应的定义位于integer.h文件。这在大多数的编译器上都不会是问题，但是当与预定义的内容发生冲突时，你必须小心地解决。

System organizations  系统组织

The dependency diagram shown below is a typical configuration of the embedded system with FatFs module.

下图是一个典型的配置了FatFS模块的嵌入式系统的关系框图

(a) If a working disk module with FatFs API is provided, no additional function is needed.

(b) To attach existing disk drivers with different API, glue functions are needed to translate the APIs between FatFs and the drivers.

Which function is required?

You need to provide only low level disk I/O functions that required by FatFs module and nothing else. If a working disk module for the target system is already existing, you need to write only glue functions to attach it to the FatFs module. If not, you need to port any other disk module or write it from scratch. Most of defined functions are not that always required. For example, disk write function is not required at read-only configuration. Following table shows which function is required depends on the configuration options.

Function	Required when	Note
disk_status disk_initialize disk_read	Always	Disk I/O functions. Samples available in ffsample.zip. There are many implementations on the web.
disk_write get_fattime disk_ioctl (CTRL_SYNC)	_FS_READONLY == 0
disk_ioctl (GET_SECTOR_COUNT) disk_ioctl (GET_BLOCK_SIZE)	_USE_MKFS == 1
disk_ioctl (GET_SECTOR_SIZE)	_MAX_SS != _MIN_SS
disk_ioctl (CTRL_TRIM)	_USE_TRIM == 1
ff_convert ff_wtoupper	_USE_LFN != 0	Unicode support functions. Just add option/unicode.c to the project.
ff_cre_syncobj ff_del_syncobj ff_req_grant ff_rel_grant	_FS_REENTRANT == 1	O/S dependent functions. Samples available in option/syscall.c.
ff_mem_alloc ff_mem_free	_USE_LFN == 3

Limits  限制

• FAT sub-types: FAT12, FAT16 and FAT32.  
  
• Number of open files: Unlimited. (depends on available memory)
• Number of volumes: Upto 10.（卷最多10个，0-9）
• File size: Upto 4G-1 bytes. (by FAT specs.)     文件大小最大为4G
  
• Volume size: Upto 2T bytes at 512 bytes/sector. (by FAT specs.)   容量
  
• Cluster size: Upto 64K bytes at 512 bytes/sector. (by FAT specs.)   簇大小
  
• Sector size: 512, 1024, 2048 and 4096 bytes. (by FAT specs.)  扇区大小
  

Memory Usage  内存使用量

The memory usage varies depends on the configuration options.  内存使用量依据配置选项不同而不同

	ARM7 32bit	ARM7 Thumb	CM3 Thumb-2	AVR	H8/300H	PIC24	RL78	V850ES	SH-2A	RX600	IA-32
Compiler	GCC	GCC	GCC	GCC	CH38	C30	CC78K0R	CA850	SHC	RXC	VC6
text (Full, R/W)	10.6k	7.1k	6.5k	13.3k	10.9k	11.7k	13.3k	8.1k	9.0k	6.0k	7.9k
text (Min, R/W)	6.7k	4.6k	4.2k	8.6k	7.3k	7.7k	9.1k	5.3k	5.8k	3.9k	5.2k
text (Full, R/O)	4.8k	3.2k	2.9k	6.2k	5.2k	5.5k	6.5k	3.8k	4.0k	2.9k	3.7k
text (Min, R/O)	3.6k	2.5k	2.3k	4.6k	4.1k	4.3k	5.0k	3.0k	3.1k	2.2k	2.9k
bss	V*4 + 2	V*4 + 2	V*4 + 2	V*2 + 2	V*4 + 2	V*2 + 2	V*2 + 2	V*4 + 2	V*4 + 2	V*4 + 2	V*4 + 2
Work area (_FS_TINY == 0)	V*560 + F*550	V*560 + F*550	V*560 + F*550	V*560 + F*544	V*560 + F*550	V*560 + F*544	V*560 + F*544	V*560 + F*544	V*560 + F*550	V*560 + F*550	V*560 + F*550
Work area (_FS_TINY == 1)	V*560 + F*36	V*560 + F*36	V*560 + F*36	V*560 + F*32	V*560 + F*36	V*560 + F*32	V*560 + F*32	V*560 + F*36	V*560 + F*36	V*560 + F*36	V*560 + F*36

These are the memory usage on some target systems with following condition.

The memory sizes are in unit of byte, V denotes number of volumes andF denotes number of open files. All samples are optimezed in code size.

这是在以下情形时一些目标系统的内存用量，内存大小以字节计算，D代表卷数量，F代表打开文件的数量。所有例子都是已优化代码大小的。

FatFs R0.11 options:
_FS_READONLY   0 (R/W) or 1 (R/O)
_FS_MINIMIZE   0 (Full basic function) or 3 (Minimized function)
_VOLUMES       V (Number of logical drives to be used)
_WORD_ACCESS   0 or 1 (Set for 1 if possible)
(Any other options are left not changed from default setting)

Module Size Reduction  裁剪模块大小

Follwing table shows which API function is removed by configuration options for the module size reduction. To use any API function, the row of the function must be clear.

Function

_FS_MINIMIZE

_FS_READONLY

_USE_STRFUNC

_FS_RPATH

_USE_FIND

_USE_LABEL

_USE_MKFS

_USE_FORWARD

_MULTI_PARTITION

0

1

2

3

0

1

0

1/2

0

1

2

0

1

0

1

0

1

0

1

0

1

f_mount

f_open

f_close

f_read

f_write

x

f_sync

x

f_lseek

x

f_opendir

x

x

f_closedir

x

x

f_readdir

x

x

f_findfirst

x

x

x

f_findnext

x

x

x

f_stat

x

x

x

f_getfree

x

x

x

x

f_truncate

x

x

x

x

f_unlink

x

x

x

x

f_mkdir

x

x

x

x

f_chmod

x

x

x

x

f_utime

x

x

x

x

f_rename

x

x

x

x

f_chdir

x

f_chdrive

x

f_getcwd

x

x

f_getlabel

x

f_setlabel

x

x

f_forward

x

f_mkfs

x

x

f_fdisk

x

x

x

f_putc

x

x

f_puts

x

x

f_printf

x

x

f_gets

x

Long File Name

FatFs module supports LFN (long file name). The two different file names, SFN (short file name) and LFN, of a file is transparent on the API except forf_readdir function. The LFN feature is disabled by default. To enable it, set_USE_LFN to 1, 2 or 3, and addoption/unicode.c to the project. The LFN feature requiers a certain working buffer in addition. The buffer size can be configured by_MAX_LFN according to the available memory. The length of an LFN will reach up to 255 characters, so that the_MAX_LFN should be set to 255 for full featured LFN operation. If the size of working buffer is insufficient for the input file name, the file function fails withFR_INVALID_NAME. When use any re-entry to the API with the LFN feature, _USE_LFN must be set to 2 or 3. In this case, the file function allocates the working buffer on the stack or heap. The working buffer occupies(_MAX_LFN + 1) * 2 bytes.

FatFs从0.07版本开始支持长文件名（LFN）。在调用文件函数时，一个文件的两个文件名（SFN与LFN）是通用的，除了 f_readdir函数。长文件名特性默认是关闭的。要使能它，需要设置_USE_LEN为1，2或3，同时将unicode添加到工程中。支持长文件特性将需要一个额外的工作缓冲区，此缓冲区的大小可以通过设置_MAX_LFN来以可用的内存大小相符。因为长文件名?长达255个字符，因此_MAX_LFN应该设置为255来支持全特性的LFN选项。当工作缓冲区的大小容不下给出的文件名时文件函数就会因为?FR_INVALID_NAME而调用失败。如果使用任何重入带LFN特性的的API，_USE_LFN必须设置为2或3。在这种情况下，函数在栈或堆中分配（_MAX_LFN+1）*2大小的工作缓冲区，

LFN cfg. at CM3/gcc

_CODE_PAGE	Code size
SBCS	+2.8K
932(Japanese)	+62.6k
936(Simplified Chinese)	+177k
949(Korean)	+139k
950(Traditional Chinese)	+111k

When the LFN feature is enabled, the module size will be increased depends on the configured code page. Right table shows how much code size increased when LFN feature is enabled with some code pages. Especially, in the CJK region, tens of thousands of characters are being used. Unfortunately, it requires a huge OEM-Unicode bidirectional conversion table and the module size will be drastically increased as shown in the table. As the result, the FatFs with LFN feature with those code pages will not able to be implemented to most 8-bit microcontrollers.

当使能LFN，模块增加的大小由编码页类型决定，右边的表显示了LFN禁用与使用某些编码来使能时模块的不同大小。日语、中文与韩国语拥?有成千上万的字词，而不幸的是，将需要一个巨大的OEM-Unicode?双向转换表，模块的大小将大大的增大，如表所示。因此，使能LFN的FatFs将不能在包括AVR在内的大多数8位微控制器上使用。这也是为什么我长期以?来对实现LFN特性不感兴趣:-)

Note that the LFN feature on the FAT file system is a patent of Microsoft Corporation. This is not the case on FAT32 but most FAT32 drivers come with the LFN feature. FatFs can swich the LFN feature on/off by configuration option. When enable LFN feature on the commercial products, a license from Microsoft may be required depends on the final destination.

请注意：FAT文件系统的LFN特性是微软公司的专利。当在商用产品上使用时，根据最终目的的不同可能需要获得微软的许可证。

Unicode API

By default, FatFs uses ANSI/OEM code set on the API even at LFN configuration. FatFs can also switch the character encoding on the API to Unicode by_LFN_UNICODE option. This means that the FatFs supports the True-LFN feature. For more information, refer to the description in thefile name.

Re-entrancy  重入

The file operations to the different volume is always re-entrant regardless of configurations and it can work simultaneously without any mutual exclusion.

对不同卷的文件操作总是可以同时地工作，而与重入设置无关。

The file operations to the same volume is not re-entrant but it can also be configured to thread-safe by_FS_REENTRANT option. It enables to control exclusive use of each file system object. In this case, also the OS dependent synchronization object control functions,ff_cre_syncobj/ff_del_syncobj/ff_req_grant/ff_rel_grant, needed to be added to the project. There are some examples in theoption/syscall.c.

而对于同一个卷的重入访问可以通过使能_FS_REENTRANT选项。此时，在ff.c中的与平台相关的锁定函数必须为每个RTOS重新编写。

When a file function is called while the volume is being accessed by any other task, the file function to the volume will be suspended until that task leaves the file function. If the wait time exceeded a period defined by_TIMEOUT, the file function will abort with FR_TIMEOUT. The timeout feature might not be supported on the some RTOSs.

如果一个文件函数调用时其访问的卷正被另一个线程使用，则此访问将阻塞直到该卷解?锁。如果等待时间超过了_TIMEOUT毫秒，则函数将因FR_TIMEOUT而终止。某些RTOS可能不支持超时操作。

There is an exception on the re-entrancy for f_mount/f_mkfs/f_fdisk function. These volume management functions are not re-entrant to the same volume and corresponding physical drive. When use these functions, any other tasks need to avoid to access the volume.

f_mount与f_mkfs函数是例外，这些函数对于同一个卷不会重入。当使用这些函数时，其他线程必须关闭此卷中相应的文件，避免对此卷的访问。

Note that this section describes on the re-entrancy of the FatFs module itself. The_FS_REENTRANT controls only exclusive use of each file system object and it does not that prevent to re-enter the low level disk functions. For example, onlydisk_status function can be re-entered at single volume system and any disk function can be re-entered at multiple volume system. Thus the low level disk I/O layer must be always thread-safe when any FatFs API is re-entered by two or more tasks.

注意此部分描述的是FatFs自身的重入，与底层磁盘I/O的重入无关。

Duplicated File Access 多文件访问

FatFs module does not support the read/write collision control of duplicated open to a file. The duplicated open is permitted only when each of open method to a file is read mode. The duplicated open with one or more write mode to a file is always prohibited, and also open file must not be renamed or deleted. A violation of these rules can cause data colluption.

The file lock control can be enabled by _FS_LOCK option. The value of option defines the number of open objects to manage simultaneously. In this case, if any open, rename or remove that violating the file shareing rule that described above is attempted, the file function will rejected with FR_LOCKED. If number of open objects, files and sub-directories, is equal to _FS_LOCK, an extra f_open/f_opendir function will fail with FR_TOO_MANY_OPEN_FILES

Performance Effective File Access

For good read/write throughput on the small embedded systems with limited size of memory, application programmer should consider what process is done in the FatFs module. The file data on the volume is transferred in following sequence byf_read function.

为了在小型的嵌入式系统中得到优秀的读写效率，应用程序程序员需要可考虑FatFs究竟做了什么。磁盘中的数据是通过下面的方式来被f_read函数传送。

Figure 1. Sector misaligned read (short)

Figure 2. Sector misaligned read (long)

Figure 3. Fully sector aligned read

The file I/O buffer is a sector buffer to read/write a partial data on the sector. The sector buffer is either file private sector buffer on each file object or shared sector buffer in the file system object. The buffer configuration option_FS_TINY determins which sector buffer is used for the file data transfer. When tiny buffer configuration (1) is selected, data memory consumption is reduced_MAX_SS bytes each file object. In this case, FatFs module uses only a sector buffer in the file system object for file data transfer and FAT/directory access. The disadvantage of the tiny buffer configuration is: the FAT data cached in the sector buffer will be lost by file data transfer and it must be reloaded at every cluster boundary. However it will be suitable for most application from view point of the decent performance and low memory comsumption.

文件I/O缓冲区（file I/O buffer）表示一个将被读/写数据的扇区的缓冲区。扇区缓冲区可以是每个文件对象私有的，或者是文件系统共享的，缓冲区配置选项_FS_TINY决定?在文件数据传输中使用哪种扇区缓冲区。当选择小缓冲区（1），数据内存的使用量将降低到每个文件对象512字节。在这种情况下，FatFS只使用一个扇区?缓冲区来进行文件数据传输以及FAT/目录访问。配置为小缓冲区的缺点是：每次文件数据传输时FAT数据缓冲都会丢失而必须从一个簇的边界开始重新载入数?据。不过从其体面的表现与少内存消耗这方面来考虑，这对于多数的应用也是合适的。

Figure 1 shows that a partial sector, sector misaligned part of the file, is transferred via the file I/O buffer. At long data transfer shown in Figure 2, middle of transfer data that covers one or more sector is transferred to the application buffer directly. Figure 3 shows that the case of entier transfer data is aligned to the sector boundary. In this case, file I/O buffer is not used. On the direct transfer, the maximum extent of sectors are read withdisk_read function at a time but the multiple sector transfer is divided at cluster boundary even if it is contiguous.

图表1显示扇区局部的数据通过文件I/O缓冲区来传输，图表2显示的长数据传输，中间的一或多个扇区的数据直接传输到应用程序缓冲区。图表3显示的是在以扇区对齐的整块数据传输的情况下，不使用文件I/O缓冲区。在直接传输时disk_read函数一次会最大程度的读取更多的扇区，但是多?扇区传输不会跨越簇边界，就算它们是相邻的。

Therefore taking effort to sector aligned read/write accesss eliminates buffered data transfer and the read/write performance will be improved. Besides the effect, cached FAT data will not be flushed by file data transfer at the tiny configuration, so that it can achieve same performance as non-tiny configuration with small memory footprint.

因此使用扇区对齐的方式来进行读写访问可以避免缓冲区数据传输，并且读写效率将被提升。除了效率以外，在tiny配置的情况下FAT快速缓存数据在文件数据传输时不会刷新，所以可以用小内存消耗来达到非tiny配置相同的性能。

Considerations on Flash Memory Media

To maximize the write performance of flash memory media, such as SDC, CFC and U Disk, it must be controlled in consideration of its characteristitcs.

Using Mutiple-Sector Write

Figure 6. Comparison between Multiple/Single Sector Write

The write throughput of the flash memory media becomes the worst at single sector write transaction. The write throughput increases as the number of sectors per a write transaction as shown in Figure 6. This effect more appers at faster interface speed and the performance ratio often becomes grater than ten. This graph is clearly explaining how fast is multiple block write (W:16K, 32 sectors) than single block write (W:100, 1 sector), and also larger card tends to be slow at single block write. Number of write transactions also affects life time of the flash memory media. When compared at same amount of write data, the single sector write in Figure 6 above wears flash memory media 16 times more than multiple sector write in Figure 6 below. Single sector write is pretty pain for the flash memory media.

Therefore the application program should write the data in large block as possible. The ideal write chunk size and alighment is size of sector, and size of cluster is the best. Of course all layers between the application and the storage device must have consideration on multiple sector write, however most of open-source memory card drivers lack it. Do not split a multiple sector write request into single sector write transactions or the write throughput gets poor. Note that FatFs module and its sample disk drivers supprt multiple sector read/write feature.

Forcing Memory Erase

When remove a file with f_remove function, the data clusters occupied by the file are marked 'free' on the FAT. But the data sectors containing the file data are not that applied any process, so that the file data left occupies a part of the flash memory array as 'live block'. If the file data is forced erased on removing the file, those data blocks will be turned in to the free block pool. This may skip internal block erase operation to the data block on next write operation. As the result the write performance might be improved. FatFs can manage this feature by setting _USE_TRIM to 1. Note that this is an expectation of internal process of the flash memory storage and not that always effective. Also f_remove function will take a time when remove a large file. Most applications will not need this feature.

Critical Section

If a write operation to the FAT volume is interrupted due to any accidental failure, such as sudden blackout, incorrect media removal and unrecoverable disk error, the FAT structure on the volume can be broken. Following images shows the critical section of the FatFs module.

当对FAT文件系统的写操作由于默写意外而中断，如突然断电，不正确的磁盘移除或不可恢复的磁盘错误，FAT结构可以被毁坏。下面的图片显示了FatFs的临界段。
Figure 4. Long critical section

Figure 5. Minimized critical section

An interruption in the red section can cause a cross link; as a result, the object being changed can be lost. If an interruption in the yellow section is occured, there is one or more possibility listed below.

红色区域的中断会导致一个交叉链接，结果，正在修改的文件/目录可能会丢失。而黄色区域中断可能导致的效果在下面列出

• The file data being rewrited is collapsed.  正在重写的文件数据被毁坏
  
• The file being appended returns initial state.  正在添加内容的文件回到初始状态
  
• The file created as new is gone.丢失新建的文件
• The file created as new or overwritten remains but no content.  一个新建或覆盖的文件保持长度为0
  
• Efficiency of disk use gets worse due to lost clusters.  因为丢失关联，磁盘的使用效率变坏。
  

Each case does not affect the files that not opened in write mode. To minimize risk of data loss, the critical section can be minimized by minimizing the time that file is opened in write mode or usingf_sync function as shown in Figure 5.

在文件不是用写模式打开时，这些情况不会发生。为了最小化磁盘数据的丢失，临界段可以像图表5显示的那样最小化，通过最小化文件处于写模式打开的时间或者适当的使用f_sync函数。

Extended Use of FatFs API

These are examples of extended use of FatFs APIs. New item will be added whenever a useful code is found.

1. Open or create a file for append
2. Empty a directory
3. Allocate contiguous area to the file
4. Function/Compatible checker for low level disk I/O module
5. FAT image creator

About FatFs License

FatFs has being developped as a personal project of the author, ChaN. It is free from the code anyone else wrote. Following code block shows a copy of the FatFs license document that included in the source files.

/*----------------------------------------------------------------------------/
/  FatFs - FAT file system module  R0.11                 (C)ChaN, 2015
/-----------------------------------------------------------------------------/
/ FatFs module is a free software that opened under license policy of
/ following conditions.
/
/ Copyright (C) 2015, ChaN, all right reserved.
/
/ 1. Redistributions of source code must retain the above copyright notice,
/    this condition and the following disclaimer.
/
/ This software is provided by the copyright holder and contributors "AS IS"
/ and any warranties related to this software are DISCLAIMED.
/ The copyright owner or contributors be NOT LIABLE for any damages caused
/ by use of this software.
/----------------------------------------------------------------------------*/

Therefore FatFs license is one of the BSD-style licenses but there is a significant feature. FatFs is mainly intended for embedded systems. In order to extend the usability for commercial products, the redistributions of FatFs in binary form, such as embedded code or any forms without source code, does not need to explain about use of FatFs in the documentations. This is equivalent to the 1-clause BSD license. Of course FatFs is compatible with the most open source software licenses including GNU GPL. When you redistribute the FatFs source code with any modification or create a fork, the license can also be changed to GNU GPL, BSD-style license or any open source software licenses that not conflict with FatFs license.