# loadrun.TWL

## 説明

このコマンドは TWL ROM 用のものです。NITRO ROM については `loadrun` を参照してください。

`loadrun.TWL` は、指定のバイナリデータを IS-TWL-DEBUGGER 等の機材にダウンロードして実行するツールです。デバッガソフトウェアを起動する必要がなく、コマンドラインからすばやく実行することが出来ます。

## 使用方法

### 起動コマンド

`% loadrun.TWL [OPTION]... [TWLSRLFILE]`

`TWLSRLFILE` は、実行する ROM ファイルです。srl ファイルを指定できます。

`-L または --list` オプションを指定すると、現在接続されていて識別可能なデバイスを一覧にして表示します。以下は表示の例です。

> `---- Connected devices:
> 0: [IS-TWL-DEBUGGER] serial:10000995
> 1: [IS-TWL-DEBUGGER] serial:10000996
> 2 device(s) found.`

`serial` は、`-s` オプションで指定するシリアル番号となります。`[IS-TWL-DEBUGGER]`はデバイスの種類です。IS-TWL-DEBUGGER など他のソフトウェアがデバイスを使用していると `loadrun.TWL` はそのデバイスを見つけることが出来ません。

`-l または --lap` オプションを指定すると、ROM ファイルから `OS_Printf()` 等でデバッグ出力されたものをコンソールに出力する際に、各行の先頭に実行開始からの時間を {xx: xx} (分:秒)の形式で付加します。以下は表示の一例です。

> `{0:01}Program started
> {0:01}--- heap init
> {0:02}x=14 y=50
> {0:04}`

`-N` または `--nitro` オプションを指定すると、HYBRID ROM を IS-TWL-DEBUGGER 上で NITRO モードで動作させることができます。何も指定しない場合、TWL モードで動作します。なお、この機能を用いるためには IS-TWL-DEBUGGER のバージョンが v0.64 以降である必要があります。

`-A` または `--architecture` オプションを指定すると、`OS_Printf()` 等のデバッグ出力に対し、ARM7 と ARM9 のどちらのアーキテクチャのプロセッサから出されたものかを各行の先頭に <A9> または<A7>　のように付加します。

`-n` または `--console` オプションを指定すると、`OS_Printf()` 等がどのウィンドウに向けて出力されたものかを各行の先頭に <0> 〜 <3> で付加します。(IS-TWL-DEBUGGER には出力ウィンドウが4つ用意されています。)　出力先は、`OS_SetPrintOutput()` で指定しない場合の出力先を決めたり、`OS_FPrintf()` などで直接指定したりすることが出来ます。

なお、プロセッサの区別と出力ウィンドウの区別の両方を指定した場合は、<A9:0> や <A7:2> のように情報がまとめられます。

`-s` または `--serial`オプションは数値の引数をとります。これは srl ファイルをダウンロードするデバイスのシリアル番号を指定するためのオプションです。ここで指定したシリアル番号を持つ機材に対して操作を行ないます。(通常ないことですが)同じシリアル番号の機材が複数ある場合は最初に見つかったものとなります。なお、`-L` オプションのデバイス一覧で 04070680 とシリアル表示表示された場合、4070680 のように前の 0 は省略することが出来ます。その他、シリアルの指定は区別できる限り、下位の数桁で行うことが可能です。たとえば 10000123 と 10000453 というシリアルの機材が接続されている場合に前者を示したい場合は、-s10000123 と指定しなくても -s123 や -s23 で指定可能です。

`-t` または `--timeout` オプションは数値の引数を取ります。このオプションは表示タイムアウトを指定するもので、単位は秒です。srl ファイルを実行したのち、最後の `OS_Printf()` データを受信してから、次のデータが指定時間こない場合に強制終了します。指定値が 0 のときは、タイムアウト指定はしないという意味になります。オプション指定がない場合も同様です。

`-T` または `--exec-timeout` オプションは数値の引数を取ります。このオプションは実行タイムアウトを指定するもので、単位は秒です。srl ファイルを実行してから、指定の秒数が経過すると強制終了します。指定値が 0 のときは、実行タイムアウト指定はしないという意味になります。オプション指定がない場合も同様です。

`-a` または`--abort-string` オプションは実行の終了文字列を指定します。ここで指定した文字列が行頭から表示されると強制終了します。また改行に出会うまでは判定が保留されます。表示の間が時間的に開いても構いません。

例えば "ABORT " が終了文字列となっている場合、

> `OS_Printf("ABORT\n")
> OS_Printf("ABORTING\n")
> OS_Printf("ABORT\nQUIT\n")
> OS_Printf("ABOR");OS_Sleep(1000);OS_Printf("T\n");`

の何れでも終了しますが、

> `OS_Printf(" 　ABORT\n")　　// 前に空白が入っている
> OS_Printf("ABO\nRT\n")　　// 途中に改行が入っている
> OS_Printf("A B O R T\n")　// 空白が入っているので "ABORT" という文字列ではない`

では終了しません。また、

> `OS_Printf("ABORT")`

としてもまだ改行されていないのですぐには終了しません。この後 `OS_Printf("\n")` や `OS_Printf(" SOON\n")` のように改行コードがくれば終了します。

`-c` または `--card-slot` オプションは引数を取ります。引数は ON か OFF かのいずれかです。このオプションでは、実行時のカードスロットのロック指定を行ないます。何も指定しない場合は OFF となります。
(このオプションに関しては未実装ですので使用しないでください。なお、今後仕様が変更になる可能性もあります)

`-C` または `--cartridge-slot` オプションは引数を取ります。引数は ON か OFF のいずれかです。このオプションでは、実行時のカートリッジのロック指定を行ないます。何も指定しない場合は OFF となります。
(このオプションに関しては未実装ですので使用しないでください。なお、今後仕様が変更になる可能性もあります)

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

`-v` または `--verbose` オプションを指定すると、詳細な動作の説明を表示します。

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

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

###
終了条件

・TWL 側で `OS_Exit()` を呼ぶと、特定の文字列が表示されてプログラムは HALT状態になります。その表示文字列データを`loadrun.TWL` が受け取ると、終了ステータスを `OS_Exit()` で指定した値にセットして `loadrun.TWL` も終了します。

・オプションにより、ユーザが定めた特定の文字列の表示で終了します。

・オプションにより、ユーザが定めた実行タイムアウト時間より長く実行時間が経過すると終了します。

・オプションにより、ユーザが定めた表示タイムアウト時間より長く表示の無い状態が続くと終了します。

・ユーザが ctrl-C などでプログラムを停止した場合にも終了します。

###
デバッガ動作禁止フラグ

`srl` ファイルの中には、デバッガでの動作を禁止しているものがあります。これは `srl` ファイルに埋め込まれた ROMヘッダの特定の場所のビットで制御されており、禁止ファイルを `loadrun.TWL` でロードしようとするとエラーで停止します。

## 場所

`$TWLSDK/tools/bin/loadrun.TWL.exe`

## 参照

`nitrorun.TWL, OS_Exit, loadrun`

## 履歴

2008/06/12 HYBRID ROM を NITRO モードで動作させる(-Nオプション)説明を追加
2008/04/28 デバッガ禁止フラグについて記述追加
2008/01/12 初版作成