BMOW title
Floppy Emu banner

ROM Hacking Tutorial with ROM-inator II

The ROM-inator II replacement flash ROM for the Mac II series and SE/30 comes pre-programmed with nifty new features for your vintage Macintosh. With the optional ROM SIMM Programmer, you can edit the ROM’s contents, altering the ROM disk or writing a different stock ROM image. But why stop there? For the truly adventurous, this tutorial will demonstrate how to patch the ROM code to alter the machine’s low-level behaviors. This is an advanced tutorial for major gear-heads, so hang on to your hat!

We’ll begin with the Macintosh IIsi ROM. It’s a universal ROM, meaning that even though it was designed for the IIsi, it also works in many other Mac models. The original IIsi ROM is just a 512K chunk of raw data, which you can find here. The ROM-inator II’s contents are also based on the IIsi ROM, with many modifications and additions. The latest ROM-inator II contents are available on the product’s web page, and at the time of writing it’s this file. Only the first 512K of the file is ROM code, and the rest is data for the ROM disk.

 
Hex Editor

To modify or patch the file, we’ll need a tool called a hex editor. I’ll be using a Windows hex editor called xvi32, but there are many other options for Windows, Mac, and Linux. Check out Synalyze It and Hex Fiend for some other examples. If we open the ROM-inator II file in xvi32, we’ll see this:

xvi32

What’s all this? Running down the left side are the file offsets in hex. These are the same as the addresses within the ROM code. In the center panel, we see the actual bytes from the file, displayed in hex, 16 bytes per line. In the right panel we see those same 16 bytes again, but displayed as printable characters instead of as hex values. That’s not especially useful in this example, but it’s handy when examining ROM code that contains embedded string constants.

In the example above, the value at offset 32 is 6E, which is equivalent to the ASCII character ‘n’.

 
Disassembler

To do anything useful with this, we’ll need to understand how these bytes are structured and what they mean, so that we’ll have some idea how to modify them. In this case, we know that the bytes are 68000 machine code, so we can feed them through a 68000 disassembler to create a more human-readable version. As with the hex editor, there are many options for 68K disassemblers, including this slick web-based disassembler. Using the web disassembler to examine the first few bytes of the file, we’ll get output like this:

oda

Once again, the left column shows the file offsets (ROM addresses), and the center column displays the actual bytes in hex. The column on the right displays those same bytes reinterpreted as 68000 machine code. The number of bytes per row is no longer fixed at 16, but instead varies with the size of the encoded 68000 instructions. Notice that the code is displayed using syntax normally employed for x86 disassembly, so it looks a bit odd for those people accustomed to 68K syntax. But even if we ignore the syntax, something about this code just looks wrong. It begins with a couple of strange move instructions, a negation, and OR-ing random-seeming registers with strange constants. It just looks wrong, and that’s because it is wrong. One of the limitations of disassemblers is that they struggle to distinguish code from data, and in this example the bytes beginning at address zero are mostly data. By attempting to interpret them as 68K code, we get garbage.

By employing some knowledge about the 68K CPU, we can make better sense of this. At reset time, the 68K initializes its stack pointer from address 0, and its program counter from address 4, then it begins executing code. So the first instruction to be executed will be the one whose address appears at offset 4 in ROM, which we can see from the hex dump is 4080002A hex. That may seem like a strange address, since it’s a 32-bit address far outside the range of the 512K ROM code. Once again, we need to employ some knowledge of Macintosh internals to know that the ROM is initially mapped into the CPU’s address space at 40800000. So 4080002A simply means offset 2A in the ROM. As it turns out, the instruction at 2A was disassembled correctly in the listing above, and it’s just a PC-relative jump to address 8C. If we try the disassembler again, this time feeding in the bytes beginning at 8C and adjusting the base address accordingly in the disassembler settings, we get something that looks more reasonable:

oda2

It begins by loading a value into the status register, which the 68000 manual tells us will disable interrupts. It then loads a value into D0 and stores it into the cache control register. More processor initialization follows. Whew! We can make sense of this, but it’s slow and tedious work.

 
A Mac-Specific Disassembler

For this work, a better disassembler is FDisasm, a 68K disassmbler with some Mac-specific intelligence. FDisasm is itself a vintage Macintosh program running under System 6 or 7, rather than a modern Windows or OSX application, so it’s normally run under emulation with the cross-platform Mini vMac emulator. In addition to simply disassembling the 68K code, FDisasm also replaces address and data constant values with their symbolic names, where those names are known from Apple reference sources or previous disassembly work. It even inserts some helpful comments into the disassembled code. To do all this, FDisasm needs to have formatting information with advance knowledge of the Mac ROM being disassembled. Unfortunately, the IIsi isn’t one of the ROMs for which FDisasm contains pre-supplied formatting information. But happily for us, Rob Braun has already done some work in this area, and created partial formatting information for FDisasm with the IIsi ROM. Using that formatting information, FDisasm generates this disassembly beginning at address 8C:

fdisasm

That looks much better! We see that address 8C has the label StartBoot, and other addresses and constants also now have meaningful names. It looks like the MOVEC instruction was disassembled incorrectly (a FDisasm bug?), but that’s a small matter. With disassembly at this level, we can finally begin to search for interesting sections of code to study, and eventually to modify.

 
Double Chime

As an example, we’ll walk through the construction of a ROM patch to make the Mac play the startup chime twice. Maybe it’s such a great chime that it deserves to be played twice? Poking through the disassembly, we eventually find some relevant code at address 45C0A:

fdisasm2

While it’s not obvious, I can tell you from super-secret sleuthing that this code is called from a computed jump instruction at 4651A:

fdisasm3

This code requires some explanation. At the point the boot chime is played, the Mac’s RAM hasn’t yet been configured, and there is no stack. That means the code can’t use the normal JSR/RTS mechanism to call and return from subroutines. If we examine the code at OrigBootBeep6, we’ll learn that it uses the A6 register as a return address, once it’s done playing the chime. So the line above that loads DT140 into A6 is setting the return address, which happens to be the address of the instruction immediately following the jump. To play two chimes, we’ll need to duplicate this block of code two times.

Patching code becomes problematic when the new code requires more bytes than the old code. The code contains many address cross-references, so we can’t simply shift the bytes down to make room for new code, the way we’d insert an extra word into a sentence in a text editor. Instead we need to find some unused area of the ROM, put the new, larger code into that area, and then modify the original code to jump to the new code. Finding a suitable unused area is as much art as science, but while skimming through the ROM disassembly, this jumps out at address 3CBE:

fdisasm4

I’m going to hazard a guess that somebody named “Gary” worked on the IIsi ROM.

Gary appears to have filled up padding space with many copies of his name, which we can replace with new code. If we’re wrong and all those “Gary” bytes are actually necessary, the computer will crash horribly. Such is the excitement of ROM hacking. We want to insert some new code that plays the chime twice, then jumps back to the instruction just after the old code. Using the original code as a template, our new code should look something like this:

        MoveQ.L   $28, D0
        Lea.L     NEXT1, A6
HERE1:  Lea.L     ($XXXX), A0
        Jmp       HERE1(A0.L)
NEXT1:  MoveQ.L   $28, D0
        Lea.L     NEXT2, A6
HERE2:  Lea.L     ($YYYY), A0
        Jmp       HERE2(A0.L)
NEXT2:  Lea.L     ($ZZZZ), A0
        Jmp       NEXT2(A0.L)

where $XXXX and $YYYY are the offsets from HERE1 and HERE2 to OrigBootBeep6, and $ZZZZ is the offset from NEXT2 to DT140, the continuation point of the original code. We can compute those offsets by doing some hexadecimal math, subtracting the addresses where those instructions lie in the “Gary” area from the addresses we need to jump to. We’ll use the hex editor to do the actual patching work. Using xvi32 to view Gary’s ROM padding beginning at address 3CBE:

xvi32.2

We can type directly into the center area of byte values to modify them. But what bytes should we type, to implement the new code that we want? Converting from assembly code to byte values is the job of an assembler, so we could use a 68K assembler like EASy68K to do the work. But in this case, almost all of the instructions already exist in the original code, so we can simply copy the assembled byte values from there, modifying the bytes that represent addresses as needed. For example, we can see from the original code that MoveQ.L $28, D0 assembles as the two bytes 70 28. Beginning with the first “Gary” at 3CC4, we’ll crib bytes from the original code, not yet worrying about the address offsets. The result looks like this:

xvi32.3

The offsets require more careful study. First, we consider the instructions like Lea.L NEXT1, A6. While this looks like an absolute address, it’s actually a PC-relative address. Another FDisasm bug? An alternative 68K disassembler represents these same instructions as LEA ($C, PC), A6. This loads A6 with the address 10 bytes ($C hex) beyond the current program counter value. 10 is still the correct adjustment in our new code, so that doesn’t need to change. Next we consider the computed jump instructions like JMP HERE1(A0.L). While this looks like an absolute offset, it’s actually a PC-relative offset that the alternative disassembler shows as JMP (-$8, PC, A0.L). Once again, -$8 is also the correct adjustment in our new code, so that doesn’t need to change either.

The XXXX, YYYY, and ZZZZ offsets are the only values that need to change. In the original code, the instruction was:

46514  41F9 FFFF F6F6 DT139:   LEA.L (-$90A), A0

46514 was the address, 41F9 was the instruction opcode, and FFFFF6F6 was the (negative) offset. So we need to find the three instances of the bytes FFFFF6F6 in the new code, and modify them to the correct offsets for OrigBootBeep6 (twice, from HERE1 and HERE2) and DT140. After applying some math, these offsets turn out to be 00003388, 00003378, and 0004283A, respectively.

xvi32.4

Finally, we need to patch the original code, so that it jumps to the new code. To do this, we’ll perform a similar hex calculation to subtract the original code’s address from the “Gary” address at 3CC4. We only need to modify the offset in the instruction at address 46514 to point to our new code instead of directly to OrigBootBeep6. This is a little bit sloppy, as D0 and A6 will end up getting set redundantly, but it’s simpler than modifying that whole block of code at 4650E.

 
Beep! Beep!

That’s it! The modified ROM file is here.

This should give you a sense of the kinds of ROM modifications that are possible with the ROM-inator II and the ROM SIMM programmer. Patching the ROM can be challenging work, but with a little imagination and patience almost anything is possible.

Read 5 comments and join the conversation 

5 Comments so far

  1. Keith Kaisershot June 11th, 2016 11:09 pm

    I’m going to hazard a guess that the “Gary” in the IIsi ROM is Gary Davidian, who would have been at Apple at the time of the IIsi’s development and who worked on the trap dispatcher and Time Manager, among other things. I found a really interesting PDF co-authored by Davidian proposing a “universal” ROM not unlike the IIsi: http://ftp.vim.org/NetBSD/misc/wrstuden/Apple_PDFs/Jaws%20ERS%20(new%20ROMS).pdf

  2. Steve June 12th, 2016 6:38 am

    Very cool! It’s also interesting to see that the Mac II, IIx, IIcx, and SE/30 all used the same ROM even before the introduction of the universal ROM.

  3. Paul Pratt June 12th, 2016 2:10 pm

    Thanks for talking about FDisasm. By the way, the latest version (1.1.7) better supports MoveC. It was released shortly after fixing other bugs you reported. It now correctly disassembles the the Macintosh Plus ROM, the Macintosh 128/512 ROM, and the Macintosh SE ROM, as tested by reassembly.

  4. Olivier July 27th, 2016 1:38 pm

    I found out about your rom-inator only today (catching up with my RSS feeds ;)), and while not being a \”Mac person\”, this is fascinating!

    Looking at that beep jump and 4650E, I was trying to see if a direct jmp to ($-90A) could be done, especially given the fact that A0 doesn\’t seem to serve any other purpose than to temp store that jmp sound address (thus freeing 3 bytes), but that might be enough to jump twice to the beep, because we also need to adjust the return address twice?

    Something like this:
    4650E 7028 MoveQ.L $28, D0
    46510 Lea.L DT140, A6 ; Return @ stored in A6
    46514 Jmp ($-90A) ; 1st DIRECT jmp to sound
    46518 DT140: AddQ.L $4, A6 ; Return from 1st jmp, we increase A6 for next jmp
    4651A Jmp ($-910) ; 2nd DIRECT jmp to sound
    4651E Clr.B $804 ; Return from 2nd jmp, because A6(DT140) + $4

  5. Steve July 27th, 2016 4:21 pm

    I would have to try it in a 68000 debugger, but I don’t think that revised code is correct. The $-90A is relative offset from DT139, and can’t be replaced with JMP ($-90A). There may be other clever ways to rewrite the code without needing more bytes of space, though.

Leave a reply. Comments may take a few minutes to appear.