Debug (String Display): Overview

Description

This page explains the debug display that can be used with 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 the OS_SetPrintOutput function. 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 such as OS_Printf that do not take the output destination as an argument. With functions such as OS_FPrintf that do take the output destination as an argument, the destination specified in that argument is given priority. With functions that take the output destination as an argument, specifying OS_PRINT_OUTPUT_CURRENT as the destination uses 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 the OS_Panic and OS_Warning functions, 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 the OS_Panic and OS_Warning functions, can be changed in the same way as standard output. The output destination can be changed by calling the OS_SetPrintOutput function. 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 such as OS_Panic that do not take an argument for the output destination of error output. With functions such as OS_FPanic that do take the error output destination as an argument, the destination specified in that argument is given priority. In functions that take the error output destination as an argument, specifying OS_PRINT_OUTPUT_CURRENT uses this error output setting as the output destination.

Output Destination (In 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 also 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.

Blocking Mode

You can switch debugging output for IS-TWL-DEBUGGER and IS-NITRO-DEBUGGER between blocking mode and non-blocking mode.

In non-blocking mode, if strings are continuously output at high speed such as by the OS_Printf function, or the PC continues not to get output characters from the buffer, some output strings may be lost. In blocking mode, output strings are certainly displayed, but for that reason, the operations of the application are temporarily slowed down.

This can be switched using the OS_SetPrintBlockingMode function. The function that gets the current configuration status is OS_GetPrintBlockingMode.

This feature is sometimes not implemented depending on the version of IS-TWL-DEBUGGER and IS-NITRO-DEBUGGER. Check the debugging software update history. You can even call this function when the feature is unsupported. If the feature is unsupported, OS_GetPrintBlockingMode always returns FALSE.

See Also

OS Function List: Debug (String Display)

Revision History

2009/04/21 Corrected the value in effect when blocking mode is unsupported.
2009/04/03 Added description of blocking mode.
2008/09/01 Added Relationship with STD Functions.
2008/01/12 Initial version.


CONFIDENTIAL