# デバッグ(文字列表示) (overview)

## 説明

TWL-SDK で使用できるデバッグ表示について説明します。

## 出力先(TWL モードの場合)

#### 標準出力

ARM9 では 出力ウィンドウ0、 ARM7 では出力ウィンドウ3 がデフォルトの出力先となっています。出力先の変更は `OS_SetPrintOutput()` を呼び出すことで行います。出力先を変更するプロセッサには `OS_PRINT_OUTPUT_ARM9` か、`OS_PRINT_OUTPUT_ARM7` を指定します。また、便利関数としてARM9 の出力先を指定する `OS_SetPrintOutput_Arm9()`、ARM7 の出力先を指定する `OS_SetPrintOutput_Arm7()` が用意されています。

出力先は、ウィンドウ0 〜 3 の指定が可能です。他に `OS_PRINT_OUTPUT_NONE` を指定することで出力を抑制することが出来ます。

> (例) ARM9 の出力先を切り替える
> `
> //---- Change ARM9 output to Window 2
> OS_SetPrintOutput_Arm9( 2 );
> OS_Printf( "This line is output in WINDOW 2.\n" );
> //---- Suppress ARM9 output
> OS_SetPrintOutput_Arm9( OS_PRINT_OUTPUT_NONE );
> OS_Printf( "This line is not displayed in any window.\n" );`

ここで指定した出力先は、`OS_Printf()` などのように通常の表示を行う関数で、出力先を引数に持たない場合に使用されます。`OS_FPrintf()` のように出力先を引数に持つ関数ではそこで行った指定が優先されます。出力先を引数にもつ関数で、出力先に`OS_PRINT_OUTPUT_CURRENT` を指定すると、この標準出力が出力先となります。

> (例) ARM9 の出力先を切り替える
> `//---- Change ARM9 output to Window 2
> OS_SetPrintOutput_Arm9( 2 );
> OS_Printf( "This line is output in WINDOW 2.\n");
> //---- Specify the output window directly
> OS_FPrintf( 3, "This line is output in WINDOW 3\n" );
> OS_FPrintf( OS_PRINT_OUTPUT_CURRENT, "This line is output in WINDOW 2\n");`

`OS_Panic()` や `OS_Warning()` のような緊急性の高い出力は後述の「エラー出力」にしたがって指定して下さい。

####
エラー出力

`OS_Panic()` や `OS_Warning()` など緊急性の高いメッセージの出力先も、標準出力同様に変更することが可能です。出力先の変更は `OS_SetPrintOutput()` を呼び出すことで行います。出力先を変更するプロセッサは `OS_PRINT_OUTPUT_PROC_ARM9ERR` か、 `OS_PRINT_OUTPUT_PROC_ARM7ERR` を指定します。また、便利関数として ARM9 のエラー出力先を指定する `OS_SetPrintOutput_Arm9Err()` 、ARM7 のエラー出力先を指定する `OS_SetPrintOutput_Arm7Err()` が用意されています。

出力先は、ウィンドウ0 〜 3 の指定が可能です。他に `OS_PRINT_OUTPUT_NONE` を指定することで出力を抑制することが出来ます。

ここで指定した出力先は、`OS_Panic()` などエラー出力表示の出力先を引数に持たない場合に使用されます。 `OS_FPanic()` のようにエラー出力先を引数に持つ関数ではそこで行った指定が優先されます。エラー出力先を引数に持つ関数で、出力先に`OS_PRINT_OUTPUT_CURRENT` を指定すると、このエラー出力が出力先となります。

## 出力先(NITRO モードの場合)

NITRO では出力先が一つしかありませんので、0〜3のいずれを指定しても同じウィンドウに出力されます。ただし、OS_PRINT_OUTPUT_NONE 指定で出力を抑制する機能はNITROモードでも使用できます。

## 出力関数の種類

デバッグ出力のための関数が数多く用意されています。

用途 | 関数 | 出力先
--- | --- | ---
文字列をそのまま出力する | `OS_PutString` `OS_FPutString` | 標準出力
フォーマット付きで出力する 通常版 | `OS_Printf` `OS_FPrintf` | 標準出力
簡易版 | `OS_TPrintf` `OS_TFPrintf` `OS_TPrintfEx` `OS_TFPrintfEx` | 標準出力
引数リスト利用 | `OS_VPrintf` `OS_VFPrintf` | 標準出力
簡易版、引数リスト利用 | `OS_TVPrintf` `OS_TVFPrintf` `OS_TVPrintfEx` `OS_TVFPrintfEx` | 標準出力
フォーマット付きでメモリ上に出力する 可変個引数利用 | `OS_SPrintf` | メモリ
引数リスト利用 | `OS_VSPrintf` | メモリ
可変個引数利用、サイズ指定あり | `OS_SNPrintf` | メモリ
引数リスト利用、サイズ指定あり | `OS_VSNPrintf` `OS_VSNPrintfEx` | メモリ
警告を出力する 通常版 | `OS_Warning` `OS_FWarning` | エラー出力
簡易版 | `OS_TWarning` `OS_TFWarning` | エラー出力

## STD_ 関数との関係

STD カテゴリにも `STD_TSPrintf()`, `STD_TVSPrintf()`, `STD_TSNPrintf()`, `STD_TVSNPrintf()` というメモリを対象とした出力関数が用意されています。OS ライブラリのメモリ対象の出力関数は、内部では最終的にこの STD_ 関数に到達しているので、あるOS_関数と STD_ 関数で同じ動作を行うものがあります。以下の表で同じ行の OS_関数 と STD_関数は同じ動作となります。

OS_ 関数 | 等しい STD_ 関数
--- | ---
`OS_SPrintf()` | `STD_TSPrintf()`
`OS_VSPrintf()` | `STD_TVNPrintf()`
`OS_SNPrintf()` | `STD_TSNPrintf()`
`OS_VSNPrintf()` | `STD_TVSNPrintf()`

OS 側には、`OS_VSNPrintfEx()` という拡張されたメモリ出力関数がありますが、こちらは OS ライブラリに実体を持っています。

## ブロッキングモード

IS-TWL-DEBUGGER ならびに IS-NITRO-DEBUGGER のデバッグ出力は、ブロッキングモードと非ブロッキングモードを切り替えることが出来ます。

非ブロッキングモードでは、高速に `OS_Printf()` 等で文字列を出力し続けたり、PC側で出力文字をバッファから取得しないことが続けば一部の出力文字列が失われる場合があります。ブロッキングモードでは出力文字列は確実に表示されますが、そのためにアプリケーションの動作が一時的に遅くなる場合もあります。

この切り替えは `OS_SetPrintBlockingMode()` で行います。現在の状態を取得する関数は `OS_GetPrintBlockingMode()` です。

この機能は、IS-TWL-DEBUGGER や IS-NITRO-DEBUGGER のバージョンによって実装されていない場合もあります。デバッガソフトウェアの更新履歴などでご確認ください。非対応の場合でも関数を呼び出すことは可能です。非対応の場合は `OS_GetPrintBlockingMode()` は常に FALSE を返します。

## 参照

`OS関数一覧(デバッグ(文字列表示))
`

## 履歴

2009/04/21 ブロッキングモードの非対応時の値を修正
2009/04/03 ブロッキングモードの説明を追加
2008/09/01 STD_関数との関係を追加
2008/01/12 初版