buryarg

Description

This command is for NITRO ROMs.See buryarg.TWL for details on TWL ROMs.

In TWL-SDK, an area for argument data is set up in the ROM image. By rewriting this section before startup, you can pass which parameters are possible to use as C language argc and argv format arguments. The ROM image file can be directly overwritten, so you can test the program under multiple conditions without having to recompile.

buryarg is a tool for writing argument data to the argument data area for the specified binary data. This tool is used with NITRO ROMs; use buryarg.TWL on NITRO/TWL hybrid ROMs or TWL-exclusive ROMs.

If the argument data region within the program is not referenced, that region will not be created. The buryarg tool cannot be used for ROMs for which this area has not been created.

Using the Tool

Start Command

% buryarg [OPTION]... NITROSRLFILE [argument]...

NITROSRLFILE is the original ROM file for rewriting. Normally, this is a .srl file. However, if you specify a .nlf file, it will be analyzed and the operation will be done on the ARM9 resident module file.

If the -r or --remain options are specified, the original file will remain. By default, the original file will be modified. So if you don't want to change the original file, specify this option. The alias filename is the original filename plus .argAdded. When the output file is selected with -o option, the original file will not be changed, even when this option is not specified.

The -o and --output options take arguments. With this option, the output file is specified as in the following: -o=dest.srl or -o dest.srl. Do not specify the same file for the source file and the output file.Also, if "-" (minus) is specified as the output file, output goes to standard output.( Specify as: -o-. See --stdout, which is explained below.

--stdout is the same as specifying -o-. It outputs to standard output.

The -f and --file options take arguments. These options are for specifying a file as the data to replace. Specify as: -f=rep.dat or -f rep.dat.

If the -q or --quiet option is specified, quiet mode is used, and only error messages will be output.

If the -v or --verbose option is specified, detailed operation descriptions are displayed. Because output is made on the standard output, do not specify these options together when writing ROM data to the standard output.

The -h or --help options display simple instructions.

The -d or --debug options are for debugging. They dump the data that is to be replaced.

The --version option displays the command version.

Argument Data Area

Immediately after a NITRO ROM is compiled, a string is written in the argument data region within the ROM data. This string is used to identify that region. buryarg searches for this text string in the ROM and then reads the argument data. The string used for finding the position is not rewritten, so the argument data can be rewritten over and over again to the same ROM data.

The argument area's data can be accessed from your program by using OS_GetArgc() and OS_GetArgv().




Caution: Be careful to avoid the following errors.

- You specified the same file as the input file with the -o option.
→ This specification is not required if you want to overwrite the argument data. This is the default behavior.
- You overwrote the argument data for the SRL file. Then started up from the NLF file.
→ When an application is started from an NLF file, the modules included in the NLF file are read by the debugger. Even if the SRL file is overwritten, those changes are not applied. If starting an application from an NLF file, be sure to specify the NLF file with buryarg and overwrite the necessary data.
- You overwrote the argument data for the NLF file. Then started up the SRL file.
→ This is the opposite of the example above. Overwrite the argument data for the SRL file.
- You tried to overwrite the argument data of an image that does not have an argument data area.
→ ROM images created with old versions of the SDK do not have an area to store the argument data. When the buryarg command is run on these images, it will display an error that indicates the string for the argument data area could not be found, and the command then terminates. → If the argument data region is not referenced at least once within the program, the argument data region will be deadstripped at compile time. For example, if the OS_GetArgc or OS_GetArgv function has never been called, an error occurs.
- You tried to overwrite the argument data on a FINALROM build image.
→ The FINALROM build image does not have an area to store the argument data.
- You tried to overwrite the argument data on a TWL mode ROM.
→ Only NITRO ROMs can be overwritten with this command. For TWL mode ROMs, use the buryarg.TWL command instead of buryarg.

FINALROM and Argument Data

Argument data cannot be handled with a FINALROM. There is no memory for storing argument data. TheOS_GetArgc function always returns 0. The OS_GetArgv always returns NULL. The reason that argument data cannot be handled for FINALROM builds is that a security hole may develop if a program depends on data that can be provided externally.

Even in the case of a FINALROM build, the check routine in the program remains as long as it is not deleted. Attention is required because this code is meaningless in the case of FINALROM builds. (For example, for a game with 30 stages, analysis is made of a check routine such as "if argument data is STAGE > 30" may lead to the assumption that there may be a hidden stage.)

Location

$TwlSDK/tools/bin/buryarg.exe

See Also

buryarg.TWL
OS_GetArgc
OS_GetArgv
OS_GetOpt*

Revision History

2008/07/08 Added information so that buryarg.TWL is used for TWL.
2008/06/24 Added the fact that this mechanism cannot be used with TWL.
2005/08/30 Added OS_GetOpt* to See Also. Added --stdout.
2005/07/22 Support for NLF files.
2005/07/21 Initial version.


CONFIDENTIAL