FatFs R0.12c, released March 4, 2017

2017-05-10 19:22:13 -07:00
parent a353339125
commit c401843323
33 changed files with 556 additions and 439 deletions
@@ -64,7 +64,7 @@ FatFsモジュールはANSI C(C89)準拠で記述されているので、普通
 <div class="para doc" id="limits">
 <h3>限界値</h3>
 <ul>
-<li>ファイルシステム: FAT12, FAT16, FAT32(r0.0) および exFAT(r1.0)。</li>
+<li>ファイルシステム: FAT, FAT32(r0.0) および exFAT(r1.0)。</li>
 <li>同時オープン ファイル数: 無制限。(利用可能メモリによる)</li>
 <li>同時マウント ボリューム数: 最大 10。</li>
 <li>ファイル サイズ: 最大 4GiB - 1 (FATボリューム) および、事実上無制限(exFATボリューム)。</li>
@@ -144,7 +144,7 @@ And any other options are left not changed from default setting.
 <div class="para doc" id="lfn">
 <h3>長いファイル名</h3>
 <p>FatFsモジュールは、長いファイル名(LFN)をサポートします。ファイルに付けられた2つの異なる名前(短いファル名と長いファイル名)は、<tt>f_readdir</tt>関数を除くファイル操作関数において透過です。デフォルト構成では、LFN機能はOFFになっています。LFN機能を有効にするには、<tt><a href="config.html#use_lfn">_USE_LFN</a></tt>を1,2または3に設定し、<tt>option/unicode.c</tt>をプロジェクトに追加します。LFN機能は、加えてある程度のワーク エリア(LFN操作バッファ)を必要とします。バッファ長は使用できるメモリに応じて<tt><a href="config.html#max_lfn">_MAX_LFN</a></tt>で構成されることができます。LFNの長さは最大255文字に達するので、LFN完全対応のためには<tt>_MAX_LFN</tt>は255に設定されるべきです。与えられたファイル名に対してバッファ長が不足した場合、ファイル関数は<tt>FR_INVALID_NAME</tt>で失敗します。</p>
-<p>ファイル関数に再入を行う条件の下でLFN機能を使用する場合は、<tt>_USE_LFN</tt>は2または3に設定されなければなりません。この場合、ファイル関数はワーク エリアを動的に確保(スタックまたはヒープ)します。ワーク エリアのサイズは、<tt>(_MAX_LFN + 1) * 2</tt>バイト(exFAT利用時はさらに+608バイト)になるので、スタック等のサイズはそれを考慮した十分な余裕がなければなりません。</p>
+<p>ファイル関数に再入を行う条件の下でLFN機能を使用する場合は、<tt>_USE_LFN</tt>は2または3に設定されなければなりません。この場合、ファイル関数はワーク エリアを動的に確保(スタックまたはヒープ)します。ワーク エリアのサイズは、<tt>(_MAX_LFN + 1) * 2</tt>バイト(exFAT利用時は加えて<tt>((_MAX_LFN + 44) / 15 * 32</tt>バイト)になるので、これらのメモリ消費量に注意を払う必要があります。</p>
 <table class="lst2 rset">
 <caption>LFN構成 at CM3</caption>
 <tr><th><tt>_CODE_PAGE</tt></th><th>追加コード</th></tr>
@@ -165,10 +165,9 @@ And any other options are left not changed from default setting.

 <div class="para doc" id="exfat">
 <h3>exFATファイルシステム</h3>
-<p>exFAT(Microsoft's Extended File Allocation Table)ファイルシステムは、既に組み込みシステムや情報家電で広く使われているFATファイルシステムを置き換える目的で開発されました。exFATは、64GiB以上のSDメモリ カードで標準ファイルシステムに採用されるなど、FATに並びリムーバブル メディアの標準ファイルシステムの一つとなりつつあります。</p>
-<p>exFATボリュームでは、FATボリュームで制約となっていた4GiB以上のサイズのファイルを扱え、ファイルシステムのオーバーヘッド(特にファイル アロケーション ディレイ)も大幅に低減され、書き込みスループットがFATより向上しています。しかし、現リビジョンのFatFsでは、実装上の理由から不連続ファイルへのサイズ拡大を伴う書き込み時のとき、スループットがFATより低下します。<tt>f_expand</tt>関数による連続領域の割り当て機能は、この問題の回避に有効かもしれません。</p>
-<p>exFATはマイクロソフト社が開発したものなので、マイクロソフト社はexFATについていくつかの特許を保有しています。FatFsのexFAT機能は、それの US. Pat. App. Pub. No. 2009/0164440 A1 に基づいた実装です。このため、商用製品でexFAT機能を利用する場合、製品の最終仕向地によってはライセンスが必要になります。最近のFATドライバの多くはexFAT機能を含んでいるため、それらの使用に当たってライセンスが必要になりますが、FatFsは構成オプションでexFAT機能を任意にON/OFFできるため、無効にしてライセンス問題を回避することもできます。</p>
-<p><em>exFATを有効にすると、FatFsモジュールのC89互換は失われます(64ビット整数型が必要なため)。</em></p>
+<p>exFAT(Microsoft's Extended File Allocation Table)ファイルシステムは、既に組み込みシステムや情報家電で広く使われているFATファイルシステムを置き換える目的で開発されました。exFATは、64GiB以上のSDメモリ カードで標準ファイルシステムに採用されるなど、FATに並びリムーバブル メディアの標準ファイルシステムの一つとなっています。exFATボリュームでは、FATボリュームで制約となっていた4GiB以上のサイズのファイルを扱え、ファイルシステムのオーバーヘッド(特にファイル アロケーション ディレイ)も大幅に低減され、書き込みスループットがFATより向上しています。</p>
+<p>exFATはマイクロソフト社が開発したものなので、マイクロソフト社はexFATについていくつかの特許を保有しています。FatFsのexFAT機能は、それの<cite>US. Pat. App. Pub. No. 2009/0164440 A1</cite>に基づいた実装です。このため、商用製品でexFAT機能を利用する場合、製品の最終仕向地によってはライセンスが必要になります。最近のFATドライバの多くはexFAT機能を含んでいるため、それらの使用に当たってライセンスが必要になりますが、FatFsは構成オプションでexFAT機能を任意にON/OFFできるため、無効にしてライセンス問題を回避することもできます。</p>
+<p><em>exFATを有効にすると、FatFsモジュールのANSI C(C89)互換は失われます(64ビット整数型が必要なため)。</em></p>
 </div>

 <div class="para doc" id="reentrant">
@@ -30,7 +30,7 @@ FRESULT f_expand (
 <dt>fp</dt>
 <dd>対象となるファイル オブジェクト構造体へのポインタを指定します。</dd>
 <dt>fsz</dt>
-<dd>ファイルに割り当てるバイト単位のサイズ。データ型<tt>FSIZE_t</tt>は、<tt>DWORD</tt>(32-bit)または<tt>QWORD</tt>(64-bit)のエリアスで、exFATサポートの有無により切り替わります。</dd>
+<dd>ファイルに割り当てるバイト単位のサイズ。データ型<tt>FSIZE_t</tt>は、<tt>DWORD</tt>(32ビット)または<tt>QWORD</tt>(64ビット)のエリアスで、exFATサポートの有無により切り替わります。</dd>
 <dt>opt</dt>
 <dd>実際に割り当てを行うかどうか指定するフラグ。</dd>
 </dl>
@@ -79,15 +79,15 @@ FRESULT f_expand (
    res = f_open(fp = malloc(sizeof (FIL)), "file.dat", FA_WRITE|FA_CREATE_ALWAYS);
    if (res) { <span class="c">/* ファイルが開かれたかチェック */</span>
        free(fp);
-        ...
+        die("Failed to open the file.");
    }

    <span class="c">/* 100 MiB の連続領域を割り当てる */</span>
    res = f_expand(fp, 104857600, 1);
    if (res) { <span class="c">/* 割り当てられたかチェック */</span>
-        ...
+        f_close(fp);
        free(fp);
-        ...
+        die("Failed to allocate contiguous area.");
    }
    <span class="c">/* 連続ファイル作成成功 fp でアクセス可能 */</span>

@@ -62,15 +62,14 @@ FRESULT f_fdisk (
    <span class="c">/* ユーザ定義のボリューム管理テーブル (_MULTI_PARTITION == 1 のとき必要) */</span>

    PARTITION VolToPart[] = {
-        {0, 1},    <span class="c">/* 論理ドライブ 0 ==> 物理ドライブ 0, 第1区画 */</span>
-        {0, 2},    <span class="c">/* 論理ドライブ 1 ==> 物理ドライブ 0, 第2区画 */</span>
-        {1, 0}     <span class="c">/* 論理ドライブ 2 ==> 物理ドライブ 1, 自動検出 */</span>
+        {0, 1},    <span class="c">/* "0:" ==> 物理ドライブ 0, 第1区画 */</span>
+        {0, 2},    <span class="c">/* "1:" ==> 物理ドライブ 0, 第2区画 */</span>
+        {1, 0}     <span class="c">/* "2:" ==> 物理ドライブ 1, 自動検出 */</span>
    };
 </pre>
 <pre>
    <span class="c">/* 新しい物理ドライブ(0)の初期化 */</span>

-    FATFS fs;
    DWORD plist[] = {50, 50, 0, 0};  <span class="c">/* 第1区画,第2区画それぞれに50%ずつ割り当て */</span>
    BYTE work[_MAX_SS];

@@ -28,7 +28,7 @@ FRESULT f_lseek (
 <dt>fp</dt>
 <dd>対象となるファイル オブジェクト構造体へのポインタを指定します。</dd>
 <dt>ofs</dt>
-<dd>移動先のオフセット(リード/ライト ポインタ)値。ファイル先頭からのオフセットをバイト単位で指定します。データ型<tt>FSIZE_t</tt>は、<tt>DWORD</tt>(32-bit)または<tt>QWORD</tt>(64-bit)のエリアスで、exFATサポートの有無により切り替わります。</dd>
+<dd>移動先のオフセット(リード/ライト ポインタ)値。ファイル先頭からのオフセットをバイト単位で指定します。データ型<tt>FSIZE_t</tt>は、<tt>DWORD</tt>(32ビット)または<tt>QWORD</tt>(64ビット)のエリアスで、exFATサポートの有無により切り替わります。</dd>
 </dl>
 </div>

@@ -48,7 +48,8 @@ FRESULT f_lseek (

 <div class="para desc">
 <h4>解説</h4>
-<p>ファイルのリード/ライト ポインタ(次に読み出し・書き込みされるバイトのオフセット)を移動します。オフセットの原点はファイル先頭です。書き込みモードでファイル サイズより大きな値を指定すると、そこまでファイル サイズが拡張され、拡張された部分のデータは未定義となります。データを遅延無く高速に書き込みたいときは、予めこの関数で必要なサイズまでファイル サイズを拡張しておくと良いでしょう。ファイルに連続したデータ領域を割り当てる必要があるときは、<tt>f_expand</tt>関数を使用してください。<tt>f_lseek</tt>関数が正常終了したあとは、リード/ライト ポインタが正しく移動したかチェックするべきです。リード/ライト ポインタが指定より小さいときは、次の原因が考えられます。</p>
+<p>各ファイル オブジェクトが持つリード/ライト ポインタは、次に読み出し・書き込みされるバイトのオフセットを保持し、読み書きされただけ進みます。この関数は、ファイルへの読み書きを行わずにリード/ライト ポインタのみ移動します。</p>
+<p>書き込みモードでファイル サイズより大きな値を指定すると、そこまでファイル サイズが拡張されますが、拡張された部分のデータは未定義となります。データを遅延無く高速に書き込みたいときは、予めこの関数で必要なサイズまでファイル サイズを拡張しておくと良いでしょう。ファイルに連続したデータ領域を割り当てる必要があるときは、<tt>f_expand</tt>関数を使用してください。<tt>f_lseek</tt>関数が正常終了したあとは、リード/ライト ポインタが正しく移動したかチェックするべきです。リード/ライト ポインタが指定より小さいときは、次の原因が考えられます。</p>
 <ul>
 <li>非書き込みモードまたは高速シーク モードのため、ファイル サイズでクリップされた。</li>
 <li>ファイル拡張中にディスクが満杯になった。</li>
@@ -27,7 +27,14 @@
 </ul>
 ※開かれたファイルの操作においてこのエラーが発生すると、そのファイル オブジェクトはアボート状態となり、クローズ以外の操作ができなくなります。</dd>
 <dt id="nr">FR_NOT_READY</dt>
-<dd>下位レイヤ(<tt>disk_initialize</tt>関数)の失敗。つまり、物理ドライブが動作可能な状態にない。</dd>
+<dd>下位レイヤ(<tt>disk_initialize</tt>関数)の失敗。次のような理由が考えられる。
+<ul>
+<li>ドライブにメディアがセットされていない。</li>
+<li>下位レイヤの実装が不完全。</li>
+<li>間違ったハードウェア構成。</li>
+<li>ストレージ デバイスの故障。</li>
+</ul>
+</dd>
 <dt id="nf">FR_NO_FILE</dt>
 <dd>指定されたファイルが見つからなかった。</dd>
 <dt id="np">FR_NO_PATH</dt>
@@ -51,9 +58,9 @@
 <dt id="io">FR_INVALID_OBJECT</dt>
 <dd>指定されたファイル オブジェクトやディレクトリ オブジェクトが無効、またはヌル ポインタが渡された。無効になる理由は次のことが考えられます。
 <ul>
-<li>オープンされていない、既に閉じられた、破損しているなど。</li>
+<li>オープンされていない、既に閉じられている、破損しているなど。</li>
 <li>そのボリュームでマウント動作があり、ボリューム上の開かれたオブジェクトが全て無効化された。</li>
-<li>物理ドライブがメディアの取り外しで動作不可能になっている。</li>
+<li>物理ドライブがメディアの取り外し等で動作不可能になっている。</li>
 </ul>
 </dd>
 <dt id="wp">FR_WRITE_PROTECTED</dt>
@@ -13,7 +13,7 @@

 <div class="para">
 <h2>FILINFO</h2>
-<p><tt>FILINFO</tt>構造体は、<tt>f_stat/f_readdir/f_findfirst/f_findnext</tt>関数で返されるオブジェクトに関する情報を保持します。</p>
+<p><tt>FILINFO</tt>構造体は、<tt>f_stat/f_readdir/f_findfirst/f_findnext</tt>関数で返されるオブジェクトに関する情報を保持します。LFN使用時はサイズが大きく増加するので注意が必要です。</p>
 <pre>
 <span class="k">typedef</span> <span class="k">struct</span> {
    FSIZE_t fsize;               <span class="c">/* ファイル サイズ */</span>