# Configuration Options

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

### Function Configurations

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

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

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

#### _USE_FIND

Disable(0) or Enable(1). This option switches filtered directory read feature and related functions, `f_findfirst` and `f_findnext`.

#### _USE_MKFS

Disable(0) or Enable(1). This option switches `f_mkfs` function.

#### _USE_FASTSEEK

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

#### _USE_LABEL

Disable(0) or Enable(1). This option switches volume label functions, `f_getlabel` and `f_setlabel`.

#### _USE_FORWARD

Disable(0) or Enable(1). This option switches `f_forward` function. also `_FS_TINY` needs to be set to 1.

### Namespace and Locale Configurations

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

Value | Description
--- | ---
1 | ASCII (No extended character. Valid at Non-LFN configuration only)
437 | United States
720 | Arabic
737 | Greek
775 | Baltic
850 | Multilingual Latin 1
852 | Latin 2
855 | Cyrillic
857 | Turkish
858 | Multilingual Latin 1 + Euro
862 | Hebrew
866 | Russian
874 | Thai
932 | Japanese Shift_JIS (DBCS)
936 | Simplified Chinese GBK (DBCS)
949 | Korean (DBCS)
950 | Traditional Chinese Big5 (DBCS)

#### _USE_LFN

This option switches the LFN feature. When enable the LFN feature, Unicode handling functions `option/unicode.c` must be added to the project. The LFN working buffer occupies `(_MAX_LFN + 1) * 2` bytes. 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`, must be added to the project.

Value | Description
--- | ---
0 | Disable LFN feature. 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.

#### _MAX_LFN

This option defines the size of LFN working buffer from 12 to 255 in unit of character. This option has no effect when LFN feature is disabled.

#### _LFN_UNICODE

ANSI/OEM(0) or Unicode(1). This option switches character encoding on the API. To use Unicode (UTF16) string for the path name, enable LFN feature and set this option to 1. This option also affects behavior of string I/O functions. When LFN feature is disabled, this option must be 0. For more information, read here.

#### _STRF_ENCODE

When Unicode API is selected by `_LFN_UNICODE`, this option selects the character encoding on the file to be read/written via string I/O functions, `f_gets`, `f_putc`, `f_puts` and `f_printf`. This option has no effect when `_LFN_UNICODE == 0`.

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

#### _FS_RPATH

This option configures relative path feature. Note that directory items read via directory functions are affected by this option. For more information, read here.

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

### Volume/Drive Configurations

#### _VOLUMES

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

#### _STR_VOLUME_ID

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

#### _VOLUME_STRS

This option defines the drive ID strings for each logical drives. Number of items must be equal to `_VOLUMES`. Valid characters for the drive ID strings are: A-Z and 0-9.

#### _MULTI_PARTITION

Disable(0) or Enable(1). This option switches multi-partition feature. By default (0), each logical drive number is bound to the same physical drive number and only an FAT volume each physical drive are 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 enabled. For more information, read here.

#### _MIN_SS and _MAX_SS

This set of options defines size of sector on the low level disk I/O interface, `disk_read` and `disk_write` function. Valid numbers are 512, 1024, 2048 and 4096. `_MIN_SS` defines minimum size of sector and `_MAX_SS` defines the maximum size of sector. Always set both 512 for all type of memory cards and harddisk. But a larger value may be required for on-board flash memory and some type of optical media. When `_MAX_SS > _MIN_SS`, FatFs is configured to variable sector size and `GET_SECTOR_SIZE` command must be implemented to the `disk_ioctl` function.

#### _USE_TRIM

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

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

#### _FS_TINY

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

#### _FS_NORTC

Use RTC(0) or Do not use RTC(1). This option controls timestamp feature. If the system does not have an RTC function or valid timestamp is not needed, set `_FS_NORTC` to 1 to disable the timestamp feature. Any object modified by FatFs will have a fixed timestamp value defined by `_NORTC_MON`, `_NORTC_MDAY` and `_NORTC_YEAR`. To use the timestamp feature, set `_FS_NORTC` to 0 and add `get_fattime` function to the project to get the current time form RTC. This option has no effect at read-only configuration.

#### _NORTC_MON, _NORTC_MDAY and _NORTC_YEAR

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

#### _FS_LOCK

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

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

#### _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 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 file system object, is under control of this feature. To enable this feature, also user provided synchronization handlers, `ff_req_grant`, `ff_rel_grant`, `ff_del_syncobj` and `ff_cre_syncobj`, must be added to the project. Samples are available in `option/syscall.c`.

#### _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 `_FS_REENTRANT == 0`.

#### _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 `_FS_REENTRANT == 0`.

#### _WORD_ACCESS

This is an only platform dependent option. It defines which access method is used to the word data on the FAT volume.

Value | Description
--- | ---
0 | Byte-by-byte access. Always compatible with all platforms.
1 | Word access. Code size will be slightly reduced but do not choose this unless under both the following conditions. * Unaligned memory access is always allowed to ALL instructions. * Byte order on the memory is little-endian.

Following table shows an example of allowable settings of some type of processors.

       ARM7TDMI   0   *2         ColdFire   0   *1         V850E      0   *2
       Cortex-M3  0   *3         Z80        0/1            V850ES     0/1
       Cortex-M0  0   *2         x86        0/1            TLCS-870   0/1
       AVR        0/1            RX600(LE)  0/1            TLCS-900   0/1
       AVR32      0   *1         RL78       0   *2         R32C       0   *2
       PIC18      0/1            SH-2       0   *1         M16C       0/1
       PIC24      0   *2         H8S        0   *1         MSP430     0   *2
       PIC32      0   *1         H8/300H    0   *1         8051       0/1

       *1:Big-endian.
       *2:Unaligned memory access is not supported.
       *3:Some compilers generate LDM/STM for mem_cpy function.

Return