FatFs - Configuration Options

# Configuration Options

There are many options to configure the functions of FatFs for requirement of each project. The configuration options are defined in the `ffconf.h`.

- Function Configurations
  - FF_FS_READONLY
  - FF_FS_MINIMIZE
  - FF_USE_STRFUNC
  - FF_USE_FIND
  - FF_USE_MKFS
  - FF_USE_FASTSEEK
  - FF_USE_EXPAND
  - FF_USE_CHMOD
  - FF_USE_LABEL
  - FF_USE_FORWARD
- Namespace and Locale Configurations
  - FF_CODE_PAGE
  - FF_USE_LFN
  - FF_MAX_LFN
  - FF_LFN_UNICODE
  - FF_LFN_BUF, FF_SFN_BUF
  - FF_STRF_ENCODE
  - FF_FS_RPATH
- Volume/Drive Configurations
  - FF_VOLUMES
  - FF_STR_VOLUME_ID
  - FF_VOLUME_STRS
  - FF_MULTI_PARTITION
  - FF_MIN_SS, FF_MAX_SS
  - FF_USE_TRIM
  - FF_FS_NOFSINFO
- System Configurations
  - FF_FS_TINY
  - FF_FS_EXFAT
  - FF_FS_NORTC
  - FF_NORTC_MON, FF_NORTC_MDAY, FF_NORTC_YEAR
  - FF_FS_LOCK
  - FF_FS_REENTRANT
  - FF_FS_TIMEOUT
  - FF_SYNC_t

### Function Configurations

#### FF_FS_READONLY

Read/Write (0) or Read-only (1). Read-only configuration removes writing API functions, `f_write`, `f_sync`, `f_unlink`, `f_mkdir`, `f_chmod`, `f_rename`, `f_truncate`, `f_getfree` and optional writing functions as well.

#### FF_FS_MINIMIZE

This option defines minimization level to remove some basic API functions as follows:

Value | Description
--- | ---
0 | All basic API functions are available.
1 | `f_stat`, `f_getfree`, `f_unlink`, `f_mkdir`, `f_chmod`, `f_utime`, `f_truncate` and `f_rename` function are removed.
2 | `f_opendir`, `f_readdir` and `f_closedir` function are removed in addition to 1.
3 | `f_lseek` function is removed in addition to 2.

#### FF_USE_STRFUNC

This option switches string functions, `f_gets`, `f_putc`, `f_puts` and `f_printf`.

Value | Description
--- | ---
0 | Disable string functions.
1 | Enable string functions without LF-CRLF conversion.
2 | Enable string functions with LF-CRLF conversion.

#### FF_USE_FIND

Disable (0) or Enable (1) filtered directory read functions, `f_findfirst` and `f_findnext`. Also `FF_FS_MINIMIZE` needs to be 0 or 1.

#### FF_USE_MKFS

Disable (0) or Enable (1) `f_mkfs` function.

#### FF_USE_FASTSEEK

Disable (0) or Enable (1) fast seek function to enable accelerated mode for `f_lseek`, `f_read` and `f_write` function. For more information, read here.

#### FF_USE_EXPAND

Disable (0) or Enable (1) `f_expand` function.

#### FF_USE_CHMOD

Disable (0) or Enable (1) metadata control functions, `f_chmod` and `f_utime`. Also `FF_FS_READONLY` needs to be 0.

#### FF_USE_LABEL

Disable (0) or Enable (1) API functions for volume label, `f_getlabel` and `f_setlabel`.

#### FF_USE_FORWARD

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

### Namespace and Locale Configurations

#### FF_CODE_PAGE

This option specifies the OEM code page to be used on the target system. Incorrect setting of the code page can cause a file open failure. If any non-ASCII character is not used at all, there is no difference between any code page settings.

Value | Code page
--- | ---
0 | Include all code pages below and set by `f_setcp()`
437 | U.S.
720 | Arabic
737 | Greek
771 | KBL
775 | Baltic
850 | Latin 1
852 | Latin 2
855 | Cyrillic
857 | Turkish
860 | Portuguese
861 | Icelandic
862 | Hebrew
863 | Canadian French
864 | Arabic
865 | Nordic
866 | Russian
869 | Greek 2
932 | Japanese (DBCS)
936 | Simplified Chinese (DBCS)
949 | Korean (DBCS)
950 | Traditional Chinese (DBCS)

#### FF_USE_LFN

This option switches the support for long file name (LFN). When enable the LFN, Unicode support module `ffunicode.c` need to be added to the project. When use stack for the working buffer, take care on stack overflow. When use heap memory for the working buffer, memory management functions (`ff_memalloc` and `ff_memfree`) need to be added to the project.

Value | Description
--- | ---
0 | Disable LFN. Path name in only 8.3 format can be used.
1 | Enable LFN with static working buffer on the BSS. Always NOT thread-safe.
2 | Enable LFN with dynamic working buffer on the STACK.
3 | Enable LFN with dynamic working buffer on the HEAP.

#### FF_MAX_LFN

LFN function requiers certain internal working buffer for the file name. This option defines size of the buffer and the value can be in range of 12 to 255 in UTF-16 encoding unit of the LFN. The buffer occupies `(FF_MAX_LFN + 1) * 2` bytes and additional `(FF_MAX_LFN + 44) / 15 * 32` bytes when exFAT is enabled. It is recommended to be set 255 to fully support the LFN specification. This option has no effect when LFN is not enabled.

#### FF_LFN_UNICODE

This option switches character encoding for the file name on the API. When Unicode is selected, `FF_CODE_PAGE` has actually no meaning except for compatibility with legacy systems. FatFs supports the code point upto U+10FFFF.

Value | Character Encoding | TCHAR
--- | --- | ---
0 | ANSI/OEM in current CP | char
1 | Unicode in UTF-16 | WCHAR
2 | Unicode in UTF-8 | char

This option also affects behavior of string I/O functions (see `FF_STRF_ENCODE`). When LFN is not enabled, this option has no effect and FatFs works at ANSI/OEM code on the API. For more information, read here.

#### FF_LFN_BUF, FF_SFN_BUF

This set of options defines size of file name members, `fname[]` and `altname[]`, in the `FILINFO` structure which is used to read out the directory items. These values should be suffcient for the file names to read. The maximum possible length of the read file name depends on the character encoding on the API as follows:

Encoding | LFN length | SFN length
--- | --- | ---
ANSI/OEM at SBCS | 255 items | 12 items
ANSI/OEM at DBCS | 510 items | 12 items
Unicode in UTF-16 | 255 items | 12 items
Unicode in UTF-8 | 765 items | 34 items

If the size of name member is insufficient for the LFN, the item is treated as without LFN. When LFN is not enabled, these options have no effect.

#### FF_STRF_ENCODE

When character encoding on the API is Unicode (`FF_LFN_UNICODE >= 1`), string I/O functions, `f_gets`, `f_putc`, `f_puts` and `f_printf`, convert the character encodins 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.

Value | Description
--- | ---
0 | ANSI/OEM in current CP
1 | Unicode in UTF-16LE
2 | Unicode in UTF-16BE
3 | Unicode in UTF-8

#### FF_FS_RPATH

This option configures relative path function. For more information, read here.

Value | Description
--- | ---
0 | Disable relative path function and remove related functions.
1 | Enable relative path function. `f_chdir` and `f_chdrive` function is available.
2 | `f_getcwd` function is available in addition to 1

### Volume/Drive Configurations

#### FF_VOLUMES

This option configures number of volumes (logical drives, from 1 to 10) to be used.

#### FF_STR_VOLUME_ID

Disable (0) or Enable (1). This option switches the support for string volume ID. When enabled, also pre-defined strings in `FF_VOLUME_STRS` can be used as drive identifier in the path name.

#### FF_VOLUME_STRS

This option defines the drive ID strings for each logical drives. Number of items must not be less than `FF_VOLUMES`. Valid characters for the drive ID string are: A-Z and 0-9.

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

#### FF_MIN_SS, FF_MAX_SS

This set of options defines the extent of sector size used on 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.

#### FF_USE_TRIM

Disable (0) or Enable (1). This option switches ATA-TRIM function. To enable Trim function, also `CTRL_TRIM` command should be implemented to the `disk_ioctl` function.

#### FF_FS_NOFSINFO

0 to 3. If you need to know correct free space on the FAT32 volume, set bit 0 of this option, and `f_getfree` function at first time after volume mount will force a full FAT scan. Bit 1 controls the use of last allocated cluster number.

Value | Description
--- | ---
bit0=0 | Use free cluster count in the FSINFO if available.
bit0=1 | Do not trust free cluster count in the FSINFO.
bit1=0 | Use last allocated cluster number in the FSINFO to find a free cluster if available.
bit1=1 | Do not trust last allocated cluster number in the FSINFO.

### System Configurations

#### FF_FS_TINY

Normal (0) or Tiny (1). At the tiny configuration, size of the file object `FIL` is reduced `FF_MAX_SS` bytes. Instead of private data buffer eliminated from the file object, common sector buffer in the filesystem object `FATFS` is used for the file data transfer.

#### FF_FS_EXFAT

This option switches support for the exFAT filesystem in addition to the FAT/FAT32 filesystem, Enabled (1) or Disabled (0). To enable exFAT, also LFN must be enabled and configureing `FF_LFN_UNICODE >= 1` and `FF_MAX_LFN == 255` is recommended for full-featured exFAT function. Note that enabling exFAT discards ANSI C (C89) compatibility because of need for 64-bit integer type.

#### FF_FS_NORTC

Use RTC (0) or Do not use RTC (1). This option controls timestamp function. If the system does not have any RTC function or valid timestamp is not needed, set `FF_FS_NORTC` to 1 to disable the timestamp function. Every objects modified by FatFs will have a fixed timestamp defined by `FF_NORTC_MON`, `FF_NORTC_MDAY` and `FF_NORTC_YEAR`. To use the timestamp function, set `FF_FS_NORTC == 0` and add `get_fattime` function to the project to get current time form the RTC. This option has no effect at read-only configuration.

#### FF_NORTC_MON, FF_NORTC_MDAY, FF_NORTC_YEAR

This set of options defines the time to be used at no RTC systems. This option has no effect at read-only configuration or `FF_FS_NORTC == 0`.

#### FF_FS_LOCK

This option switches file lock function to control duplicated file open and illegal operations to open objects. Note that the file lock function is independent of re-entrancy. This option must be 0 at read-only configuration.

Value | Description
--- | ---
0 | Disable file lock function. To avoid collapsing file by wrong file operation, application program needs to avoid illegal open, remove and rename to the open objects.
>0 | Enable file lock function. The value defines how many files/sub-directories can be opened simultaneously under the file lock control. Illigal operations to the open object will be rejected with `FR_LOCKED`.

#### FF_FS_REENTRANT

Disable (0) or Enable (1). This option switches the re-entrancy (thread safe) of the FatFs module itself. Note that file/directory access to the different volume is always re-entrant and it can work simultaneously regardless of this option but volume control functions. `f_mount`, `f_mkfs` and `f_fdisk`, are always not re-entrant. Only file/directory access to the same volume, in other words, exclusive use of each filesystem object, is under control of this function. To enable this feature, also user provided synchronization handlers, `ff_req_grant`, `ff_rel_grant`, `ff_del_syncobj` and `ff_cre_syncobj`, need to be added to the project. Sample code is available in `ffsystem.c`.

#### FF_FS_TIMEOUT

Number of time ticks to abort the file function with `FR_TIMEOUT` when wait time is too long. This option has no effect when `FF_FS_REENTRANT == 0`.

#### FF_SYNC_t

This option defines O/S dependent sync object type. e.g. `HANDLE`, `ID`, `OS_EVENT*`, `SemaphoreHandle_t` and etc. A header file for O/S definitions needs to be included somewhere in the scope of `ff.c`. This option has no effect when `FF_FS_REENTRANT == 0`.

Return