X-Git-Url: http://cloudbase.mooo.com/gitweb/z180-stamp.git/blobdiff_plain/3531528ecedde37d5ebc67a330d192565290175a..05437fb4cdb907816a4fc3ffafa2617fcf33266a:/fatfs/doc/en/appnote.html diff --git a/fatfs/doc/en/appnote.html b/fatfs/doc/en/appnote.html index 7f5ad89..fee2af9 100644 --- a/fatfs/doc/en/appnote.html +++ b/fatfs/doc/en/appnote.html @@ -54,7 +54,7 @@ The FatFs module assumes that size of char/short/long are 8/16/32 bit and int is 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_ERASE_SECTOR)_USE_ERASE == 1 +disk_ioctl (CTRL_TRIM)_USE_TRIM == 1 ff_convert
ff_wtoupper_USE_LFN >= 1Unicode support functions.
Available in option/unicode.c. 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 @@ -98,7 +98,7 @@ _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) +_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) @@ -151,17 +151,17 @@ _FS_LOCK 0 (Disable file lock control)

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

+

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.

- +
LFN cfg on ARM7TDMI
Code pageProgram size
SBCS+3.7K
932(Shift-JIS)+62K
932(Shift_JIS)+62K
936(GBK)+177K
949(Korean)+139K
950(Big5)+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 that 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.

+

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.

@@ -181,7 +181,7 @@ _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 objects, files and sub-directories, gets larger than _FS_LOCK, the f_open(), f_optndir() 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.

@@ -196,7 +196,7 @@ _FS_LOCK 0 (Disable file lock control)

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.

+

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.

@@ -211,7 +211,7 @@ 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. 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, 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.

+

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.

@@ -267,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 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 folk, 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 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.

Return