buryarg[.TWL]

# buryarg

# buryarg.TWL

## 説明

TWL SDK では、ROMイメージに引数データ領域を設け、その部分を起動前に書き換えることで、プログラムに C言語 の argc, argv 形式の引数として利用できるパラメータを与える仕組みを提供しています。ROM イメージファイルを直接書き換えることが出来るので、プログラムを再コンパイルしなくても複数の条件下でプログラムを試すことが出来ます。

`buryarg[.TWL]` は、指定のバイナリデータに対して、引数データ領域に引数データを書き込むためのツールです。なお、`buryarg` は NITRO ROM に対して、`buryarg.TWL` は TWL HYBRID ROM や TWL LIMITED ROM に対して使用します。

またプログラム内で引数データ領域を参照していない場合は、その領域は作成されません。領域が作成されていない ROM に対しては `buryarg[.TWL]` を適用することができません。

TWL SDK 5.3 より、`buryarg.TWL` での引数データの埋め込み方法が、`buryarg` と同じ仕様に変更されました。これにより、TWL HYBRID ROM に対して埋め込んだ引数データを NITRO モードで読むことができなかった問題が解決されています。
但し、`buryarg.TWL` の使用に際しては、注意事項があります。後述の TWL ROM での注意 をお読みください。

## 使用方法

### 起動コマンド

`% buryarg [OPTION]... SRLFILE [argument]...`

`SRLFILE` は、書き換えの元となる ROM ファイル (srl) です。但し、ROM ファイルリスト (nlf or tlf) を指定することもできます。ROM ファイルリストを指定すると、`buryarg[.TWL]` は内容を解析して ARM9 の常駐モジュールファイルに対し操作を行います。

`-r または --remain` オプションを指定すると元のファイルを残します。デフォルトでは元ファイルを変更しますので、元のファイルを変更したくない場合はこのオプションを指定します。なお別名のファイルは、元ファイルに "`.argAdded` " のついたファイル名となります。 `-o` オプションで出力ファイルを選択した場合はこのオプションを指定しなくても元ファイルは変更されません。

`-o または --output オプションは引数をとります。このオプションは、出力ファイルを、-o=dest.srl` または `-o dest.srl` のように指定します。出力ファイルとして元ファイルと同じファイルを指定しないようにしてください。また、出力ファイルとして "`-`" (マイナス) を指定すると、標準出力に対し出力します。( `-o-` のように指定します。)　後述の `--stdout` も参照してください。

`--stdout` は、`-o-` の指定と同じです。標準出力に対し出力します。

`-f` または `--file` オプションは引数をとります。このオプションは、置き換えるデータをファイルで指定するためのものです。`-f=rep.dat` または`-f rep.dat` のように指定します。

`-q` または `--quiet` オプション を指定すると quiet モードとなり、エラー以外のメッセージを出しません。

`-v` または `--verbose` オプションを指定すると、詳細な動作の説明を表示します。これは標準出力に出力されますので、ROMデータを標準出力に書き出すときには一緒に指定しないで下さい。

`-h` または `--help` オプションは、簡単な使い方を表示します。

`-d` または `--debug` オプションは、デバッグのためのオプションです。置き換えるデータをダンプします。

`--version` オプションは、コマンドのバージョンを表示します。

### 引数データ領域

コンパイルした直後の ROM データの中の引数データ領域にはその領域を識別するための文字列が書き込まれています。`buryarg[.TWL]` では、この文字列を ROM から探し出して、その直後に引数データを書き込みます。位置を見つけるための文字列は書き換わりませんので、同じ ROM データに対して何度でも引数データを書き込むことが出来ます。

プログラム中からは、引数領域のデータに `OS_GetArgc()` 、 `OS_GetArgv()` でアクセスすることが出来ます。

(注意) 以下のようなミスにご注意ください。

> ・`-o` オプションで、入力ファイルと同じファイルを指定した。
> → 上書きしたい場合にはこのような指定をする必要がありません。デフォルトでその動作を行ないます。

> ・ROM ファイル (srl) に対して引数データの書き換えを行なった。そして ROM ファイルリスト (nlf or tlf) から起動した。
> → ROM ファイルリスト から起動した場合、ファイルに書かれているモジュールがデバッガに読み込まれるので、ROM ファイルに対して書き換えを行ってもそれを反映させることは出来ません。ROM ファイルリストから起動するのなら、`buryarg[.TWL]` で ROM ファイルリストを指定して書き換えを行ってください。

> ・ROM ファイルリスト (nlf or tlf) に対してデータの書き換えを行なった。そして ROM ファイル (srl) を起動した。
> → 上の例の逆です。ROM ファイルに対して引数データの書き換えを行なってください。

> ・引数データ領域のないイメージに対して引数データ書き換えを行なおうとした。
> → 古い SDK で作成された ROM イメージには引数データを書き込む領域が用意されていません。そのイメージに対して `buryarg[.TWL]` コマンドを実行すると、引数データ領域を表す文字列が見つからないというエラーを表示して終了します。
> → プログラム中一度も引数データ領域を参照していない場合はコンパイル時に引数データ領域がデッドストリップされます。すなわち `OS_GetArgc()` や `OS_GetArgv()` が一度も呼び出されていないような場合ですが、この場合もエラーとなります。

> ・FINALROM ビルドのイメージに対して引数データ書き換えを行なおうとした。
> → FINALROM ビルドのイメージには引数データを格納する領域がありません。

> ・常駐領域に圧縮をかけたイメージに対して引数データ書き換えを行なおうとした。
> → 常駐領域に圧縮がかかっていると、文字列を探し出すことができなくなり、エラーとなります。引数データを埋め込む場合は、圧縮をかけないようにしてください。

### FINALROM と引数データ

FINALROM では引数データを扱うことが出来ません。引数データを格納する領域がありませんし、`OS_GetArgc()` は必ず 0 を返し、`OS_GetArgv()` は必ず NULL を返すようになります。FINALROM で引数データを扱えないのは、最終的にプログラムが外部から与えることの出来るデータに依存したままだとそれがセキュリティホールになってしまうかもしれないからです。

FINALROM であってもプログラム中の判定ルーチンは消さない限り残ります。FINALROM では意味のないコードではあるのですが、注意が必要です。(たとえば ステージ数30という触れ込みのゲームで "引数データがSTAGE>30 ならば" などという判定ルーチンを解析されたりすると、隠しステージがあるのではないかという推測に繋がるかもしれません。)

### TWL ROM での注意

TWL ROM では、ROM イメージ作成時にハッシュ値の計算を行っています。よって、ROM イメージに対して `buryarg.TWL` を使用して引数データを埋め込んでしまうと、ハッシュ値が変わってしまい、起動することができなくなります。
TWL ROM の場合には、ROM ファイルリスト (tlf) に対して `buryarg.TWL` を使用し、その後に `makerom.TWL` を使用して ROM ファイル (srl) を作成しなおすようにしてください。
この方法を行うには、OS ライブラリの サンプルデモ が参考になります。

## 場所

`$TwlSDK/tools/bin/buryarg.exe`
`$TwlSDK/tools/bin/buryarg.TWL.exe`

## 参照

`OS_GetArgc, OS_GetArgv, OS_GetOpt*`

## 履歴

2009/05/25 `buryarg.TWL` の仕様を `buryarg` と統一。それに伴い、マニュアルも統合。圧縮と併用できない旨を追記。
2008/07/08 TWL 用には `buryarg.TWL` を用いるよう追記
2008/06/24 TWL ではこの仕組みが使用できないことを記述
2005/08/30 参照に `OS_GetOpt*` を追加。`--stdout` を追加
2005/07/22 nlf ファイルへの対応
2005/07/21 初版作成