README


Directory structure:

bbplayer/tools/romhack
  libs/
    various sgi and pc .a files
  sigs/
    .sigs files that correspond to libs
  utils/
    sig.py - converts .a to .sigs
    extract.py - converts .a to a binary file per function in .a
  romhack.[ch] - actual rom hack program
  crc.c - crc computation (stolen from somewhere, gzip?)
  vimodes.c - big array of vi modes

Rom Hacking:
--- --------

Preprocessing:

Prior to running the actual rom hack program, signatures
need to be generated for the various versions of libultra. The python 
script utils/sig.py is used for this purpose because I was too lazy to
figure out how to use libelf.

In addition to preparing the n64 libultra signatures, you must prepare the
BB libultra library as well.  For now this is done with utils/sig.py which
is really overkill (all that is needed is the symbol name and # of 
instructions), and utils/extract.py which creates a file per function in
from the BB libultra .a file (again because I'm too lazy to figure out libelf).

Hacking a rom:

The 'romhack' program has the following usage:

Usage: ./romhack [options] rom
        -i, --input <rom>        Read rom image from <rom>
        -o, --output <rom>       Write patched rom file to <rom>
        -j, --jdebug <file>      Dump symbol information for jdebug
        -p, --patch <funcfile>   Attempt to patch the functions in <funcfile>
            --sgi                Use the SGI signatures
            --pc                 Use the PC signatures
        -f, --force-lib <lib>    Use OS 20<lib> signatures
        -D <symbol>=<offset>     Override <symbol> @ <offset>
        -v, --vitbl              Scan for and patch vitbl
            --osinit             Scan for and patch osInitialize
        -c, --crc                Scan for and patch crc miscompare (Indy)
            --pal                Scan boot code and set osTvType = PAL(Indy)
        -h, --help               Print this message and exit

The basic operation is to specify an input rom image (-i), an output rom 
image (-o), and a list of functions to patch (-p). The algorithm is to load
the image into memory, scan the image completely for all known functions,
patch the specified functions if found, and then write out the resulting
rom file.

All known functions are hashed based on their first op.  Each memory location
is examined, and for functions that have the same first op, a checksum is 
computed (using relocation information to mask off necessary bits).  If the
checksum matches and the signature information is unambiguous, then that 
signature is considered found (and all symbols that it references are marked
as found).

Building:

For the time being, you must do the preprocessing steps before running make.
Eventually this will all be automated by the Makefile, but I'm too tired.

I've checked in the os20*.sigs files so you don't need to run utils/sig.py on
the corresponding archive files, but if you change sig.py, you'll need to 
rerun them.  For each file, the command will look something like:

utils/sig.py libs/os20l_sgi.a > sigs/os20l_sgi.sigs

The archive files are on source:/home/routefree/bb/ultras

In addition, if you make modifications to your BB libultra, you'll need to 
generate signatures for that archive as well. Also, you'll need to extract
the functions into the routines directory:

utils/sig.py $ROOT/usr/lib/libultra_rom.a > sigs/bb_ultra_rom.sigs
utils/extract.py $ROOT/usr/lib/libultra_rom.a

The Makefile dependencies are not setup correctly on the sig files, so if
you modify the sig files, do:

touch romhack.c
make

Example command-line options for various ROMs that we have working can be
stored in the 'recipes' directory.

Caveats:
I've modified my libultra slightly, but I don't want to check in the changes
because they are a little gross and still not working 100%.  The important
changes are in nintendo/pi/devmgr.c.  I've commented out the leo crap, 
turned the bcopy into a for-loop, and changed the switch to a big if/else
construct.

Things seem happier if __osDevMgrMain is always up in high
memory (maybe), but other functions didn't seem so happy there.

Hacked roms need to be run with a recent launch.aes because of the high
mem stuff.  They will not work if run with mon (for right now).

More debugging to go, but I'm out of time.  Oh well...