diff --git a/README.OpenSource b/README.OpenSource index d9803a9..fdc3646 100644 --- a/README.OpenSource +++ b/README.OpenSource @@ -3,7 +3,7 @@ "Name" : "FatFs", "License" : "BSD 3-Clause License", "License File" : "LICENSE.txt", - "Version Number" : "R0.15", + "Version Number" : "R0.15a", "Owner" : "yesiyuan2@huawei.com", "Upstream URL" : "http://elm-chan.org/fsw/ff/00index_e.html", "Description" : "FatFs is a generic FAT/exFAT filesystem module for small embedded systems. The FatFs module is written in compliance with ANSI C (C89) and completely separated from the disk I/O layer. Therefore it is independent of the platform. It can be incorporated into small microcontrollers with limited resource, such as 8051, PIC, AVR, ARM, Z80, RX and etc. Also Petit FatFs module for tiny microcontrollers is available here." diff --git a/documents/00index_e.html b/documents/00index_e.html index b3b8adb..c385601 100644 --- a/documents/00index_e.html +++ b/documents/00index_e.html @@ -17,7 +17,7 @@
layer -

FatFs is a generic FAT/exFAT filesystem module for small embedded systems. The FatFs module is written in compliance with ANSI C (C89) and completely separated from the disk I/O layer. Therefore it is independent of the platform. It can be incorporated into small microcontrollers with limited resource, such as 8051, PIC, AVR, ARM, Z80, RX and etc. Also Petit FatFs module for tiny microcontrollers is available here.

+

FatFs is a generic FAT/exFAT filesystem module for small embedded systems. The FatFs module is written in compliance with ANSI C (C89) and completely separated from the disk control layer. Therefore it is independent of the platforms and storage devices. It can be incorporated into small microcontrollers with limited resource, such as 8051, PIC, AVR, ARM, Z80, RX and etc. Also Petit FatFs module for tiny microcontrollers is available here.

Features

+ +
+

Unicode API

+

By default, FatFs uses ANSI/OEM code set on the API even in LFN configuration. FatFs can also switch the character encoding on the API to Unicode by configuration option FF_LFN_UNICODE. This means that FatFs is compliant with the full featured LFN specification. The data type TCHAR specifies path name strings on the API is an alias of either char(ANSI/OEM or UTF-8), WCHAR(UTF-16) or DWORD(UTF-32) depends on that option. For more information, refer to the description in the file name.

+

Note that setting of code page, FF_CODE_PAGE, has actually no meaning when FatFs is configured for the Unicode API. It should be set 437 to reduce the module size. However it still affects code conversion of string I/O functions when FF_STRF_ENCODE == 0, and also backward compatibility with legacy systems. In this case, the code page may need to be configured properly if it is considered a problem.

+
+ +
+

exFAT Filesystem

+

The exFAT (Microsoft's Extended File Allocation Table) filesystem is a succession of the FAT/FAT32 filesystem which has been widely used in embedded systems, consumer devices and portable storage media. It is adopted by SDA (SD Association) as the filesystem for SDXC card, 64 GB and larger, and they are being shipped with this format. Therefore the exFAT is one of the standard filesystems for removable media as well as FAT. The exFAT filesystem allows the file size beyond the 4 GB limit what FAT filesystem allows up to and some filesystem overhead, especially cluster allocation delay, are reduced as well. These features allow to record the large data without dividing into some files and improve the write throughput to the file.

+

Note that the exFAT filesystem is a patent of Microsoft Corporation. The exFAT feature of FatFs is an implementation based on US. Pat. App. Pub. No. 2009/0164440 A1. FatFs module can switch the exFAT on or off by a configuration option, FF_FS_EXFAT. When enable the exFAT for the commercial products, a license by Microsoft will be needed depends on the final destination of the products.

+

Remarks: Enabling exFAT discards C89 compatibility and it wants C99 because of need for 64-bit integer type.

+
+ +
+

64-bit LBA

+

LBA (Logical Block Addressing) is an addressing method to specify the location of data block, called sector, on the storage media. It is a simple linear address beginning from 0 as the first sector, 1 as the second sector and so on. The host system does not need to consider how the data block is located and managed in the storage device. FatFs supports only LBA for the media access. 32-bit LBA is a common size in the most LBA scheme. It can address up to 232 sectors, 2 TB in 512 bytes/sector. When a storage device larger than 2 TB is used, larger sector size or 64-bit LBA will be needed to address the entire sectors of the storage device.

+

By default, FatFs works in 32-bit LBA for media access. FatFs can also switch it to 64-bit LBA by a configuration option FF_LBA64. It also enables GPT (GUID Partition Table) for partiotion management on the storage device. For further information about GPT, refer to f_mkfs and f_fdisk function.

+
+ +
+

Re-entrancy

+

The file operations of two tasks to the different volumes each other is always re-entrant and it can work concurrently without any mutual exclusion regardless of the configurations except when LFN is enabled with static working buffer (FF_USE_LFN = 1).

+

The file operations of two tasks to the same volume is not thread-safe by default. FatFs can also be configured to make it thread-safe by an option FF_FS_REENTRANT. When a file function is called while the volume is being accessed by another 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 FF_TIMEOUT, the file function will abort with FR_TIMEOUT. The timeout feature might not be supported on the some OSs. To enable this feature, OS dependent synchronization control functions, ff_mutex_create/ff_mutex_delete/ff_mutex_take/ff_mutex_give, need to be added to the project. There is an example code in the ffsystem.c for some OSs.

+

Note that there is an exception on the re-entrancy for f_mount and f_mkfs function. You will know why it is. These volume management functions are always not thread-safe to the volume being processed. When use these functions, other tasks need to avoid to access the corresponding volume.

+
+ + + + + + + + +
FunctionCase 1Case 2Case 3
disk_statusYesYesYes(*)
disk_initializeNoYesYes(*)
disk_readNoYesYes(*)
disk_writeNoYesYes(*)
disk_ioctlNoYesYes(*)
get_fattimeNoYesYes
+ +Case 1: Same volume.
+Case 2: Different volume on the same drive.
+Case 3: Different volume on the different drive.
+(*) In only different drive number. + +
+

Remarks: This section describes on the re-entrancy of the FatFs module itself. The FF_FS_REENTRANT option enables only exclusive use of each filesystem objects and FatFs does not that prevent to re-enter the storage device control functions. Thus the device control layer needs to be always thread-safe when FatFs API is re-entered for different volumes. Right table shows which control function can be re-entered when FatFs API is re-entered on some conditions.

+
+ +
+

Duplicated File Open

+

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

+

The file lock control can be enabled by FF_FS_LOCK option. The value of option defines the number of open objects to manage simultaneously. In this case, if any opening, renaming or removing against the file shareing rule that described above is attempted, the file function will be rejected with FR_LOCKED. If number of open objects, files and sub-directories, is equal to FF_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.

+

Figure 1. Sector unaligned read (short)
+ +

+

Figure 2. Sector unaligned read (long)
+ +

+

Figure 3. Fully sector aligned read
+ +

+

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 filesystem object. The buffer configuration option FF_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 FF_MAX_SS bytes each file object. In this case, FatFs module uses only a sector buffer in the filesystem 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 unaligned 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 +
+

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 result 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_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 FF_USE_TRIM to 1. Note that because this effect is from an expectation of internal process of the storage device, it is 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 an accidental failure, such as sudden blackout, wrong 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 +
+
+Figure 5. Minimized critical section
+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.

+ +

Each case does not affect any file 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.

+
+ +
+

Various Usable Functions for FatFs Projects

+

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

+
    +
  1. Open or Create File for Append (superseded by FA_OPEN_APPEND flag added at R0.12)
    2. +
  2. Delete Non-empty Sub-directory (for R0.12 and later)
    3. +
  3. Create Contiguous File (superseded by f_expand function added at R0.12)
    4. +
  4. Test if the File is Contiguous or Not
    5. +
  5. Compatibility Checker for Storage Device Control Module
    6. +
  6. Performance Checker for Storage Device Control Module
    7. +
  7. FAT Volume Image Creator (Pre-creating built-in FAT volume)
    8. +
  8. Virtual Drive Feature (refer to lpc176x/ in ffsample.zip)
    9. +
  9. Embedded Unicode String Utilities (OEMxxx→Unicode, Unicode→OEMxxx, Unicode→Unicode)
    10. +
+
+ +
+

About FatFs License

+

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 Filesystem Module  Rx.xx                               /
+/-----------------------------------------------------------------------------/
+/
+/ Copyright (C) 20xx, 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.
+/
+/ 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 of open source software licenses includes 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 license that compatible with FatFs license.

+
+ + +

Return

+ + diff --git a/documents/doc/chdir.html b/documents/doc/chdir.html index 93e116c..a91ab0f 100644 --- a/documents/doc/chdir.html +++ b/documents/doc/chdir.html @@ -3,8 +3,6 @@ - - FatFs - f_chdir @@ -83,6 +81,7 @@ FRESULT f_chdir (

f_chdrive, f_getcwd

+

Return

diff --git a/documents/doc/chdrive.html b/documents/doc/chdrive.html index 4dfc7d8..fd821c4 100644 --- a/documents/doc/chdrive.html +++ b/documents/doc/chdrive.html @@ -3,8 +3,6 @@ - - FatFs - f_chdrive @@ -65,6 +63,7 @@ FRESULT f_chdrive (

f_chdir, f_getcwd

+

Return

diff --git a/documents/doc/chmod.html b/documents/doc/chmod.html index 91e520f..ebc46e8 100644 --- a/documents/doc/chmod.html +++ b/documents/doc/chmod.html @@ -3,8 +3,6 @@ - - FatFs - f_chmod @@ -84,6 +82,7 @@ FRESULT f_chmod ( +

Return

diff --git a/documents/doc/close.html b/documents/doc/close.html index f4cd2df..3fe9827 100644 --- a/documents/doc/close.html +++ b/documents/doc/close.html @@ -3,8 +3,6 @@ - - FatFs - f_close @@ -60,6 +58,7 @@ FRESULT f_close (

f_open, f_read, f_write, f_sync, FIL, FATFS

+

Return

diff --git a/documents/doc/closedir.html b/documents/doc/closedir.html index 3f5df57..bf4febe 100644 --- a/documents/doc/closedir.html +++ b/documents/doc/closedir.html @@ -3,8 +3,6 @@ - - FatFs - f_closedir @@ -59,6 +57,7 @@ FRESULT f_closedir (

f_opendir, f_readdir, DIR

+

Return

diff --git a/documents/doc/config.html b/documents/doc/config.html index 788e075..198a199 100644 --- a/documents/doc/config.html +++ b/documents/doc/config.html @@ -3,8 +3,6 @@ - - FatFs - Configuration Options @@ -105,29 +103,29 @@

Disable (0) or Enable (1) f_forward function.

FF_USE_STRFUNC

-

This option switches string functions, f_gets, f_putc, f_puts and f_printf. These functions are equivalents of regular string stream I/O functions in POSIX. If sprintf is available and code conversion is not needed, f_write with sprintf will be efficient in code size and performance rather than f_printf. When enable this feature, stdarg.h is included in ff.c.

+

This option switches string I/O functions, f_gets, f_putc, f_puts and f_printf. These functions are the equivalents of regular string stream I/O functions in POSIX. If sprintf is available and code conversion is not needed, f_write with sprintf will be efficient in code size and performance better than f_printf. When enable this feature, stdarg.h is included in ff.c.

- - + +
ValueDescription
0Disable string functions.
1Enable string functions without LF-CRLF conversion.
2Enable string functions with LF-CRLF conversion.
1Enable string functions without LF - CRLF conversion.
2Enable string functions with LF - CRLF conversion.

This option switches support for long long integer argument in f_printf.

-

Disable (0) or Enable (1). When enable this feature, C standard needs to be C99 or later.

+

Disable (0) or Enable (1). When enable this feature, C standard needs to be C99 or later. This option has no effect when FF_USE_STRFUNC == 0.

-

This option switches support for floating point argument in f_printf. When enable this feature, C standard needs to be C99 or later and math.h is included in ff.c.

+

This option switches support for floating point argument in f_printf. When enable this feature, C standard needs to be C99 or later and math.h is included in ff.c. This option has no effect when FF_USE_STRFUNC == 0.

- +
ValueDescription
0Disable floating point argument.
1Enable floating point argument in type 'f', 'e' and 'E'.
2Enable it with decimal separator ',' instead of '.'.
2Same as 1 but with decimal separator ',' instead of '.' in output string.

FF_STRF_ENCODE

-

When character encoding on the API is Unicode (FF_LFN_UNICODE >= 1), string I/O functions enabled by FF_USE_STRFUNC convert the character encoding in it. This option defines the assumption of character encoding on the file to be read/written via those functions. When LFN is not enabled or FF_LFN_UNICODE == 0, the string functions work without any code conversion and this option has no effect.

+

When the character encoding on the API is Unicode (FF_LFN_UNICODE >= 1), string I/O functions enabled by FF_USE_STRFUNC convert the character encoding in it. This option defines the assumption of character encoding on the file to be read/written via the string I/O functions. When LFN is not enabled or FF_LFN_UNICODE == 0, the string I/O functions work without any code conversion and this option has no effect.

@@ -228,9 +226,9 @@

This option switches the support for string volume ID. When arbitrary string for the volume ID is enabled for the drive prefix, also pre-defined strings by FF_VOLUME_STRS or user defined strings can be used as drive prefix in the path name. Numeric drive number is always valid regardless of this option, and also either format of drive prefix can be enabled by this option.

ValueCharacter encoding on the file
0ANSI/OEM in current code page
- - - + + +
ValueDescriptionExample
0Only DOS/Windows style drive prefix in numeric ID can be used.1:/filename
1Also DOS/Windows style drive prefix in string ID can be used.flash:/filename
2Also Unix style drive prefix in string ID can be used./flash/filename
0DOS/Windows style drive prefix in numeric ID.1:/filename
10 + DOS/Windows style drive prefix in arbitry string ID.flash:/filename
20 + Unix style drive prefix in arbitry string ID./flash/filename

FF_VOLUME_STRS

@@ -241,7 +239,7 @@ const char* VolumeStr[FF_VOLUMES] = {"ram","flash","sd","usb"};

FF_MULTI_PARTITION

-

Disable (0) or Enable (1). This option switches multi-partition function. By default (0), each logical drive number is bound to the same physical drive number and only a volume in the physical drive is mounted. When enabled, each logical drive is bound to the partition on the physical drive listed in the user defined partition resolution table VolToPart[]. Also f_fdisk funciton will be available. For more information, read here.

+

This option switches multi-partition featuer. By default (0), each logical drive number is bound to the same physical drive number and only one volume found in the physical drive is mounted. When it is enabled (1), each logical drive is bound to the specific partition listed in the user defined partition resolution table VolToPart[]. Also f_fdisk funciton is available to create the arbitrary partitions on the physical drive. For more information, read here.

FF_MIN_SS, FF_MAX_SS

This set of options defines the extent of sector size used for the low level disk I/O interface, disk_read and disk_write function. Valid values are 512, 1024, 2048 and 4096. FF_MIN_SS defines minimum sector size and FF_MAX_SS defines the maximum sector size. Always set both 512 for memory card and harddisk. But a larger value may be required for on-board flash memory and some type of optical media. When FF_MAX_SS > FF_MIN_SS, support of variable sector size is enabled and GET_SECTOR_SIZE command needs to be implemented to the disk_ioctl function.

@@ -299,6 +297,7 @@ const char* VolumeStr[FF_VOLUMES] = {"ram","flash","sd","usb"}; +

Return

diff --git a/documents/doc/dinit.html b/documents/doc/dinit.html index c668c66..688118c 100644 --- a/documents/doc/dinit.html +++ b/documents/doc/dinit.html @@ -3,8 +3,6 @@ - - FatFs - disk_initialize @@ -41,6 +39,7 @@ DSTATUS disk_initialize (

Remarks: This function needs to be under control of FatFs module. Application program MUST NOT call this function while FatFs is in use, or FAT structure on the volume can be broken. To re-initialize the filesystem, use f_mount function instead.

+

Return

diff --git a/documents/doc/dioctl.html b/documents/doc/dioctl.html index fc5f24c..3c45bc9 100644 --- a/documents/doc/dioctl.html +++ b/documents/doc/dioctl.html @@ -3,8 +3,6 @@ - - FatFs - disk_ioctl @@ -58,9 +56,9 @@ DRESULT disk_ioctl ( Standard ioctl command used by FatFs CommandDescription CTRL_SYNCMakes sure that the device has finished pending write process. If the disk I/O layer or storage device has a write-back cache, the dirty cache data must be committed to the medium immediately. Nothing to do for this command if each write operation to the medium is completed in the disk_write function. -GET_SECTOR_COUNTRetrieves number of available sectors, the largest allowable LBA + 1, on the drive into the LBA_t variable that pointed by buff. This command is used by f_mkfs and f_fdisk function to determine the size of volume/partition to be created. It is required when FF_USE_MKFS == 1. -GET_SECTOR_SIZERetrieves sector size, minimum data unit for generic read/write, into the WORD variable that pointed by buff. Valid sector sizes are 512, 1024, 2048 and 4096. This command is required only if FF_MAX_SS > FF_MIN_SS. When FF_MAX_SS == FF_MIN_SS, this command will be never used and the read/write function must work in FF_MAX_SS bytes/sector. -GET_BLOCK_SIZERetrieves erase block size in unit of sector of the flash memory media into the DWORD variable that pointed by buff. The allowable value is 1 to 32768 in power of 2. Return 1 if the value is unknown or non flash memory media. This command is used by only f_mkfs function and it attempts to align data area on the suggested block boundary. It is required when FF_USE_MKFS == 1. Note that FatFs does not have FTL (flash translation layer). Either disk I/O layter or storage device must have an FTL in it. +GET_SECTOR_COUNTRetrieves number of available sectors (the largest allowable LBA + 1) on the drive into the LBA_t variable that pointed by buff. This command is used by f_mkfs and f_fdisk function to determine the size of volume/partition to be created. +GET_SECTOR_SIZERetrieves sector size (minimum data unit for generic read/write) into the WORD variable that pointed by buff. Valid sector sizes are 512, 1024, 2048 and 4096. This command is required only if FF_MAX_SS > FF_MIN_SS. When FF_MAX_SS == FF_MIN_SS, this command will never be used and the disk_read and disk_write function must work in FF_MAX_SS bytes/sector. +GET_BLOCK_SIZERetrieves erase block size in unit of sector of the flash memory media into the DWORD variable that pointed by buff. The allowable value is 1 to 32768 in power of 2. Return 1 if it is unknown or in non flash memory media. This command is used by f_mkfs function with block size not specified and it attempts to align the data area on the suggested block boundary. Note that FatFs does not have FTL (flash translation layer), so that either disk I/O layter or storage device must have an FTL in it. CTRL_TRIMInforms the disk I/O layter or the storage device that the data on the block of sectors is no longer needed and it can be erased. The sector block is specified in an LBA_t array {<Start LBA>, <End LBA>} that pointed by buff. This is an identical command to Trim of ATA device. Nothing to do for this command if this funcion is not supported or not a flash memory device. FatFs does not check the result code and the file function is not affected even if the sector block was not erased well. This command is called on remove a cluster chain and in the f_mkfs function. It is required when FF_USE_TRIM == 1. diff --git a/documents/doc/dread.html b/documents/doc/dread.html index 1be191b..c87c9db 100644 --- a/documents/doc/dread.html +++ b/documents/doc/dread.html @@ -3,8 +3,6 @@ - - FatFs - disk_read diff --git a/documents/doc/dstat.html b/documents/doc/dstat.html index a891489..404ca24 100644 --- a/documents/doc/dstat.html +++ b/documents/doc/dstat.html @@ -3,8 +3,6 @@ - - FatFs - disk_status @@ -43,6 +41,7 @@ DSTATUS disk_status ( +

Return

diff --git a/documents/doc/dwrite.html b/documents/doc/dwrite.html index fef5106..bc2ae0b 100644 --- a/documents/doc/dwrite.html +++ b/documents/doc/dwrite.html @@ -3,8 +3,6 @@ - - FatFs - disk_write @@ -60,7 +58,7 @@ DRESULT disk_write (

Description

The specified memory address is not that always aligned to word boundary because the argument is defined as BYTE*. For more information, refer to the description of disk_read function.

Generally, a multiple sector write request (count > 1) must not be split into single sector transactions to the storage device, or the file write throughput will be drastically decreased.

-

FatFs expects delayed write function of the disk control layer. The write operation to the media does not need to be completed when return from this function by what write operation is in progress or data is only stored into the write-back cache. But write data on the buff is invalid after return from this function. The write completion request is done by CTRL_SYNC command of disk_ioctl function. Therefore, if a delayed write function is implemented, the write throughput of the filesystem will be improved.

+

FatFs expects delayed write function in the disk control layer. The write operation to the media does not need to be completed when return from this function by what write operation is in progress or data is only stored into the write-back cache. The write data on the buff is invalid after return from this function. The write completion request is done by CTRL_SYNC command of disk_ioctl function. Therefore, if a delayed write function is implemented, the write throughput of the filesystem will be improved.

Remarks: Application program MUST NOT call this function, or FAT structure on the volume can be collapsed.

diff --git a/documents/doc/eof.html b/documents/doc/eof.html index efacfbf..549ae4e 100644 --- a/documents/doc/eof.html +++ b/documents/doc/eof.html @@ -3,8 +3,6 @@ - - FatFs - f_eof @@ -57,6 +55,7 @@ int f_eof (

f_open, f_lseek, FIL

+

Return

diff --git a/documents/doc/error.html b/documents/doc/error.html index bee9685..b122dc2 100644 --- a/documents/doc/error.html +++ b/documents/doc/error.html @@ -3,8 +3,6 @@ - - FatFs - f_error @@ -57,6 +55,7 @@ int f_error (

f_open, FIL

+

Return

diff --git a/documents/doc/expand.html b/documents/doc/expand.html index 7620ba9..86a0824 100644 --- a/documents/doc/expand.html +++ b/documents/doc/expand.html @@ -3,8 +3,6 @@ - - FatFs - f_expand @@ -28,7 +26,7 @@ FRESULT f_expand (

Parameters

fp
-
Pointer to the open file object.
+
Pointer to the open file object. If a null pointer is given, the function fails with FR_INVALID_OBJECT.
fsz
Number of bytes in size to prepare or allocate for the file. The data type FSIZE_t is an alias of either DWORD(32-bit) or QWORD(64-bit) depends on the configuration option FF_FS_EXFAT.
opt
@@ -61,7 +59,7 @@ FRESULT f_expand (

When opt is 0, the function finds a contiguous data area and set it as suggested point for next allocation. The subsequent cluster allocation begins at top of the contiguous area found by this function. Thus the file allocation is guaranteed be contiguous and without allocation delay until the file size reaches this size unless any other changes to the volume is performed.

The contiguous file has an advantage for time-critical read/write operations. It eliminates some overheads in the filesystem and the storage device caused by random access for fragmented file.

-

Also the contiguous file can be easily accessed directly via low-level disk functions. However, this is not recommended in consideration of portability and future compatibility. If the file has not been confirmed be contiguous, use this function to examine if the file is contiguous or not.

+

The contiguou files can easily be accessed via low-level disk functions. However, this is not recommended in consideration of portability and future compatibility. If the file has not been confirmed be contiguous, use this function to examine if the file is contiguous or not.

@@ -76,16 +74,16 @@ FRESULT f_expand ( /* Creating a contiguous file */ /* Create a new file */ - res = f_open(fp = malloc(sizeof (FIL)), "file.dat", FA_WRITE|FA_CREATE_ALWAYS); + res = f_open(fp = malloc(sizeof (FIL)), "file.dat", FA_WRITE|FA_CREATE_ALWAYS); if (res) { /* Check if the file has been opened */ free(fp); die("Failed to open the file."); } - /* Alloacte a 100 MiB of contiguous area to the file */ + /* Allocate a 100 MiB of contiguous area to the file */ res = f_expand(fp, 104857600, 1); if (res) { /* Check if the file has been expanded */ - f_close(fp); + f_close(fp); free(fp); die("Failed to allocate contiguous area."); } @@ -101,7 +99,7 @@ FRESULT f_expand ( lba = fp->obj.fs->database + fp->obj.fs->csize * (fp->obj.sclust - 2); /* Write 2048 sectors from top of the file at a time */ - res = disk_write(drv, buffer, lba, 2048); + res = disk_write(drv, data, lba, 2048);
@@ -112,6 +110,7 @@ FRESULT f_expand (

f_open, f_lseek, FIL

+

Return

diff --git a/documents/doc/fattime.html b/documents/doc/fattime.html index 002733a..227c06e 100644 --- a/documents/doc/fattime.html +++ b/documents/doc/fattime.html @@ -3,8 +3,6 @@ - - FatFs - get_fattime diff --git a/documents/doc/fdisk.html b/documents/doc/fdisk.html index d8c40bd..1f0fd49 100644 --- a/documents/doc/fdisk.html +++ b/documents/doc/fdisk.html @@ -3,8 +3,6 @@ - - FatFs - f_fdisk @@ -49,7 +47,7 @@ FRESULT f_fdisk (

Description

-

The f_fdisk function creates partitions on the physical drive. The partitioning format can be in generic MBR or GPT. The partition map table specifies how to divide the physical drive. The first item specifies the size of the first partition and the partitions are located on the drive in order of from the first item. When the value of item is less than or equal to 100, it specifies the partition size in percentage of the entire drive space. When it is larger than 100, it specifies number of sectors. The partition map table is terminated by a zero, no space is remaining for next allocation or 4th partition is created in MBR format. If the specified size is larger than remaining space on the drive, the partition is truncated at end of the drive.

+

The f_fdisk function creates partitions on the physical drive. The partitioning format can be in generic MBR or GPT. The partition map table specifies how to divide the physical drive. The first item specifies the size of the first partition and the partitions are located on the drive in order of from the first item. When the value of item is less than or equal to 100, it specifies the partition size in percentage of the entire drive space. When it is larger than 100, it specifies number of sectors. The partition map table is terminated by a zero, 4th partition in MBR format or no remainin space for next allocation. If the specified size is larger than remaining space on the drive, the partition is truncated at end of the drive.

By default, partitions are created in MBR format. It can create upto four primary partitions on a drive. GPT format is used to create the partitions when 64-bit LBA is enabled (FF_LBA64 = 1) and the drive size is equal to or larger than FF_MIN_GPT sectors. It can create over ten partitions on a drive.

@@ -64,23 +62,23 @@ FRESULT f_fdisk ( /* Volume mapping table defined by user (required when FF_MULTI_PARTITION == 1) */ PARTITION VolToPart[FF_VOLUMES] = { - {0, 1}, /* "0:" ==> 1st partition in PD#0 */ - {0, 2}, /* "1:" ==> 2nd partition in PD#0 */ - {1, 0} /* "2:" ==> PD#1 as removable drive */ + {0, 1}, /* "0:" ==> 1st partition in physical drive 0 */ + {0, 2}, /* "1:" ==> 2nd partition in physical drive 0 */ + {1, 0} /* "2:" ==> Physical drive 1 as removable drive */ }; 
     /* Initialize a brand-new disk drive mapped to physical drive 0 */
 
     BYTE work[FF_MAX_SS];         /* Working buffer */
-    LBA_t plist[] = {50, 50, 0};  /* Divide the drive into two partitions */
-                 /* {0x10000000, 100}; 256M sectors for 1st partition and left all for 2nd partition */
+    LBA_t plist[] = {50, 50, 0};  /* Divide the drive by 2 */
+                 /* {0x10000000, 100}; 256M sectors for the 1st partition and the remaining for the 2nd partition */
                  /* {20, 20, 20, 0}; 20% for 3 partitions each and remaing space is left not allocated */
 
-    f_fdisk(0, plist, work);                    /* Divide physical drive 0 */
+    f_fdisk(0, plist, work);            /* Divide the physical drive 0 */
 
-    f_mkfs("0:", 0, work, sizeof work); /* Create FAT volume on the logical drive 0 */
-    f_mkfs("1:", 0, work, sizeof work); /* Create FAT volume on the logical drive 1 */
+    f_mkfs("0:", 0, work, sizeof work); /* Create FAT volume on the logical drive 0 */
+    f_mkfs("1:", 0, work, sizeof work); /* Create FAT volume on the logical drive 1 */
@@ -90,6 +88,7 @@ FRESULT f_fdisk (

Volume management, f_mkfs

+

Return

diff --git a/documents/doc/filename.html b/documents/doc/filename.html index 8ff028d..bf28457 100644 --- a/documents/doc/filename.html +++ b/documents/doc/filename.html @@ -3,8 +3,6 @@ - - FatFs - Path Names @@ -36,15 +34,15 @@ /..Invalid nameThe root directory (sticks the top level)

Also the drive prefix can be in pre-defined arbitrary string. When the option FF_STR_VOLUME_ID == 1, also arbitrary string volume ID can be used as drive prefix. e.g. "flash:file1.txt", "ram:temp.dat" or "sd:". If the srting does not match any volume ID, the function fails with FR_INVALID_DRIVE.

-

When FF_STR_VOLUME_ID == 2, Unix style drive prefix can be used. e.g. "/flash/file1.txt", "/ram/temp.dat" or "/sd". If a heading separator is exist, it is treated as start of drive prefix and in absolute path. Any form as "root directory in current drive" and "current directory in specified drive" cannot be used. Double dot name cannot traverse the drives such as "/flash/../ram/foo.dat".

+

When FF_STR_VOLUME_ID == 2, Unix style drive prefix can be used. e.g. "/flash/file1.txt", "/ram/temp.dat" or "/sd". If a heading separator is exist, it is treated as an absolute path with a heading node ID. Any form as "root directory in current drive" and "current directory in specified drive" cannot be used. Double dot name cannot traverse the volumes such as "/flash/../ram/foo.dat".

Remark: In this revision, double dot name ".." cannot follow the parent directory on the exFAT volume. It will work as "." and stay there.

Legal Characters and Case Sensitivity

In the generic FAT filesystems, the legal characters for object name (file/directory name) are, 0-9 A-Z ! # $ % & ' ( ) - @ ^ _ ` { } ~ in ASCII and extended characters \x80 to \xFF. In the FAT filesystems with LFN extention, also + , ; = [ ], white space and extended characters U+000080 to U+10FFFF are legal for the object name. White spaces and dots can be placed anywhere in the path name except end of the name. Trailing white spaces and dots are ignored.

-

FAT filesystem is case-insensitive to the object names on the volume. Object name on the FAT volume is compared in case-insensitive. For instance, these three names, file.txt, File.Txt and FILE.TXT, are identical on the FAT filesystem. This is applied to extended charactres as well. When an object is created on the FAT volume, up converted name is recorded to the SFN entry, and the raw name is recorded to the LFN entry when LFN extension is exist.

-

As for the MS-DOS and PC DOS for CJK (DOS/DBCS), extended characters ware recorded to the SFN entry without up-case conversion and compared in case-sensitive. This causes a problem on compatibility with Windows system when the object with extended characters is created on the volume by DOS/DBCS system; therfore the object names with DBCS extended characters should not be used on the FAT volume shared by those systems. FatFs works with case-sensitive to the extended characters in only non-LFN with DBCS configuration (DOS/DBCS specs). However, FatFs works with case-insensitive to the extended character (WindowsNT specs) in LFN configuration.

+

FAT filesystem is case-insensitive to the object names on the volume. Object names on the FAT volume are compared in case-insensitive. For instance, these three names, file.txt, File.Txt and FILE.TXT, are identical on the FAT filesystem. This is applied to extended charactres as well. When an object is created on the FAT volume, up converted name is recorded to the SFN entry, and the original name is recorded to the LFN entry if LFN extension is enabled.

+

On the MS-DOS and PC DOS for Chinese, Japanese and Korean (DOS/DBCS), extended characters are recorded to the SFN entry without up-case conversion and compared in case-sensitive. This causes a problem on compatibility with Windows system when the object with extended characters is created on the volume by DOS/DBCS system; therfore the object names with DBCS extended characters should not be used on the FAT volume shared by those systems. FatFs works with case-sensitive to the extended characters in only non-LFN with DBCS configuration (DOS/DBCS specs). However, FatFs works with case-insensitive to the extended character (WindowsNT specs) in LFN configuration.

@@ -84,11 +82,12 @@ PARTITION VolToPart[FF_VOLUMES] = {
  • On the MBR format drive, up to four primary partitions (1-4) can be specified. The partition number 1 specifies the first item in the partition table and the partition number 2 specifies the second one, and so on. The logical patitions (5-) in the extended partition is not supported.
  • On the GPT format drive, the partition number 1 specifies the first Microsoft BDP found in the partition table and the partition number 2 specifies the second one found, and so on.
  • Windows 10 earlier than 1703 does not support multiple volumes on the physical drive with removable class. Only the first parition found on the drive will be mounted. Windows OS does not support SFD format on the physical drive with non-removable class.
    • -
  • Some systems manage the on-board storage in non-standard partition format and each partition is mapped as physical drive in disk_* functions. For such system, FF_MULTI_PARTITION should be always 0.
    • -
  • For further information about the volume management, refer to the description in f_fdisk and f_mkfs.
    • +
  • Some systems manage the on-board storage in non-standard partition format and each partition is mapped as physical drive in disk_* functions. For such system, FF_MULTI_PARTITION should be always 0 and use FM_SFD flag in f_mkfs.
    • +
  • For further information about the volume management, refer to the description in f_mkfs and f_fdisk.
    • +

    Return

    diff --git a/documents/doc/findfirst.html b/documents/doc/findfirst.html index 5f1e344..d3ae56d 100644 --- a/documents/doc/findfirst.html +++ b/documents/doc/findfirst.html @@ -3,8 +3,6 @@ - - FatFs - f_findfirst @@ -28,7 +26,7 @@ FRESULT f_findfirst (

    Parameters

    dp
    -
    Pointer to the blank directory object.
    +
    Pointer to the blank directory object. If a null pointer is given, the function fails with FR_INVALID_OBJECT.
    fno
    Pointer to the file information structure to store the information about the found item.
    path
    @@ -99,10 +97,10 @@ void find_image_file (void) while (fr == FR_OK && fno.fname[0]) { /* Repeat while an item is found */ printf("%s\n", fno.fname); /* Print the object name */ - fr = f_findnext(&dj, &fno); /* Search for next item */ + fr = f_findnext(&dj, &fno); /* Search for next item */ } - f_closedir(&dj); + f_closedir(&dj); } diff --git a/documents/doc/findnext.html b/documents/doc/findnext.html index f39f0fb..1800f61 100644 --- a/documents/doc/findnext.html +++ b/documents/doc/findnext.html @@ -3,8 +3,6 @@ - - FatFs - f_findnext @@ -64,6 +62,7 @@ FRESULT f_findnext (

    f_findfirst, f_closedir, DIR, FILINFO

    +

    Return

    diff --git a/documents/doc/forward.html b/documents/doc/forward.html index fdb5f49..056a48e 100644 --- a/documents/doc/forward.html +++ b/documents/doc/forward.html @@ -3,8 +3,6 @@ - - FatFs - f_forward @@ -28,13 +26,13 @@ FRESULT f_forward (

    Parameters

    fp
    -
    Pointer to the open file object.
    +
    Pointer to the open file object. If a null pointer is given, the function fails with FR_INVALID_OBJECT.
    func
    Pointer to the user-defined data streaming function. For details, refer to the sample code.
    btf
    Number of bytes to forward in range of UINT.
    bf
    -
    Pointer to the UINT variable to return number of bytes forwarded.
    +
    Pointer to the variable in UINT type to return number of bytes forwarded.
    @@ -109,11 +107,11 @@ FRESULT play_file ( UINT dmy; /* Open the audio file in read only mode */ - rc = f_open(&fil, fn, FA_READ); + rc = f_open(&fil, fn, FA_READ); if (rc) return rc; /* Repeat until the file pointer reaches end of the file */ - while (rc == FR_OK && !f_eof(&fil)) { + while (rc == FR_OK && !f_eof(&fil)) { /* some processes... */ @@ -122,7 +120,7 @@ FRESULT play_file ( } /* Close the file and return */ - f_close(&fil); + f_close(&fil); return rc; } @@ -134,6 +132,7 @@ FRESULT play_file (

    f_open, fgets, f_write, f_close, FIL

    +

    Return

    diff --git a/documents/doc/getcwd.html b/documents/doc/getcwd.html index 6eb9a58..22a31e1 100644 --- a/documents/doc/getcwd.html +++ b/documents/doc/getcwd.html @@ -3,8 +3,6 @@ - - FatFs - f_getcwd @@ -78,6 +76,7 @@ FRESULT f_getcwd (

    f_chdrive, f_chdir

    +

    Return

    diff --git a/documents/doc/getfree.html b/documents/doc/getfree.html index 5e4f419..ac378a7 100644 --- a/documents/doc/getfree.html +++ b/documents/doc/getfree.html @@ -3,8 +3,6 @@ - - FatFs - f_getfree diff --git a/documents/doc/getlabel.html b/documents/doc/getlabel.html index 0ec6d0d..d7d3362 100644 --- a/documents/doc/getlabel.html +++ b/documents/doc/getlabel.html @@ -3,8 +3,6 @@ - - FatFs - f_getlabel @@ -27,7 +25,7 @@ FRESULT f_getlabel (

    Parameters

    path
    -
    Pointer to the null-terminated string that specifies the logical drive. Null-string specifies the default drive.
    +
    Pointer to the null-terminated string that specifies the logical drive. Null-string specifies the default drive. If a null pointer is given, the function fails with FR_INVALID_DRIVE.
    label
    Pointer to the buffer to store the volume label. If the volume has no label, a null-string will be returned. Set null pointer if this information is not needed. The buffer size should be shown below at least to avoid buffer overflow.
    diff --git a/documents/doc/gets.html b/documents/doc/gets.html index 89d9560..f4a22ca 100644 --- a/documents/doc/gets.html +++ b/documents/doc/gets.html @@ -3,8 +3,6 @@ - -FatFs - f_gets @@ -45,13 +43,13 @@ TCHAR* f_gets (

    Description

    The read operation continues until a '\n' is stored, reached end of the file or the buffer is filled with len - 1 characters. The read string is terminated with a '\0'. When no character to read or any error occured during read operation, it returns a null pointer. The status of EOF and error can be examined with f_eof and f_error function.

    -

    When FatFs is configured to Unicode API (FF_LFN_UNICODE >= 1), data types on the srting fuctions, f_putc, f_puts, f_printf and f_gets, is also switched to Unicode. The character encoding on the file to be read via this function is assumed as FF_STRF_ENCODE. If the character encoding on the file differs from that on the API, it is converted in this function. In this case, input characters with wrong encoding will be lost.

    +

    When FatFs is configured to Unicode API (FF_LFN_UNICODE >= 1), data types on the srting fuctions, f_putc, f_puts, f_printf and f_gets, is also switched to Unicode. The character encoding on the file to be read via this function is assumed as FF_STRF_ENCODE. If the character encoding differs between file data and API, it is converted in this function. Input characters with wrong encoding for output will be lost.

    QuickInfo

    -

    This is a wrapper function of f_read function. Available when FF_USE_STRFUNC >= 1. When it is set to 2, '\r's contained in the file are stripped out.

    +

    This is a wrapper function of f_read function. Available when FF_USE_STRFUNC >= 1. When it is set to 2, '\r's contained in the read data are stripped off.

    @@ -60,6 +58,7 @@ TCHAR* f_gets (

    f_open, f_read, f_putc, f_puts, f_printf, f_close, FIL

    +

    Return

    diff --git a/documents/doc/lseek.html b/documents/doc/lseek.html index ffd1f62..a0ff7f9 100644 --- a/documents/doc/lseek.html +++ b/documents/doc/lseek.html @@ -3,8 +3,6 @@ - -FatFs - f_lseek @@ -32,7 +30,7 @@ FRESULT f_rewind (

    Parameters

    fp
    -
    Pointer to the open file object.
    +
    Pointer to the open file object. If a null pointer is given, the function fails with FR_INVALID_OBJECT.
    ofs
    Byte offset from top of the file to set read/write pointer. The data type FSIZE_t is an alias of either DWORD(32-bit) or QWORD(64-bit) depends on the configuration option FF_FS_EXFAT.
    @@ -53,11 +51,12 @@ FRESULT f_rewind (

    Description

    -

    File read/write ponter in the open file object points the data byte to be read/written at next read/write operation. It advances as the number of bytes read/written. The f_lseek function moves the file read/write pointer without any read/write operation to the file. The f_rewind function is impremented as a macro.

    +

    File read/write ponter in the open file object points the data byte to be read/written at next read/write operation. It advances as the number of bytes read/written. The f_lseek function moves the file read/write pointer without read/write operation to the file. The f_rewind function is impremented as a macro.

     #define f_rewind(fp) f_lseek((fp), 0)
    -

    If an offset beyond the file size is specified in write mode, the file size is expanded to the specified offset. The file data in the expanded part is undefined, because no data is written to the file in this process. This is suitable to pre-allocate a data area to the file quickly for fast write operation. When a contiguous data area needs to be allocated to the file, use f_expand function instead. After the f_lseek function succeeded, the current read/write pointer should be checked in order to make sure the read/write pointer has been moved correctry. In case of the read/write pointer is not pointing expected offset, either of followings has been occured.

    +

    When an offset beyond the file size is specified in write mode, the file size is expanded to the specified offset in this function. The file data in the expanded part is undefined, because no data is written to the file in this process. Be careful about these behaviours differ from POSIX fseek function. This is suitable to pre-allocate a data area to the file for subsequent fast write operation. If a contiguous data area needs to be allocated to the file, use f_expand function instead.

    +

    After the f_lseek function succeeded, the current read/write pointer should be checked in order to make sure the read/write pointer has been moved correctry. In case of the read/write pointer is not pointing expected offset, either of followings has been occured.

    • End of file. The specified ofs was clipped at end of the file in read-only mode.
    • Disk full. There is no free space on the volume to expand the file.
      • @@ -78,7 +77,7 @@ FRESULT f_rewind ( 
           /* Open file */
     fp = malloc(sizeof (FIL));
-    res = f_open(fp, "file.dat", FA_READ|FA_WRITE);
+    res = f_open(fp, "file.dat", FA_READ|FA_WRITE);
     if (res) ...
 
     /* Set read/write pointer to 5000 */
@@ -96,15 +95,15 @@ FRESULT f_rewind (
 
       /* Cluster pre-allocation (to prevent buffer overrun on streaming write) */
 
-    res = f_open(fp, recfile, FA_CREATE_NEW | FA_WRITE);   /* Create a file */
+    res = f_open(fp, recfile, FA_CREATE_NEW | FA_WRITE);   /* Create a file */
 
     res = f_lseek(fp, PRE_SIZE);             /* Expand file size (cluster pre-allocation) */
-    if (res || f_tell(fp) != PRE_SIZE) ...   /* Check if the file has been expanded successfly */
+    if (res || f_tell(fp) != PRE_SIZE) ...   /* Check if the file has been expanded successfly */
 
     res = f_lseek(fp, OFS_DATA);             /* Record data stream with free from cluster allocation delay */
     ...                                      /* Write operation should be aligned to sector boundary to optimize the write throughput */
 
-    res = f_truncate(fp);                    /* Truncate unused area */
+    res = f_truncate(fp);                    /* Truncate unused area */
     res = f_lseek(fp, OFS_HEADER);           /* Set file header */
     ...
 
@@ -115,7 +114,7 @@ FRESULT f_rewind (
 
     DWORD clmt[SZ_TBL];                    /* Cluster link map table buffer */
 
-    res = f_open(fp, fname, FA_READ | FA_WRITE);   /* Open a file */
+    res = f_open(fp, fname, FA_READ | FA_WRITE);   /* Open a file */
 
     res = f_lseek(fp, ofs1);               /* This is normal seek (cltbl is nulled on file open) */
 
@@ -134,6 +133,7 @@ FRESULT f_rewind (
 
      f_open, f_truncate, f_expand, FIL
    +

    Return

    diff --git a/documents/doc/mkdir.html b/documents/doc/mkdir.html index de32f83..7027cd8 100644 --- a/documents/doc/mkdir.html +++ b/documents/doc/mkdir.html @@ -3,8 +3,6 @@ - -FatFs - f_mkdir @@ -75,6 +73,7 @@ FRESULT f_mkdir ( +

    Return

    diff --git a/documents/doc/mkfs.html b/documents/doc/mkfs.html index f40ebb0..8a452a0 100644 --- a/documents/doc/mkfs.html +++ b/documents/doc/mkfs.html @@ -3,8 +3,6 @@ - -FatFs - f_mkfs @@ -36,12 +34,12 @@ FRESULT f_mkfs (
    Specifies a combination of FAT type flags, FM_FAT, FM_FAT32, FM_EXFAT and bitwise-or of these three, FM_ANY. FM_EXFAT is ignored when exFAT is not enabled. These flags specify which type of FAT volume to be created. If two or more types are specified, one out of them will be selected depends on the volume size and au_size. The flag FM_SFD specifies to create the volume on the drive in SFD format. The default value is FM_ANY.
    BYTE n_fat
    Specifies number of FAT copies on the FAT/FAT32 volume. Valid value for this member is 1 or 2. The default value (0) and any invaid value gives 1. If the FAT type is exFAT, this member has no effect.
    -
    UINT n_align
    -
    Specifies alignment of the volume data area (file allocation pool, usually erase block boundary of flash memory media) in unit of sector. The valid value for this member is between 1 and 32768 inclusive in power of 2. If a zero (the default value) or any invalid value is given, the function obtains the block size from lower layer with disk_ioctl function.
    -
    DWORD au_size
    -
    Specifies size of the allocation unit (cluter) in unit of byte. The valid value is power of 2 between sector size and 128 * sector size inclusive for FAT/FAT32 volume, or up to 16 MB for exFAT volume. If a zero (default value) or any invalid value is given, the function uses default allocation unit size depends on the volume size.
    +
    UINT align
    +
    Specifies alignment of the volume data area (file allocation pool, usually erase block boundary of flash memory media) in unit of sector. The valid value for this member is between 1 and 32768 inclusive in power of 2. If a zero (the default value) or any invalid value is given, the function obtains the block size from lower layer with disk_ioctl function.
    UINT n_root
    Specifies number of root directory entries on the FAT volume. Valid value for this member is up to 32768 and aligned to sector size / 32. The default value (0) and any invaid value gives 512. If the FAT type is FAT32 or exFAT, this member has no effect.
    +
    DWORD au_size
    +
    Specifies size of the cluster (allocation unit) in unit of byte. The valid value for this member is between sector size and 128 * sector size inclusive in power of 2 for FAT/FAT32 volume and up to 16 MB in power of 2 for exFAT volume. If a zero (default value) or any invalid value is given, the function uses a default cluster size depends on the volume size.
    work
    Pointer to the working buffer used for the format process. If a null pointer is given with FF_USE_LFN == 3, the function uses a len bytes of heap memory in this function.
    @@ -69,7 +67,7 @@ FRESULT f_mkfs (

    The FAT sub-type, FAT12/FAT16/FAT32, of FAT volume except exFAT is determined by only number of clusters on the volume and nothing else, according to the FAT specification issued by Microsoft. Thus the FAT sub-type of created volume depends on the volume size and the cluster size. In case of the combination of FAT type and cluter size specified by argument is not valid for the volume size, the function will fail with FR_MKFS_ABORTED.

    The allocation unit, also known as cluster, is a unit of disk space allocation for files. When the size of allocation unit is 32768 bytes, a file with 100 bytes in size occupies 32768 bytes of disk space. The space efficiency of disk usage gets worse as increasing size of allocation unit, but, on the other hand, the read/write performance increases. Therefore the size of allocation unit is a trade-off between space efficiency and performance. For the large volumes in GB order, 32768 bytes or larger, automatically selected by default, is recommended for most case unless extremely many small files are created in the volume.

    When the logical drive to be formatted is associated with a physical drive (FF_MULTI_PARTITION == 0 or VolToPart[].pt == 0) and FM_SFD flag is not specified, a partition occupies entire drive space is created and then the FAT volume is created in the partition. When FM_SFD flag is specified, the FAT volume is created without any disk partitioning.

    -

    When the logical drive to be formatted is associated with a specific partition by multiple partition feature (FF_MULTI_PARTITION == 1 and VolToPart[].pt > 0), the FAT volume is created in the partition of the physical drive specified by volume mapping table and FM_SFD flag is ignored. The hosting physical drive needs to be partitioned with f_fdisk function or any partitioning tool prior to create the FAT volume with this function. If the partition is not exist, the function aborts with FR_MKFS_ABORTED.

    +

    When the logical drive to be formatted is associated with a specific partition by multiple partition feature (FF_MULTI_PARTITION == 1 and VolToPart[].pt > 0), the FAT volume is created in the partition of the physical drive specified by volume mapping table and FM_SFD flag is ignored. The hosting physical drive needs to be partitioned with f_fdisk function or some partitioning tool prior to create the FAT volume with this function. If the partition is not exist, the function fails with FR_MKFS_ABORTED.

    There are three standard disk partitioning formats, MBR, GPT and SFD. The MBR format, also known as FDISK format, is usually used for harddisk, memory card and U disk. It can divide a physical drive into one or more partitions with a partition table. The GPT, GUID Partition Table, is a newly defined patitioning format for large storage devices. FatFs suppors the GPT only when 64-bit LBA is enabled. The SFD, Super-Floppy Disk, is non-partitioned disk format. The FAT volume is located at LBA 0 and occupies the entire physical drive without any disk partitioning. It is usually used for floppy disk, optical disk and most super-floppy media. Some combination of systems and media support only either partitioned format or non-partitioned format and the other is not supported.

    Some systems manage the partitions in the on-board storage in non-standard format. The partitions are mapped as physical drives identified by pdrv in disk_* functions. For such systems, SFD format is suitable to create the FAT volume in the partition.

    @@ -97,21 +95,21 @@ int main (void) if (res) ... /* Give a work area to the default drive */ - f_mount(&fs, "", 0); + f_mount(&fs, "", 0); /* Create a file as new */ - res = f_open(&fil, "hello.txt", FA_CREATE_NEW | FA_WRITE); + res = f_open(&fil, "hello.txt", FA_CREATE_NEW | FA_WRITE); if (res) ... /* Write a message */ - f_write(&fil, "Hello, World!\r\n", 15, &bw); + f_write(&fil, "Hello, World!\r\n", 15, &bw); if (bw != 15) ... /* Close the file */ - f_close(&fil); + f_close(&fil); /* Unregister work area */ - f_mount(0, "", 0); + f_mount(0, "", 0); ... @@ -122,6 +120,7 @@ int main (void)

    Example of volume size and format parameters, Volume management, f_fdisk

    +

    Return

    diff --git a/documents/doc/mount.html b/documents/doc/mount.html index 57f40be..f0383b9 100644 --- a/documents/doc/mount.html +++ b/documents/doc/mount.html @@ -3,8 +3,6 @@ - -FatFs - f_mount @@ -92,19 +90,19 @@ int main (void) FATFS *fs; /* Ponter to the filesystem object */ - fs = malloc(sizeof (FATFS)); /* Get work area for the volume */ - f_mount(fs, "", 0); /* Mount the default drive */ + fs = malloc(sizeof (FATFS)); /* Get work area for the volume */ + f_mount(fs, "", 0); /* Mount the default drive */ - f_open(... /* Here any file API can be used */ + f_open(... /* Here any file API can be used */ ... - f_mount(fs, "", 0); /* Re-mount the default drive to reinitialize the filesystem */ + f_mount(fs, "", 0); /* Re-mount the default drive to reinitialize the filesystem */ ... - f_mount(0, "", 0); /* Unmount the default drive */ - free(fs); /* Here the work area can be discarded */ + f_unmount(""); /* Unmount the default drive */ + free(fs); /* Here the work area can be discarded */ ... } @@ -117,6 +115,7 @@ int main (void)

    f_open, FATFS

    +

    Return

    diff --git a/documents/doc/open.html b/documents/doc/open.html index cc8b87a..b533249 100644 --- a/documents/doc/open.html +++ b/documents/doc/open.html @@ -3,8 +3,6 @@ - -FatFs - f_open @@ -27,19 +25,19 @@ FRESULT f_open (

    Parameters

    fp
    -
    Pointer to the blank file object structure.
    +
    Pointer to the blank file object structure. If a null pointer is given, the function fails with FR_INVALID_OBJECT.
    path
    -
    Pointer to the null-terminated string that specifies the file name to open or create.
    +
    Pointer to the null-terminated string that specifies the file name to open or create. If a null pointer is given, the function fails with FR_INVALID_DRIVE.
    mode
    Mode flags that specifies the type of access and open method for the file. It is specified by a combination of following flags.
    - - - - + + + +
    FlagsMeaning
    FA_READSpecifies read access to the file. Data can be read from the file.
    FA_WRITESpecifies write access to the file. Data can be written to the file. Combine with FA_READ for read-write access.
    FA_OPEN_EXISTINGOpens a file. The function fails if the file is not existing. (Default)
    FA_CREATE_NEWCreates a new file. The function fails with FR_EXIST if the file is existing.
    FA_CREATE_ALWAYSCreates a new file. If the file is existing, it will be truncated and overwritten.
    FA_OPEN_ALWAYSOpens the file if it is existing. If not, a new file will be created.
    FA_OPEN_EXISTINGOpens the file. The function fails if the file is not existing. (Default)
    FA_CREATE_ALWAYSCreates a new file. If the file is existing, the file is truncated and overwritten.
    FA_CREATE_NEWCreates a new file. The function fails if the file is existing.
    FA_OPEN_ALWAYSOpens the file. If it is not exist, a new file is created.
    FA_OPEN_APPENDSame as FA_OPEN_ALWAYS except the read/write pointer is set end of the file.
    Mode flags in POSIX fopen() function corresponds to FatFs mode flags as follows:
    @@ -86,7 +84,8 @@ Mode flags in POSIX fopen() function corresponds to FatFs mode flags as follows:

    Description

    -

    The f_open function opens a file and creates a file object. The file object is an identifier for subsequent operations to the file. Open file should be closed with f_close function after the session of the file access. If any change to the file has been made and not closed prior to power off, media removal or re-mount, or the file can be collapsed.

    +

    The f_open function opens a file and creates a file object. It is the identifier for subsequent read/write operations to the file. After the function succeeded, the file object is valid. If the function failed, the file object is set invalid.

    +

    Open file should be closed with f_close function after the session of the file access. If any change to the file has been made and not closed prior to power off, media removal or re-mount, or the file can be collapsed.

    If duplicated file open is needed, read here carefully. However duplicated open of a file with any write mode flag is always prohibited.

    @@ -112,19 +111,19 @@ int main (void) /* Give a work area to the default drive */ - f_mount(&FatFs, "", 0); + f_mount(&FatFs, "", 0); /* Open a text file */ fr = f_open(&fil, "message.txt", FA_READ); if (fr) return (int)fr; /* Read every line and display it */ - while (f_gets(line, sizeof line, &fil)) { + while (f_gets(line, sizeof line, &fil)) { printf(line); } /* Close the file */ - f_close(&fil); + f_close(&fil); return 0; } @@ -142,8 +141,8 @@ int main (void) /* Give work areas to each logical drive */ - f_mount(&fs0, "0:", 0); - f_mount(&fs1, "1:", 0); + f_mount(&fs0, "0:", 0); + f_mount(&fs1, "1:", 0); /* Open source file on the drive 1 */ fr = f_open(&fsrc, "1:file.bin", FA_READ); @@ -155,19 +154,19 @@ int main (void) /* Copy source to destination */ for (;;) { - fr = f_read(&fsrc, buffer, sizeof buffer, &br); /* Read a chunk of data from the source file */ + fr = f_read(&fsrc, buffer, sizeof buffer, &br); /* Read a chunk of data from the source file */ if (br == 0) break; /* error or eof */ - fr = f_write(&fdst, buffer, br, &bw); /* Write it to the destination file */ + fr = f_write(&fdst, buffer, br, &bw); /* Write it to the destination file */ if (bw < br) break; /* error or disk full */ } /* Close open files */ - f_close(&fsrc); - f_close(&fdst); + f_close(&fsrc); + f_close(&fdst); /* Unregister work area prior to discard it */ - f_unmount("0:"); - f_unmount("1:"); + f_unmount("0:"); + f_unmount("1:"); return (int)fr; } @@ -180,6 +179,7 @@ int main (void)

    f_read, f_write, f_close, FIL, FATFS

    +

    Return

    diff --git a/documents/doc/opendir.html b/documents/doc/opendir.html index 215c37a..1955bc3 100644 --- a/documents/doc/opendir.html +++ b/documents/doc/opendir.html @@ -3,8 +3,6 @@ - - FatFs - f_opendir @@ -26,9 +24,9 @@ FRESULT f_opendir (

    Parameters

    dp
    -
    Pointer to the blank directory object to create a new one.
    +
    Pointer to the blank directory object to create a new one. If a null pointer is given, the function fails with FR_INVALID_OBJECT.
    path
    -
    Pointer to the null-terminated string that specifies the directory name to be opened.
    +
    Pointer to the null-terminated string that specifies the directory name to be opened. If a null pointer is given, the function fails with FR_INVALID_DRIVE.
    @@ -70,6 +68,7 @@ FRESULT f_opendir (

    f_readdir, f_closedir, DIR

    +

    Return

    diff --git a/documents/doc/printf.html b/documents/doc/printf.html index eb64e8d..7e29ed2 100644 --- a/documents/doc/printf.html +++ b/documents/doc/printf.html @@ -3,8 +3,6 @@ - - FatFs - f_printf @@ -57,19 +55,19 @@ int f_printf (
    type
    Specifies type of the output format and the argument as shown below. The length of generated string is in assumtion of int is 32-bit. - + - - + +
    TypeFormatArgumentLength
    cCharacterint,
    long,
    long long    		1 character.
    cCharacterint,
    long,
    long long    		1 character.
    dSigned decimal1 to 11 (20 for ll) characters.
    uUnsigned decimal1 to 10 (20 for ll) characters.
    oUnsigned octal1 to 11 (22 for ll) characters.
    x XUnsigned hexdecimal1 to 8 (16 for ll) characters.
    bUnsigned binary1 to 32 characters. Limited to lower 32 digits when ll is specified.
    sStringTCHAR*As input string. Null pointer generates a null string.
    fFloating point
    (decimal)    		double1 to 31 characters. If the number of characters exceeds 31, it writes "±OV". Not a number and infinite write "NaN" and "±INF".
    sStringTCHAR*As input string. A null pointer generates a zero-length string.
    fFloating point
    (decimal)    		double1 to 31 characters. If the number of characters exceeds 31, it writes "±OV". Not a number and infinite value write "NaN" and "±INF" respectively.
    e EFloating point
    (e notation)    		4 to 31 characters. If the number of characters exceeds 31 or exponent exceeds +99, it writes "±OV".
    -

    When FatFs is configured for Unicode API (FF_LFN_UNICODE >= 1), character encoding on the string fuctions, f_putc, f_puts, f_printf and f_gets function, is also switched to Unicode. The Unicode characters in multiple encoding unit, such as surrogate pair and multi-byte sequence, should not be divided into two function calls, or the character will be lost. The character encoding on the file to be written via this function is selected by FF_STRF_ENCODE. The characters with wrong encoding or invalid for the output encoding will be lost.

    +

    When FatFs is configured for Unicode API (FF_LFN_UNICODE >= 1), character encoding on the string fuctions, f_putc, f_puts, f_printf and f_gets function, is also switched to Unicode. The Unicode characters in multiple encoding unit, such as surrogate pair and multi-byte sequence, should not be divided into two function calls, or the character will be lost. The character encoding on the file to be written via this function is selected by FF_STRF_ENCODE. If the character encoding differs between file data and API, it is converted in this function. Input characters with wrong encoding for output will be lost.

    If sprintf is used in the project and code conversion is not needed, f_write with sprintf will be efficient in code size and performance rather than f_printf.

    @@ -110,6 +108,7 @@ int f_printf (

    f_open, f_putc, f_puts, f_gets, f_close, FIL

    +

    Return

    diff --git a/documents/doc/putc.html b/documents/doc/putc.html index 747b5fd..e48fbb1 100644 --- a/documents/doc/putc.html +++ b/documents/doc/putc.html @@ -3,8 +3,6 @@ - - FatFs - f_putc @@ -55,6 +53,7 @@ int f_putc (

    f_open, f_puts, f_printf, f_gets, f_close, FIL

    +

    Return

    diff --git a/documents/doc/puts.html b/documents/doc/puts.html index 3695942..2def40f 100644 --- a/documents/doc/puts.html +++ b/documents/doc/puts.html @@ -3,8 +3,6 @@ - - FatFs - f_puts @@ -41,7 +39,7 @@ int f_puts (

    Description

    -

    When FatFs is configured for Unicode API (FF_LFN_UNICODE >= 1), character encoding on the string fuctions, f_putc, f_puts, f_printf and f_gets function, is also switched to Unicode. The input Unicode characters in multiple encoding unit, such as surrogate pair and multi-byte sequence, should not be divided into two function calls, or the character will be lost. The character encoding on the file to be written via this functions is selected by FF_STRF_ENCODE. The characters with wrong encoding or invalid for the output encoding will be lost.

    +

    When FatFs is configured for Unicode API (FF_LFN_UNICODE >= 1), character encoding on the string fuctions, f_putc, f_puts, f_printf and f_gets function, is also switched to Unicode. The input Unicode characters in multiple encoding unit, such as surrogate pair and multi-byte sequence, should not be divided into two function calls, or the character will be lost. The character encoding on the file to be written via this functions is selected by FF_STRF_ENCODE. If the character encoding differs between file data and API, it is converted in this function. Input characters with wrong encoding for output will be lost.

    @@ -56,6 +54,7 @@ int f_puts (

    f_open, f_putc, f_printf, f_gets, f_close, FIL

    +

    Return

    diff --git a/documents/doc/rc.html b/documents/doc/rc.html index 8f7fffa..89823ec 100644 --- a/documents/doc/rc.html +++ b/documents/doc/rc.html @@ -3,8 +3,6 @@ - - FatFs - API Return Code @@ -75,10 +73,10 @@ Note that if once this error occured in the operation to an open file, the file
    Name collision. An object with the same name is already existing in the directory.
    FR_INVALID_OBJECT
    -
    The file/directory object is invalid or a null pointer is given. There are some reasons as follows: +
    The file/directory object is invalid or the pointer is null. There are some reasons as follows:
      -
    • It has been closed, or the structure has been collapsed.
      • -
    • It has been invalidated. Open objects on the volume are invalidated by voulme mount process.
      • +
    • The file/directory has been closed.
      • +
    • The file/directory object has been invalidated or the structure has been collapsed. Open objects on the volume will be invalidated by a voulme mount process.
    • Physical drive is not ready to work due to a media removal.
    @@ -130,6 +128,7 @@ Note that if once this error occured in the operation to an open file, the file
    The given parameter is invalid or there is an inconsistent for the volume.
    +

    Return

    diff --git a/documents/doc/read.html b/documents/doc/read.html index 9dff623..0dd7f53 100644 --- a/documents/doc/read.html +++ b/documents/doc/read.html @@ -3,8 +3,6 @@ - - FatFs - f_read @@ -28,13 +26,13 @@ FRESULT f_read (

    Parameters

    fp
    -
    Pointer to the open file object.
    +
    Pointer to the open file object structure. If a null pointer is given, the function fails with FR_INVALID_OBJECT.
    buff
    Pointer to the buffer to store the read data.
    btr
    Number of bytes to read in range of UINT type. If the file needs to be read fast, it should be read in large chunk as possible.
    br
    -
    Pointer to the UINT variable that receives number of bytes read. This value is always valid after the function call regardless of the function return code. If the return value is equal to btr, the function return code should be FR_OK.
    +
    Pointer to the variable in UINT type that receives number of bytes read. This value is always valid after the function call regardless of the function return code. If the return value is equal to btr, the function return code should be FR_OK.
    @@ -54,7 +52,7 @@ FRESULT f_read (

    Description

    -

    The function starts to read data from the file at the file offset pointed by read/write pointer. The read/write pointer advances as number of bytes read. After the function succeeded, *br should be checked to detect end of the file. In case of *br < btr, it means the read/write pointer hit end of the file during read operation.

    +

    The function starts to read data from the file at the file offset pointed by read/write pointer of the file object. The read/write pointer advances as number of bytes read. After the function succeeded, *br should be checked to detect end of the file. In case of *br < btr, it means the read/write pointer hit end of the file during read operation.

    @@ -75,6 +73,7 @@ FRESULT f_read (

    f_open, fgets, f_write, f_close, FIL

    +

    Return

    diff --git a/documents/doc/readdir.html b/documents/doc/readdir.html index 52a96b9..f7209a6 100644 --- a/documents/doc/readdir.html +++ b/documents/doc/readdir.html @@ -3,8 +3,6 @@ - - FatFs - f_readdir @@ -53,19 +51,19 @@ FRESULT f_rewinddir (

    Description

    -

    The f_readdir function reads a directory item, informations about the object, from the open directory. Items in the directory can be read in sequence by f_readdir function calls. When all items in the directory have been read and no item to read, a null string is stored into the fno->fname[] without any error. When a null pointer is given to the fno, the read index of the directory object is rewinded. The f_rewinddir function is implemented as a macro.

    +

    The f_readdir function reads a directory item, informations about the object, from the open directory. Items in the directory can be read by f_readdir function calls in order of the directory table. When all items in the directory have been read and no item to read any more, a null string in fno->fname[] will be returned without an error. If a null pointer is given to the fno, the read index of the directory object will be rewound. The f_rewinddir function is implemented as a macro.

     #define f_rewinddir(dp) f_readdir((dp), 0)
    -

    When LFN is enabled, a member altname[] is defined in the file information structure to store the short file name of the object. If the long file name is not accessible due to a reason listed below, short file name is stored to the fname[] and the altname[] has a null string.

    +

    When LFN is enabled, a member altname[] is defined in the file information structure to store the short file name of the object. If the long file name is not accessible due to any reason listed below, short file name is stored to the fname[] and the altname[] has a null string.

    -

    There is an issue on read directories in exFAT volume. The exFAT does not support short file name. This means no name can be returned on the condition above. If it is the case, "?" is returned as the file name to indicate that the object is not accessible. To avoid this problem, configure FatFs FF_LFN_UNICODE != 0 and FF_MAX_LFN == 255 to support the full feature of LFN specification.

    -

    Dot entries ("." and "..") in the sub-directory of FAT volume are filtered out and they will never appear in the read items because exFAT lacks dot entries in the sub-directory.

    +

    There is an issue on read the directories on the exFAT volume. The exFAT does not support short file name. This means no name can be returned on the condition above. If it is the case, "?" is returned as the file name to indicate that the object is not accessible. To avoid this problem, configure FatFs FF_LFN_UNICODE != 0 and FF_MAX_LFN == 255 to support the full feature of LFN specification.

    +

    Dot entries ("." and "..") in the sub-directory of FAT volume are filtered out and they will never appear in the read items because of the consistency with exFAT which lacks dot entries in the sub-directory.

    @@ -78,6 +76,41 @@ FRESULT f_rewinddir (

    Sample Code

    +/* List contents of a directory */
+
+FRESULT list_dir (const char *path)
+{
+    FRESULT res;
+    DIR dir;
+    FILINFO fno;
+    int nfile, ndir;
+
+
+    res = f_opendir(&dir, path);                       /* Open the directory */
+    if (res == FR_OK) {
+        nfile = ndir = 0;
+        for (;;) {
+            res = f_readdir(&dir, &fno);                   /* Read a directory item */
+            if (res != FR_OK || fno.fname[0] == 0) break;  /* Error or end of dir */
+            if (fno.fattrib & AM_DIR) {            /* Directory */
+                printf("   <DIR>   %s\n", fno.fname);
+                ndir++;
+            } else {                               /* File */
+                printf("%10u %s\n", fno.fsize, fno.fname);
+                nfile++;
+            }
+        }
+        f_closedir(&dir);
+        printf("%d dirs, %d files.\n", ndir, nfile);
+    } else {
+        printf("Failed to open \"%s\". (%u)\n", path, res);
+    }
+    return res;
+}
+
    +
    +/* Recursive scan of all items in the directory */
+
 FRESULT scan_files (
     char* path        /* Start node to be scanned (***also used as work area***) */
 )
@@ -88,7 +121,7 @@ FRESULT scan_files (
     static FILINFO fno;
 
 
-    res = f_opendir(&dir, path);                       /* Open the directory */
+    res = f_opendir(&dir, path);                       /* Open the directory */
     if (res == FR_OK) {
         for (;;) {
             res = f_readdir(&dir, &fno);                   /* Read a directory item */
@@ -103,7 +136,7 @@ FRESULT scan_files (
                 printf("%s/%s\n", path, fno.fname);
             }
         }
-        f_closedir(&dir);
+        f_closedir(&dir);
     }
 
     return res;
@@ -117,7 +150,7 @@ int main (void)
     char buff[256];
 
 
-    res = f_mount(&fs, "", 1);
+    res = f_mount(&fs, "", 1);
     if (res == FR_OK) {
         strcpy(buff, "/");
         res = scan_files(buff);
@@ -134,6 +167,7 @@ int main (void)
 
    f_opendir, f_closedir, f_stat, FILINFO, DIR
    +

    Return

    diff --git a/documents/doc/rename.html b/documents/doc/rename.html index 326af0d..9919bd8 100644 --- a/documents/doc/rename.html +++ b/documents/doc/rename.html @@ -3,8 +3,6 @@ - - FatFs - f_rename diff --git a/documents/doc/sdir.html b/documents/doc/sdir.html index eb18cc3..d137a07 100644 --- a/documents/doc/sdir.html +++ b/documents/doc/sdir.html @@ -3,8 +3,6 @@ - - FatFs - DIR @@ -33,6 +31,7 @@ +

    Return

    diff --git a/documents/doc/setcp.html b/documents/doc/setcp.html index a1d124b..9d5c774 100644 --- a/documents/doc/setcp.html +++ b/documents/doc/setcp.html @@ -3,8 +3,6 @@ - - FatFs - f_setcp diff --git a/documents/doc/setlabel.html b/documents/doc/setlabel.html index 9eb5e78..e547bff 100644 --- a/documents/doc/setlabel.html +++ b/documents/doc/setlabel.html @@ -3,8 +3,6 @@ - - FatFs - f_setlabel @@ -25,7 +23,7 @@ FRESULT f_setlabel (

    Parameters

    label
    -
    Pointer to the null-terminated string that specifies the volume label to be set.
    +
    Pointer to the null-terminated string that specifies the volume label to be set. If a null pointer is given, the function fails with FR_INVALID_DRIVE.
    @@ -49,7 +47,7 @@ FRESULT f_setlabel (

    Description

    -

    When the string has a drive prefix, the volume label will be set to the volume specified by the drive prefix. Unix style volume ID cannot be used to specify the volume. If drive number is not specified, the volume label will be set to the default drive. If length of the given volume label is zero, the volume label on the volume will be removed. The format of the volume label is as shown below:

    +

    When the string has a drive prefix, the volume label will be set to the volume specified by the drive prefix. If drive number is not specified, the volume label will be set to the default drive. If length of the given volume label is zero, the volume label on the volume will be removed. The format of the volume label is as shown below:

    diff --git a/documents/doc/sfatfs.html b/documents/doc/sfatfs.html index 6ecd6e5..b002ccf 100644 --- a/documents/doc/sfatfs.html +++ b/documents/doc/sfatfs.html @@ -3,8 +3,6 @@ - - FatFs - FATFS diff --git a/documents/doc/sfile.html b/documents/doc/sfile.html index 9234d32..c361483 100644 --- a/documents/doc/sfile.html +++ b/documents/doc/sfile.html @@ -3,8 +3,6 @@ - - FatFs - FIL @@ -38,6 +36,7 @@ +

    Return

    diff --git a/documents/doc/sfileinfo.html b/documents/doc/sfileinfo.html index db0f45e..ca40ac3 100644 --- a/documents/doc/sfileinfo.html +++ b/documents/doc/sfileinfo.html @@ -3,8 +3,6 @@ - - FatFs - FILINFO @@ -73,6 +71,7 @@
    Alternative object name is stored if available. This member is not available in non-LFN configuration.
    +

    Return

    diff --git a/documents/doc/size.html b/documents/doc/size.html index 0be1a76..6946145 100644 --- a/documents/doc/size.html +++ b/documents/doc/size.html @@ -3,8 +3,6 @@ - - FatFs - f_size @@ -57,6 +55,7 @@ FSIZE_t f_size (

    f_open, f_lseek, FIL

    +

    Return

    diff --git a/documents/doc/stat.html b/documents/doc/stat.html index a4e4fc8..841fef1 100644 --- a/documents/doc/stat.html +++ b/documents/doc/stat.html @@ -3,8 +3,6 @@ - - FatFs - f_stat @@ -26,7 +24,7 @@ FRESULT f_stat (

    Parameters

    path
    -
    Pointer to the null-terminated string that specifies the object to get its information. The object must not be the root direcotry.
    +
    Pointer to the null-terminated string that specifies the object to get its information. The object must not be the root direcotry. If a null pointer is given, the function fails with FR_INVALID_DRIVE.
    fno
    Pointer to the blank FILINFO structure to store the information of the object. Set null pointer if this information is not needed.
    @@ -54,8 +52,8 @@ FRESULT f_stat (

    Description

    -

    The f_stat function checks the existence of a file or sub-directory in the directory. If it is not exist, the function returns with FR_NO_FILE. If it is exist, the function returns with FR_OK and the informations about the object, size, timestamp and attribute, is stored to the file information structure. For details of the file information, refer to the FILINFO structure and f_readdir function.

    -

    Note that the file information comes from the meta data in the directory. If the file has been opend and modified, the file will need to be synched or closed in order to obtain the latest file information.

    +

    The f_stat function checks the existence of a file or sub-directory. If it is not exist, the function returns with FR_NO_FILE. If it is exist, the function returns with FR_OK and the informations about the object, size, timestamp and attribute, is stored to the file information structure. For details of the file information, refer to the FILINFO structure and f_readdir function.

    +

    Note that the file information comes from the meta data in the directory. If the file has been opend and modified, the file will need to be synced or closed in order to obtain the latest file information. This function cannot be used to retrieve the long file name with the short file name.

    @@ -92,6 +90,7 @@ FRESULT f_stat ( break; case FR_NO_FILE: + case FR_NO_PATH: printf("\"%s\" is not exist.\n", fname); break; @@ -107,6 +106,7 @@ FRESULT f_stat (

    f_opendir, f_readdir, FILINFO

    +

    Return

    diff --git a/documents/doc/sync.html b/documents/doc/sync.html index 9fb42a0..f135c5b 100644 --- a/documents/doc/sync.html +++ b/documents/doc/sync.html @@ -3,8 +3,6 @@ - - FatFs - f_sync @@ -68,7 +66,7 @@ C - f_close() w - f_write() S - f_sync() -

    However there is no sense in f_sync function immediataly before f_close function because it performs f_sync function in it. In other words, the differnce between those functions is that the file object is invalidated or not.

    +

    However there is no sense in f_sync function jsut before f_close function, because the f_close performs f_sync in it. Actually, the differnce between these functions is that the file object is invalidated or not.

    @@ -83,6 +81,7 @@ S - f_sync()

    f_close, Critical section

    +

    Return

    diff --git a/documents/doc/tell.html b/documents/doc/tell.html index 075f033..c40ebe5 100644 --- a/documents/doc/tell.html +++ b/documents/doc/tell.html @@ -3,8 +3,6 @@ - - FatFs - f_tell @@ -57,6 +55,7 @@ FSIZE_t f_tell (

    f_open, f_lseek, FIL

    +

    Return

    diff --git a/documents/doc/truncate.html b/documents/doc/truncate.html index 0ac012f..bbc335b 100644 --- a/documents/doc/truncate.html +++ b/documents/doc/truncate.html @@ -3,8 +3,6 @@ - - FatFs - f_truncate @@ -25,7 +23,7 @@ FRESULT f_truncate (

    Parameter

    fp
    -
    Pointer to the open file object to be truncated.
    +
    Pointer to the open file object to be truncated. If a null pointer is given, the function fails with FR_INVALID_OBJECT.
    diff --git a/documents/doc/unlink.html b/documents/doc/unlink.html index 7809648..f8e1d20 100644 --- a/documents/doc/unlink.html +++ b/documents/doc/unlink.html @@ -3,8 +3,6 @@ - - FatFs - f_unlink @@ -25,7 +23,7 @@ FRESULT f_unlink (

    Parameter

    path
    -
    Pointer to a null-terminated string that specifies the file or sub-directory to be removed.
    +
    Pointer to a null-terminated string that specifies the file or sub-directory to be removed. If a null pointer is given, the function fails with FR_INVALID_DRIVE.
    diff --git a/documents/doc/utime.html b/documents/doc/utime.html index 40e39eb..4d8f78b 100644 --- a/documents/doc/utime.html +++ b/documents/doc/utime.html @@ -3,8 +3,6 @@ - - FatFs - f_utime @@ -26,7 +24,7 @@ FRESULT f_utime (

    Parameters

    path
    -
    Pointer to the null-terminated string that specifies an object to be changed.
    +
    Pointer to the null-terminated string that specifies an object to be changed. If a null pointer is given, the function fails with FR_INVALID_DRIVE.
    fno
    Pointer to the file information structure that has a timestamp to be set in member fdate and ftime. Do not care any other members.
    @@ -94,6 +92,7 @@ FRESULT set_timestamp (

    f_stat, FILINFO

    +

    Return

    diff --git a/documents/doc/write.html b/documents/doc/write.html index 3d16674..78d525e 100644 --- a/documents/doc/write.html +++ b/documents/doc/write.html @@ -3,8 +3,6 @@ - - FatFs - f_write @@ -28,13 +26,13 @@ FRESULT f_write (

    Parameters

    fp
    -
    Pointer to the open file object structure.
    +
    Pointer to the open file object structure. If a null pointer is given, the function fails with FR_INVALID_OBJECT.
    buff
    Pointer to the data to be written.
    btw
    Specifies number of bytes to write in range of UINT type. If the data needs to be written fast, it should be written in large chunk as possible.
    bw
    -
    Pointer to the UINT variable that receives the number of bytes written. This value is always valid after the function call regardless of the function return code. If the return value is equal to btw, the function return code should be FR_OK.
    +
    Pointer to the variable in UINT type that receives the number of bytes written. This value is always valid after the function call regardless of the function return code. If the return value is equal to btw, the function return code should be FR_OK.
    @@ -54,7 +52,7 @@ FRESULT f_write (

    Description

    -

    The function starts to write data to the file at the file offset pointed by read/write pointer. The read/write pointer advances as number of bytes written. After the function succeeded, *bw should be checked to detect the disk full. In case of *bw < btw, it means the volume got full during the write operation. The function can take a time when the volume is full or close to full.

    +

    The function starts to write data to the file at the file offset pointed by read/write pointer of the file object. The read/write pointer advances as number of bytes written. After the function succeeded, *bw should be checked to detect the disk full. In case of *bw < btw, it means the volume got full during the write operation. The function can take a time when the volume is full or close to full.

    @@ -75,6 +73,7 @@ FRESULT f_write (

    f_open, f_read, fputc, fputs, fprintf, f_close, FIL

    +

    Return

    diff --git a/documents/res/funcs.png b/documents/res/funcs.png index 022cd74..f381ec5 100644 Binary files a/documents/res/funcs.png and b/documents/res/funcs.png differ diff --git a/documents/res/layers2.png b/documents/res/layers2.png index 406c453..c7dbef4 100644 Binary files a/documents/res/layers2.png and b/documents/res/layers2.png differ diff --git a/documents/res/mkfs.xls b/documents/res/mkfs.xls deleted file mode 100644 index ee6b2bf..0000000 Binary files a/documents/res/mkfs.xls and /dev/null differ diff --git a/documents/res/mkfs.xlsx b/documents/res/mkfs.xlsx index e69de29..6024888 100644 Binary files a/documents/res/mkfs.xlsx and b/documents/res/mkfs.xlsx differ diff --git a/documents/res/modules.png b/documents/res/modules.png index 885a15a..d7e69a3 100644 Binary files a/documents/res/modules.png and b/documents/res/modules.png differ diff --git a/documents/res/uniconv.zip b/documents/res/uniconv.zip index e69de29..be7d84f 100644 Binary files a/documents/res/uniconv.zip and b/documents/res/uniconv.zip differ diff --git a/documents/updates.html b/documents/updates.html index 29d881f..24b8fd4 100644 --- a/documents/updates.html +++ b/documents/updates.html @@ -6,7 +6,7 @@ -FatFs - Known Problems +FatFs - Updates and Migration Notes

    Updates and Migration Notes

    @@ -23,7 +23,7 @@ Fixed string functions cannot write the unicode characters not in BMP when F Fixed a compatibility issue in identification of GPT header.
    -User provided synchronization functions, ff_cre_syncobj, ff_del_syncobj, ff_req_grant and ff_rel_grant, needed when FF_FS_REENTRANT are replaced by ff_mutex_create, ff_mutex_delete, ff_mutex_take and ff_mutex_give respectively. For examples, see ffsystem.c.
    +User provided synchronization functions, ff_cre_syncobj, ff_del_syncobj, ff_req_grant and ff_rel_grant, needed when FF_FS_REENTRANT are replaced with ff_mutex_create, ff_mutex_delete, ff_mutex_take and ff_mutex_give respectively. For example, see ffsystem.c.
    FF_SYNC_t is removed from the configuration options.
    @@ -172,10 +172,12 @@ Fixed errors in the case conversion teble of Unicode (cc*.c).
    Usage and members of FINFO sructure used in f_readdir is changed.
    +Dot entries in the sub-directory are never appear in f_readdir.
    +".." does not work as path name in exFAT volume.
    +f_getcwd does not work in exFAT volume.
    Many members in FIL and DIR structure are changed.
    To use f_chmod, _USE_CHMOD needs to be set.
    _WORD_ACCESS is removed from the configuration options.
    -Dot entries are never appear in f_reeddir.
    diff --git a/source/00history.txt b/source/00history.txt index 4fa1d7a..29c76b0 100644 --- a/source/00history.txt +++ b/source/00history.txt @@ -367,3 +367,11 @@ R0.15 (November 6, 2022) Fixed string functions cannot write the unicode characters not in BMP when FF_LFN_UNICODE == 2 (UTF-8). Fixed a compatibility issue in identification of GPT header. + + +R0.15a (November 22, 2024) + Fixed a complie error when FF_FS_LOCK != 0. + Fixed a potential issue when work FatFs concurrency with FF_FS_REENTRANT, FF_VOLUMES >= 2 and FF_FS_LOCK > 0. + Made f_setlabel() accept a volume label in Unix style volume ID when FF_STR_VOLUME_ID == 2. + Made FatFs update PercInUse field in exFAT VBR. (A preceding f_getfree() is needed for the accuracy) + diff --git a/source/diskio.c b/source/diskio.c index 8b16927..4c4d0a8 100644 --- a/source/diskio.c +++ b/source/diskio.c @@ -6,6 +6,7 @@ /* This is an example of glue functions to attach various exsisting */ /* storage control modules to the FatFs module with a defined API. */ /*-----------------------------------------------------------------------*/ + #include "ff.h" /* Obtains integer types */ #include "diskio.h" /* Declarations of disk functions */ #ifndef __LITEOS_M__ diff --git a/source/diskio.h b/source/diskio.h index e2860a0..60fb49e 100644 --- a/source/diskio.h +++ b/source/diskio.h @@ -1,5 +1,5 @@ /*-----------------------------------------------------------------------/ -/ Low level disk interface modlue include file (C)ChaN, 2014 / +/ Low level disk interface modlue include file (C)ChaN, 2019 / /-----------------------------------------------------------------------*/ #ifndef _DISKIO_DEFINED diff --git a/source/ff.c b/source/ff.c index 5bc8493..625d84d 100644 --- a/source/ff.c +++ b/source/ff.c @@ -1,8 +1,8 @@ /*----------------------------------------------------------------------------/ -/ FatFs - Generic FAT Filesystem Module R0.15 w/patch2 / +/ FatFs - Generic FAT Filesystem Module R0.15a w/patch 1 / /-----------------------------------------------------------------------------/ / -/ Copyright (C) 2022, ChaN, all right reserved. +/ Copyright (C) 2024, 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 @@ -39,7 +39,7 @@ ---------------------------------------------------------------------------*/ -#if FF_DEFINED != 80286 /* Revision ID */ +#if FF_DEFINED != 5380 /* Revision ID */ #error Wrong include file (ff.h). #endif diff --git a/source/ff.h b/source/ff.h index dad9b64..dc0c8b9 100644 --- a/source/ff.h +++ b/source/ff.h @@ -1,8 +1,8 @@ /*----------------------------------------------------------------------------/ -/ FatFs - Generic FAT Filesystem module R0.15 / +/ FatFs - Generic FAT Filesystem module R0.15a / /-----------------------------------------------------------------------------/ / -/ Copyright (C) 2022, ChaN, all right reserved. +/ Copyright (C) 2024, 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 @@ -20,7 +20,7 @@ #ifndef FF_DEFINED -#define FF_DEFINED 80286 /* Revision ID */ +#define FF_DEFINED 5380 /* Revision ID */ #ifdef __cplusplus extern "C" { diff --git a/source/ffconf.h b/source/ffconf.h index c5052b4..3af96fd 100644 --- a/source/ffconf.h +++ b/source/ffconf.h @@ -19,7 +19,7 @@ extern "C" { #endif /* __cplusplus */ #endif /* __cplusplus */ -#define FFCONF_DEF 80286 /* Revision ID */ +#define FFCONF_DEF 5380 /* Revision ID */ /*---------------------------------------------------------------------------/ / Function Configurations diff --git a/source/ffsystem.c b/source/ffsystem.c index ee1e414..e0a30a3 100644 --- a/source/ffsystem.c +++ b/source/ffsystem.c @@ -1,6 +1,5 @@ /*------------------------------------------------------------------------*/ -/* Sample Code of OS Dependent Functions for FatFs */ -/* (C)ChaN, 2018 */ +/* A Sample Code of User Provided OS Dependent Functions for FatFs */ /*------------------------------------------------------------------------*/