\r
<div class="para func">\r
<h2>f_mkfs</h2>\r
-<p>The f_mkfs fucntion creates an FAT file system on the logical drive.</p>\r
+<p>The f_mkfs fucntion creates an FAT/exFAT volume on the logical drive.</p>\r
<pre>\r
FRESULT f_mkfs (\r
const TCHAR* <span class="arg">path</span>, <span class="c">/* [IN] Logical drive number */</span>\r
- BYTE <span class="arg">sfd</span>, <span class="c">/* [IN] Partitioning rule */</span>\r
- UINT <span class="arg">au</span> <span class="c">/* [IN] Size of the allocation unit */</span>\r
+ BYTE <span class="arg">opt</span>, <span class="c">/* [IN] Format options */</span>\r
+ DWORD <span class="arg">au</span>, <span class="c">/* [IN] Size of the allocation unit */</span>\r
+ void* <span class="arg">work</span>, <span class="c">/* [-] Working buffer */</span>\r
+ UINT <span class="arg">len</span> <span class="c">/* [IN] Size of working buffer */</span>\r
);\r
</pre>\r
</div>\r
<h4>Parameters</h4>\r
<dl class="par">\r
<dt>path</dt>\r
-<dd>Pinter to the null-terminated string that specifies the <a href="filename.html">logical drive</a> to be formatted. If there is no drive number, it means the default drive.</dd>\r
-<dt>sfd</dt>\r
-<dd>Specifies partitioning rule (FDISK(0) or SFD(1)). This argument will be ignored on some case.</dd>\r
+<dd>Pointer to the null-terminated string specifies the <a href="filename.html">logical drive</a> to be formatted. If there is no drive number in it, it means the default drive. The logical drive may or may not be mounted for the format process.</dd>\r
+<dt>opt</dt>\r
+<dd>Specifies the format option in combination of <tt>FM_FAT</tt>, <tt>FM_FAT32</tt>, <tt>FM_EXFAT</tt> and bitwise-or of these three, <tt>FM_ANY</tt>. <tt>FM_EXFAT</tt> is ignored when exFAT is not enabled. These flags specify which FAT type to be created on the volume. If two or more types are specified, one out of them will be selected depends on the volume size. The flag <tt>FM_SFD</tt> specifies to place the volume on the drive in SFD format.</dd>\r
<dt>au</dt>\r
-<dd>Specifies size of the allocation unit (cluter) in number of bytes or sectors. When the value is from 1 to 128, it specifies number of sectors. When the value is <tt>>= _MIN_SS</tt>, it specifies number of bytes. If any invalid value, zero or not power of 2, is given, the cluster size is automatically determined depends on the volume size.</dd>\r
+<dd>Specifies size of the allocation unit (cluter) in unit of byte. The valid value is N times the sector size. N is power of 2 from 1 to 128 for FAT volume and upto 16MiB for exFAT volume. If zero is given, the default allocation unit size is selected depends on the volume size.</dd>\r
+<dt>work</dt>\r
+<dd>Pointer to the working buffer used for the format process.</dd>\r
+<dt>len</dt>\r
+<dd>Size of the working buffer in unit of byte. It needs to be the sector size at least. Plenty of working buffer reduces number of write transaction to the device and the format process will be finished quickly.</dd>\r
</dl>\r
</div>\r
\r
<a href="rc.html#nr">FR_NOT_READY</a>,\r
<a href="rc.html#wp">FR_WRITE_PROTECTED</a>,\r
<a href="rc.html#id">FR_INVALID_DRIVE</a>,\r
-<a href="rc.html#ne">FR_NOT_ENABLED</a>,\r
<a href="rc.html#ma">FR_MKFS_ABORTED</a>,\r
<a href="rc.html#ip">FR_INVALID_PARAMETER</a>\r
</p>\r
\r
<div class="para desc">\r
<h4>Description</h4>\r
-<p>The <tt>f_mkfs()</tt> function creates an FAT volume on the specified logical drive. When FDISK format is specified, a primary partition occupies entire space of the physical drive is created and then an FAT volume is created on the partition. When SFD format is specified, the FAT volume starts from the first sector of the physical drive.</p>\r
-<p>If the logical drive is bound to the specific partition (1-4) by multiple partition feature (<tt>_MULTI_PARTITION</tt>), the FAT volume is created into the partition. In this case, the second argument <tt class="arg">sfd</tt> is ignored. The physical drive must have been partitioned with <tt>f_fdisk()</tt> function or any other partitioning tools prior to create the FAT volume with this function.</p>\r
-<p>Note that there are two partitioning rules, FDISK and SFD. The FDISK partitioning is usually used for harddisk, MMC, SDC, CFC and U Disk. It can divide a physical drive into one or more partitions with a partition table on the MBR. However Windows does not support multiple partition on the removable disk. The SFD is non-partitioned method. The FAT volume starts from the first sector on the physical drive without partition table. It is usually used for floppy disk, Microdrive, optical disk and any type of super-floppy media.</p>\r
-<p>The FAT sub-type, FAT12/FAT16/FAT32, is determined by number of clusters on the volume and nothing else, according to the FAT specification issued by Microsoft. Thus which FAT sub-type is selected, is depends on the volume size and the specified cluster size. The cluster size affects read/write throughput and space usage efficiency. Larger cluster size increases the read/write throughput and decreases the space usage efficiency of the volume.</p>\r
-<p>In case of the number of clusters gets near the FAT sub-type boundaries, the function can fail with <tt>FR_MKFS_ABORTED</tt>.</p>\r
+<p>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 which FAT sub-type is selected, is depends on the volume size and the specified cluster size. In case of the combination of FAT type and cluter size specified by argument cannot be valid on the volume, the function will fail with <tt>FR_MKFS_ABORTED</tt>.</p>\r
+<p>The allocation unit, also called '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 as the size of allocation unit. Therefore the allocation unit is a trade-off between space efficiency and performance. For the large storages in GB order, 32768 bytes or larger cluster (this is automatically selected by default) is recommended for most case unless extremely many files are created on a volume.</p>\r
+<p>There are two disk formats, FDISK and SFD. The FDISK format is usually used for harddisk, MMC, SDC, CFC and U Disk. It can divide a physical drive into one or more partitions with a partition table on the MBR (maser boot record, the first sector of the physical drive). The SFD (super-floppy disk) is non-partitioned disk format. The FAT volume starts at the first sector of the physical drive without any disk partitioning. It is usually used for floppy disk, Microdrive, optical disk and most type of super-floppy media. Some systems support only either one of two formats and other is not supported.</p>\r
+<p>When <tt>FM_SFD</tt> is not specified, a primary partition occupies whole drive space is created and then the FAT volume is created in it. When <tt>FM_SFD</tt> is specified, the FAT volume occupies from the first sector of the drive is created.</p>\r
+<p>If the logical drive to be formatted is bound to the specific partition (1-4) by support of multiple partition, <tt><a href="config.html#multi_partition">_MULTI_PARTITION</a></tt>, the FAT volume is created into the partition and <tt>FM_SFD</tt> flag is ignored. The physical drive needs to be partitioned with <tt>f_fdisk</tt> function or any other partitioning tools prior to create the FAT volume with this function.</p>\r
</div>\r
\r
<div class="para comp">\r
<div class="para use">\r
<h4>Example</h4>\r
<pre>\r
-<span class="c">/* Format the default drive */</span>\r
+<span class="c">/* Format default drive and create a file */</span>\r
int main (void)\r
{\r
- FATFS fs; <span class="c">/* File system object (volume work area) */</span>\r
- FIL fil; <span class="c">/* File object */</span>\r
- FRESULT res; <span class="c">/* API result code */</span>\r
- UINT bw; <span class="c">/* Bytes written */</span>\r
+ FATFS fs; <span class="c">/* File system object */</span>\r
+ FIL fil; <span class="c">/* File object */</span>\r
+ FRESULT res; <span class="c">/* API result code */</span>\r
+ UINT bw; <span class="c">/* Bytes written */</span>\r
+ BYTE work[_MAX_SS]; <span class="c">/* Work area (larger is better for process time) */</span>\r
\r
\r
+ <span class="c">/* Create FAT volume */</span>\r
+ res = f_mkfs("", FM_ANY, 0, work, sizeof work);\r
+ if (res) ...\r
+\r
<span class="c">/* Register work area */</span>\r
f_mount(&fs, "", 0);\r
\r
- <span class="c">/* Create FAT volume with default cluster size */</span>\r
- res = f_mkfs("", 0, 0);\r
- if (res) ...\r
-\r
<span class="c">/* Create a file as new */</span>\r
- res = f_open(&fil, "hello.txt", FA_CREATE_NEW | FA_WRITE);\r
+ res = f_open(&fil, "hello.txt", FA_CREATE_NEW | FA_WRITE);\r
if (res) ...\r
\r
<span class="c">/* Write a message */</span>\r
- f_write(&fil, "Hello, World!\r\n", 15, &bw);\r
+ f_write(&fil, "Hello, World!\r\n", 15, &bw);\r
if (bw != 15) ...\r
\r
<span class="c">/* Close the file */</span>\r
- f_close(&fil);\r
+ f_close(&fil);\r
\r
<span class="c">/* Unregister work area */</span>\r
f_mount(0, "", 0);\r
\r
+ ...\r
</pre>\r
</div>\r
\r
<div class="para ref">\r
<h4>See Also</h4>\r
-<p><
tt><a href="filename.html#vol">Volume management</a>, <a href="fdisk.html">f_fdisk</a></tt></p>
\r+<p><
a href="../res/mkfs.xls">Example of volume size and format parameters</a>, <a href="filename.html#vol">Volume management</a>, <tt><a href="fdisk.html">f_fdisk</a></tt></p>
\r </div>\r
\r
<p class="foot"><a href="../00index_e.html">Return</a></p>\r
projects / z180-stamp.git / blobdiff