# Debug (String Display): Overview

## Description

This page explains the debug display that can be used with the TWL-SDK.

## Output Destination (TWL mode)

#### Standard Output

Output window 0 is the default for the ARM9, and Output window 3 is the default for the ARM7. The output destination can be changed by calling `OS_SetPrintOutput()`. Specify either `OS_PRINT_OUTPUT_ARM9` or `OS_PRINT_OUTPUT_ARM7` as the processor whose output destinations you want to change. Two convenience functions are also available: `OS_SetPrintOutput_Arm9()`, which sets the output destination for the ARM9, and `OS_SetPrintOutput_Arm7()`, which sets the output destination for the ARM7.

Windows 0 through 3 can be specified for the output destination. In addition, output can be suppressed by specifying `OS_PRINT_OUTPUT_NONE`.

> (Example) Switch the output destination for the 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" );`

The output destinations specified here are used with standard display functions like `OS_Printf()` that do not take the output destination as an argument. With functions like `OS_FPrintf` that do take the output destination as an argument, the destination specified in that argument will be given priority. With functions that take the output destination as an argument, specifying `OS_PRINT_OUTPUT_CURRENT` as the destination will use this standard output.

> (Example) Switch the output destination for the 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");`

For highly urgent output, such as that displayed by `OS_Panic()` and `OS_Warning()`, follow the guidelines shown in "Error Output" below for specifying the destination.

####
Error Output

The output destination for highly urgent messages, such as those displayed by `OS_Panic()` and `OS_Warning()`, can be changed in the same way as standard output. The output destination can be changed by calling `OS_SetPrintOutput()`. Specify either `OS_PRINT_OUTPUT_PROC_ARM9ERR` or `OS_PRINT_OUTPUT_PROC_ARM7ERR` as the processor whose output destinations you want to change. Two convenience functions are also available: `OS_SetPrintOutput_Arm9Err()`, which sets the error output destination for the ARM9, and `OS_SetPrintOutput_Arm7Err()`, which sets the error output destination for the ARM7.

Windows 0 through 3 can be specified for the output destination. In addition, output can be suppressed by specifying `OS_PRINT_OUTPUT_NONE`.

The output destinations specified here are used with functions like `OS_Panic()` that do not take an argument for the output destination of error output. With functions like `OS_FPanic()` that do take the error output destination as an argument, the destination specified in that argument will be given priority. In functions that take the error output destination as an argument, specifying `OS_PRINT_OUTPUT_CURRENT` will use this error output setting as the output destination.

## Output Destination (NITRO mode)

In NITRO, there is only one output destination, so the output will be directed to the same window regardless of which window (0-3) is specified. However, the feature to suppress output can be used even in NITRO mode by specifying `OS_PRINT_OUTPUT_NONE`.

## Types of Output Functions

There are many functions available for debug output.

Usage | Functions | Output Destination
--- | --- | ---
Outputs the raw strings. | `OS_PutString` `OS_FPutString` | Standard Output
Output with formatting Ordinary version | `OS_Printf` `OS_FPrintf` | Standard Output
Simple version | `OS_TPrintf` `OS_TFPrintf` `OS_TPrintfEx` `OS_TFPrintfEx` | Standard Output
Uses an argument list | `OS_VPrintf` `OS_VFPrintf` | Standard Output
Simple version; uses an argument list | `OS_TVPrintf` `OS_TVFPrintf` `OS_TVPrintfEx` `OS_TVFPrintfEx` | Standard Output
Output with formatting to memory Uses variable arguments | `OS_SPrintf` | Memory
Uses an argument list | `OS_VSPrintf` | Memory
Uses a variable number of arguments; specifies the size | `OS_SNPrintf` | Memory
Uses an argument list; specifies the size | `OS_VSNPrintf` `OS_VSNPrintfEx` | Memory
Outputs warning Ordinary version | `OS_Warning` `OS_FWarning` | Error Output
Simple version | `OS_TWarning` `OS_TFWarning` | Error Output

## Relationship with STD Functions

The STD category, as well, provides functions that output to memory, such as `STD_TSPrintf`, `STD_TVSPrintf`, `STD_TSNPrintf`, and `STD_TVSNPrintf`. The OS library functions that output to memory ultimately use STD functions internally, so some OS functions may have the same behavior as STD functions. OS functions and STD functions on the same rows in the following table have the same behavior.

OS Functions | Equivalent STD Functions
--- | ---
`OS_SPrintf()` | `STD_TSPrintf()`
`OS_VSPrintf()` | `STD_TVNPrintf()`
`OS_SNPrintf()` | `STD_TSNPrintf()`
`OS_VSNPrintf()` | `STD_TVSNPrintf()`

The OS has the `OS_VSNPrintfEx` extended memory output function, but this has an implementation in the OS library.

## See Also

`OS Function List: Debug (String Display)
`

## Revision History

2008/09/01 Added a description of the relationship with STD functions.
2008/01/12 Initial version.

CONFIDENTIAL