1<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
2<HTML>
3<HEAD>
4<META http-equiv="Content-Type" content="text/html; charset=windows-1252">
5<META name="GENERATOR" content="IBM WebSphere Studio Homepage Builder Version 7.0.1.0 for Windows">
6<META http-equiv="Content-Style-Type" content="text/css">
7<TITLE>Debug (String Display): Overview</TITLE>
8<LINK rel="stylesheet" href="../../css/nitro.css" type="text/css">
9</HEAD>
10<BODY>
11<H1 align="left">Debug (String Display): Overview <IMG src="../../image/NTR.gif" align="middle"><IMG src="../../image/TWL.gif" align="middle"></H1>
12<H2>Description</H2>
13<P>This page explains the debug display that can be used with TWL-SDK.</P>
14<H2>Output Destination (TWL mode)</H2>
15<H4>Standard Output</H4>
16<P>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 <A href="OS_SetPrintOutput.html"><CODE>OS_SetPrintOutput</CODE></A> function. Specify either <CODE>OS_PRINT_OUTPUT_ARM9</CODE> or <CODE>OS_PRINT_OUTPUT_ARM7</CODE> as the processor whose output destinations you want to change. Two convenience functions are also available: <A href="OS_SetPrintOutput.html"><CODE>OS_SetPrintOutput_Arm9</CODE></A>, which sets the output destination for the ARM9, and <A href="OS_SetPrintOutput.html"><CODE>OS_SetPrintOutput_Arm7</CODE></A>, which sets the output destination for the ARM7.</P>
17<P>Windows 0 through 3 can be specified for the output destination. In addition, output can be suppressed by specifying <CODE>OS_PRINT_OUTPUT_NONE</CODE>.</P>
18<BLOCKQUOTE style="background-color:#ffffcc;">(Example) Switch the output destination for the ARM9:<BR> <CODE><BR> //---- Change ARM9 output to Window 2<BR> <FONT color="#ff0000">OS_SetPrintOutput_Arm9( 2 );</FONT><BR> OS_Printf( &quot;This line is output in WINDOW 2.\n&quot; );<BR> <BR> //---- Suppress ARM9 output<BR> <FONT color="#ff0000">OS_SetPrintOutput_Arm9( OS_PRINT_OUTPUT_NONE );</FONT><BR> OS_Printf( &quot;This line is not displayed in any window.\n&quot; );</CODE><BR>
19</BLOCKQUOTE>
20<P>The output destinations specified here are used with standard display functions such as <A href="OS_Printf.html"><CODE>OS_Printf</CODE></A> that do not take the output destination as an argument. With functions such as <A href="OS_FPrintf.html"><CODE>OS_FPrintf</CODE></A> 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 <CODE>OS_PRINT_OUTPUT_CURRENT</CODE> as the destination uses this standard output.</P>
21<BLOCKQUOTE style="background-color:#ffffcc;">(Example) Switch the output destination for the ARM9:<BR> <BR> <CODE>//---- Change ARM9 output to Window 2<BR> <FONT color="#ff0000">OS_SetPrintOutput_Arm9( 2 );</FONT><BR> OS_Printf( &quot;This line is output in WINDOW 2.\n&quot;);<BR> <BR> //---- Specify the output window directly<BR> <FONT color="#ff0000">OS_FPrintf</FONT>( 3, &quot;This line is output in WINDOW 3\n&quot; );<BR> <FONT color="#ff0000">OS_FPrintf</FONT>( <FONT color="#ff0000">OS_PRINT_OUTPUT_CURRENT</FONT>, &quot;This line is output in WINDOW 2\n&quot;);</CODE><BR>
22</BLOCKQUOTE>
23<P>For highly urgent output, such as that displayed by the <A href="OS_Panic.html"><CODE>OS_Panic</CODE></A> and <A href="OS_Warning.html"><CODE>OS_Warning</CODE></A> functions, follow the guidelines shown in <B>Error Output</B>, below, for specifying the destination.</P>
24<H4><BR> Error Output</H4>
25<P>The output destination for highly urgent messages, such as those displayed by the <A href="OS_Panic.html"><CODE>OS_Panic</CODE></A> and <A href="OS_Warning.html"><CODE>OS_Warning</CODE></A> functions, can be changed in the same way as standard output. The output destination can be changed by calling the <A href="OS_SetPrintOutput.html"><CODE>OS_SetPrintOutput</CODE></A> function. Specify either <CODE>OS_PRINT_OUTPUT_PROC_ARM9ERR</CODE> or <CODE>OS_PRINT_OUTPUT_PROC_ARM7ERR</CODE> as the processor whose output destinations you want to change. Two convenience functions are also available: <A href="OS_SetPrintOutput.html"><CODE>OS_SetPrintOutput_Arm9Err</CODE></A>, which sets the error output destination for the ARM9, and <A href="OS_SetPrintOutput.html"><CODE>OS_SetPrintOutput_Arm7Err</CODE></A>, which sets the error output destination for the ARM7.</P>
26<P>Windows 0 through 3 can be specified for the output destination. In addition, output can be suppressed by specifying <CODE>OS_PRINT_OUTPUT_NONE</CODE>.</P>
27<P>The output destinations specified here are used with functions such as <A href="OS_Panic.html"><CODE>OS_Panic</CODE></A> that do not take an argument for the output destination of error output. With functions such as <A href="OS_FPanic.html"><CODE>OS_FPanic</CODE></A> 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 <CODE>OS_PRINT_OUTPUT_CURRENT</CODE> uses this error output setting as the output destination.</P>
28<H2>Output Destination (In NITRO Mode)</H2>
29<P>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 <CODE>OS_PRINT_OUTPUT_NONE</CODE>.</P>
30<H2>Types of Output Functions</H2>
31<P>There are many functions available for debug output.</P>
32<TABLE border="1">
33  <TBODY>
34    <TR>
35<TH>Usage</TH>
36<TH>Functions</TH>
37<TH>Output Destination</TH>
38    </TR>
39    <TR>
40<TD>Outputs the raw strings.</TD>
41<TD align="left"><A href="OS_PutString.html"><CODE>OS_PutString</CODE></A><BR> <A href="OS_FPutString.html"><CODE>OS_FPutString</CODE></A></TD>
42<TD>Standard Output</TD>
43    </TR>
44    <TR>
45<TD>Output with formatting<BR>Ordinary version</TD>
46<TD><A href="OS_Printf.html"><CODE>OS_Printf</CODE></A><BR> <A href="OS_FPrintf.html"><CODE>OS_FPrintf</CODE></A></TD>
47<TD>Standard Output</TD>
48    </TR>
49    <TR>
50<TD>    Simple version</TD>
51<TD><A href="OS_TPrintf.html"><CODE>OS_TPrintf</CODE></A><BR> <A href="OS_TFPrintf.html"><CODE>OS_TFPrintf</CODE></A><BR> <A href="OS_TPrintfEx.html"><CODE>OS_TPrintfEx</CODE></A><BR> <A href="OS_TFPrintfEx.html"><CODE>OS_TFPrintfEx</CODE></A></TD>
52<TD>Standard Output</TD>
53    </TR>
54    <TR>
55<TD>    Uses an argument list</TD>
56<TD><A href="OS_VPrintf.html"><CODE>OS_VPrintf</CODE></A><BR> <A href="OS_VFPrintf.html"><CODE>OS_VFPrintf</CODE></A></TD>
57<TD>Standard Output</TD>
58    </TR>
59    <TR>
60<TD>    Simple version; uses an argument list</TD>
61<TD><A href="OS_TVPrintf.html"><CODE>OS_TVPrintf</CODE></A><BR> <A href="OS_TVFPrintf.html"><CODE>OS_TVFPrintf</CODE></A><BR> <A href="OS_TVPrintfEx.html"><CODE>OS_TVPrintfEx</CODE></A><BR> <A href="OS_TVFPrintfEx.html"><CODE>OS_TVFPrintfEx</CODE></A></TD>
62<TD>Standard Output</TD>
63    </TR>
64    <TR>
65<TD>Output with formatting to memory<BR>Uses variable arguments</TD>
66<TD><A href="OS_SPrintf.html"><CODE>OS_SPrintf</CODE></A></TD>
67<TD>Memory</TD>
68    </TR>
69    <TR>
70<TD>    Uses an argument list</TD>
71<TD><A href="OS_VSPrintf.html"><CODE>OS_VSPrintf</CODE></A></TD>
72<TD>Memory</TD>
73    </TR>
74    <TR>
75<TD>    Uses a variable number of arguments; specifies the size</TD>
76<TD><A href="OS_SNPrintf.html"><CODE>OS_SNPrintf</CODE></A></TD>
77<TD>Memory</TD>
78    </TR>
79    <TR>
80<TD>    Uses an argument list; specifies the size</TD>
81<TD><A href="OS_VSNPrintf.html"><CODE>OS_VSNPrintf</CODE></A><BR> <A href="OS_VSNPrintfEx.html"><CODE>OS_VSNPrintfEx</CODE></A></TD>
82<TD>Memory</TD>
83    </TR>
84    <TR>
85<TD>Outputs warning<BR>Ordinary version</TD>
86<TD><A href="OS_Warning.html"><CODE>OS_Warning</CODE></A><BR> <A href="OS_FWarning.html"><CODE>OS_FWarning</CODE></A></TD>
87<TD>Error Output</TD>
88    </TR>
89    <TR>
90<TD>    Simple version</TD>
91<TD><A href="OS_TWarning.html"><CODE>OS_TWarning</CODE></A><BR> <A href="OS_TFWarning.html"><CODE>OS_TFWarning</CODE></A></TD>
92<TD>Error Output</TD>
93    </TR>
94  </TBODY>
95</TABLE>
96<H2>Relationship with STD Functions</H2>
97<P>The STD category also provides functions that output to memory, such as <A href="../../std/string/STD_TSPrintf.html"><CODE>STD_TSPrintf</CODE></A>, <A href="../../std/string/STD_TVSPrintf.html"><CODE>STD_TVSPrintf</CODE></A>, <A href="../../std/string/STD_TSNPrintf.html"><CODE>STD_TSNPrintf</CODE></A>, and <A href="../../std/string/STD_TVSNPrintf.html"><CODE>STD_TVSNPrintf</CODE></A>. 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.</P>
98<TABLE border="1">
99  <TBODY>
100    <TR>
101<TH>OS Functions</TH>
102<TH>Equivalent STD Functions</TH>
103    </TR>
104    <TR>
105<TD><CODE><A href="OS_Sprintf.html">OS_SPrintf</A></CODE></TD>
106<TD><CODE><A href="../../std/string/STD_TSPrintf.html">STD_TSPrintf</A></CODE></TD>
107    </TR>
108    <TR>
109<TD><A href="OS_VSPrintf.html"><CODE>OS_VSPrintf</CODE></A></TD>
110<TD><CODE><A href="../../std/string/STD_TVSPrintf.html">STD_TVNPrintf</A></CODE></TD>
111    </TR>
112    <TR>
113<TD><CODE><A href="OS_SNPrintf.html">OS_SNPrintf</A></CODE></TD>
114<TD><CODE><A href="../../std/string/STD_TSNPrintf.html">STD_TSNPrintf</A></CODE></TD>
115    </TR>
116    <TR>
117<TD><CODE><A href="OS_VSNPrintf.html">OS_VSNPrintf</A></CODE></TD>
118<TD><CODE><A href="../../std/string/STD_TVSNPrintf.html">STD_TVSNPrintf</A></CODE></TD>
119    </TR>
120  </TBODY>
121</TABLE>
122<P>The OS has the <A href="OS_VSNPrintfEx.html"><CODE>OS_VSNPrintfEx</CODE></A> extended memory output function, but this has an implementation in the OS library.</P>
123<H2>Blocking Mode</H2>
124<P>You can switch debugging output for IS-TWL-DEBUGGER and IS-NITRO-DEBUGGER between blocking mode and non-blocking mode.</P>
125<P>In non-blocking mode, if strings are continuously output at high speed such as by the <A href="OS_Printf.html"><CODE>OS_Printf</CODE></A> 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. </P>
126<P>This can be switched using the <A href="OS_SetPrintBlockingMode.html"><CODE>OS_SetPrintBlockingMode</CODE></A> function. The function that gets the current configuration status is <A href="OS_GetPrintBlockingMode.html"><CODE>OS_GetPrintBlockingMode</CODE></A>.</P>
127<P>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, <CODE><A href="OS_GetPrintBlockingMode.html">OS_GetPrintBlockingMode</A></CODE> always returns <CODE><A href="OS_GetPrintBlockingMode.html">FALSE</A></CODE>.</P>
128<H2>See Also</H2>
129<P><CODE><A href="../list_os.html#Debug-Print">OS Function List: Debug (String Display)</A><BR></CODE></P>
130<H2>Revision History</H2>
131<P>2009/04/21 Corrected the value in effect when blocking mode is unsupported.<BR> 2009/04/03 Added description of blocking mode.<BR> 2008/09/01 Added <B>Relationship with STD Functions</B>. <BR> 2008/01/12 Initial version.</P>
132<hr><p>CONFIDENTIAL</p></body>
133</HTML>