174 changed files with 25870 additions and 42304 deletions
@ -1,118 +0,0 @@ |
|||
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd"> |
|||
<html lang="en"> |
|||
<head> |
|||
<meta http-equiv="Content-Type" content="text/html; charset=utf-8"> |
|||
<meta http-equiv="Content-Style-Type" content="text/css"> |
|||
<meta http-equiv="cache-control" content="no-cache"> |
|||
<meta name="description" content="Open source FAT file system module for embedded projects"> |
|||
<link rel="alternate" hreflang="ja" title="Japanese version" href="00index_j.html"> |
|||
<link rel="stylesheet" href="css_e.css" type="text/css" media="screen" title="ELM Default"> |
|||
<title>FatFs - Generic FAT File System Module</title> |
|||
</head> |
|||
|
|||
<body> |
|||
<h1>FatFs - Generic FAT File System Module</h1> |
|||
<hr> |
|||
|
|||
<div class="abst"> |
|||
<img src="img/layers.png" class="rset" width="245" height="255" alt="layer"> |
|||
<p>FatFs is a generic FAT file system module for small embedded systems. The FatFs is written in compliance with ANSI C and completely separated from the disk I/O layer. Therefore it is independent of hardware architecture. It can be incorporated into small microcontrollers with limited resource, such as AVR, 8051, PIC, ARM, Z80, 68k and etc. Also Petit FatFs module for tiny microcontrollers is available <a href="http://elm-chan.org/fsw/ff/00index_p.html">here</a>.</p> |
|||
|
|||
<h4>Features</h4> |
|||
<ul> |
|||
<li>Windows compatible FAT file system.</li> |
|||
<li>Platform independent. Easy to port.</li> |
|||
<li>Very small footprint for code and work area.</li> |
|||
<li>Various configuration options: |
|||
<ul> |
|||
<li>Multiple volumes (physical drives and partitions).</li> |
|||
<li>Multiple ANSI/OEM code pages including DBCS.</li> |
|||
<li>Long file name support in ANSI/OEM or Unicode.</li> |
|||
<li>RTOS support.</li> |
|||
<li>Multiple sector size support.</li> |
|||
<li>Read-only, minimized API, I/O buffer and etc...</li> |
|||
</ul> |
|||
</li> |
|||
</ul> |
|||
</div> |
|||
|
|||
|
|||
<div class="para"> |
|||
<h3>Application Interface</h3> |
|||
<p>FatFs module provides following functions to the applications. In other words, this list describes what FatFs can do to access the FAT volumes.</p> |
|||
<ul> |
|||
<li><a href="en/mount.html">f_mount</a> - Register/Unregister a work area</li> |
|||
<li><a href="en/open.html">f_open</a> - Open/Create a file</li> |
|||
<li><a href="en/close.html">f_close</a> - Close an open file</li> |
|||
<li><a href="en/read.html">f_read</a> - Read file</li> |
|||
<li><a href="en/write.html">f_write</a> - Write file</li> |
|||
<li><a href="en/lseek.html">f_lseek</a> - Move read/write pointer, Expand file size</li> |
|||
<li><a href="en/truncate.html">f_truncate</a> - Truncate file size</li> |
|||
<li><a href="en/sync.html">f_sync</a> - Flush cached data</li> |
|||
<li><a href="en/forward.html">f_forward</a> - Forward file data to the stream</li> |
|||
<li><a href="en/stat.html">f_stat</a> - Check existance of a file or sub-directory</li> |
|||
<li><a href="en/opendir.html">f_opendir</a> - Open a directory</li> |
|||
<li><a href="en/closedir.html">f_closedir</a> - Close an open directory</li> |
|||
<li><a href="en/readdir.html">f_readdir</a> - Read a directory item</li> |
|||
<li><a href="en/mkdir.html">f_mkdir</a> - Create a sub-directory</li> |
|||
<li><a href="en/unlink.html">f_unlink</a> - Remove a file or sub-directory</li> |
|||
<li><a href="en/chmod.html">f_chmod</a> - Change attribute</li> |
|||
<li><a href="en/utime.html">f_utime</a> - Change timestamp</li> |
|||
<li><a href="en/rename.html">f_rename</a> - Rename/Move a file or sub-directory</li> |
|||
<li><a href="en/chdir.html">f_chdir</a> - Change current directory</li> |
|||
<li><a href="en/chdrive.html">f_chdrive</a> - Change current drive</li> |
|||
<li><a href="en/getcwd.html">f_getcwd</a> - Retrieve the current directory</li> |
|||
<li><a href="en/getfree.html">f_getfree</a> - Get free space on the volume</li> |
|||
<li><a href="en/getlabel.html">f_getlabel</a> - Get volume label</li> |
|||
<li><a href="en/setlabel.html">f_setlabel</a> - Set volume label</li> |
|||
<li><a href="en/mkfs.html">f_mkfs</a> - Create a file system on the drive</li> |
|||
<li><a href="en/fdisk.html">f_fdisk</a> - Divide a physical drive</li> |
|||
<li><a href="en/gets.html">f_gets</a> - Read a string</li> |
|||
<li><a href="en/putc.html">f_putc</a> - Write a character</li> |
|||
<li><a href="en/puts.html">f_puts</a> - Write a string</li> |
|||
<li><a href="en/printf.html">f_printf</a> - Write a formatted string</li> |
|||
<li><a href="en/tell.html">f_tell</a> - Get current read/write pointer</li> |
|||
<li><a href="en/eof.html">f_eof</a> - Test for end-of-file on a file</li> |
|||
<li><a href="en/size.html">f_size</a> - Get size of a file</li> |
|||
<li><a href="en/error.html">f_error</a> - Test for an error on a file</li> |
|||
</ul> |
|||
</div> |
|||
|
|||
|
|||
<div class="para"> |
|||
<h3>Device Control Interface</h3> |
|||
<p>Since the FatFs module is a file system driver, it is completely separated from physical devices, such as memory card, harddisk and any type of storage devices. The low level device control module is not a part of FatFs module. FatFs accesses the storage device via a simple interface described below. These functions are provided by implementer. Sample implementations for some platforms are also available in the downloads.</p> |
|||
<ul> |
|||
<li><a href="en/dstat.html">disk_status</a> - Get device status</li> |
|||
<li><a href="en/dinit.html">disk_initialize</a> - Initialize device</li> |
|||
<li><a href="en/dread.html">disk_read</a> - Read sector(s)</li> |
|||
<li><a href="en/dwrite.html">disk_write</a> - Write sector(s)</li> |
|||
<li><a href="en/dioctl.html">disk_ioctl</a> - Control device dependent features</li> |
|||
<li><a href="en/fattime.html">get_fattime</a> - Get current time</li> |
|||
</ul> |
|||
</div> |
|||
|
|||
|
|||
<div class="para"> |
|||
<h3>Resources</h3> |
|||
<p>The FatFs module is a free software opened for education, research and development. You can use, modify and/or redistribute it for personal projects or commercial products without any restriction under your responsibility. For further information, refer to the application note.</p> |
|||
<ul> |
|||
<li><a href="http://elm-chan.org/fsw/ff/bd/"><em>FatFs User Forum</em></a>↗</li> |
|||
<li>Read first: <a href="en/appnote.html">FatFs module application note</a></li> |
|||
<li>Latest Information: <a href="http://elm-chan.org/fsw/ff/00index_e.html">http://elm-chan.org/fsw/ff/00index_e.html</a>↗</li> |
|||
<li><a href="http://nemuisan.blog.bai.ne.jp/">Nemuisan's Blog</a>↗ (Well written implementations for STM32F/SDIO and LPC2300/MCI)</li> |
|||
<li><a href="http://www.siwawi.arubi.uni-kl.de/avr_projects/arm_projects/arm_memcards/index.html">ARM-Projects by Martin THOMAS</a>↗ (Examples for LPC2000, AT91SAM and STM32)</li> |
|||
<li><a href="http://www.microsoft.com/whdc/system/platform/firmware/fatgen.mspx">FAT32 Specification by Microsoft</a>↗ (The reference document on FAT file system)</li> |
|||
<li><a href="http://elm-chan.org/docs/fat.html">The basics of FAT file system [ja]</a>↗</li> |
|||
<li><a href="http://elm-chan.org/docs/mmc/mmc_e.html">How to Use MMC/SDC</a>↗</li> |
|||
<li><a href="img/rwtest.png">Benchmark 1</a> (ATmega64/9.2MHz with MMC via SPI, HDD/CFC via GPIO)</li> |
|||
<li><a href="img/rwtest2.png">Benchmark 2</a> (LPC2368/72MHz with MMC via MCI)</li> |
|||
<li><a href="http://members.jcom.home.ne.jp/felm/fd.mp4">Demo movie of an application</a> (this project is in ffsample.zip/lpc23xx)</li> |
|||
</ul> |
|||
</div> |
|||
|
|||
|
|||
<hr> |
|||
<p class="foot"><a href="../../fsw_e.html">Return</a></p> |
|||
</body> |
|||
</html> |
|||
@ -1,118 +0,0 @@ |
|||
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd"> |
|||
<html lang="ja"> |
|||
<head> |
|||
<meta http-equiv="Content-Type" content="text/html; charset=utf-8"> |
|||
<meta http-equiv="Content-Style-Type" content="text/css"> |
|||
<meta http-equiv="cache-control" content="no-cache"> |
|||
<meta name="description" content="組み込みシステム向け汎用FATファイル・システム"> |
|||
<link rel="start" title="Site Top" href="../../index_j.html"> |
|||
<link rel="up" title="Freewares" href="../../fsw.html"> |
|||
<link rel="alternate" hreflang="en" title="英文" href="00index_e.html"> |
|||
<link rel="stylesheet" href="css_j.css" type="text/css" media="screen" title="ELM Default"> |
|||
<title>FatFs 汎用FATファイルシステム・モジュール</title> |
|||
</head> |
|||
|
|||
<body> |
|||
<h1>FatFs 汎用FATファイルシステム・モジュール</h1> |
|||
<hr> |
|||
|
|||
<div class="abst"> |
|||
<img src="img/layers.png" class="rset" width="245" height="255" alt="layer"> |
|||
<p>FatFsは小規模な組み込みシステム向けの汎用FATファイルシステム・モジュールです。ANSI C準拠でハードウェア・アーキテクチャには依存しないので、必要なワーク・エリアが確保できれば、8051, PIC, AVR, SH, Z80, 68k, H8, ARMなど安価なマイコンでも使用可能です。FatFsをシュリンクした<a href="http://elm-chan.org/fsw/ff/00index_p.html">ぷちFatFs</a>↗もあります。</p> |
|||
<h4>FatFsモジュールの特徴</h4> |
|||
<ul> |
|||
<li>Windows互換 FATファイル・システム</li> |
|||
<li>プラットフォーム非依存</li> |
|||
<li>コンパクトなコードとRAM使用量</li> |
|||
<li>多くの構成オプション: |
|||
<ul> |
|||
<li>複数のボリューム(物理ドライブ・区画)</li> |
|||
<li>DBCSを含む複数のANSI/OEMコード・ページ</li> |
|||
<li>長いファイル名(LFN) (Unicode APIも選択可)</li> |
|||
<li>マルチタスク関連</li> |
|||
<li>マルチ・セクタ・サイズ</li> |
|||
<li>リード・オンリー構成、一部APIの削除、バッファ構成、その他…</li> |
|||
</ul> |
|||
</li> |
|||
</ul> |
|||
</div> |
|||
|
|||
|
|||
<div class="para"> |
|||
<h3>上位レイヤ・インターフェース</h3> |
|||
<p>FatFsモジュールは、アプリケーション・レイヤに対し、次のファイル操作関数(API)を提供します。つまり、このリストはFatFsにできることをシンプルに示しています。</p> |
|||
<ul> |
|||
<li><a href="ja/mount.html">f_mount</a> - ワークエリアの登録・抹消</li> |
|||
<li><a href="ja/open.html">f_open</a> - ファイルのオープン・作成</li> |
|||
<li><a href="ja/close.html">f_close</a> - ファイルのクローズ</li> |
|||
<li><a href="ja/read.html">f_read</a> - ファイルの読み出し</li> |
|||
<li><a href="ja/write.html">f_write</a> - ファイルの書き込み</li> |
|||
<li><a href="ja/lseek.html">f_lseek</a> - リード/ライト・ポインタの移動, ファイルの拡張</li> |
|||
<li><a href="ja/truncate.html">f_truncate</a> - ファイル・サイズの切り詰め</li> |
|||
<li><a href="ja/sync.html">f_sync</a> - キャッシュされたデータのフラッシュ</li> |
|||
<li><a href="ja/forward.html">f_forward</a> - ファイル・データをストリーム関数に転送</li> |
|||
<li><a href="ja/stat.html">f_stat</a> - ファイル/サブ・ディレクトリの存在チェックと情報の取得</li> |
|||
<li><a href="ja/opendir.html">f_opendir</a> - ディレクトリのオープン</li> |
|||
<li><a href="ja/closedir.html">f_closedir</a> - ディレクトリのクローズ</li> |
|||
<li><a href="ja/readdir.html">f_readdir</a> - ディレクトリの読み出し</li> |
|||
<li><a href="ja/mkdir.html">f_mkdir</a> - サブ・ディレクトリの作成</li> |
|||
<li><a href="ja/unlink.html">f_unlink</a> - ファイル/サブ・ディレクトリの削除</li> |
|||
<li><a href="ja/chmod.html">f_chmod</a> - ファイル/サブ・ディレクトリの属性の変更</li> |
|||
<li><a href="ja/utime.html">f_utime</a> - ファイル/サブ・ディレクトリのタイムスタンプの変更</li> |
|||
<li><a href="ja/rename.html">f_rename</a> - ファイル/サブ・ディレクトリの名前の変更・移動</li> |
|||
<li><a href="ja/chdir.html">f_chdir</a> - カレント・ディレクトリの変更</li> |
|||
<li><a href="ja/chdrive.html">f_chdrive</a> - カレント・ドライブの変更</li> |
|||
<li><a href="ja/getcwd.html">f_getcwd</a> - カレント・ディレクトリの取得</li> |
|||
<li><a href="ja/getfree.html">f_getfree</a> - ボリューム空き領域の取得</li> |
|||
<li><a href="ja/getlabel.html">f_getlabel</a> - ボリューム・ラベルの取得</li> |
|||
<li><a href="ja/setlabel.html">f_setlabel</a> - ボリューム・ラベルの設定</li> |
|||
<li><a href="ja/mkfs.html">f_mkfs</a> - 論理ドライブのフォーマット</li> |
|||
<li><a href="ja/fdisk.html">f_fdisk</a> - 物理ドライブの分割</li> |
|||
<li><a href="ja/gets.html">f_gets</a> - 文字列の読み出し</li> |
|||
<li><a href="ja/putc.html">f_putc</a> - 文字の書き込み</li> |
|||
<li><a href="ja/puts.html">f_puts</a> - 文字列の書き込み</li> |
|||
<li><a href="ja/printf.html">f_printf</a> - 書式化文字列の書き込み</li> |
|||
<li><a href="ja/tell.html">f_tell</a> - 現在のリード/ライト・ポインタの取得</li> |
|||
<li><a href="ja/eof.html">f_eof</a> - ファイル終端の有無の取得</li> |
|||
<li><a href="ja/size.html">f_size</a> - ファイル・サイズの取得</li> |
|||
<li><a href="ja/error.html">f_error</a> - ファイルのエラーの有無の取得</li> |
|||
</ul> |
|||
</div> |
|||
|
|||
|
|||
<div class="para"> |
|||
<h3>下位レイヤ・インターフェース</h3> |
|||
<p>FatFsモジュールは、単なるファイル・システム・レイヤなので、ストレージ・デバイス制御レイヤは含まれません。使用するストレージに対応した制御関数は、ユーザによって提供される必要があります。FatFsモジュールは、下位レイヤに対し少なくとも次のインターフェースを要求します。OS関連機能を有効にしたときは、これに加えてプロセス/メモリ関連関数も必要になります。サンプル・プロジェクトに下位レイヤの実装例を示します。</p> |
|||
<ul> |
|||
<li><a href="ja/dstat.html">disk_status</a> - デバイスの状態取得</li> |
|||
<li><a href="ja/dinit.html">disk_initialize</a> - デバイスの初期化</li> |
|||
<li><a href="ja/dread.html">disk_read</a> - データの読み出し</li> |
|||
<li><a href="ja/dwrite.html">disk_write</a> - データの書き込み</li> |
|||
<li><a href="ja/dioctl.html">disk_ioctl</a> - その他のデバイス制御</li> |
|||
<li><a href="ja/fattime.html">get_fattime</a> - 日付・時刻の取得</li> |
|||
</ul> |
|||
</div> |
|||
|
|||
|
|||
<div class="para"> |
|||
<h3>資料</h3> |
|||
<p>FatFsモジュールはフリー・ソフトウェアとして教育・研究・開発用に公開しています。どのような利用目的（個人利用から商用まで）でも使用・改変・配布について一切の制限はありませんが、全て利用者の責任の下での利用とします。詳しくはアプリケーション・ノートを参照してください。</p> |
|||
<ul> |
|||
<li><a href="http://elm-chan.org/fsw/ff/bd/"><em>FatFsユーザ・フォーラム</em></a>↗</li> |
|||
<li>最初に読め: <a href="ja/appnote.html">FatFsモジュール・アプリケーション・ノート</a></li> |
|||
<li>最新版: <a href="http://elm-chan.org/fsw/ff/00index_j.html">http://elm-chan.org/fsw/ff/00index_j.html</a>↗</li> |
|||
<li><a href="http://nemuisan.blog.bai.ne.jp/">ねむいさんのぶろぐ</a>↗ (Well written implementations for STM32F/SDIO and LPC2300/MCI)</li> |
|||
<li><a href="http://www.siwawi.arubi.uni-kl.de/avr_projects/arm_projects/arm_memcards/index.html">ARM-Projects by Martin THOMAS</a>↗ (Examples for LPC2000, AT91SAM and STM32)</li> |
|||
<li><a href="http://www.microsoft.com/whdc/system/platform/firmware/fatgen.mspx">FATファイル・システム仕様書 by Microsoft</a>↗ (The reference document on FAT file system)</li> |
|||
<li><a href="http://elm-chan.org/docs/fat.html">FATファイル・システム概要</a>↗ (↑を読むためのガイド)</li> |
|||
<li><a href="http://elm-chan.org/docs/mmc/mmc.html">MMCの使いかた</a>↗</li> |
|||
<li><a href="img/rwtest.png">パフォーマンス・テスト1</a> (ATmega64/9.2MHz with MMC via SPI, HDD/CFC via GPIO)</li> |
|||
<li><a href="img/rwtest2.png">パフォーマンス・テスト2</a> (LPC2368/72MHz with MMC via MCI)</li> |
|||
</ul> |
|||
</div> |
|||
|
|||
|
|||
<hr> |
|||
<p class="foot"><a href="../../fsw.html">戻る</a></p> |
|||
</body> |
|||
</html> |
|||
@ -1,68 +0,0 @@ |
|||
@charset "Shift_JIS"; |
|||
/* Common style sheet for Tech Notes */ |
|||
|
|||
* {margin: 0; padding: 0; border-width: 0;} |
|||
body {margin: 8px; background-color: #e0ffff; font-color: black; font-family:"ＭＳ Ｐ明朝", serif; line-height: 150%; letter-spacing: 1px; max-width: 1024px;} |
|||
a:link {color: blue;} |
|||
a:visited {color: darkmagenta;} |
|||
a:hover {background-color: #a0ffff;} |
|||
a:active {color: darkmagenta; overflow: hidden; outline:none; position: relative; top: 1px; left: 1px;} |
|||
abbr {border-width: 1px;} |
|||
|
|||
p {text-indent: 1em; margin: 0 0 0.3em 0.5em;} |
|||
i {margin: 0 0.3em 0 0;} |
|||
b {margin: 0 0.1em;} |
|||
em {font-style: normal; font-weight: bold; margin: 0 0.1em;} |
|||
strong {} |
|||
pre {border: 1px dashed gray; margin: 0.5em 1em; padding: 0.5em; line-height: 1.2em; letter-spacing: 0; font-size: 0.85em; font-family: "Consolas", "Courier New", "ＭＳ ゴシック", monospace; background-color: white;} |
|||
pre span.c {color: green;} |
|||
pre span.k {color: blue;} |
|||
pre span.arg {font-style: italic;} |
|||
tt {margin: 0 0.2em; letter-spacing: 0; font-size: 0.85em; font-family: "Consolas", "Courier New", "ＭＳ ゴシック", monospace;} |
|||
tt.arg {font-style: italic;} |
|||
ol {margin: 0.5em 2.5em;} |
|||
ul {margin: 0.5em 2em;} |
|||
dl {margin: 0.5em 1em;} |
|||
dd {margin: 0em 2em;} |
|||
dt {font-size: 0.85em; font-family: "Consolas", "Courier New", "ＭＳ ゴシック", monospace;} |
|||
dl.par dt {margin: 0.5em 0 0 0 ; font-style: italic; letter-spacing: 0;} |
|||
dl.ret dt {margin: 0.5em 0 0 0 ; font-size: 0.85em; font-family: "Consolas", "Courier New", "ＭＳ ゴシック", monospace; letter-spacing: 0; } |
|||
hr {border-width: 1px; margin: 1em;} |
|||
div.abst {font-family: "ＭＳ Ｐゴシック",sans-serif;} |
|||
div.para {clear: both; font-family: "ＭＳ Ｐ明朝",serif;} |
|||
div.ret a {font-size: 0.85em; font-family: "Consolas", "Courier New", monospace; } |
|||
.equ {text-indent: 0; margin: 1em 2em 1em;} |
|||
.indent {margin-left: 2em;} |
|||
.rset {float: right; margin: 0.3em 0 0.5em 0.5em;} |
|||
.lset {float: left; margin: 0.3em 0.5em 0.5em 0.5em;} |
|||
ul.flat li {list-style-type: none; margin: 0;} |
|||
a.imglnk img {border: 1px solid;} |
|||
.iequ {white-space: nowrap; font-weight: bold;} |
|||
.clr {clear: both;} |
|||
.it {font-style: italic;} |
|||
.mfd {font-size: 0.7em; padding: 0 1px; border: 1px solid; white-space : nowrap} |
|||
.ral {text-align: right; } |
|||
.lal {text-align: left; } |
|||
.cal {text-align: center; } |
|||
|
|||
h1 {line-height: 1em; font-size: 2em; font-family: sans-serif; padding: 0.3em 0 0.3em;} |
|||
p.hdd {float: right; text-align: right; margin-top: 0.5em;} |
|||
hr.hds {clear: both; margin-bottom: 1em;} |
|||
|
|||
h2 {font-size: 2em; font-family: "ＭＳ Ｐゴシック",sans-serif; background-color: #d8d8FF; padding: 0.5em 0.5em; margin: 0 0 0.5em;} |
|||
h3 {font-size: 1.5em; font-family: "ＭＳ Ｐゴシック",sans-serif; margin: 1.5em 0 0.5em;} |
|||
h4 {font-size: 1.2em; font-family: "ＭＳ Ｐゴシック",sans-serif; margin: 1em 0 0.2em;} |
|||
h5 {font-size: 1em; font-family: "ＭＳ Ｐゴシック",sans-serif; margin: 0.5em 0 0em;} |
|||
small {font-size: 80%;} |
|||
.indent {margin-left: 2em;} |
|||
|
|||
/* Tables */ |
|||
table {margin: 0.5em 1em; border-collapse: collapse; border: 2px solid black; letter-spacing: 0;} |
|||
th {background-color: white; border-style: solid; border-width: 1px 1px 2px; border-color: black; padding: 0 3px; vertical-align: top;} |
|||
td {background-color: white; border: 1px solid black; padding: 0 3px; vertical-align: top; line-height: 1.3em;} |
|||
table.lst td:first-child {font-size: 0.85em; font-family: "Consolas", "Courier New", monospace; white-space: nowrap;} |
|||
table.lst2 td {font-size: 0.85em; font-family: "Consolas", "Courier New", monospace; white-space: nowrap;} |
|||
table caption {font-family: sans-serif; font-weight: bold;} |
|||
tr.lst3 td {border-width: 2px 1px 1px; } |
|||
|
|||
p.foot {clear: both; text-indent: 0; margin: 1em 0.5em 1em;} |
|||
@ -1 +0,0 @@ |
|||
body {margin: 8px; background-color: #ffecf0; font-color: black; font-family: serif; line-height: 133%; max-width: 1024px;} |
|||
@ -1,275 +0,0 @@ |
|||
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd"> |
|||
<html lang="en"> |
|||
<head> |
|||
<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> |
|||
<meta http-equiv="Content-Style-Type" content="text/css"> |
|||
<link rel="up" title="FatFs" href="../00index_e.html"> |
|||
<link rel="alternate" hreflang="ja" title="Japanese" href="../ja/appnote.html"> |
|||
<link rel="stylesheet" href="../css_e.css" type="text/css" media="screen" title="ELM Default"> |
|||
<title>FatFs Module Application Note</title> |
|||
</head> |
|||
|
|||
<body> |
|||
<h1>FatFs Module Application Note</h1> |
|||
<ol class="toc"> |
|||
<li><a href="#port">How to Port</a></li> |
|||
<li><a href="#limits">Limits</a></li> |
|||
<li><a href="#memory">Memory Usage</a></li> |
|||
<li><a href="#reduce">Module Size Reduction</a></li> |
|||
<li><a href="#lfn">Long File Name</a></li> |
|||
<li><a href="#unicode">Unicode API</a></li> |
|||
<li><a href="#reentrant">Re-entrancy</a></li> |
|||
<li><a href="#dup">Duplicated File Access</a></li> |
|||
<li><a href="#fs1">Performance Effective File Access</a></li> |
|||
<li><a href="#fs2">Considerations on Flash Memory Media</a></li> |
|||
<li><a href="#critical">Critical Section</a></li> |
|||
<li><a href="#fs3">Extended Use of FatFs API</a></li> |
|||
<li><a href="#license">About FatFs License</a></li> |
|||
</ol> |
|||
<hr> |
|||
|
|||
<div class="para" id="port"> |
|||
<h3>How to Port</h3> |
|||
|
|||
<h4>Basic considerations</h4> |
|||
<p>The FatFs module is assuming following conditions on portability.</p> |
|||
<ul> |
|||
<li>ANSI C<br> |
|||
The FatFs module is a middleware written in ANSI C (C89). There is no platform dependence, so long as the compiler is in compliance with ANSI C.</li> |
|||
<li>Size of integer types<br> |
|||
The FatFs module assumes that size of char/short/long are 8/16/32 bit and int is 16 or 32 bit. These correspondence are defined in <tt>integer.h</tt>. This will not be a problem on most compilers. When any conflict with existing definitions is occured, you must resolve it with care.</li> |
|||
</ul> |
|||
|
|||
<h4>System organizations</h4> |
|||
<p>The dependency diagram shown below is a typical configuration of the embedded system with FatFs module.</p> |
|||
<p><img src="../img/modules.png" width="580" height="280" alt="dependency diagram"></p> |
|||
<p>(a) If a working disk module with FatFs API is provided, no additional function is needed. (b) To attach existing disk drivers with different API, glue functions are needed to translate the APIs between FatFs and the drivers.</p> |
|||
<p><img src="../img/funcs.png" width="680" height="430" alt="functional diagram"></p> |
|||
|
|||
<h4>Which function is required?</h4> |
|||
<p>You need to provide only low level disk I/O functions that required by FatFs module and nothing else. If a working disk module for the target is already existing, you need to write only glue functions to attach it to the FatFs module. If not, you need to port any other disk module or write it from scratch. Most of defined functions are not that always required. For example, disk write function is not required in read-only configuration. Following table shows which function is required depends on configuration options.</p> |
|||
<table class="lst2"> |
|||
<tr><th>Function</th><th>Required when:</th><th>Note</th></tr> |
|||
<tr><td>disk_status<br>disk_initialize<br>disk_read</td><td>Always</td><td rowspan="5">Disk I/O functions.<br>Samples available in ffsample.zip.<br>There are many implementations on the web.</td></tr> |
|||
<tr><td>disk_write<br>get_fattime<br>disk_ioctl (CTRL_SYNC)</td><td>_FS_READONLY == 0</td></tr> |
|||
<tr><td>disk_ioctl (GET_SECTOR_COUNT)<br>disk_ioctl (GET_BLOCK_SIZE)</td><td>_USE_MKFS == 1</td></tr> |
|||
<tr><td>disk_ioctl (GET_SECTOR_SIZE)</td><td>_MAX_SS != _MIN_SS</td></tr> |
|||
<tr><td>disk_ioctl (CTRL_ERASE_SECTOR)</td><td>_USE_ERASE == 1</td></tr> |
|||
<tr><td>ff_convert<br>ff_wtoupper</td><td>_USE_LFN >= 1</td><td>Unicode support functions.<br>Available in option/unicode.c.</td></tr> |
|||
<tr><td>ff_cre_syncobj<br>ff_del_syncobj<br>ff_req_grant<br>ff_rel_grant</td><td>_FS_REENTRANT == 1</td><td rowspan="2">O/S dependent functions.<br>Samples available in option/syscall.c.</td></tr> |
|||
<tr><td>ff_mem_alloc<br>ff_mem_free</td><td>_USE_LFN == 3</td></tr> |
|||
</table> |
|||
</div> |
|||
|
|||
<div class="para" id="limits"> |
|||
<h3>Limits</h3> |
|||
<ul> |
|||
<li>FAT sub-types: FAT12, FAT16 and FAT32.</li> |
|||
<li>Number of open files: Unlimited, depends on available memory.</li> |
|||
<li>Number of volumes: Upto 10.</li> |
|||
<li>File size: Depends on the FAT specs. (upto 4G-1 bytes)</li> |
|||
<li>Volume size: Depends on the FAT specs. (upto 2T bytes at 512 bytes/sector)</li> |
|||
<li>Cluster size: Depends on the FAT specs. (upto 64K bytes at 512 bytes/sector)</li> |
|||
<li>Sector size: Depends on the FAT specs. (512, 1024, 2048 and 4096 bytes)</li> |
|||
</ul> |
|||
</div> |
|||
|
|||
<div class="para" id="memory"> |
|||
<h3>Memory Usage</h3> |
|||
<table class="lst2"> |
|||
<tr><th></th><th>ARM7<small><br>32bit</small></th><th>ARM7<small><br>Thumb</small></th><th>CM3<small><br>Thumb-2</small></th><th>AVR</th><th>H8/300H</th><th>PIC24</th><th>RL78</th><th>V850ES</th><th>SH-2A</th><th>RX600</th><th>IA-32</th></tr> |
|||
<tr class="cal"> <td>Compiler</td><td>GCC</td><td>GCC</td><td>GCC</td><td>GCC</td><td>CH38</td><td>C30</td><td>CC78K0R</td><td>CA850</td><td>SHC</td><td>RXC</td><td>VC6</td></tr> |
|||
<tr class="cal"> <td>_WORD_ACCESS</td><td>0</td><td>0</td><td>0</td><td>1</td><td>0</td><td>0</td><td>0</td><td>1</td><td>0</td><td>1</td><td>1</td></tr> |
|||
<!-- ARM Thumb CM3 AVR H8 PIC24 RL78 V850ES SH-2A RX600 IA-32 --> |
|||
<tr class="lst3 ral"><td class="cal">text (Full, R/W)</td><td>10675</td><td>7171</td><td>6617</td><td>13355</td><td>10940</td><td>11722</td><td>13262</td><td>8113</td><td>9048</td><td>6032</td><td>7952</td></tr> |
|||
<tr class="ral"> <td class="cal">text (Min, R/W)</td> <td>6727</td><td>4631</td><td>4331</td> <td>8569</td> <td>7262</td> <td>7720</td> <td>9088</td><td>5287</td><td>5800</td><td>3948</td><td>5183</td></tr> |
|||
<tr class="ral"> <td class="cal">text (Full, R/O)</td> <td>4731</td><td>3147</td><td>2889</td> <td>6235</td> <td>5170</td> <td>5497</td> <td>6482</td><td>3833</td><td>3972</td><td>2862</td><td>3719</td></tr> |
|||
<tr class="ral"> <td class="cal">text (Min, R/O)</td> <td>3559</td><td>2485</td><td>2295</td> <td>4575</td> <td>4064</td> <td>4240</td> <td>5019</td><td>2993</td><td>3104</td><td>2214</td><td>2889</td></tr> |
|||
<tr class="ral"> <td class="cal">bss</td><td>V*4 + 2</td><td>V*4 + 2</td><td>V*4 + 2</td><td>V*2 + 2</td><td>V*4 + 2</td><td>V*2 + 2</td><td>V*2 + 2</td><td>V*4 + 2</td><td>V*4 + 2</td><td>V*4 + 2</td><td>V*4 + 2</td></tr> |
|||
<tr class="ral"> <td class="cal">Work area<br>(_FS_TINY == 0)</td><td>V*560<br>+ F*550</td><td>V*560<br>+ F*550</td><td>V*560<br>+ F*550</td><td>V*560<br>+ F*544</td><td>V*560<br>+ F*550</td><td>V*560<br>+ F*544</td><td>V*560<br>+ F*544</td><td>V*560<br>+ F*544</td><td>V*560<br>+ F*550</td><td>V*560<br>+ F*550</td><td>V*560<br>+ F*550</td></tr> |
|||
<tr class="ral"> <td class="cal">Work area<br>(_FS_TINY == 1)</td><td>V*560<br>+ F*36</td><td>V*560<br>+ F*36</td><td>V*560<br>+ F*36</td><td>V*560<br>+ F*32</td><td>V*560<br>+ F*36</td><td>V*560<br>+ F*32</td><td>V*560<br>+ F*32</td><td>V*560<br>+ F*36</td><td>V*560<br>+ F*36</td><td>V*560<br>+ F*36</td><td>V*560<br>+ F*36</td></tr> |
|||
</table> |
|||
<p>These are the memory usage on some target systems with following condition. The memory sizes are in unit of byte, <em>V</em> denotes number of volumes and <em>F</em> denotes number of open files. All samples are optimezed in code size.</p> |
|||
<pre> |
|||
FatFs R0.10a options: |
|||
_FS_READONLY 0 (R/W) or 1 (R/O) |
|||
_FS_MINIMIZE 0 (Full function) or 3 (Minimized function) |
|||
_USE_STRFUNC 0 (Disable string functions) |
|||
_USE_MKFS 0 (Disable f_mkfs function) |
|||
_USE_FORWARD 0 (Disable f_forward function) |
|||
_USE_FASTSEEK 0 (Disable fast seek feature) |
|||
_CODE_PAGE 932 (Japanese Shift-JIS) |
|||
_USE_LFN 0 (Disable LFN feature) |
|||
_MAX_SS 512 (Fixed sector size) |
|||
_FS_RPATH 0 (Disable relative path feature) |
|||
_FS_LABEL 0 (Disable volume label functions) |
|||
_VOLUMES V (Number of logical drives to be used) |
|||
_MULTI_PARTITION 0 (Single partition per drive) |
|||
_FS_REENTRANT 0 (Disable thread safe) |
|||
_FS_LOCK 0 (Disable file lock control) |
|||
</pre> |
|||
</div> |
|||
|
|||
<div class="para" id="reduce"> |
|||
<h3>Module Size Reduction</h3> |
|||
<p>Follwing table shows which API function is removed by configuration options for the module size reduction.</p> |
|||
<table class="lst2"> |
|||
<tr><td rowspan="2">Function</td><td colspan="4">_FS_MINIMIZE</td><td colspan="2">_FS_READONLY</td><td colspan="2">_USE_STRFUNC</td><td colspan="3">_FS_RPATH</td><td colspan="2">_FS_LABEL</td><td colspan="2">_USE_MKFS</td><td colspan="2">_USE_FORWARD</td><td colspan="2">_MULTI_PARTITION</td></tr> |
|||
<tr><td>0</td><td>1</td><td>2</td><td>3</td><td>0</td><td>1</td><td>0 </td><td>1/2</td><td>0</td><td>1</td><td>2</td><td>0</td><td>1</td><td>0</td><td>1</td><td>0</td><td>1</td><td>0</td><td>1</td></tr> |
|||
<tr class="lst3"><td>f_mount</td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td></tr> |
|||
<tr><td>f_open</td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td></tr> |
|||
<tr><td>f_close</td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td></tr> |
|||
<tr><td>f_read</td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td></tr> |
|||
<tr><td>f_write</td><td></td><td></td><td></td><td></td><td></td><td>x</td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td></tr> |
|||
<tr><td>f_sync</td><td></td><td></td><td></td><td></td><td></td><td>x</td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td></tr> |
|||
<tr><td>f_lseek</td><td></td><td></td><td></td><td>x</td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td></tr> |
|||
<tr><td>f_opendir</td><td></td><td></td><td>x</td><td>x</td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td></tr> |
|||
<tr><td>f_closedir</td><td></td><td></td><td>x</td><td>x</td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td></tr> |
|||
<tr><td>f_readdir</td><td></td><td></td><td>x</td><td>x</td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td></tr> |
|||
<tr><td>f_stat</td><td></td><td>x</td><td>x</td><td>x</td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td></tr> |
|||
<tr><td>f_getfree</td><td></td><td>x</td><td>x</td><td>x</td><td></td><td>x</td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td></tr> |
|||
<tr><td>f_truncate</td><td></td><td>x</td><td>x</td><td>x</td><td></td><td>x</td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td></tr> |
|||
<tr><td>f_unlink</td><td></td><td>x</td><td>x</td><td>x</td><td></td><td>x</td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td></tr> |
|||
<tr><td>f_mkdir</td><td></td><td>x</td><td>x</td><td>x</td><td></td><td>x</td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td></tr> |
|||
<tr><td>f_chmod</td><td></td><td>x</td><td>x</td><td>x</td><td></td><td>x</td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td></tr> |
|||
<tr><td>f_utime</td><td></td><td>x</td><td>x</td><td>x</td><td></td><td>x</td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td></tr> |
|||
<tr><td>f_rename</td><td></td><td>x</td><td>x</td><td>x</td><td></td><td>x</td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td></tr> |
|||
<tr><td>f_chdir</td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td>x</td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td></tr> |
|||
<tr><td>f_chdrive</td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td>x</td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td></tr> |
|||
<tr><td>f_getcwd</td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td>x</td><td>x</td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td></tr> |
|||
<tr><td>f_getlabel</td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td>x</td><td></td><td></td><td></td><td></td><td></td><td></td><td></td></tr> |
|||
<tr><td>f_setlabel</td><td></td><td></td><td></td><td></td><td></td><td>x</td><td></td><td></td><td></td><td></td><td></td><td>x</td><td></td><td></td><td></td><td></td><td></td><td></td><td></td></tr> |
|||
<tr><td>f_forward</td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td>x</td><td></td><td></td><td></td></tr> |
|||
<tr><td>f_mkfs</td><td></td><td></td><td></td><td></td><td></td><td>x</td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td>x</td><td></td><td></td><td></td><td></td><td></td></tr> |
|||
<tr><td>f_fdisk</td><td></td><td></td><td></td><td></td><td></td><td>x</td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td>x</td><td></td><td></td><td></td><td>x</td><td></td></tr> |
|||
<tr><td>f_putc</td><td></td><td></td><td></td><td></td><td></td><td>x</td><td>x</td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td></tr> |
|||
<tr><td>f_puts</td><td></td><td></td><td></td><td></td><td></td><td>x</td><td>x</td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td></tr> |
|||
<tr><td>f_printf</td><td></td><td></td><td></td><td></td><td></td><td>x</td><td>x</td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td></tr> |
|||
<tr><td>f_gets</td><td></td><td></td><td></td><td></td><td></td><td></td><td>x</td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td></tr> |
|||
</table> |
|||
</div> |
|||
|
|||
<div class="para" id="lfn"> |
|||
<h3>Long File Name</h3> |
|||
<p>FatFs module supports LFN (long file name). The two different file names, SFN (short file name) and LFN, of a file is transparent on the API except for <tt>f_readdir()</tt> function. The LFN feature is disabled by default. To enable it, set <tt>_USE_LFN</tt> to 1, 2 or 3, and add <tt>option/unicode.c</tt> to the project. The LFN feature requiers a certain working buffer in addition. The buffer size can be configured by <tt>_MAX_LFN</tt> according to the available memory. The length of an LFN will reach up to 255 characters, so that the <tt>_MAX_LFN</tt> should be set to 255 for full featured LFN operation. If the size of working buffer is insufficient for the input file name, the file function fails with <tt>FR_INVALID_NAME</tt>. When enable the LFN feature with re-entrant configuration, <tt>_USE_LFN</tt> must be set to 2 or 3. In this case, the file function allocates the working buffer on the stack or heap. The working buffer occupies <tt>(_MAX_LFN + 1) * 2</tt> bytes.</p> |
|||
<table class="lst2 rset"> |
|||
<caption>LFN cfg on ARM7TDMI</caption> |
|||
<tr><th>Code page</th><th>Program size</th></tr> |
|||
<tr><td>SBCS</td><td>+3.7K</td></tr> |
|||
<tr><td>932(Shift-JIS)</td><td>+62K</td></tr> |
|||
<tr><td>936(GBK)</td><td>+177K</td></tr> |
|||
<tr><td>949(Korean)</td><td>+139K</td></tr> |
|||
<tr><td>950(Big5)</td><td>+111K</td></tr> |
|||
</table> |
|||
<p>When the LFN feature is enabled, the module size will be increased depends on the selected code page. Right table shows how many bytes increased when LFN feature is enabled with some code pages. Especially, in the CJK region, tens of thousands of characters are being used. Unfortunately, it requires a huge OEM-Unicode bidirectional conversion table and the module size will be drastically increased that shown in the table. As the result, the FatFs with LFN feature with those code pages will not able to be implemented to most 8-bit microcontrollers.</p> |
|||
<p>Note that the LFN feature on the FAT file system is a patent of Microsoft Corporation. This is not the case on FAT32 but most FAT32 drivers come with the LFN feature. FatFs can swich the LFN feature off by configuration option. When enable LFN feature on the commercial products, a license from Microsoft may be required depends on the final destination.</p> |
|||
</div> |
|||
|
|||
<div class="para" id="unicode"> |
|||
<h3>Unicode API</h3> |
|||
<p>By default, FatFs uses ANSI/OEM code set on the API under LFN configuration. FatFs can also switch the character encoding to Unicode on the API by <tt>_LFN_UNICODE</tt> option. This means that the FatFs supports the True-LFN feature. For more information, refer to the description in the <a href="filename.html">file name</a>.</p> |
|||
</div> |
|||
|
|||
<div class="para" id="reentrant"> |
|||
<h3>Re-entrancy</h3> |
|||
<p>The file operations to the different volume is always re-entrant and can work simultaneously. The file operations to the same volume is not re-entrant but it can also be configured to thread-safe by <tt>_FS_REENTRANT</tt> option. In this case, also the OS dependent synchronization object control functions, <tt>ff_cre_syncobj(), ff_del_syncobj(), ff_req_grant() and ff_rel_grant()</tt> must be added to the project. There are some examples in the <tt>option/syscall.c</tt>.</p> |
|||
<p>When a file function is called while the volume is in use by any other task, the file function is suspended until that task leaves the file function. If wait time exceeded a period defined by <tt>_TIMEOUT</tt>, the file function will abort with <tt>FR_TIMEOUT</tt>. The timeout feature might not be supported by some RTOS.</p> |
|||
<p>There is an exception for <tt>f_mount(), f_mkfs(), f_fdisk()</tt> function. These functions are not re-entrant to the same volume or corresponding physical drive. When use these functions, all other tasks must unmount the volume and avoid to access the volume.</p> |
|||
<p>Note that this section describes on the re-entrancy of the FatFs module itself but also the low level disk I/O layer will need to be re-entrant.</p> |
|||
</div> |
|||
|
|||
<div class="para" id="dup"> |
|||
<h3>Duplicated File Access</h3> |
|||
<p>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 and deleted. A violation of these rules can cause data colluption.</p> |
|||
<p>The file lock control can also be available by <tt>_FS_LOCK</tt> option. The value defines the number of open objects to manage simultaneously. In this case, if any open, rename or remove that violating the file shareing rule that described above is attempted, the file function will fail with <tt>FR_LOCKED</tt>. If number of open objects, files and sub-directories, gets larger than <tt>_FS_LOCK</tt>, the <tt>f_open(), f_optndir()</tt> function will fail with <tt>FR_TOO_MANY_OPEN_FILES</tt>.</p> |
|||
</div> |
|||
|
|||
<div class="para" id="fs1"> |
|||
<h3>Performance Effective File Access</h3> |
|||
<p>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 <tt>f_read()</tt> function.</p> |
|||
<p>Figure 1. Sector misaligned read (short)<br> |
|||
<img src="../img/f1.png" width="490" height="110" alt=""> |
|||
</p> |
|||
<p>Figure 2. Sector misaligned read (long)<br> |
|||
<img src="../img/f2.png" width="490" height="140" alt=""> |
|||
</p> |
|||
<p>Figure 3. Fully sector aligned read<br> |
|||
<img src="../img/f3.png" width="490" height="119" alt=""> |
|||
</p> |
|||
<p>The file I/O buffer is a sector buffer to read/write a partial data on the sector. The sector buffer is either file private sector buffer on each file object or shared sector buffer in the file system object. The buffer configuration option <tt>_FS_TINY</tt> determins which sector buffer is used for the file data transfer. When tiny buffer (1) is selected, data memory consumption is reduced 512 bytes each file object. In this case, FatFs module uses only a sector buffer in the file system 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.</p> |
|||
<p>Figure 1 shows that a partial sector, sector misaligned 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 <tt>disk_read()</tt> function at a time but the multiple sector transfer is divided at cluster boundary even if it is contiguous.</p> |
|||
<p>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.</p> |
|||
</div> |
|||
|
|||
<div class="para" id="fs2"> |
|||
<h3>Considerations on Flash Memory Media</h3> |
|||
<p>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.</p> |
|||
<h4>Using Mutiple-Sector Write</h4> |
|||
<div class="rset"> |
|||
Figure 6. Comparison between Multiple/Single Sector Write<br> |
|||
<img src="../img/f6.png" width="630" height="148" alt="fig.6"> |
|||
</div> |
|||
<p>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. This effect more appers at faster interface speed and the performance ratio often becomes grater than ten. <a href="../img/rwtest2.png">This graph</a> 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. The number of write transactions also affects the life time of 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 disk 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 feature. </p> |
|||
<h4>Forcing Memory Erase</h4> |
|||
<p>When remove a file with <tt>f_remove()</tt> 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 is forced erased on removing the file, those data blocks will be turned in to 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 feature by setting <tt>_USE_ERASE</tt> to 1. Note that this is an expectation of internal process of the flash memory storage and not that always effective. Also <tt>f_remove()</tt> function will take a time when remove a large file. Most applications will not need this feature.</p> |
|||
</div> |
|||
|
|||
<div class="para" id="critical"> |
|||
<h3>Critical Section</h3> |
|||
<p>If a write operation to the FAT volume is interrupted due to any accidental failure, such as sudden blackout, incorrect disk removal and unrecoverable disk error, the FAT structure on the volume can be broken. Following images shows the critical section of the FatFs module.</p> |
|||
<div class="lset"> |
|||
Figure 4. Long critical section<br> |
|||
<img src="../img/f4.png" width="320" height="436" alt="fig.4"> |
|||
</div> |
|||
<div class="lset"> |
|||
Figure 5. Minimized critical section<br> |
|||
<img src="../img/f5.png" width="320" height="436" alt="fig.5"> |
|||
</div> |
|||
<br class="clr"> |
|||
<p>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.</p> |
|||
<ul> |
|||
<li>The file data being rewrited is collapsed.</li> |
|||
<li>The file being appended returns initial state.</li> |
|||
<li>The file created as new is gone.</li> |
|||
<li>The file created as new or overwritten remains but no content.</li> |
|||
<li>Efficiency of disk use gets worse due to lost clusters.</li> |
|||
</ul> |
|||
<p>Each case does not affect the files that 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 <tt>f_sync()</tt> function as shown in Figure 5.</p> |
|||
</div> |
|||
|
|||
<div class="para" id="fs3"> |
|||
<h3>Extended Use of FatFs API</h3> |
|||
<p>These are examples of extended use of FatFs APIs. New item will be added whenever a useful code is found.</p> |
|||
<ol> |
|||
<li><a href="../img/app1.c">Open or create a file for append</a></li> |
|||
<li><a href="../img/app2.c">Empty a directory</a></li> |
|||
<li><a href="../img/app3.c">Allocate contiguous area to the file</a></li> |
|||
<li><a href="../img/app4.c">Function/Compatible checker for low level disk I/O module</a></li> |
|||
<li><a href="../img/mkfatimg.zip">FAT image creator</a></li> |
|||
</ol> |
|||
</div> |
|||
|
|||
<div class="para" id="license"> |
|||
<h3>About FatFs License</h3> |
|||
<p>FatFs has being developped as a personal project of author, ChaN. It is free from the code anyone else wrote. Following code block shows a copy of the FatFs license document that included in the source files.</p> |
|||
<pre>/*----------------------------------------------------------------------------/ |
|||
/ FatFs - FAT file system module R0.10b (C)ChaN, 2014 |
|||
/-----------------------------------------------------------------------------/ |
|||
/ FatFs module is a generic FAT file system module for small embedded systems. |
|||
/ This is a free software that opened for education, research and commercial |
|||
/ developments under license policy of following trems. |
|||
/ |
|||
/ Copyright (C) 2014, ChaN, all right reserved. |
|||
/ |
|||
/ * The FatFs module is a free software and there is NO WARRANTY. |
|||
/ * No restriction on use. You can use, modify and redistribute it for |
|||
/ personal, non-profit or commercial products UNDER YOUR RESPONSIBILITY. |
|||
/ * Redistributions of source code must retain the above copyright notice. |
|||
/ |
|||
/-----------------------------------------------------------------------------/</pre> |
|||
<p>Therefore FatFs license is one of the BSD-style licenses but there is a significant feature. Because FatFs is for embedded projects, the conditions of redistributions in binary form, such as embedded code, hex file, binary library or any forms without source code, are not specified in order to extend usability for commercial products. The documentation of the distributions need not include about FatFs and its license document, and it may also. This is equivalent to the BSD 1-Clause License. Of course FatFs is compatible with the projects under GNU GPL. When redistribute the FatFs with any modification or branch it as a folk, the license can also be changed to GNU GPL or BSD-style license.</p> |
|||
</div> |
|||
|
|||
<p class="foot"><a href="../00index_e.html">Return</a></p> |
|||
</body> |
|||
</html> |
|||
@ -1,71 +0,0 @@ |
|||
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd"> |
|||
<html lang="en"> |
|||
<head> |
|||
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> |
|||
<meta http-equiv="Content-Style-Type" content="text/css"> |
|||
<link rel="up" title="FatFs" href="../00index_e.html"> |
|||
<link rel="alternate" hreflang="ja" title="Japanese" href="../ja/dread.html"> |
|||
<link rel="stylesheet" href="../css_e.css" type="text/css" media="screen" title="ELM Default"> |
|||
<title>FatFs - disk_read</title> |
|||
</head> |
|||
|
|||
<body> |
|||
|
|||
<div class="para func"> |
|||
<h2>disk_read</h2> |
|||
<p>The disk_read function reads sector(s) from the storage device.</p> |
|||
<pre> |
|||
DRESULT disk_read ( |
|||
BYTE <span class="arg">pdrv</span>, <span class="c">/* [IN] Physical drive number */</span> |
|||
BYTE* <span class="arg">buff</span>, <span class="c">/* [OUT] Pointer to the read data buffer */</span> |
|||
DWORD <span class="arg">sector</span>, <span class="c">/* [IN] Start sector number */</span> |
|||
UINT <span class="arg">count</span> <span class="c">/* [IN] Number of sectros to read */</span> |
|||
); |
|||
</pre> |
|||
</div> |
|||
|
|||
<div class="para arg"> |
|||
<h4>Parameters</h4> |
|||
<dl class="par"> |
|||
<dt>pdrv</dt> |
|||
<dd>Physical drive number to identify the target device.</dd> |
|||
<dt>buff</dt> |
|||
<dd>Pointer to the <em>byte array</em> to store the read data.</dd> |
|||
<dt>sector</dt> |
|||
<dd>Start sector number in logical block address (LBA).</dd> |
|||
<dt>count</dt> |
|||
<dd>Number of sectors to read. FatFs specifis it in range of from 1 to 128.</dd> |
|||
</dl> |
|||
</div> |
|||
|
|||
|
|||
<div class="para ret"> |
|||
<h4>Return Value</h4> |
|||
<dl class="ret"> |
|||
<dt>RES_OK (0)</dt> |
|||
<dd>The function succeeded.</dd> |
|||
<dt>RES_ERROR</dt> |
|||
<dd>Any hard error occured during the read operation and could not recover it.</dd> |
|||
<dt>RES_PARERR</dt> |
|||
<dd>Invalid parameter.</dd> |
|||
<dt>RES_NOTRDY</dt> |
|||
<dd>The device has not been initialized.</dd> |
|||
</dl> |
|||
</div> |
|||
|
|||
|
|||
<div class="para desc"> |
|||
<h4>Description</h4> |
|||
<p>The memory address specified by <tt class="arg">buff</tt> is not that always aligned to word boundary because the type of argument is defined as <tt>BYTE*</tt>. The misaligned read/write request can occure at <a href="appnote.html#fs1">direct transfer</a>. If the bus architecture, especially DMA controller, does not allow misaligned memory access, it should be solved in this function. There are some workarounds described below to avoid this issue.</p> |
|||
<ul> |
|||
<li>Convert word transfer to byte transfer in this function. - Recommended.</li> |
|||
<li>For <tt>f_read()</tt>, avoid long read request that includes a whole of sector. - Direct transfer will never occure.</li> |
|||
<li>For <tt>f_read(fp, buff, btr, &br)</tt>, make sure that <tt>(((UINT)buff & 3) == (f_tell(fp) & 3))</tt> is true. - Word aligned direct transfer is guaranteed.</li> |
|||
</ul> |
|||
<p>Generally, a multiple sector transfer request must not be split into single sector transactions to the storage device, or you will not get good read throughput.</p> |
|||
</div> |
|||
|
|||
|
|||
<p class="foot"><a href="../00index_e.html">Return</a></p> |
|||
</body> |
|||
</html> |
|||
@ -1,97 +0,0 @@ |
|||
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd"> |
|||
<html lang="en"> |
|||
<head> |
|||
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> |
|||
<meta http-equiv="Content-Style-Type" content="text/css"> |
|||
<link rel="up" title="FatFs" href="../00index_e.html"> |
|||
<link rel="alternate" hreflang="ja" title="Japanese" href="../ja/fdisk.html"> |
|||
<link rel="stylesheet" href="../css_e.css" type="text/css" media="screen" title="ELM Default"> |
|||
<title>FatFs - f_fdisk</title> |
|||
</head> |
|||
|
|||
<body> |
|||
|
|||
<div class="para func"> |
|||
<h2>f_fdisk</h2> |
|||
<p>The f_fdisk fucntion divides a physical drive.</p> |
|||
<pre> |
|||
FRESULT f_fdisk ( |
|||
BYTE <span class="arg">pdrv</span>, <span class="c">/* [IN] Physical drive number */</span> |
|||
const DWORD <span class="arg">part[]</span>, <span class="c">/* [IN] Partition size */</span> |
|||
void* <span class="arg">work</span> <span class="c">/* [IN] Work area */</span> |
|||
); |
|||
</pre> |
|||
</div> |
|||
|
|||
<div class="para arg"> |
|||
<h4>Parameters</h4> |
|||
<dl class="par"> |
|||
<dt>pdrv</dt> |
|||
<dd>Specifies the <em>physical drive</em> to be divided.</dd> |
|||
<dt>part[]</dt> |
|||
<dd>Partition map table. It must have four items.</dd> |
|||
<dt>work</dt> |
|||
<dd>Pointer to the function work area. The size must be at least <tt>_MAX_SS</tt> bytes.</dd> |
|||
</dl> |
|||
</div> |
|||
|
|||
<div class="para ret"> |
|||
<h4>Return Values</h4> |
|||
<p> |
|||
<a href="rc.html#ok">FR_OK</a>, |
|||
<a href="rc.html#de">FR_DISK_ERR</a>, |
|||
<a href="rc.html#nr">FR_NOT_READY</a>, |
|||
<a href="rc.html#wp">FR_WRITE_PROTECTED</a>, |
|||
<a href="rc.html#ip">FR_INVALID_PARAMETER</a> |
|||
</p> |
|||
</div> |
|||
|
|||
<div class="para desc"> |
|||
<h4>Description</h4> |
|||
<p>The <tt>f_fdisk()</tt> function creates a partition table into the MBR of the physical drive. The partitioning rule is in generic FDISK format, so that it can create upto four primary partitions. Logical volumes in the extended partition is not supported. The <tt class="arg">part[]</tt> with four items specifies how to divide the physical drive. The first item specifies the size of first primary partition and fourth item specifies the fourth primary partition. If the value is less than or equal to 100, it specifies percentage of the partition in the entire disk space. If it is larger than 100, it specifies the partition size in unit of sector.</p> |
|||
</div> |
|||
|
|||
<div class="para comp"> |
|||
<h4>QuickInfo</h4> |
|||
<p>Available when <tt>_FS_READOLNY == 0</tt>, <tt>_USE_MKFS == 1</tt> and <tt>_MULTI_PARTITION == 1</tt>.</p> |
|||
</div> |
|||
|
|||
<div class="para use"> |
|||
<h4>Example</h4> |
|||
<pre> |
|||
<span class="c">/* Volume management table defined by user (required when _MULTI_PARTITION == 1) */</span> |
|||
|
|||
PARTITION VolToPart[] = { |
|||
{0, 1}, <span class="c">/* Logical drive 0 ==> Physical drive 0, 1st partition */</span> |
|||
{0, 2}, <span class="c">/* Logical drive 1 ==> Physical drive 0, 2nd partition */</span> |
|||
{1, 0} <span class="c">/* Logical drive 2 ==> Physical drive 1, auto detection */</span> |
|||
}; |
|||
</pre> |
|||
<pre> |
|||
<span class="c">/* Initialize a brand-new disk drive mapped to physical drive 0 */</span> |
|||
|
|||
FATFS fs; |
|||
DWORD plist[] = {50, 50, 0, 0}; <span class="c">/* Divide drive into two partitions */</span> |
|||
BYTE work[_MAX_SS]; |
|||
|
|||
f_fdisk(0, plist, work); <span class="c">/* Divide physical drive 0 */</span> |
|||
|
|||
f_mount(&fs, "0:", 0); <span class="c">/* Register work area to the logical drive 0 */</span> |
|||
f_mkfs("0:", 0, 0); <span class="c">/* Create FAT volume on the logical drive 0. 2nd argument is ignored. */</span> |
|||
f_mount(0, "0:", 0); <span class="c">/* Unregister work area from the logical drive 0 */</span> |
|||
|
|||
f_mount(&fs, "1:", 0); <span class="c">/* Register a work area to the logical drive 1 */</span> |
|||
f_mkfs("1:", 0, 0); <span class="c">/* Create FAT volume on the logical drive 1. 2nd argument is ignored. */</span> |
|||
f_mount(0, "1:", 0); <span class="c">/* Unregister work area from the logical drive 1 */</span> |
|||
|
|||
</pre> |
|||
</div> |
|||
|
|||
<div class="para ref"> |
|||
<h4>See Also</h4> |
|||
<p><a href="filename.html#vol">Volume management</a>, <a href="mkfs.html"><tt>f_mkfs</tt></a></p> |
|||
</div> |
|||
|
|||
<p class="foot"><a href="../00index_e.html">Return</a></p> |
|||
</body> |
|||
</html> |
|||
@ -1,78 +0,0 @@ |
|||
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd"> |
|||
<html lang="en"> |
|||
<head> |
|||
<meta http-equiv="Content-Type" content="text/html; charset=utf-8"> |
|||
<meta http-equiv="Content-Style-Type" content="text/css"> |
|||
<link rel="up" title="FatFs" href="../00index_e.html"> |
|||
<link rel="alternate" hreflang="ja" title="Japanese" href="../ja/filename.html"> |
|||
<link rel="stylesheet" href="../css_e.css" type="text/css" media="screen" title="ELM Default"> |
|||
<title>FatFs - Path Names</title> |
|||
</head> |
|||
|
|||
<body> |
|||
<h1>Path Names</h1> |
|||
|
|||
<div class="para" id="nam"> |
|||
<h3>Format of the path names</h3> |
|||
<p>The format of path name on the FatFs module is similer to the filename specs of DOS/Windos as follows:</p> |
|||
<pre>"[<em>drive</em>:][/]<em>directory</em>/<em>file</em>"</pre> |
|||
<p>The FatFs module supports long file name (LFN) and 8.3 format file name (SFN). The LFN can be used when LFN feature is enabled (<tt>_USE_LFN > 0</tt>). The sub directories are separated with a \ or / in the same way as DOS/Windows API. Duplicated separators are skipped and ignored. Only a difference is that the logical drive is specified in a numeral with a colon. When drive number is omitted, the drive number is assumed as <em>default drive</em> (drive 0 or current drive).</p> |
|||
<p>Control characters (<tt>'\0'</tt> to <tt>'\x1F'</tt>) are recognized as end of the path name. Leading/embedded spaces in the path name are valid as a part of the name at LFN configuration but they are recognized as end of the path name at non-LFN configuration. Trailing spaces and dots are ignored.</p> |
|||
<p>In default configuration (<tt>_FS_RPATH == 0</tt>), it does not have a concept of current directory like OS oriented file system. All objects on the volume are always specified in full path name that follows from the root directory. Dot directory names are not allowed. Heading separator is ignored and it can be exist or omitted. The default drive is fixed to drive 0.</p> |
|||
<p>When relative path feature is enabled (<tt>_FS_RPATH == 1</tt>), specified path is followed from the root directory if a heading separator is exist. If not, it is followed from the current directory of the drive set with <a href="chdir.html">f_chdir</a> function. Dot names are also allowed for the path name. The default drive is the current drive set with <a href="chdrive.html">f_chdrive</a> function.</p> |
|||
<table class="lst2"> |
|||
<tr><td>Path name</td><td>_FS_RPATH == 0</td><td>_FS_RPATH == 1</td></tr> |
|||
<tr class="lst3"><td>file.txt</td><td>A file in the root directory of the drive 0</td><td>A file in the current directory of the current drive</td></tr> |
|||
<tr><td>/file.txt</td><td>A file in the root directory of the drive 0</td><td>A file in the root directory of the current drive</td></tr> |
|||
<tr><td></td><td>The root directory of the drive 0</td><td>The current directory of the current drive</td></tr> |
|||
<tr><td>/</td><td>The root directory of the drive 0</td><td>The root directory of the current drive</td></tr> |
|||
<tr><td>2:</td><td>The root directory of the drive 2</td><td>The current directory of the drive 2</td></tr> |
|||
<tr><td>2:/</td><td>The root directory of the drive 2</td><td>The root directory of the drive 2</td></tr> |
|||
<tr><td>2:file.txt</td><td>A file in the root directory of the drive 2</td><td>A file in the current directory of the drive 2</td></tr> |
|||
<tr><td>../file.txt</td><td>Invalid name</td><td>A file in the parent directory</td></tr> |
|||
<tr><td>.</td><td>Invalid name</td><td>This directory</td></tr> |
|||
<tr><td>..</td><td>Invalid name</td><td>Parent directory of the current directory</td></tr> |
|||
<tr><td>dir1/..</td><td>Invalid name</td><td>The current directory</td></tr> |
|||
<tr><td>/..</td><td>Invalid name</td><td>The root directory (sticks the top level)</td></tr> |
|||
</table> |
|||
<p>When option <tt>_STR_VOLUME_ID</tt> is specified, also pre-defined strings can be used as drive identifier in the path name instead of a numeral.</p> |
|||
</div> |
|||
|
|||
<p><br></p> |
|||
<div class="para" id="uni"> |
|||
<h3>Unicode API</h3> |
|||
<p>The path names are input/output in either ANSI/OEM code (SBCS/DBCS) or Unicode depends on the configuration options. The type of arguments which specify the file names are defined as <tt>TCHAR</tt>. It is an alias of <tt>char</tt> in default. The code set used to the file name string is ANSI/OEM specifid by <tt>_CODE_PAGE</tt>. When <tt>_LFN_UNICODE</tt> is set to 1, the type of the <tt>TCHAR</tt> is switched to <tt>WCHAR</tt> to support Unicode (UTF-16 encoding). In this case, the LFN feature is fully supported and the Unicode specific characters, such as ✝☪✡☸☭, can also be used for the path name. It also affects data types and encoding of the string I/O functions. To define literal strings, <tt>_T(s)</tt> and <tt>_TEXT(s)</tt> macro are available to select either ANSI/OEM or Unicode automatically. The code shown below is an example to define the literal strings.</p> |
|||
<pre> |
|||
f_open(fp, "filename.txt", FA_READ); <span class="c">/* ANSI/OEM string */</span> |
|||
f_open(fp, L"filename.txt", FA_READ); <span class="c">/* Unicode string */</span> |
|||
f_open(fp, _T("filename.txt"), FA_READ); <span class="c">/* Changed by configuration */</span> |
|||
</pre> |
|||
</div> |
|||
|
|||
<p><br></p> |
|||
<div class="para" id="vol"> |
|||
<h3>Volume Management</h3> |
|||
<p>The FatFs module needs dynamic work area called <em>file system object</em> for each volume (logical drive). It is registered to the FatFs module by <tt>f_mount()</tt> function. By default, each logical drive is bound to the physical drive with the same drive number and an FAT volume on the drive is serched by auto detect feature. It loads boot sectors and checks it if it is an FAT boot sector in order of sector 0 as SFD format, 1st partition, 2nd partition, 3rd partition and 4th partition as FDISK format.</p> |
|||
<p>When <tt>_MULTI_PARTITION == 1</tt> is specified by configuration option, each individual logical drive is bound to the partition on the physical drive specified by volume management table. The volume management table must be defined by user to resolve relationship between logical drives and partitions. Following code is an example of a volume management table.</p> |
|||
<pre> |
|||
Example: Logical drive 0-2 are tied to three pri-partitions on the physical drive 0 (fixed disk) |
|||
Logical drive 3 is tied to an FAT volume on the physical drive 1 (removable disk) |
|||
|
|||
PARTITION VolToPart[] = { |
|||
{0, 1}, <span class="c">/* Logical drive 0 ==> Physical drive 0, 1st partition */</span> |
|||
{0, 2}, <span class="c">/* Logical drive 1 ==> Physical drive 0, 2nd partition */</span> |
|||
{0, 3}, <span class="c">/* Logical drive 2 ==> Physical drive 0, 3rd partition */</span> |
|||
{1, 0} <span class="c">/* Logical drive 3 ==> Physical drive 1 (auto detection) */</span> |
|||
}; |
|||
|
|||
<img src="../img/f7.png" width="828" height="288" alt="relationship between logical drive and physical drive"> |
|||
</pre> |
|||
<p>There are some considerations on using <tt>_MULTI_PARTITION</tt> configuration.</p> |
|||
<ul> |
|||
<li>Only four primary partitions can be specified. Logical partition is not supported.</li> |
|||
<li>The physical drive that has two or more mounted partitions must be non-removable. Media change while a system operation is prohibited.</li> |
|||
</ul> |
|||
</div> |
|||
|
|||
</body> |
|||
</html> |
|||
@ -1,129 +0,0 @@ |
|||
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd"> |
|||
<html lang="en"> |
|||
<head> |
|||
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> |
|||
<meta http-equiv="Content-Style-Type" content="text/css"> |
|||
<link rel="up" title="FatFs" href="../00index_e.html"> |
|||
<link rel="alternate" hreflang="ja" title="Japanese" href="../ja/lseek.html"> |
|||
<link rel="stylesheet" href="../css_e.css" type="text/css" media="screen" title="ELM Default"> |
|||
<title>FatFs - f_lseek</title> |
|||
</head> |
|||
|
|||
<body> |
|||
|
|||
<div class="para func"> |
|||
<h2>f_lseek</h2> |
|||
<p>The f_lseek function moves the file read/write pointer of an open file object. It can also be used to expand the file size (cluster pre-allocation). </p> |
|||
|
|||
<pre> |
|||
FRESULT f_lseek ( |
|||
FIL* <span class="arg">fp</span>, <span class="c">/* [IN] File object */</span> |
|||
DWORD <span class="arg">ofs</span> <span class="c">/* [IN] File read/write pointer */</span> |
|||
); |
|||
</pre> |
|||
</div> |
|||
|
|||
<div class="para arg"> |
|||
<h4>Parameters</h4> |
|||
<dl class="par"> |
|||
<dt>fp</dt> |
|||
<dd>Pointer to the open file object.</dd> |
|||
<dt>ofs</dt> |
|||
<dd>Byte offset from top of the file.</dd> |
|||
</dl> |
|||
</div> |
|||
|
|||
|
|||
<div class="para ret"> |
|||
<h4>Return Values</h4> |
|||
<p> |
|||
<a href="rc.html#ok">FR_OK</a>, |
|||
<a href="rc.html#de">FR_DISK_ERR</a>, |
|||
<a href="rc.html#ie">FR_INT_ERR</a>, |
|||
<a href="rc.html#nr">FR_NOT_READY</a>, |
|||
<a href="rc.html#io">FR_INVALID_OBJECT</a>, |
|||
<a href="rc.html#tm">FR_TIMEOUT</a> |
|||
</p> |
|||
</div> |
|||
|
|||
|
|||
<div class="para desc"> |
|||
<h4>Description</h4> |
|||
<p>The <tt>f_lseek()</tt> function moves the file read/write pointer of an open file. The offset can be specified in only origin from top of the file. When an offset beyond the file size is specified at write mode, the file size is expanded to the specified offset. The file data in the expanded area is undefined because no data is written to the file. This is suitable to pre-allocate a cluster chain quickly, for fast write operation. After the <tt>f_lseek()</tt> 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 current read/write pointer is not the expected value, either of followings has been occured.</p> |
|||
<ul> |
|||
<li>End of file. The specified <tt class="arg">ofs</tt> was clipped at end of the file because the file has been opened in read-only mode.</li> |
|||
<li>Disk full. There is insufficient free space on the volume to expand the file.</li> |
|||
</ul> |
|||
<p>Fast seek feature is enabled when <tt>_USE_FASTSEEK</tt> is set to 1 and the member <tt>cltbl</tt> in the file object is not NULL. This feature enables fast backward/long seek operations without FAT access by using CLMT (cluster link map table). The fast seek feature is also applied to <tt>f_read()/f_write()</tt> function, however, the file size cannot be expanded by <tt>f_write()/f_lseek()</tt> function.</p> |
|||
<p>The CLMT must be created in the user defined <tt>DWORD</tt> array prior to use the fast seek feature. To create the CLMT, set address of the <tt>DWORD</tt> array to the member <tt>cltbl</tt> in the file object, set the array size in unit of items into the first item and call the <tt>f_lseek()</tt> function with <tt class="arg">ofs</tt><tt> = CREATE_LINKMAP</tt>. After the function succeeded and CLMT is created, no FAT access is occured at subsequent <tt>f_read()/f_write()/f_lseek()</tt> function to the file. If the function failed with <tt>FR_NOT_ENOUGH_CORE</tt>, the given array size is insufficient for the file and number of items required is returned into the first item of the array. The required array size is (number of fragments + 1) * 2 items. For example, when the file is fragmented in 5, 12 items will be required for the CLMT.</p> |
|||
</div> |
|||
|
|||
|
|||
<div class="para comp"> |
|||
<h4>QuickInfo</h4> |
|||
<p>Available when <tt>_FS_MINIMIZE <= 2</tt>.</p> |
|||
</div> |
|||
|
|||
|
|||
<div class="para use"> |
|||
<h4>Example</h4> |
|||
<pre> |
|||
<span class="c">/* Open file */</span> |
|||
fp = malloc(sizeof (FIL)); |
|||
res = f_open(fp, "file.dat", FA_READ|FA_WRITE); |
|||
if (res) ... |
|||
|
|||
<span class="c">/* Move to offset of 5000 from top of the file */</span> |
|||
res = f_lseek(fp, 5000); |
|||
|
|||
<span class="c">/* Move to end of the file to append data */</span> |
|||
res = f_lseek(fp, f_size(fp)); |
|||
|
|||
<span class="c">/* Forward 3000 bytes */</span> |
|||
res = f_lseek(fp, f_tell(fp) + 3000); |
|||
|
|||
<span class="c">/* Rewind 2000 bytes (take care on wraparound) */</span> |
|||
res = f_lseek(fp, f_tell(fp) - 2000); |
|||
</pre> |
|||
<pre> |
|||
<span class="c">/* Cluster pre-allocation (to prevent buffer overrun on streaming write) */</span> |
|||
|
|||
res = f_open(fp, recfile, FA_CREATE_NEW | FA_WRITE); <span class="c">/* Create a file */</span> |
|||
|
|||
res = f_lseek(fp, PRE_SIZE); <span class="c">/* Expand file size (cluster pre-allocation) */</span> |
|||
if (res || f_tell(fp) != PRE_SIZE) ... <span class="c">/* Check if the file has been expanded */</span> |
|||
|
|||
res = f_lseek(fp, DATA_START); <span class="c">/* Record data stream WITHOUT cluster allocation delay */</span> |
|||
... <span class="c">/* DATA_START and write block size should be aligned to sector boundary */</span> |
|||
|
|||
res = f_truncate(fp); <span class="c">/* Truncate unused area */</span> |
|||
res = f_lseek(fp, 0); <span class="c">/* Put file header */</span> |
|||
... |
|||
|
|||
res = f_close(fp); |
|||
</pre> |
|||
<pre> |
|||
<span class="c">/* Using fast seek feature */</span> |
|||
|
|||
DWORD clmt[SZ_TBL]; <span class="c">/* Cluster link map table buffer */</span> |
|||
|
|||
res = f_lseek(fp, ofs1); <span class="c">/* This is normal seek (cltbl is nulled on file open) */</span> |
|||
|
|||
fp->cltbl = clmt; <span class="c">/* Enable fast seek feature (cltbl != NULL) */</span> |
|||
clmt[0] = SZ_TBL; <span class="c">/* Set table size */</span> |
|||
res = f_lseek(fp, CREATE_LINKMAP); <span class="c">/* Create CLMT */</span> |
|||
... |
|||
|
|||
res = f_lseek(fp, ofs2); <span class="c">/* This is fast seek */</span> |
|||
</pre> |
|||
</div> |
|||
|
|||
|
|||
<div class="para ref"> |
|||
<h4>See Also</h4> |
|||
<p><tt><a href="open.html">f_open</a>, <a href="truncate.html">f_truncate</a>, <a href="sfile.html">FIL</a></tt></p> |
|||
</div> |
|||
|
|||
<p class="foot"><a href="../00index_e.html">Return</a></p> |
|||
</body> |
|||
</html> |
|||
@ -1,73 +0,0 @@ |
|||
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd"> |
|||
<html lang="en"> |
|||
<head> |
|||
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> |
|||
<meta http-equiv="Content-Style-Type" content="text/css"> |
|||
<link rel="up" title="FatFs" href="../00index_e.html"> |
|||
<link rel="alternate" hreflang="ja" title="Japanese" href="../ja/mkfs.html"> |
|||
<link rel="stylesheet" href="../css_e.css" type="text/css" media="screen" title="ELM Default"> |
|||
<title>FatFs - f_mkfs</title> |
|||
</head> |
|||
|
|||
<body> |
|||
|
|||
<div class="para func"> |
|||
<h2>f_mkfs</h2> |
|||
<p>The f_mkfs fucntion creates an FAT file system on the logical drive.</p> |
|||
<pre> |
|||
FRESULT f_mkfs ( |
|||
const TCHAR* <span class="arg">path</span>, <span class="c">/* [IN] Logical drive number */</span> |
|||
BYTE <span class="arg">sfd</span>, <span class="c">/* [IN] Partitioning rule */</span> |
|||
UINT <span class="arg">au</span> <span class="c">/* [IN] Size of the allocation unit */</span> |
|||
); |
|||
</pre> |
|||
</div> |
|||
|
|||
<div class="para arg"> |
|||
<h4>Parameters</h4> |
|||
<dl class="par"> |
|||
<dt>path</dt> |
|||
<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> |
|||
<dt>sfd</dt> |
|||
<dd>Specifies partitioning rule (FDISK(0) or SFD(1)). This argument will be ignored on some case.</dd> |
|||
<dt>au</dt> |
|||
<dd>Specifies size of the allocation unit (cluter) in unit of byte. The value must be sector size * n (n is 1 to 128 and power of 2). When a zero is given, the cluster size is determined depends on the volume size.</dd> |
|||
</dl> |
|||
</div> |
|||
|
|||
<div class="para ret"> |
|||
<h4>Return Values</h4> |
|||
<p> |
|||
<a href="rc.html#ok">FR_OK</a>, |
|||