Patch a position
The most important patcher command is the “patch” command, with this you overwrite (never insert) bytes
patch <position> 0x<value>
# Patch position 12 (0x0C) with the four bytes 0x0025015E - changes the ROM version number to r37.350
CapCLI> patch 0x0C 0x0025015ECreate/set alias
Within Cap you can create variables (for some reason, I started using the word alias, now its stuck), but it’s just a variable, you can directly assign values to aliases, grab a chunk of the ROM and put it into an alias (to patch somewhere else or change), if the alias looks like it could be a number, you can add to or subtract from it, and you can treat it like a string and chop it up using the mid function.
I’ll probably add some extra functions here, like conversion between hex, int and strings, as it’s a little limited at the mo.
alias <aliasname> <value>
CapCLI> alias FRED 0x01020304
CapCLI> echo $FRED
0x01020304
alias <aliasname> romdata <start> <size>
CapCLI> loadrom "ROMs/TOSEC.Firmware/Kickstart v2.05 r37.350 (1992-04)(Commodore)(A600HD)[!].rom"
CapCLI> alias FRED romdata 0x0C 0x04
CapCLI> echo $FRED
0x0025015E
alias <aliasname> add <value>
CapCLI> echo $FRED
0x0025015e
CapCLI> alias FRED add 1
CapCLI> echo $FRED
0x0025015f
Note, add and subtract only work properly on hex values, i.e. they must begin 0x (I might change this later)
alias <aliasname> subtract <value>
CapCLI> echo $FRED
0x0025015f
CapCLI> alias FRED subtract 51
CapCLI> echo $FRED
0x0025012c
alias <aliasname> mid <start> <size>
CapCLI> echo $FRED
0x0025012c
CapCLI> alias FRED mid 3 2
CapCLI> echo $FRED
02
Note, the alias has 0x at the start of it, this is included in the length, so position 0 is "0", position 1 is "x" etc.Inbuilt aliases
For your delectation, I have created some inbuilt aliases that help you access/modify ROM and library information, you (almost) only ever change data with the patch command.
ROM things
The ROMBASE calculated from the ROM
$ROMBASE
CapCLI> echo $ROMBASE
0x00f80000
The Commodore checksum (not CRC32)
$CALCCHECKSUM
CapCLI> echo $CALCCHECKSUM
0xba5d5fa4
The location within the ROM of the kickstart version (usually 12, 0x0C)
$(KICKSTARTVERSION)
CapCLI> echo $(KICKSTARTVERSION)
0x0000000c
Note the use of brackets, to say "location of" rather than the actual kickstart version.
# read the kickstart version into the KSV alias
CapCLI> alias KSV romdata $(KICKSTARTVERSION) 4
CapCLI> echo $KSV
0x0025015E
Locations of library things
These will give you the location of things that relate to specific libraries, so you can read or manipulate them - remember, the brackets mean "give me the location" not the value stored at that location
$libraryname.(START)
$libraryname.(END)
$libraryname.(ROMTAG)
$libraryname.(ROMTAG.MATCHTAG)
$libraryname.(ROMTAG.ENDSKIP)
$libraryname.(ROMTAG.FLAGS)
$libraryname.(ROMTAG.VERSION)
$libraryname.(ROMTAG.TYPE)
$libraryname.(ROMTAG.PRI)
$libraryname.(ROMTAG.NAME)
$libraryname.(ROMTAG.IDSTRING)
$libraryname.(ROMTAG.INIT)
If you want the start and end location of a library, then you can simply use the name;
$libraryname
CapCLI> echo $cia.resource
274624 275640
Hash aliases
You can find and refer to files by their hash value, but only if you have previously done an “auditfiles” command, the auditfiles command hashes every file under the named directory and creates an alias for every file based upon it’s hash value – as you can guess, scanning an entire directory tree is very CPU and disk intensive, so don’t do this on gigs or data, it’s only really worthwhile on ROMs or Components.
This is used extensively in the “Recipes and Tests” to load a specific ROM or component (without having to know the exact name).
Scan all files under a directory and evaluate the hash value
auditfiles <dirname>
CapCLI> auditfiles ROMs
CapCLI> echo "$0x43b0df7b"
ROMs/TOSEC.Firmware/Kickstart v2.05 r37.350 (1992-04)(Commodore)(A600HD)[!].romPatching the checksum
If you have altered the ROM, you will need to update the C= checksum, there’s a hard way and an easy way, but the hard way isn’t that hard.
Using the location of the start of the checksum, patch it with a newly calculated value
patch $Checksum.(START) $CALCCHECKSUM
The "checksum" command does this for you
checksum Finding data
If you want to scan the ROM (or just a library) for the location of things, I have a command for that… the unusually named find command, if the find is successful then the alias $FIND is set to the position that it found it, if it’s not found then $FIND is not updated and you just get “Not found” (I might change this to reset $FIND).
You can search for binary text using hex representation (so searching for strings is a bit laborious) or you can search for 68000 opcodes
find <from> <to> <what>
CapCLI> find 0 262143 0x6C696272617279
CapCLI> echo $FIND
0x00000038
CapCLI> find 0 262143 0x112233445566778899aa
Not found
CapCLI> echo $FIND
0x00000038
findopcode <from> <to> <what>
CapCLI> findopcode $0x75094a7b.scsidisk_40.12_(21.12.93) "JSR FCD6(A6)"
CapCLI> echo $FIND
0x00000090