FatFs R0.12a, released July 10, 2016

doc/en/appnote.html

@@ -42,9 +42,9 @@ The FatFs module assumes that size of <tt>char</tt>/<tt>short</tt>/<tt>long</tt>
 
 <h4>System organizations</h4>
 <p>The dependency diagram shown below is a typical but not specific configuration of the embedded system with FatFs module.</p>
-<p><img src="../img/modules.png" width="580" height="280" alt="dependency diagram"></p>
+<p><img src="../res/modules.png" width="580" height="280" alt="dependency diagram"></p>
 <p>(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.</p>
-<p><img src="../img/funcs.png" width="750" height="420" alt="functional diagram"></p>
+<p><img src="../res/funcs.png" width="750" height="420" alt="functional diagram"></p>
 
 <h4>Which function is required?</h4>
 <p>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.</p>
@@ -69,7 +69,7 @@ The FatFs module assumes that size of <tt>char</tt>/<tt>short</tt>/<tt>long</tt>
 <li>Number of volumes: Upto 10.</li>
 <li>Volume size: Upto 2 TiB at 512 bytes/sector.</li>
 <li>File size: Upto 4 GiB - 1 on FAT volume and virtually unlimited on exFAT volume.</li>
-<li>Cluster size: Upto 128 sector on FAT volume, upto 32768 sectors on exFAT volume.</li>
+<li>Cluster size: Upto 128 sectors on FAT volume and upto 16 MiB on exFAT volume.</li>
 <li>Sector size: 512, 1024, 2048 and 4096 bytes.</li>
 </ul>
 </div>
@@ -144,7 +144,7 @@ And any other options are left unchanged from original setting.
 
 <div class="para doc" id="lfn">
 <h3>Long File Name</h3>
-<p>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 <tt>f_readdir</tt> function. The support for LFN is disabled by default. To enable the LFN, set <tt><a href="config.html#use_lfn">_USE_LFN</a></tt> to 1, 2 or 3, and add <tt>option/unicode.c</tt> to the project. The LFN requiers a certain working buffer in addition. The buffer size can be configured by <tt><a href="config.html#max_lfn">_MAX_LFN</a></tt> according to the available memory. The length of an LFN will be up to 255 characters, so that the <tt>_MAX_LFN</tt> 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 <tt>FR_INVALID_NAME</tt>. When use any re-entry to the API with LFN is enabled, <tt>_USE_LFN</tt> 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 <tt>(_MAX_LFN + 1) * 2</tt> bytes.</p>
+<p>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 <tt>f_readdir</tt> function. The support for LFN is disabled by default. To enable the LFN, set <tt><a href="config.html#use_lfn">_USE_LFN</a></tt> to 1, 2 or 3, and add <tt>option/unicode.c</tt> to the project. The LFN requiers a certain working buffer in addition. The buffer size can be configured by <tt><a href="config.html#max_lfn">_MAX_LFN</a></tt> according to the available memory. The length of an LFN will be up to 255 characters, so that the <tt>_MAX_LFN</tt> 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 <tt>FR_INVALID_NAME</tt>. When use any re-entry to the API with LFN is enabled, <tt>_USE_LFN</tt> 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 <tt>(_MAX_LFN + 1) * 2</tt> bytes and additional 608 bytes when exFAT enabled.</p>
 <table class="lst2 rset">
 <caption>With LFN at CM3+gcc</caption>
 <tr><th><tt>_CODE_PAGE</tt></th><th>Code size</th></tr>
@@ -166,9 +166,9 @@ And any other options are left unchanged from original setting.
 <div class="para doc" id="exfat">
 <h3>exFAT File System</h3>
 <p>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 (&gt;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.</p>
-<p>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 on the fragmented file with extension of size gets less than the throughput on the FAT volume. Pre-allocating a contiguous block with <tt>f_expand</tt> function may be a workaround of this problem.</p>
+<p>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 <tt>f_expand</tt> function may be a workaround of this problem.</p>
 <p>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 or 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.</p></div>
-<p><em>Remark: Enabling exFAT discards C89 compatibility due to need for 64-bit integer type.</em></p>
+<p><em>Remark: Enabling exFAT discards C89 compatibility because of need for 64-bit integer type.</em></p>
 
 <div class="para doc" id="reentrant">
 <h3>Re-entrancy</h3>
@@ -189,13 +189,13 @@ And any other options are left unchanged from original setting.
 <h3>Performance Effective File Access</h3>
 <p>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 <tt>f_read</tt> function.</p>
 <p>Figure 1. Sector misaligned read (short)<br>
-<img src="../img/f1.png" width="490" height="110" alt="">
+<img src="../res/f1.png" width="490" height="110" alt="">
 </p>
 <p>Figure 2. Sector misaligned read (long)<br>
-<img src="../img/f2.png" width="490" height="140" alt="">
+<img src="../res/f2.png" width="490" height="140" alt="">
 </p>
 <p>Figure 3. Fully sector aligned read<br>
-<img src="../img/f3.png" width="490" height="119" alt="">
+<img src="../res/f3.png" width="490" height="119" alt="">
 </p>
 <p>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 <tt><a href="config.html#fs_tiny">_FS_TINY</a></tt> determins which sector buffer is used for the file data transfer. When tiny buffer configuration (1) is selected, data memory consumption is reduced <tt>_MAX_SS</tt> 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.</p>
 <p>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 <tt>disk_read</tt> function at a time but the multiple sector transfer is divided at cluster boundary even if it is contiguous.</p>
@@ -208,12 +208,12 @@ And any other options are left unchanged from original setting.
 <h4>Using Mutiple-Sector Write</h4>
 <div class="rset">
 Figure 6. Comparison between Multiple/Single Sector Write<br>
-<img src="../img/f6.png" width="630" height="148" alt="fig.6">
+<img src="../res/f6.png" width="630" height="148" alt="fig.6">
 </div>
-<p>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. <a href="../img/rwtest2.png">This graph</a> 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.</p>
+<p>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. <a href="../res/rwtest2.png">This graph</a> 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.</p>
 <p>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. </p>
 <h4>Forcing Memory Erase</h4>
-<p>When remove a file with <tt>f_remove</tt> 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 function by setting <tt><a href="config.html#use_trim">_USE_TRIM</a></tt> to 1. Note that this is an expectation of internal process of the flash memory storage and not that always effective. Also <tt>f_remove</tt> function will take a time when remove a large file. Most applications will not need this function.</p>
+<p>When remove a file with <tt>f_unlink</tt> 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 <tt><a href="config.html#use_trim">_USE_TRIM</a></tt> 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 <tt>f_unlink</tt> function can take a time when remove a large file.</p>
 </div>
 
 <div class="para doc" id="critical">
@@ -221,11 +221,11 @@ Figure 6. Comparison between Multiple/Single Sector Write<br>
 <p>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.</p>
 <div class="lset">
 Figure 4. Long critical section<br>
-<img src="../img/f4.png" width="320" height="436" alt="fig.4">
+<img src="../res/f4.png" width="320" height="436" alt="fig.4">
 </div>
 <div class="lset">
 Figure 5. Minimized critical section<br>
-<img src="../img/f5.png" width="320" height="436" alt="fig.5">
+<img src="../res/f5.png" width="320" height="436" alt="fig.5">
 </div>
 <br class="clr">
 <p>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.</p>
@@ -243,11 +243,11 @@ Figure 5. Minimized critical section<br>
 <h3>Extended Use of FatFs API</h3>
 <p>These are examples of extended use of FatFs APIs. New item will be added whenever a useful code is found.</p>
 <ol>
-<li><a href="../img/app1.c">Open or create a file for append</a></li>
-<li><a href="../img/app2.c">Empty a directory</a></li>
-<li><a href="../img/app3.c">Allocate contiguous area to the file</a> (R0.11a and older)</li>
-<li><a href="../img/app4.c">Function/Compatible checker for low level disk I/O module</a></li>
-<li><a href="../img/mkfatimg.zip">FAT image creator</a></li>
+<li><a href="../res/app1.c">Open or create a file for append</a> (for R0.12 and older)</li>
+<li><a href="../res/app2.c">Empty a directory</a></li>
+<li><a href="../res/app3.c">Allocate contiguous area to the file</a> (for R0.11a and older)</li>
+<li><a href="../res/app4.c">Function/compatibility checker for low level disk I/O module</a></li>
+<li><a href="../res/mkfatimg.zip">FAT image creator</a></li>
 </ol>
 </div>
 
@@ -256,13 +256,15 @@ Figure 5. Minimized critical section<br>
 <p>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.</p>
 <pre>
 /*----------------------------------------------------------------------------/
-/  FatFs - FAT file system module  R0.12                 (C)ChaN, 2016
+/  FatFs - Generic FAT file system module  R0.12a                             /
 /-----------------------------------------------------------------------------/
-/ FatFs module is a free software that opened under license policy of
-/ following conditions.
 /
 / Copyright (C) 2016, ChaN, all right reserved.
 /
+/ 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.
 /
@@ -272,7 +274,7 @@ Figure 5. Minimized critical section<br>
 / by use of this software.
 /----------------------------------------------------------------------------*/
 </pre>
-<p>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.</p>
+<p>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.</p>
 </div>
 
 <p class="foot"><a href="../00index_e.html">Return Home</a></p>