X-Git-Url: http://cloudbase.mooo.com/gitweb/z180-stamp.git/blobdiff_plain/05437fb4cdb907816a4fc3ffafa2617fcf33266a..b30c4e8f1aef96f6fdc93da9f125545f5f74d06e:/fatfs/doc/en/appnote.html diff --git a/fatfs/doc/en/appnote.html b/fatfs/doc/en/appnote.html index fee2af9..4cd111f 100644 --- a/fatfs/doc/en/appnote.html +++ b/fatfs/doc/en/appnote.html @@ -15,9 +15,10 @@
  • How to Port
  • Limits
  • Memory Usage
    • -
  • Module Size Reduction
    • +
  • Reducing Module Size
  • Long File Name
  • Unicode API
    • +
  • exFAT File System
  • Re-entrancy
  • Duplicated File Access
  • Performance Effective File Access
    • @@ -26,9 +27,8 @@
  • Extended Use of FatFs API
  • About FatFs License
    • -
    -
    +

    How to Port

    Basic considerations

    @@ -37,193 +37,195 @@
  • 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 and int 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.
    • +The FatFs module assumes that size of char/short/long are 8/16/32 bit and int is 16 or 32 bit. These correspondence are defined in integer.h. This will not be a problem on most compilers. When a conflict with existing definitions is occured, you must resolve it with care.

    System organizations

    -

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

    -

    dependency diagram

    -

    (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.

    -

    functional diagram

    +

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

    +

    dependency diagram

    +

    (a) If a working disk module with FatFs disk interface is provided, nothing else will be needed. (b) To attach existing disk drivers with different interface, glue functions are needed to translate the interfaces between FatFs and the drivers.

    +

    functional diagram

    -

    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 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 in read-only configuration. Following table shows which function is required depends on configuration options.

    +

    The functions required

    +

    You need to provide only low level disk I/O functions 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.

    - + - +
    FunctionRequired when:Note
    FunctionRequired whenNote
    disk_status
    disk_initialize
    disk_read    		AlwaysDisk 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 >= 1Unicode support functions.
    Available in option/unicode.c.
    ff_convert
    ff_wtoupper    		_USE_LFN != 0Unicode support functions.
    Just add option/unicode.c to the project.
    ff_cre_syncobj
    ff_del_syncobj
    ff_req_grant
    ff_rel_grant    		_FS_REENTRANT == 1O/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.
      • +
    • File system type: FAT12, FAT16, FAT32(r0.0) and exFAT(r1.0).
      • +
    • Number of open files: Unlimited. (depends on available memory)
    • Number of volumes: Upto 10.
      • -
    • File size: Depends on the FAT specs. (upto 4G-1 bytes)
      • -
    • Volume size: Depends on the FAT specs. (upto 2T bytes at 512 bytes/sector)
      • -
    • Cluster size: Depends on the FAT specs. (upto 64K bytes at 512 bytes/sector)
      • -
    • Sector size: Depends on the FAT specs. (512, 1024, 2048 and 4096 bytes)
      • +
    • Volume size: Upto 2 TiB at 512 bytes/sector.
      • +
    • File size: Upto 4 GiB - 1 on FAT volume and virtually unlimited on exFAT volume.
      • +
    • Cluster size: Upto 128 sectors on FAT volume and upto 16 MiB on exFAT volume.
      • +
    • Sector size: 512, 1024, 2048 and 4096 bytes.
    -
    +

    Memory Usage

    +

    The memory usage varies depends on the configuration options.

    - - - - - - - - - - + + + + + + + + +
    ARM7
    32bit    		ARM7
    Thumb    		CM3
    Thumb-2    		AVRH8/300HPIC24RL78V850ESSH-2ARX600IA-32
    CompilerGCCGCCGCCGCCCH38C30CC78K0RCA850SHCRXCVC6
    _WORD_ACCESS00010001011
    text (Full, R/W)1067571716617133551094011722132628113904860327952
    text (Min, R/W) 672746314331 8569 7262 7720 90885287580039485183
    text (Full, R/O) 473131472889 6235 5170 5497 64823833397228623719
    text (Min, R/O) 355924852295 4575 4064 4240 50192993310422142889
    bssV*4 + 2V*4 + 2V*4 + 2V*2 + 2V*4 + 2V*2 + 2V*2 + 2V*4 + 2V*4 + 2V*4 + 2V*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
    CompilerGCCGCCGCCGCCCH38C30CC78K0RCA850SHCRXCMSC
    text (Full, R/W)10.4k6.8k6.3k12.4k 9.8k11.1k12.8k8.6k8.9k6.4k8.5k
    text (Min, R/W) 6.8k4.6k4.3k 8.2k 6.7k 7.6k 9.1k6.0k5.9k4.5k5.9k
    text (Full, R/O) 4.8k3.1k2.8k 5.6k 4.6k 5.3k 6.3k4.0k3.9k3.0k3.9k
    text (Min, R/O) 3.6k2.4k2.3k 4.4k 3.5k 4.0k 4.9k3.3k3.0k2.4k3.1k
    bssV*4 + 2V*4 + 2V*4 + 2V*2 + 2V*4 + 2V*2 + 2V*2 + 2V*4 + 2V*4 + 2V*4 + 2V*4 + 2
    Work area
    (_FS_TINY == 0)    		V*564
    + F*552    		V*564
    + F*552    		V*564
    + F*552    		V*560
    + F*546    		V*560
    + F*546    		V*560
    + F*546    		V*560
    + F*546    		V*564
    + F*552    		V*564
    + F*552    		V*564
    + F*552    		V*564
    + F*552
    Work area
    (_FS_TINY == 1)    		V*564
    + F*40    		V*564
    + F*40    		V*564
    + F*40    		V*560
    + F*34    		V*560
    + F*34    		V*560
    + F*34    		V*560
    + F*34    		V*564
    + F*40    		V*564
    + F*40    		V*564
    + F*40    		V*564
    + F*40
    -

    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 and F denotes number of open files. All samples are optimezed in code size.

    +

    These are the memory usage on some target systems with following condition. The memory sizes are in unit of byte, V denotes option _VOLUMES and F denotes number of open files. All samples here are optimezed in code size.

    -FatFs R0.10a options:
-_FS_READONLY     0 (R/W) or 1 (R/O)
-_FS_MINIMIZE     0 (Full function) or 3 (Minimized function)
-_USE_STRFUNC     0 (Disable string functions)
-_USE_MKFS        0 (Disable f_mkfs function)
-_USE_FORWARD     0 (Disable f_forward function)
-_USE_FASTSEEK    0 (Disable fast seek feature)
-_CODE_PAGE       932 (Japanese Shift_JIS)
-_USE_LFN         0 (Disable LFN feature)
-_MAX_SS          512 (Fixed sector size)
-_FS_RPATH        0 (Disable relative path feature)
-_FS_LABEL        0 (Disable volume label functions)
-_VOLUMES         V (Number of logical drives to be used)
-_MULTI_PARTITION 0 (Single partition per drive)
-_FS_REENTRANT    0 (Disable thread safe)
-_FS_LOCK         0 (Disable file lock control)
+FatFs R0.12b options:
+_FS_READONLY   0 (R/W) or 1 (R/O)
+_FS_MINIMIZE   0 (Full, with all basic functions) or 3 (Min, with fully minimized)
+_FS_TINY       0 (Default) or 1 (Tiny file object)
+And other options are left unchanged from original setting.
    -
    -

    Module Size Reduction

    -

    Follwing table shows which API function is removed by configuration options for the module size reduction.

    +
    +

    Reducing Modle Size

    +

    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_FS_LABEL_USE_MKFS_USE_FORWARD_MULTI_PARTITION
    0123010  1/201201010101
    f_mount
    f_open
    f_close
    f_read
    f_writex
    f_syncx
    f_lseekx
    f_opendirxx
    f_closedirxx
    f_readdirxx
    f_statxxx
    f_getfreexxxx
    f_truncatexxxx
    f_unlinkxxxx
    f_mkdirxxxx
    f_chmodxxxx
    f_utimexxxx
    f_renamexxxx
    f_chdirx
    f_chdrivex
    f_getcwdxx
    f_getlabelx
    f_setlabelxx
    f_forwardx
    f_mkfsxx
    f_fdiskxxx
    f_putcxx
    f_putsxx
    f_printfxx
    f_getsx
    Function_FS_
    MINIMIZE    		_FS_
    READONLY    		_USE_
    STRFUNC    		_FS_
    RPATH    		_USE_
    FIND    		_USE_
    CHMOD    		_USE_
    EXPAND    		_USE_
    LABEL    		_USE_
    MKFS    		_USE_
    FORWARD    		_MULTI_
    PARTITION
    0123010101201010101010101
    f_mount
    f_open
    f_close
    f_read
    f_write x
    f_sync x
    f_lseek x
    f_opendir xx
    f_closedir xx
    f_readdir xx
    f_findfirst xx x
    f_findnext xx x
    f_stat xxx
    f_getfree xxx x
    f_truncate xxx x
    f_unlink xxx x
    f_mkdir xxx x
    f_rename xxx x
    f_chdir x
    f_chdrive x
    f_getcwd xx
    f_chmod x x
    f_utime x x
    f_getlabel x
    f_setlabel x x
    f_expand x x
    f_forward x
    f_mkfs x x
    f_fdisk x x x
    f_putc xx
    f_puts xx
    f_printf xx
    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 for f_readdir() function. The LFN feature is disabled by default. To enable it, set _USE_LFN to 1, 2 or 3, and add option/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 with FR_INVALID_NAME. When enable the LFN feature under re-entrant configuration, _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 module supports long file name (LFN). The two different file names, short file name (SFN) and LFN, of a file is transparent on the API except for f_readdir function. The support for LFN is disabled by default. To enable the LFN, set _USE_LFN to 1, 2 or 3, and add option/unicode.c to the project. The LFN 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 be up to 255 characters, so that the _MAX_LFN should be set to 255 for all file names. If the size of working buffer is insufficient for the input file name, the file function fails with FR_INVALID_NAME. When use any re-entry to the API with LFN is enabled, _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 and additional 608 bytes when exFAT enabled.

    - - - - - - - + + + + + + +
    LFN cfg on ARM7TDMI
    Code pageProgram size
    SBCS+3.7K
    932(Shift_JIS)+62K
    936(GBK)+177K
    949(Korean)+139K
    950(Big5)+111K
    With LFN at CM3+gcc
    _CODE_PAGECode 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 selected code page. Right table shows how many bytes 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.

    -

    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 off by configuration option. When enable LFN feature on the commercial products, a license from Microsoft may be required depends on the final destination.

    +

    When the LFN is enabled, the module size will be increased depends on the configured code page. Right table shows how much code size increased when LFN 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 enebled with those code pages will not able to be ported on the most 8-bit MCU systems.

    +

    Note that the support for LFN on the FAT volume is a patent of Microsoft Corporation. This is not the case on FAT32 but most FAT32 drivers come with the support for LFN. FatFs can switch the LFN on/off by configuration option. When enable LFN on the commercial products, you will need to be licensed by Microsoft depends on the final destination of the products.

    -
    +

    Unicode API

    -

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

    +

    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 configuration option _LFN_UNICODE. This means that FatFs supports the full featured LFN specification. The data type TCHAR specifies strings on the API is an alias of char(ANSI/OEM) or WCHAR(UTF-16). For more information, refer to the description in the file name.

    -
    +
    +

    exFAT File System

    +

    The exFAT (Microsoft's Extended File Allocation Table) file system is a replacement of the FAT file system which has been widely used in the embedded systems and consumer devices. It is adopted by SDA (SD Association) as a recommended file system for high capacity SD cards (>32GB) and they are being shipped with this format, so that the exFAT will soon become one of the standard file systems for removable media.

    +

    The exFAT file system allows the file size larger than 4 GiB limit what FAT file system allows upto and some file system overhead, especially file allocation delay, are reduced as well. This feature improves the write throughput to the file. However a problem on the current implementation of FatFs is that write throughput at writing to the growing edge of the fragmented file gets less than the throughput on the FAT volume. Pre-allocating a contiguous block with f_expand function may be a workaround of this problem.

    +

    Note that the exFAT is a patent of Microsoft Corporation. The exFAT function of FatFs is an implementation based on US. Pat. App. Pub. No. 2009/0164440 A1. FatFs module can swich the exFAT on/off by configuration option. When enable the exFAT on the commercial products, you will need to be licensed by Microsoft depends on the final destination of the products.

    +

    Remark: Enabling exFAT discards C89 compatibility because of need for 64-bit integer type.

    + +

    Re-entrancy

    -

    The file operations to the different volume is always re-entrant and can work simultaneously. The file operations to the same volume is not re-entrant but it can also be configured to thread-safe by _FS_REENTRANT option. In this case, also the OS dependent synchronization object control functions, ff_cre_syncobj(), ff_del_syncobj(), ff_req_grant() and ff_rel_grant() must be added to the project. There are some examples in the option/syscall.c.

    -

    When a file function is called while the volume is in use by any other task, the file function is suspended until that task leaves the file function. If wait time exceeded a period defined by _TIMEOUT, the file function will abort with FR_TIMEOUT. The timeout feature might not be supported by some RTOS.

    -

    There is an exception for f_mount(), f_mkfs(), f_fdisk() function. These functions are not re-entrant to the same volume or corresponding physical drive. When use these functions, all other tasks must unmount the volume and avoid to access the volume.

    -

    Note that this section describes on the re-entrancy of the FatFs module itself but also the low level disk I/O layer will need to be re-entrant.

    +

    The file operations to the different volume is always re-entrant regardless of configurations except when LFN enabled with static working buffer. 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 thread-safe by option _FS_REENTRANT. 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 the option/syscall.c.

    +

    When a file function is called while the volume is being accessed by 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 function might not be supported on the some RTOSs.

    +

    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, other tasks need to avoid to access the volume.

    +

    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, only disk_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.

    -
    +

    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 and 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 fail with FR_LOCKED. If number of open objects, files and sub-directories, is equal to _FS_LOCK, an extra f_open(), f_optndir() function will fail with FR_TOO_MANY_OPEN_FILES.

    +

    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 by f_read() function.

    +

    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 by f_read function.

    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.

    -

    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 with disk_read() function at a time but the multiple sector transfer is divided at cluster boundary even if it is contiguous.

    +

    The file I/O buffer is a sector buffer to read/write a part of 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.

    +

    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 with disk_read function at a time but the multiple sector transfer is divided at cluster boundary even if it is contiguous.

    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.

    -
    +

    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
    -fig.6 +fig.6
    -

    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. 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. The number of write transactions also affects the life time of 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 disk 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.

    +

    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 operation.

    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.

    +

    When remove a file with f_unlink 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 can be erased on removing the file, those data blocks will be turned into 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 function by setting _USE_TRIM to 1. Note that this is an expectation of internal process of the storage device and not that always effective. Most applications will not need this function. Also f_unlink function can take a time when remove a large file.

    -
    +

    Critical Section

    -

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

    +

    If a write operation to the FAT volume is interrupted due to an 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.

    Figure 4. Long critical section
    -fig.4 +fig.4
    Figure 5. Minimized critical section
    -fig.5 +fig.5

    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.

    @@ -234,42 +236,47 @@ Figure 5. Minimized critical section
  • The file created as new or overwritten remains but no content.
  • 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 using f_sync() function as shown in Figure 5.

    +

    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 using f_sync function as shown in Figure 5.

    -
    +

    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. -
    2. Empty a directory
      3. -
    3. Allocate contiguous area to the file
      4. -
    4. Function/Compatible checker for low level disk I/O module
      5. -
    5. FAT image creator
      6. +
    6. Open or create a file for append (for only R0.12 and earlier)
      7. +
    7. Empty a directory
      8. +
    8. Allocate contiguous area to the file (for only R0.11a and earlier)
      9. +
    9. Compatibility checker for low level disk I/O module
      10. +
    10. FAT image creator
    -
    +

    About FatFs License

    -

    FatFs has being developped as a personal project of 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.10b                    (C)ChaN, 2014
+
    FatFs has being developped as a personal project of the author, ChaN. It is free from the code anyone else wrote at current release. Following code block shows a copy of the FatFs license document that included in the source files.
    
+
    +/*----------------------------------------------------------------------------/
+/  FatFs - Generic FAT file system module  R0.12a                             /
 /-----------------------------------------------------------------------------/
-/ FatFs module is a generic FAT file system module for small embedded systems.
-/ This is a free software that opened for education, research and commercial
-/ developments under license policy of following trems.
 /
-/  Copyright (C) 2014, ChaN, all right reserved.
+/ Copyright (C) 2016, ChaN, all right reserved.
 /
-/ * The FatFs module is a free software and there is NO WARRANTY.
-/ * No restriction on use. You can use, modify and redistribute it for
-/   personal, non-profit or commercial products UNDER YOUR RESPONSIBILITY.
-/ * Redistributions of source code must retain the above copyright notice.
+/ FatFs module is an open source software. Redistribution and use of FatFs in
+/ source and binary forms, with or without modification, are permitted provided
+/ that the following condition is met:
+
+/ 1. Redistributions of source code must retain the above copyright notice,
+/    this condition and the following disclaimer.
 /
-/-----------------------------------------------------------------------------/
    
-
    Therefore FatFs license is one of the BSD-style licenses but there is a significant feature. Because FatFs is mainly intended for embedded projects, the redistributions in binary form, such as embedded code or any forms without source code, need not to explain about FatFs in order to extend usability for commercial products. The documentation of the distributions need not include about FatFs and its license documents, and it may also. This is equivalent to the BSD 1-Clause License. Of course FatFs is compatible with the projects under GNU GPL. When redistribute the FatFs with any modification or branch it as a fork, the license can also be changed to GNU GPL, BSD-style license or any free software licenses that not conflict with FatFs license.
    
+/ 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, binary library and any forms without source code, does not need to include about 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 changes 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.

    -

    Return

    +

    Return Home