Home Explore Help
Register Sign In
embedded
/
owner-nrf52sdk
2
0
Fork 0
Files Issues 0 Pull Requests 0 Wiki
Tree: fd41ddea6b
Branches Tags
owner-nrf52sdk
/
nRF5_SDK_17.0.2
/
external
/
fatfs
/
doc
/
en
/
config.html

config.html 14 KB
History Raw

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204 
  1. <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">
    2. 

  2. <html lang="en">
    3. 

  3. <head>
    4. 

  4. <meta http-equiv="Content-Type" content="text/html; charset=utf-8">
    5. 

  5. <meta http-equiv="Content-Style-Type" content="text/css">
    6. 

  6. <link rel="up" title="FatFs" href="../00index_e.html">
    7. 

  7. <link rel="alternate" hreflang="ja" title="Japanese" href="../ja/config.html">
    8. 

  8. <link rel="stylesheet" href="../css_e.css" type="text/css" media="screen" title="ELM Default">
    9. 

  9. <title>FatFs - Configuration Options</title>
    10. 

  10. </head>
    11. 

  11. 

  12. <body>
    13. 

  13. <h1>Configuration Options</h1>
    14. 

  14. <p>There are many options to configure the functions of FatFs for each project. The configuration options are defined in the <tt>ffconf.h</tt>.</p>
    15. 

  15. 

  16. <div class="para doc" id="func">
    17. 

  17. <h3>Function Configurations</h3>
    18. 

  18. 

  19. <h4 id="fs_readonly">_FS_READONLY</h4>
    20. 

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

  21. 

  22. <h4 id="fs_minimize">_FS_MINIMIZE</h4>
    23. 

  23. <p>This option defines minimization level to remove some basic API functions as follows:</p>
    24. 

  24. <table class="lst1">
    25. 

  25. <tr><th>Value</th><th>Description</th></tr>
    26. 

  26. <tr><td>0</td><td>All basic API functions are available.</td></tr>
    27. 

  27. <tr><td>1</td><td><tt>f_stat</tt>, <tt>f_getfree</tt>, <tt>f_unlink</tt>, <tt>f_mkdir</tt>, <tt>f_chmod</tt>, <tt>f_utime</tt>, <tt>f_truncate</tt> and <tt>f_rename</tt> function are removed.</td></tr>
    28. 

  28. <tr><td>2</td><td><tt>f_opendir</tt>, <tt>f_readdir</tt> and <tt>f_closedir</tt> function are removed in addition to 1.</td></tr>
    29. 

  29. <tr><td>3</td><td><tt>f_lseek</tt> function is removed in addition to 2.</td></tr>
    30. 

  30. </table>
    31. 

  31. 

  32. <h4 id="use_strfunc">_USE_STRFUNC</h4>
    33. 

  33. <p>This option switches string functions, <tt>f_gets</tt>, <tt>f_putc</tt>, <tt>f_puts</tt> and <tt>f_printf</tt>.</p>
    34. 

  34. <table class="lst1">
    35. 

  35. <tr><th>Value</th><th>Description</th></tr>
    36. 

  36. <tr><td>0</td><td>Disable string functions.</td></tr>
    37. 

  37. <tr><td>1</td><td>Enable string functions without LF-CRLF conversion.</td></tr>
    38. 

  38. <tr><td>2</td><td>Enable string functions with LF-CRLF conversion.</td></tr>
    39. 

  39. </table>
    40. 

  40. 

  41. <h4 id="use_find">_USE_FIND</h4>
    42. 

  42. <p>Disable (0) or Enable (1) filtered directory read functions, <tt>f_findfirst</tt> and <tt>f_findnext</tt>. Also <tt>_FS_MINIMIZE</tt> needs to be 0 or 1.</p>
    43. 

  43. 

  44. <h4 id="use_mkfs">_USE_MKFS</h4>
    45. 

  45. <p>Disable (0) or Enable (1) <tt>f_mkfs</tt> function.</p>
    46. 

  46. 

  47. <h4 id="use_fastseek">_USE_FASTSEEK</h4>
    48. 

  48. <p>Disable (0) or Enable (1) fast seek function to enable accelerated mode for <tt>f_lseek</tt>, <tt>f_read</tt> and <tt>f_write</tt> function. For more information, read <a href="lseek.html">here</a>.</p>
    49. 

  49. 

  50. <h4 id="use_expand">_USE_EXPAND</h4>
    51. 

  51. <p>Disable (0) or Enable (1) , <tt>f_enpand</tt> function. Also <tt>_FS_READONLY</tt> needs to be 0.</p>
    52. 

  52. 

  53. <h4 id="use_chmod">_USE_CHMOD</h4>
    54. 

  54. <p>Disable (0) or Enable (1) metadata control functions, <tt>f_chmod</tt> and <tt>f_utime</tt>. Also <tt>_FS_READONLY</tt> needs to be 0.</p>
    55. 

  55. 

  56. <h4 id="use_label">_USE_LABEL</h4>
    57. 

  57. <p>Disable (0) or Enable (1) API functions for volume label, <tt>f_getlabel</tt> and <tt>f_setlabel</tt>.</p>
    58. 

  58. 

  59. <h4 id="use_forward">_USE_FORWARD</h4>
    60. 

  60. <p>Disable (0) or Enable (1) <tt>f_forward</tt> function.</p>
    61. 

  61. 

  62. </div>
    63. 

  63. 

  64. 

  65. <div class="para doc" id="name">
    66. 

  66. <h3>Namespace and Locale Configurations</h3>
    67. 

  67. 

  68. <h4 id="code_page">_CODE_PAGE</h4>
    69. 

  69. <p>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 extended character is not used at all, there is no difference between any code pages.</p>
    70. 

  70. <table class="lst1">
    71. 

  71. <tr><th>Value</th><th>Description</th></tr>
    72. 

  72. <tr><td>1</td><td>ASCII (valid at non-LFN cfg.)</td></tr>
    73. 

  73. <tr><td>437</td><td>U.S.</td></tr>
    74. 

  74. <tr><td>720</td><td>Arabic</td></tr>
    75. 

  75. <tr><td>737</td><td>Greek</td></tr>
    76. 

  76. <tr><td>771</td><td>KBL</td></tr>
    77. 

  77. <tr><td>775</td><td>Baltic</td></tr>
    78. 

  78. <tr><td>850</td><td>Latin 1</td></tr>
    79. 

  79. <tr><td>852</td><td>Latin 2</td></tr>
    80. 

  80. <tr><td>855</td><td>Cyrillic</td></tr>
    81. 

  81. <tr><td>857</td><td>Turkish</td></tr>
    82. 

  82. <tr><td>860</td><td>Portuguese</td></tr>
    83. 

  83. <tr><td>861</td><td>Icelandic</td></tr>
    84. 

  84. <tr><td>862</td><td>Hebrew</td></tr>
    85. 

  85. <tr><td>863</td><td>Canadian French</td></tr>
    86. 

  86. <tr><td>864</td><td>Arabic</td></tr>
    87. 

  87. <tr><td>865</td><td>Nordic</td></tr>
    88. 

  88. <tr><td>866</td><td>Russian</td></tr>
    89. 

  89. <tr><td>869</td><td>Greek 2</td></tr>
    90. 

  90. <tr><td>932</td><td>Japanese (DBCS)</td></tr>
    91. 

  91. <tr><td>936</td><td>Simplified Chinese (DBCS)</td></tr>
    92. 

  92. <tr><td>949</td><td>Korean (DBCS)</td></tr>
    93. 

  93. <tr><td>950</td><td>Traditional Chinese (DBCS)</td></tr>
    94. 

  94. </table>
    95. 

  95. 

  96. <h4 id="use_lfn">_USE_LFN</h4>
    97. 

  97. <p>This option switches the support for long file name (LFN). When enable the LFN, Unicode support functions <tt>option/unicode.c</tt> need to be added to the project. The working buffer occupies <tt>(_MAX_LFN + 1) * 2</tt> bytes and additional 608 bytes when exFAT enabled. When use stack for the working buffer, take care on stack overflow. When use heap memory for the working buffer, memory management functions, <tt>ff_memalloc</tt> and <tt>ff_memfree</tt>, need to be added to the project.</p>
    98. 

  98. <table class="lst1">
    99. 

  99. <tr><th>Value</th><th>Description</th></tr>
    100. 

  100. <tr><td>0</td><td>Disable LFN. Only 8.3 format can be used.</td></tr>
    101. 

  101. <tr><td>1</td><td>Enable LFN with static working buffer on the BSS. Always NOT thread-safe.</td></tr>
    102. 

  102. <tr><td>2</td><td>Enable LFN with dynamic working buffer on the STACK.</td></tr>
    103. 

  103. <tr><td>3</td><td>Enable LFN with dynamic working buffer on the HEAP.</td></tr>
    104. 

  104. </table>
    105. 

  105. 

  106. <h4 id="max_lfn">_MAX_LFN</h4>
    107. 

  107. <p>This option defines the size of LFN working buffer from 12 to 255 in unit of character. This option has no effect when LFN is disabled.</p>
    108. 

  108. 

  109. <h4 id="lfn_unicode">_LFN_UNICODE</h4>
    110. 

  110. <p>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 and set this option to 1. This option also affects behavior of string I/O functions. When LFN is disabled, this option must be 0. For more information, read <a href="filename.html#uni">here</a>.</p>
    111. 

  111. 

  112. <h4 id="strf_encode">_STRF_ENCODE</h4>
    113. 

  113. <p>When Unicode API is selected by setting <tt>_LFN_UNICODE</tt> 1, this option defines the assumption of character encoding on the file to be read/written via string I/O functions, <tt>f_gets</tt>, <tt>f_putc</tt>, <tt>f_puts</tt> and <tt>f_printf</tt>. This option has no effect when <tt>_LFN_UNICODE = 0</tt>.</p>
    114. 

  114. <table class="lst1">
    115. 

  115. <tr><th>Value</th><th>Description</th></tr>
    116. 

  116. <tr><td>0</td><td>ANSI/OEM</td></tr>
    117. 

  117. <tr><td>1</td><td>UTF-16LE</td></tr>
    118. 

  118. <tr><td>2</td><td>UTF-16BE</td></tr>
    119. 

  119. <tr><td>3</td><td>UTF-8</td></tr>
    120. 

  120. </table>
    121. 

  121. 

  122. <h4 id="fs_rpath">_FS_RPATH</h4>
    123. 

  123. <p>This option configures relative path function. For more information, read <a href="filename.html#nam">here</a>.</p>
    124. 

  124. <table class="lst1">
    125. 

  125. <tr><th>Value</th><th>Description</th></tr>
    126. 

  126. <tr><td>0</td><td>Disable relative path function and remove related functions.</td></tr>
    127. 

  127. <tr><td>1</td><td>Enable relative path function. <tt>f_chdir</tt> and <tt>f_chdrive</tt> function is available.</td></tr>
    128. 

  128. <tr><td>2</td><td><tt>f_getcwd</tt> function is available in addition to 1</td></tr>
    129. 

  129. </table>
    130. 

  130. 

  131. </div>
    132. 

  132. 

  133. 

  134. <div class="para doc" id="volume">
    135. 

  135. <h3>Volume/Drive Configurations</h3>
    136. 

  136. 

  137. <h4 id="volumes">_VOLUMES</h4>
    138. 

  138. <p>This option configures number of volumes (logical drives, from 1 to 10) to be used.</p>
    139. 

  139. 

  140. <h4 id="str_volume_id">_STR_VOLUME_ID</h4>
    141. 

  141. <p>Disable (0) or Enable (1). This option switches the support for string volume ID. When enabled, also pre-defined strings in <tt>_VOLUME_STRS</tt> can be used as drive identifier in the path name.</p>
    142. 

  142. 

  143. <h4 id="volume_strs">_VOLUME_STRS</h4>
    144. 

  144. <p>This option defines the drive ID strings for each logical drives. Number of items must not be less than <tt>_VOLUMES</tt>. Valid characters for the drive ID string are: A-Z and 0-9.</p>
    145. 

  145. 

  146. <h4 id="multi_partition">_MULTI_PARTITION</h4>
    147. 

  147. <p>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 an FAT 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 <tt>VolToPart[]</tt>. Also <tt>f_fdisk</tt> funciton will be available. For more information, read <a href="filename.html#vol">here</a>.</p>
    148. 

  148. 

  149. <h4 id="max_ss">_MIN_SS, _MAX_SS</h4>
    150. 

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

  151. 

  152. <h4 id="use_trim">_USE_TRIM</h4>
    153. 

  153. <p>Disable (0) or Enable (1). This option switches ATA-TRIM function. To enable Trim function, also <tt>CTRL_TRIM</tt> command should be implemented to the <tt>disk_ioctl</tt> function.</p>
    154. 

  154. 

  155. <h4 id="fs_nofsinfo">_FS_NOFSINFO</h4>
    156. 

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

  157. <table class="lst1">
    158. 

  158. <tr><th>Value</th><th>Description</th></tr>
    159. 

  159. <tr><td>bit0=0</td><td>Use free cluster count in the FSINFO if available.</td></tr>
    160. 

  160. <tr><td>bit0=1</td><td>Do not trust free cluster count in the FSINFO.</td></tr>
    161. 

  161. <tr><td>bit1=0</td><td>Use last allocated cluster number in the FSINFO to find a free cluster if available.</td></tr>
    162. 

  162. <tr><td>bit1=1</td><td>Do not trust last allocated cluster number in the FSINFO.</td></tr>
    163. 

  163. </table>
    164. 

  164. 

  165. </div>
    166. 

  166. 

  167. 

  168. <div class="para doc" id="system">
    169. 

  169. <h3>System Configurations</h3>
    170. 

  170. 

  171. <h4 id="fs_tiny">_FS_TINY</h4>
    172. 

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

  173. 

  174. <h4 id="fs_exfat">_FS_EXFAT</h4>
    175. 

  175. <p>This option switches support for the exFAT file system in addition to the FAT file system, Enabled(1) or Disabled(1). To enable this feature, also LFN must be enabled and configureing <tt>_LFN_UNICODE = 1</tt> and <tt>_MAX_LFN = 255</tt> is recommended for full-featured exFAT function. Note that enabling exFAT discards C89 compatibility because of need for 64-bit integer type.</p>
    176. 

  176. 

  177. <h4 id="fs_nortc">_FS_NORTC</h4>
    178. 

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

  179. 

  180. <h4 id="nortc_time">_NORTC_MON, _NORTC_MDAY, _NORTC_YEAR</h4>
    181. 

  181. <p>This set of options defines the time to be used at no RTC systems. This option has no effect at read-only configuration or <tt>_FS_NORTC = 0</tt>.</p>
    182. 

  182. 

  183. <h4 id="fs_lock">_FS_LOCK</h4>
    184. 

  184. <p>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.</p>
    185. 

  185. <table class="lst1">
    186. 

  186. <tr><th>Value</th><th>Description</th></tr>
    187. 

  187. <tr><td>0</td><td>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.</td></tr>
    188. 

  188. <tr><td>&gt;0</td><td>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 <tt>FR_LOCKED</tt>.</td></tr>
    189. 

  189. </table>
    190. 

  190. 

  191. <h4 id="fs_reentrant">_FS_REENTRANT</h4>
    192. 

  192. <p>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. <tt>f_mount</tt>, <tt>f_mkfs</tt> and <tt>f_fdisk</tt>, 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 function. To enable this feature, also user provided synchronization handlers, <tt>ff_req_grant</tt>, <tt>ff_rel_grant</tt>, <tt>ff_del_syncobj</tt> and <tt>ff_cre_syncobj</tt>, need to be added to the project. Sample code is available in <tt>option/syscall.c</tt>.</p>
    193. 

  193. 

  194. <h4 id="fs_timeout">_FS_TIMEOUT</h4>
    195. 

  195. <p>Number of time ticks to abort the file function with <tt>FR_TIMEOUT</tt> when wait time is too long. This option has no effect when <tt>_FS_REENTRANT = 0</tt>.</p>
    196. 

  196. 

  197. <h4 id="sync_t">_SYNC_t</h4>
    198. 

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

  199. 

  200. </div>
    201. 

  201. 

  202. <p class="foot"><a href="../00index_e.html">Return</a></p>
    203. 

  203. </body>
    204. 

  204. </html>
    205.