wit dolpatch

1. Syntax

wit DOLPATCH dolfile [sub_command]...

2. Options

Options
Option		Param	Description
`-t`	`--test`		Run in test mode, modify nothing. >>> USE THIS OPTION IF UNSURE! <<<
`-l`	`--long`		If set, a address to file offset translation table is printed.
`-v`	`--verbose`		Normally, only applied patches and warnings are printed. If verbose is set, also logs about already patched and ignored patches because of a wrong condition are printed.
`-q`	`--quiet`		Suppress logging and print only warnings. If set twice, warnings are also suppressed and only reported as status message.
`-s`	`--source`	path	Define a search path for source files (e.g. 'valuefile=' attribute). If the source is a directory, it is used for every searched file. Otherwise it is a file path and only used for files with the same file name (case ignored).
`-d`	`--dest`	path	Define a destination path (directory or file). If not set, the source file is replaced by the patched version.
`-D`	`--DEST`	path	Like --dest, but create the directory path automatically.
`-o`	`--overwrite`		Overwrite already existing files without warning.

3. Inspiration

It started with the publishing of Newer Super Mario Bros. Wii. It is a custom version of New Super Mario Bros. Wii. The release comes with a Riivolution setup and the authors argued, that an ISO patch is impossible because of the modification of file main.dol.

Triggerd by this, I started to inmplement the DOLPATCH command. Together with damysteryman, a user of GBATEMP.net we created the NSMBW Mod ISO Builder.

4. Description

The very first parameter is the filename of the DOL file and all other parmeters are sub-commands.

Syntax:: wit DOLPATCH dolfile [sub_command]...

First, the DOL file is loaded and checked. The maximal allowed file size is 100 MiB. If option --long is set, a address-to-file-offset translation table is printed.

All sub-commands are executed step by step in the entered order. A sub-command is one of the following and keywords (the parts between '...') are case insensitive:

xml command: 'XML' '=' filename
entry command: 'ENTRY'= address
create section command: 'NEW' '=' 'TEXT' ',' address ',' size or
'NEW' '=' 'DATA' ',' address ',' size
auto section command: 'NEW' '=' 'TEXT' ',' 'AUTO' or
'NEW' '=' 'DATA' ',' 'AUTO'
load file command: 'LOAD' '=' address ',' filename
patch command: address '=' patch [ '#' condition ]

A xml command defines the filename of a Riivoluton xml file. The maximal allowed file size is 10 MiB. A fast text scan without context is done to find <memory ../>' tags. All other xml tags are completly ignored including options, conditions and comments. The following attributes are recognized:

offset: Define the virtual address, where the patch should be applied. This is the only place, where a '0x' prefix is required for hexadecimal numbers; like Riivolution does.
original: Define a condition as hex string with up to 1000 bytes (2000 hex digits). The patch is only applied, if the DOL file matches the hexstring.
value: Define the patch as hex string with up to 4 MiB (more than 8 million digits). It is used to patch the DOL file.
valuefile: Define a file with patch data. The file is searched in the directories defined by the --source option. The maximal allowed file size is 10 MiB. If valuefile is defined, attribute value is ignored.

The entry command defines a new entry point. 'address' is a hexadecimal number. No validation tests are done.

A create section command creates a new TEXT or DATA section. 'address' and 'size' are hexadecimal numbers and are aligned to a multiple of 4. More tests are not done and so the user must be careful to define correct address and size.

An auto section command enables the automatic creation of a section. If a patch address is outside of all existing TEXT and DATA sections, then a new section is automatically created for exactly this patch. After creation, the auto creation is disabled until the next auto section command.

A patch command defines the virtual hexadecimal 'address' and the 'patch' string. If the optional 'condition' is defined, the patch is only applied, if the DOL file matches the condition. 'patch' is a hex strings of maximal 4 MiB (more than 8 million digits) and 'condition' a hex strings of maximal 1000 bytes (2000 digits). Single bytes (not digits) can be separated by spaces and/or points.

A load file command is similar to the patch command, but it loads the content of a complete file into the virtual 'address'. The file is searched in the directories defined by the --source option, if it is not found with the entered path. The maximal allowed file size is 10 MiB.

4.1 Example

wit dolpatch nsmb.d/sys/main.dol
	xml=NewerFiles/riivolution/NewerSMBW.xml
	--source NewerFiles/NewerSMBW/

This example (one single command line) will first load the DOL file nsmb.d/sys/main.dol. The XML file NewerFiles/riivolution/NewerSMBW.xml is used to find the patch commands (<memory> tags). Additional files (here Loader.bin) are searched in NewerFiles/NewerSMBW/.

The log looks like this:

+Patched:         [D4] addr 802f148c+07, offset  2ed58c: 77 69 69 ... -> 4e 65 72 ...
+Patched:         [D5] addr 80328478+04, offset  324578: 80 15 bc 60 -> 80 00 18 00
+Patched:         [T1] addr 800e4a84+04, offset   e0ac4: 3c 60 01 20 -> 3c 60 01 40
+Patched:         [T1] addr 800b64ec+04, offset   b252c: 3c 80 00 30 -> 3c 80 00 32
+Patched:         [T1] addr 801b0204+04, offset  1ac244: 54 00 ff fe -> 38 00 00 00
+Patched:         [T1] addr 8015d850+04, offset  159890: 38 60 00 00 -> 4e 80 00 20
+Patched:         [T1] addr 800e4e84+04, offset   e0ec4: 38 63 33 0c -> 38 60 00 00
!Can't patch: Range outside dol: addr 80001800+968
* Save patched DOL to: nsmb.d/sys/main.dol

Normally only applied patches are logged. This behavior can be changed by the options --quiet and --verbose. The warning appears, because the patch address for Loader.bin is outside of the dol file.

If executing the command a second time, the log is reduced, because the file is already patched:

!Can't patch: Range outside dol: addr 80001800+968
* DOL not modified: nsmb.d/sys/main.dol

If adding option --verbose, the log is:

-Already patched: [D4] addr 802f148c+07, offset  2ed58c: 4e 65 72 53 4d 42 57
-Original differ: [D4] addr 802f118c+07, offset  2ed28c: 00 00 00 00 80 31 65
-Original differ: [D4] addr 802f0fac+07, offset  2ed0ac: 00 00 00 2a 00 00 00
-Already patched: [D5] addr 80328478+04, offset  324578: 80 00 18 00
-Original differ: [D5] addr 80328130+04, offset  324230: 80 15 a5 b0
-Original differ: [D5] addr 80327e98+04, offset  323f98: 72 75 5f 30
...
!Can't patch: Range outside dol: addr 80001800+968
* DOL not modified: nsmb.d/sys/main.dol

5. Usual error/exit codes:

If an error occured, the associated error status is returned.

Otherwise, if a patching warning occured, WARNING is returned. Otherwise, if a condition didn't match, FILES DIFFER is returned. Otherwise, OK is returned.