gz injection mechanism

upon boot, the n64 loads 1MiB of data from the cart at address 0x00001000 and then jumps to it.
the address to which the data is loaded is stored at offset 8 in the rom header (0x00000008 in the rom).
in oot, and most other games, it is 0x80000400, but in sm64 it is 0x80246000.
at the very beginning of the loaded data is the initial code that gets executed by the game.
it is usually a small function (0x50 bytes in sm64, 0x60 bytes in oot) that clears the bss segment,
sets up a stack, and then jumps to a bigger initialization function.

in gz, this function is replaced by a custom loader that DMA's the gz binary to the
expansion pak space (4MiB at 0x80400000) that is unused by oot.
the original function is moved to the very beginning of the expansion pak space,
so that the custom loader can jump to it and continue the game's execution as normal.

so far, the game will boot up normally, except now with the gz binary loaded into memory.
however, at some point during the rest of oot's initialization routines, it will perform a self-test on the memory
to decide how much memory is available, and then clear all of it.
this includes all of the expansion pak memory, even though oot will never use it.
in order to prevent the game from clearing away the gz binary, a patch is applied to this initialization code (mem_patch.gsc),
that prevents the self-test from executing and sets the amount of memory available to a constant 4MiB.
as such, only the lower 4MiB will be cleared, and gz will remain in the upper 4MiB.
note that this step is not necessary if gz is injected while the game is already running.

finally, a hook point is to be inserted into the game's code that calls gz's main hook function as desired.
in oot, this is done using the z64 file system capabilities of the gru tool.
since the hook point resides in a compressed code file on the rom, simply applying a code patch to the rom will not work.
instead the file system is loaded with gru, the code file is extracted, patched (with main_hook.gsc),
recompressed and inserted back into the filesystem.
the file system is reassembled into a complete rom image, and then the gz binary is inserted into the unused
space at the end of the rom, after the file system.

below is the layout of a 1.0 oot rom before and after patching;
--------------------------------------------------------------------------------------
address   before patching                       after patching                          ldr.bin   gz.bin
--------------------------------------------------------------------------------------    v         v
00000000  rom header                            rom header (crc updated)                  |         |
00000040  boot code                             boot code                                 |         |
00001000  primary init function >----------+    custom gz loader <------------------------+         |
00001060  more init code                   |    more init code (with mem patch)                     |
00007430  file system                      |    file system (with patched code file)                |
01F7B720  end of file system (padding)     +--> primary init function                               |
01F7B780  padding                               gz binary <-----------------------------------------+
02000000  end of rom                            end of rom

boot procedure of a 1.0 oot rom before patching;
--------------------------------------------------------------------------------------
address   description
--------------------------------------------------------------------------------------
80000400  primary init function
80000498  secondary init function
...       more initialization and loading
800A1934  main game function

boot procedure of a 1.0 oot rom after patching;
--------------------------------------------------------------------------------------
address   description
--------------------------------------------------------------------------------------
80000400  custom gz loader (loads rom 0x01F7B720 to ram 0x80400000)
80400000  primary init function
80000498  secondary init function (with mem patch)
...       more initialization and loading
800A1934  main game function
800A0C3C  hook point (from patched code file), executed by oot once per frame
80400060  gz's main hook function