標準アーカイブ (overview)

説明

FSライブラリは、起動したプログラムの種類に応じていくつかの標準的なアーカイブをマウントします。
ここでは、それぞれのアーカイブについておおまかな特徴を解説します。

ROMアーカイブ

全てのプログラムは、makeromツールによって構築された1個のディレクトリツリーをDSカードのROMデータ領域内に格納しています。 このディレクトリツリーにアクセスするアーカイブがROMアーカイブであり、常に"rom:"という名前でマウントされます。 ROMに収録すべきデータはビルド時にmakeromツールで指定することができ、 NitroROMフォーマットと呼ばれるデータ構造を持ちます。 データの収録方法に関する詳細はmakeromツールのリファレンスをご参照ください。

ROMアーカイブは通常のカードアプリであれば特に問題なく使用することができますが、 それ以外のモードで起動した場合にはDSカードが実際に挿入されているかどうか定かではないため、 あたかも空のディレクトリであるかのように振舞います。 プログラムのブート種別については別途OS_GetBootType( )の説明をご参照ください。

DSダウンロードプレイによって起動したプログラムでカードアプリと同様にROMアーカイブを使用したい場合は、 WFSライブラリの使用をおすすめします。 このライブラリは、ダウンロード元の親機と再接続してローカル通信経由でROMデータへアクセスするためのユーティリティです。

ニンテンドーDSiでの機能拡張にともない、TWL-SDKではROMアーカイブの動作に大きな変更がありました。 以下、旧パッケージであるNITRO-SDKからの変更点をおおまかにまとめます。

NANDアーカイブ

TWLには本体NANDメモリが内蔵されており、この領域に存在するファイルシステムへアクセスするための何種類かのアーカイブを総称してNANDアーカイブと呼びます。 本体NANDメモリはそれ自体がいくつかのパーティションに分割されており、 個々のNANDアプリが保持するセーブデータファイルもそれぞれが1個の独立したファイルシステムになっていますが、 内部構造は全てFATフォーマットを採用しています。
本体NANDメモリの性能については別途プログラミングマニュアルをご参照ください。

NANDアーカイブとしてマウントされるアーカイブはNANDアプリの設定によって最大で10個近く存在し、それぞれが"photo:"や"dataPub:"などの異なる名前を持ちます。 各々のアーカイブに関する詳細はNANDアプリ開発用の関連ドキュメントをご参照ください。

SDメモリカードアーカイブ

TWLにはSDメモリカードスロットが搭載されており、プログラムの設定によってはこのスロットへのアクセスが可能です。 このときに使用するアーカイブがSDメモリカードアーカイブであり、"sdmc:"という名前でマウントされます。 SDメモリカードもFATフォーマットで構成されているため基本的な使用方法はNANDアーカイブとまったく同じですが、 データ転送速度が個々のSDメモリカードごとに大きく異なる点やアクセス中にメディアを抜き挿しされてしまう可能性がある点には注意が必要です。

メディアの抜き挿しをイベントとして監視したい場合はFS_RegisterEventHook()を利用することができます。現在のスロットの状態やライトプロテクトなどを確認したい場合はFS_GetPathInfo("sdmc:/", info)のようにルートディレクトリの情報として取得することができますが、スロットが空であったり不明なデバイスが挿入されている場合はこの関数が失敗しますので、FS_GetArchiveResultCode()の返り値で詳細を確認する必要があります。(たとえばFS_RESULT_MEDIA_NOTHINGであればスロットが空であることを示します)

また、SDメモリカードはパーソナルコンピュータや多くのデジタル家電製品でも一般的に使用される記憶媒体であり、 使用にあたってはアプリケーションの意図していない不正な内容のデータを外部から受け取ってしまう危険性を常に充分に考慮する必要があります。このような安全上の観点により現行ではSDメモリカードアーカイブは原則的に使用禁止となっていますが、開発の利便性を考慮し、TWL-SDK5.1PR以降ではDebug/Releaseビルド時のみ限定的にアクセスが許可されるようになりました。

メモリファイルアーカイブ

このアーカイブはFSライブラリ内部に存在する無名のアーカイブであり、システムにはマウントされていません。 FS_CreateFileFromMemory( )を呼び出してオープンした無名のファイルはこのアーカイブに属します。

任意のメモリ空間をあたかもファイルのように扱うことができるため、 頻繁に使用する小さなファイルをオンメモリ化するなど、使い方によっては大変便利なアーカイブです。

内部フォーマット

前述したいくつかの標準アーカイブは、それぞれに特性の異なる内部フォーマットを採用しています。 ここでは、各フォーマットのおおまかな特徴を解説します。

NitroROMフォーマット

makeromツールやTWL-Systemのnnsarc.exeツールなどで採用されている、 TWL-SDK固有のデータアーカイブフォーマットです。以下のような特徴を備えています。

NitroROMフォーマットの概要については $TwlSDK/docs/technicalNotes/AboutFileSystem.pdf で紹介されていますが、通常は一般開発者がこの仕様を考慮する必要はありません。

FATフォーマット

国際規格ISO/IEC 9293として標準化され、SDメモリカードやハードディスクなどで広く採用されている、いわゆるFATファイルシステムです。 FATフォーマットに関してはさまざまな解説書籍や仕様書などが存在しますので説明を省略しますが、 ここでは実際の使用にあたって注意しておきたいいくつかの特徴を述べておきます。

また、TWLにおけるFATのドライバ実装は以下のような特徴を持っています。

また、SDメモリカードへアクセスしている最中にSDメモリカードを抜かれてしまうと、 FATの内部状態に不整合をきたしてしまう致命的なタイミングが存在します。 そのときに起こりえる不具合と対策を以下にまとめます。

抜かれる状況まれに起こる症状プログラムでとりうる対策
ファイルサイズ変更中(SetFileLength) 増加予定分のファイルサイズが空き容量から失われる。
または減少した分のファイルサイズが空き容量から失われる。
(ファイル自体には異常なし)		 プログラムからこれを復旧する方法はありません。PCなどの外部環境でチェックディスクツールを使用すれば復旧できるかもしれません。
エントリの作成中(Create)
エントリの移動中(Rename)		 内部で確保中だった長いファイル名が消失し、13文字あたり32バイトが空き容量から失われる。
エントリの削除中(Delete)
エントリの移動中(Rename)		 削除中のエントリが使用していた全クラスタが空き容量から失われる。*1
長いファイル名だけが消失してしまい、8.3形式の短いファイル名となる。*2 プログラムが大文字と小文字の違いを特に区別しないのであれば問題ありません。
エントリの移動中(Rename) 新旧両方のエントリが存在し、どちらを参照/変更しても同じ内容を指すようになる。
一方を削除したらもう一方は削除操作以外全てFS_RESULT_ERRORで失敗する。		 新旧両方のエントリを削除して作り直す必要があります。
ファイル追記後のクローズ中(Close) 追記した領域の実体が確保されないままファイルサイズ情報だけが更新され、不整合が生じる。
追記した領域へアクセスするとFS_RESULT_ERRORで失敗する。		 ファイルを削除して作り直す必要があります。
*1と*2が同時に発生することはありません。

各フォーマットの動作比較

FSライブラリは多くのファイルシステム操作APIを用意し、各アーカイブがそのインタフェースに準拠することを要求していますが、 ファイルシステムの仕様上どうしてもサポートできないオペレーションについては実装しないことも許容しています。 そのようなアーカイブに対してAPIを呼び出した場合、常にFS_RESULT_UNSUPPORTEDのエラーが返されます。
主要な関数に対する各フォーマットの対応状況を下表に示します。

使用可能使用不可能

関数 NitroROMフォーマット
(ROMアーカイブ)		 FATフォーマット
(NANDアーカイブ、
SDメモリカードアーカイブ)		 (メモリファイルアーカイブ)
FS_OpenFileEx (FS_OpenFile) *3
FS_OpenFileFast *4 *3
FS_ConvertPathToFileID *4 *3
FS_OpenFileDirect *5 *3
FS_GetFileImageTop *5
FS_GetFileImageBottom *5
FS_CloseFile
FS_GetFileLength
FS_SetFileLength
FS_GetFilePosition
FS_SeekFile
FS_SeekFileToBegin
FS_SeekFileToEnd
FS_ReadFile
FS_ReadFileAsync
FS_WriteFile *1
FS_WriteFileAsync *1
FS_FlushFile *1
FS_OpenDirectory (FS_FindDir) *3
FS_ReadDirectory (FS_ReadDir) *3
FS_CloseDirectory *3
FS_TellDir *4 *3
FS_SeekDir *4 *3
FS_RewindDir *4 *3
FS_GetPathName *4 *3
FS_GetPathLength *4 *3
FS_CreateFile *2 *3
FS_DeleteFile *2 *3
FS_RenameFile *2 *3
FS_CreateDirectory *2 *3
FS_DeleteDirectory *2 *3
FS_RenameDirectory *2 *3
*1 ファイルの内容を書き換えるコマンドは非対応です。
*2 ディレクトリ構造を動的に変更するコマンドは非対応です。
*3 ディレクトリ構造へアクセスするコマンドは非対応です。
*4 ファイルIDやディレクトリIDを使用するコマンドは非対応です。
*5 デバイスのアドレス空間へ直接アクセスするコマンドは非対応です。

返しうるエラーコードの一覧

FSライブラリが定義しているエラーコードは全てのアーカイブの内部処理を包括したものなので、 エラーコードによっては特定のアーカイブからしか返されないものもいくつか存在します。 参考までに、各アーカイブが返す可能性のあるエラーコードの一覧を下表に示します。

エラーコード (FSResult)ROMアーカイブNANDアーカイブSDメモリカードアーカイブメモリファイルアーカイブ備考
FS_RESULT_SUCCESS YesYesYesYes
FS_RESULT_FAILURE YesYesYesYes
FS_RESULT_BUSY YesYesYesYes
FS_RESULT_CANCELED YesYesYesYes
FS_RESULT_UNSUPPORTED YesYesYesYes
FS_RESULT_ERROR YesYesYesYes
FS_RESULT_INVALID_PARAMETER YesYesYesYes
FS_RESULT_NO_MORE_RESOURCE NoYesYesNo
FS_RESULT_ALREADY_DONE NoYesYesNo
FS_RESULT_PERMISSION_DENIED YesYesYesNo
FS_RESULT_MEDIA_FATAL NoYesYesNoNAND/SDメモリカード固有のエラーです。
FS_RESULT_NO_ENTRY YesYesYesNo
FS_RESULT_MEDIA_NOTHING NoNoYesNoSDメモリカード固有のエラーです。
FS_RESULT_MEDIA_UNKNOWN NoNoYesNoSDメモリカード固有のエラーです。
FS_RESULT_BAD_FORMAT NoYesYesNoFATフォーマット固有のエラーです。

参照

FS関数一覧

履歴

2010/07/10 長い処理時間がかかるコマンド中の電源断でNANDがFS_RESULT_BAD_FORMATを返す状態になる旨を追記
2009/06/08 TWL専用領域とTWL専用ファイルについて追記。
2009/05/13 SDメモリカードの挿抜検出やスロット状態の判定方法について追記。
2009/04/13 参考資料の文書名を訂正。TWLモードでのROMアーカイブ動作について追記。
2009/04/10 表中で使用する記号を標準的な表記に置き換え。
2009/02/27 FATドライバのファイルアクセス動作について追記
2009/01/13 SDメモリカードアーカイブがDebug/Releaseビルド時のみ限定的にアクセス許可される旨を追記
2008/12/08 各アーカイブが返しうるエラーコードの一覧を追記
2008/10/28 FATで連番ファイルを作成する際の注意を追記
2008/10/20 TLFをロードしてた場合にROMの検証処理が実行されない旨を追記
2008/09/30 SDメモリカードの挿抜で生じるFAT状態不整合に関して追記
2008/09/26 SDメモリカードの挿抜に関して追記、ROMアーカイブのアクセス速度に関して追記
2008/09/16 FATドライバの仕様に関して追記
2008/09/12 初版