The FatFs module has started to support long file name (LFN) at revision 0.07. The two different file names, SFN and LFN, of a file is transparent in the file functions except for f_readdir function. To enable LFN feature, set _USE_LFN to 1, 2 or 3, and add a Unicode code conversion function ff_convert() and ff_wtoupper() to the project. The LFN feature requiers a certain working buffer in addition. The buffer size can be configured by _MAX_LFN corresponding to the available memory size. The size of long file name 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 given file name, the file function fails with FR_INVALID_NAME. When enable the LFN feature with re-entrant 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 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 with 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.
LFN cfg on ARM7TDMI
| Code page | Program size |
|---|
@@ -167,13 +167,13 @@ _FS_LOCK 0 (Disable file lock control)
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 (_LFN_UNICODE). This means 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 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.
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 with _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.
-
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 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.
+
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.
@@ -181,37 +181,37 @@ _FS_LOCK 0 (Disable file lock control)
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 also be available by _FS_LOCK option. The value 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 files and sub-directories gets larger than _FS_LOCK, the open function will fail with FR_TOO_MANY_OPEN_FILES.
+
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.
Performance Effective File Access
-
For good performance to read/write files on the small embedded system, 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 miss-aligned read (short)
+
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 miss-aligned read (long)
+
Figure 2. Sector misaligned read (long)
-
Figure 3. Sector aligned read
+
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 (1) is selected, data memory consumption is reduced 512 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 mis-aligned part of the file, is transferred via the file I/O buffer. On 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 never across the cluster boundary even if it is contiguous.
-
Therefore taking effort to sector aligned read/write accesss avoids 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.
+
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.
+
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 and CFC, it must be controlled in consideration of its characteristitcs.
+
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 and it increases proportional to the number of sectors per a write transaction. This effect more appers at more fast bus clock and its ratio often becomes grater than ten. The number of write transaction also affects the life time of the media. Therefore the application program should write the data in large block as possible. The ideal block size is cluster size or power of 2 bytes and the byte offset should be aligned to the block. Of course all layers between the application and the media must support multiple sector write feature, however most of open-source disk drivers lack it. Do not split a multiple sector write request into single sector writes 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. 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.
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, the number of free blocks on the flash memory will be increased. This may skip internal block erase operation to the data block on next write. As the result the write performance might be improved. To enable this feature, set _USE_ERASE to 1. Note that this is a feature with expectation of internal process of the flash memory media. It may not always effective and f_remove() function will take a time to remove a large file. Most applications will not need this feature.
+
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_ERASE 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.
@@ -252,7 +253,7 @@ Figure 5. Minimized critical section
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.10a (C)ChaN, 2014
+/ FatFs - FAT file system module R0.10b (C)ChaN, 2014
/-----------------------------------------------------------------------------/
/ 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
@@ -266,7 +267,7 @@ Figure 5. Minimized critical section
/ * Redistributions of source code must retain the above copyright notice.
/
/-----------------------------------------------------------------------------/
-Therefore FatFs license is one of the BSD-style licenses but there is a significant feature. Because FatFs is for embedded projects, the conditions of redistributions in binary form, such as embedded code, hex file, binary library and any form without source code, are not specified in order to extend usability to commercial use. The documentation of the distributions need not include about FatFs and its license document, 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, the license can also be changed to GNU GPL or BSD-style license.
+Therefore FatFs license is one of the BSD-style licenses but there is a significant feature. Because FatFs is for embedded projects, the conditions of redistributions in binary form, such as embedded code, hex file, binary library or any forms without source code, are not specified in order to extend usability for commercial products. The documentation of the distributions need not include about FatFs and its license document, 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.
diff --git a/doc/en/close.html b/doc/en/close.html
index 3f8ef52..0746700 100644
--- a/doc/en/close.html
+++ b/doc/en/close.html
@@ -46,7 +46,7 @@ FRESULT f_close (
Description
The f_close() function closes an open file object. If any data has been written to the file, the cached information of the file is written back to the volume. After the function succeeded, the file object is no longer valid and it can be discarded.
-
Note that if the file object is in read-only mode and _FS_LOCK option is not enabled, the file object can also be discarded without this process. However it is not recommended for future compatibility.
+
Note that if the file object is in read-only mode and _FS_LOCK option is not enabled, the file object can also be discarded without this process. However this is not recommended for future compatibility.
diff --git a/doc/en/closedir.html b/doc/en/closedir.html
index 5186496..05ef6f6 100644
--- a/doc/en/closedir.html
+++ b/doc/en/closedir.html
@@ -44,7 +44,7 @@ FRESULT f_closedir (
Description
The f_closedir() function closes an open directory object. After the function succeeded, the directory object is no longer valid and it can be discarded.
-
Note that the directory object can also be discarded without this process if _FS_LOCK option is not enabled. However it is not recommended for future compatibility.
+
Note that the directory object can also be discarded without this process if _FS_LOCK option is not enabled. However this is not recommended for future compatibility.
diff --git a/doc/en/dinit.html b/doc/en/dinit.html
index 709c7d0..4675dd9 100644
--- a/doc/en/dinit.html
+++ b/doc/en/dinit.html
@@ -13,7 +13,7 @@
disk_initialize
-
The disk_initialize function initializes the disk drive.
+
The disk_initialize function initializes the storage device.
DSTATUS disk_initialize (
BYTE pdrv /* [IN] Physical drive number */
@@ -25,7 +25,7 @@ DSTATUS disk_initialize (
Parameter
- pdrv
-- Specifies the physical drive number to initialize.
+- Physical drive number to identify the target device.
@@ -37,8 +37,8 @@ DSTATUS disk_initialize (
Description
-
This function initializes a physical drive and put it ready to generic read/write data. When the function succeeded, STA_NOINIT flag in the return value is cleared.
-
Application program MUST NOT call this function, or FAT structure on the volume can be broken. To re-initialize the file system, use f_mount() function instead. This function is called on volume mount process by FatFs module to manage the media change.
+
This function initializes a storage device and put it ready to generic read/write data. When the function succeeded, STA_NOINIT flag in the return value is cleared.
+
Application program MUST NOT call this function, or FAT structure on the volume can be broken. To re-initialize the file system, use f_mount() function instead. This function is called at volume mount process by FatFs module to manage the media change.
diff --git a/doc/en/dioctl.html b/doc/en/dioctl.html
index 808a741..fec70c8 100644
--- a/doc/en/dioctl.html
+++ b/doc/en/dioctl.html
@@ -53,23 +53,38 @@ DRESULT disk_ioctl (
Description
-
The FatFs module uses only device independent commands described below. Any device dependent functions and user defined functions are not used.
+
The FatFs module requires only five device independent commands described below.
+Standard ioctl command used by FatFs
| Command | Description |
|---|
-| CTRL_SYNC | Make sure that the device has finished pending write process. If the disk I/O module has a write back cache, the dirty buffers must be written back to the media immediately. If each write operation to the media is completed within the disk_write() function, nothing to do for this command. |
-| GET_SECTOR_COUNT | Returns number of available sectors on the drive into the DWORD variable pointed by buff. This command is used by only f_mkfs() and f_fdisk() function to determine the volume/partition size to be created. |
-| GET_SECTOR_SIZE | Returns sector size of the media into the WORD variable pointed by buff. Valid return values of this command are 512, 1024, 2048 or 4096. This command is never used at fixed sector size configuration, _MAX_SS == _MIN_SS, and it must work at that sector size. |
-| GET_BLOCK_SIZE | Returns erase block size of the flash memory in unit of sector into the DWORD variable pointed by buff. The allowable value is from 1 to 32768 in power of 2. Return 1 if the erase block size is unknown or disk media. This command is used by only f_mkfs() function and it attempts to align data area to the erase block boundary. |
-| CTRL_ERASE_SECTOR | Erases a part of the flash memory specified by a DWORD array {<start sector>, <end sector>} pointed by buff. This is similar command to Trim command of ATA device. When this feature is not supported or not a flash memory media, nothing to do for this command. The FatFs does not check the result code and the file function is not affected even if the sectors ware not erased well. This command is called on removing a cluster chain and f_mkfs() function when _USE_ERASE is 1. |
+| CTRL_SYNC | Make sure that the device has finished pending write process. If the disk I/O module has a write back cache, the dirty buffers must be written back to the media immediately. Nothing to do for this command if each write operation to the media is completed within the disk_write() function. Required at _FS_READONLY == 0. |
+| GET_SECTOR_COUNT | Returns number of available sectors on the drive into the DWORD variable pointed by buff. This command is used by only f_mkfs() and f_fdisk() function to determine the volume/partition size to be created. Required at _USE_MKFS == 1 or _MULTI_PARTITION == 1. |
+| GET_SECTOR_SIZE | Returns sector size of the media into the WORD variable pointed by buff. Valid return values of this command are 512, 1024, 2048 or 4096. This command is required at variable sector size configuration, _MAX_SS > _MIN_SS. Never used at fixed sector size configuration, _MAX_SS == _MIN_SS, and it must work at that sector size. |
+| GET_BLOCK_SIZE | Returns erase block size of the flash memory in unit of sector into the DWORD variable pointed by buff. The allowable value is from 1 to 32768 in power of 2. Return 1 if the erase block size is unknown or disk media. This command is used by only f_mkfs() function and it attempts to align data area to the erase block boundary. Required at _USE_MKFS == 1. |
+| CTRL_ERASE_SECTOR | Informs device that the data on the block of sectors specified by a DWORD array {<start sector>, <end sector>} pointed by buff is no longer needed and may be erased. The device would force erased the memory block. This is a command similar to Trim command of ATA device. When this feature is not supported or not a flash memory media, nothing to do for this command. The FatFs does not check the result code and the file function is not affected even if the sectors ware not erased well. This command is called on removing a cluster chain and f_mkfs() function. Required at _USE_ERASE == 1. |
+
+
+
FatFs never uses any device dependent command and user defined command. Following table shows an example of non-standard commands usable for some applications.
+
+Example of optional ioctl command
+| Command | Description |
|---|
+| CTRL_FORMAT | Create a physical format on the media. If buff is not null, it is pointer to the call-back function for progress notification. |
+| CTRL_POWER_IDLE | Put the device idle state. STA_NOINIT in status flag may not be set if the device would go active state by generic read/write function. |
+| CTRL_POWER_OFF | Put the device off state. Shut-down the power to the device and deinitialize the device interface if needed. STA_NOINIT in status flag must be set. The device goes active state by disk_initialize() function. |
+| CTRL_LOCK | Lock media eject mechanism. |
+| CTRL_UNLOCK | Unlock media eject mechanism. |
+| CTRL_EJECT | Eject media cartridge. STA_NOINIT and STA_NODISK in status flag are set after the function succeeded. |
+| MMC_GET_TYPE | Get card type. The type flags, bit0:MMCv3, bit1:SDv1, bit2:SDv2+ and bit3:LBA, is stored to a BYTE variable pointed by buff. (MMC/SDC specific command) |
+| MMC_GET_CSD | Get CSD register into a 16-byte buffer pointed by buff. (MMC/SDC specific command) |
+| MMC_GET_CID | Get CID register into a 16-byte buffer pointed by buff. (MMC/SDC specific command) |
+| MMC_GET_OCR | Get OCR register into a 4-byte buffer pointed by buff. (MMC/SDC specific command) |
+| MMC_GET_SDSTAT | Get SDSTATUS register into a 64-byte buffer pointed by buff. (SDC specific command) |
+| ATA_GET_REV | Get the revision string into a 16-byte buffer pointed by buff. (ATA/CFC specific command) |
+| ATA_GET_MODEL | Get the model string into a 40-byte buffer pointed by buff. (ATA/CFC specific command) |
+| ATA_GET_SN | Get the serial number string into a 20-byte buffer pointed by buff. (ATA/CFC specific command) |
-
-
QuickInfo
-
This function is not needed when _FS_READONLY == 1 and _MAX_SS == _MIN_SS.
-
-
