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 (Arguments): Overview</TITLE> 8<LINK rel="stylesheet" href="../../css/nitro.css" type="text/css"> 9</HEAD> 10<BODY> 11<H1 align="left">Debug (Arguments): Overview <IMG src="../../image/NTR.gif" align="middle"><IMG src="../../image/TWL.gif" align="middle"></H1> 12 13<P>The TWL-SDK has a mechanism that passes arguments to an SRL file, which are then obtained by the program to determine its behavior. This is effective for debugging and automated testing, because it allows you to change the arguments and run the same ROM without having to recompile. However, this mechanism was only intended to be used during development, so it cannot be used with FINALROM builds.</P> 14<P><FONT color="#ff0000">This cannot be used by a HYBRID ROM running in NITRO mode.</FONT></P> 15<H2>The Argument Data Area</H2> 16<P>The area used to store the argument data differs between NITRO ROMs and TWL ROMs.</P> 17<P>With NITRO ROMs, it will be stored in the application's variable region. This region is in the <CODE>.version</CODE> section of the ARM9.</P> 18<P>With TWL ROMs, it will be stored in the ROM header region.</P> 19<P><IMG src="argumentArea1.gif" width="223" height="381" border="0"><IMG src="argumentArea2.gif" width="227" height="381" border="0"></P> 20<P><BR> The argument data region stores the argument data along with the program name. For example, if the arguments <CODE>-A=35 -V test.dat</CODE> are passed to an SRL file called <CODE>main.srl</CODE>, they will be stored as follows:</P> 21<P><IMG src="argumentArea3.gif" width="475" height="280" border="0"></P> 22<P>The argument data region is of size <CODE>OS_ARGUMENT_BUFFER_SIZE</CODE> bytes. This value is defined as 256 for both NITRO and TWL.</P> 23<H2>Configuring the Argument Data</H2> 24<P>The <CODE><A href="../../tools/buryarg.html">buryarg</A></CODE> and <CODE><A href="../../tools/buryargTWL.html">buryarg.TWL</A></CODE> tools are provided to use for configuring argument data for an <CODE>.srl</CODE> file.</P> 25<P>NITRO ROMs and TWL ROMs each use a different tool. Make sure to use <CODE><A href="../../tools/buryarg.html">buryarg</A></CODE> for NITRO ROMs and <CODE><A href="../../tools/buryargTWL.html">buryarg.TWL</A></CODE> for TWL ROMs.</P> 26<P>Instead of specifying an SRL file to one of these tools, you can also specify an NLF file for a NITRO ROM or a TLF file for a TWL ROM. If you do, it will analyze the NLF or TLF file and overwrite the file that constructs the ROM. In this case, the "program name" that is written in the argument data region will be the name of the overwritten file.</P> 27<P>If you embedded argument data for use with SRL files, that argument data will not be applied to programs started from an NLF or TLF file. The converse is also true: if you embedded argument data for use with NLF or TLF files, that argument data will not be applied to programs started from an SRL file. This means that you should always start programs from the type of file intended to use the embedded data.</P> 28<H2>Retrieving Argument Data</H2> 29<P>Argument data that is embedded in an SRL file can be loaded by a program using <CODE><A href="OS_GetArgc.html">OS_GetArgc()</A></CODE> and <CODE><A href="OS_GetArgv.html">OS_GetArgv()</A></CODE>. These functions' specifications are compliant with the C standard functions <CODE>argc()</CODE> and <CODE>argv()</CODE>, and in the example above (the example in which the arguments <CODE>-A=35 -V test.dat</CODE> are passed to <CODE>main.srl</CODE>), the value of <CODE><A href="OS_GetArgc.html">OS_GetArgc()</A></CODE> will be <CODE>3</CODE>. Additionally, <CODE>OS_GetArgv(0)</CODE> will be "<CODE>main.srl</CODE>," <CODE>OS_GetArgv(1)</CODE> will be "<CODE>-A=35</CODE>," <CODE>OS_GetArgv(2)</CODE> will be "<CODE>-V</CODE>," and <CODE>OS_GetArgv(3)</CODE> will be "<CODE>test.dat</CODE>."</P> 30<P>The <CODE><A href="OS_GetOpt.html">OS_GetOpt()</A></CODE> function has been provided to handle arguments as option strings.</P> 31<H2>Setting and Getting the Argument Region</H2> 32<P>The <CODE><A href="OS_GetArgumentBuffer.html">OS_GetArgumentBuffer()</A></CODE> and <CODE><A href="OS_SetArgumentBuffer.html">OS_SetArgumentBuffer()</A></CODE> functions have been provided to change the argument data region accessed by <CODE><A href="OS_GetArgc.html">OS_GetArgc()</A></CODE> and <CODE><A href="OS_GetArgv.html">OS_GetArgv()</A></CODE>.</P> 33<P><CODE><A href="OS_GetArgumentBuffer.html">OS_GetArgumentBuffer()</A></CODE> gets the pointer to the current argument region. <CODE><A href="OS_SetArgumentBuffer.html">OS_SetArgumentBuffer()</A></CODE> sets a specified region as the argument data region.</P> 34<P>The <CODE><A href="OS_ConvertToArguments.html">OS_ConvertToArguments()</A></CODE> function has been provided for writing a specified string to a buffer in argument data format.</P> 35<H2>For FINALROM Builds:</H2> 36<P>The mechanism for passing these arguments was created for development purposes only, so it cannot be used with FINALROM builds of ROMs. Another reason for this decision is to avoid unforeseen bugs that could arise from leaving in a mechanism for passing parameters from outside the ROM. As a result, in FINALROM builds, <CODE><A href="OS_GetArgc.html">OS_GetArgc()</A></CODE> will always return 0, and <CODE><A href="OS_GetArgv.html">OS_GetArgv()</A></CODE> will always return <CODE>NULL</CODE>.</P> 37<P>FINALROM builds of NITRO ROMs do not even include a region to store argument data. Accordingly, the <CODE><A href="../../tools/buryarg.html">buryarg</A></CODE> tool cannot be used with FINALROM builds of NITRO ROMs. In contrast, the <CODE><A href="../../tools/buryargTWL.html">buryarg.TWL</A></CODE> tool can be used even for FINALROM builds of TWL ROMs, since for TWL ROMs the argument data is always located in a fixed region of the ROM header. However, as described earlier, the values that can be obtained will be only 0 or <CODE>NULL</CODE>.</P> 38<H2>Embedding Argument Data and Running the Files</H2> 39<P>The <CODE><A href="../../tools/nitrorun.html">nitrorun</A></CODE> and <CODE><A href="../../tools/nitrorunTWL.html">nitrorun.TWL</A></CODE> scripts have been provided for embedding arguments with <CODE><A href="../../tools/buryarg.html">buryarg</A></CODE> or <CODE><A href="../../tools/buryargTWL.html">buryarg.TWL</A></CODE> and running with <CODE><A href="../../tools/loadrun.html">loadrun</A></CODE> or <CODE><A href="../../tools/loadrunTWL.html">loadrun.TWL</A></CODE> in one step.</P> 40<H2>See Also</H2> 41<P><CODE><A href="../list_os.html#Debug-Argument">OS Function List: Debug (Arguments)</A><BR></CODE></P> 42<H2>Revision History</H2> 43<P>2008/07/10 Initial version.</P> 44<hr><p>CONFIDENTIAL</p></body> 45</HTML>
