ROM Fiend: A DeclROM, Extended DeclROM, and System ROM parser

[eharmon]

Hey folks, I've been digging into Mac ROMs pretty extensively lately, and I've created a file template for Hex Fiend that can help you introspect and examine all types of Mac ROMs.

GitHub - eharmon/rom_fiend: Macintosh ROM file template for Hex Fiend

Macintosh ROM file template for Hex Fiend. Contribute to eharmon/rom_fiend development by creating an account on GitHub.

github.com

From the README:

Supported Data Types​

• Declaration ROM (DeclROM)
  • NuBus and PDS peripherals on 68020+ Macs. Also used for System ROMs before 4.0 (most machines released before the PowerBook 160).
  • These define plug-and-play parameters for devices, including memory mappings, driver support, and basic identification.
  • Almost all data types are supported. Unsupported entries are marked with "TODO" in the Hex Fiend view.
• Extended DeclROM
  • Board definitions in System ROMs after the PowerBook 160.
  • This is a superset of the normal DeclROM, allowing for multiple data directories to be defined which are selected from on system boot.
  • Supports the same data types as regular DeclROMs.
• System ROM Resources
  • Toolbox resources including cursors, sounds, drivers, and some device support definitions.

Unsupported Data Types​

• System ROM tables
  • Used for some low-level hardware configuration.
  • These are encoded inline with assembly and thus are difficult to parse with Hex Fiend without hardcoding per ROM

Most interestingly, I think this might be the first implementation capable of parsing the Extended DeclROM, allowing you to see all pseudo-slot definitions on newer Macs, and the System ROM Resources. This makes it significantly easier to understand the layout for ROM hacks.

Unlike a real parser, this file template only works in Hex Fiend, but serves to allow for easy point-and-click drill down of data and selection and editing of key sections.

It could serve as a reference for anyone to implement a real parser/ROM hacking tool in a traditional language or make improvements to existing tools.

Some screenshots:

Resources in the PowerBook 160 System ROM:

Pseudo-Slot Extended DeclROM data:

Video modes from the 24AC Display Board:

 

[eharmon]

I updated this to additionally annotate the System ROM symbol tables exported by @cy384!

 

[Jockelill]

Nice!! This is truly amazing! Well done!

 

[demik]

Very useful thank you. May I ask for a small improvement ?

Neither install.sh or Hex Friend is creating the Templates folder which gives this:

> ./install.sh
Updating submodules...
Submodule 'rom_maps/68k-mac-rom-maps' (https://github.com/cy384/68k-mac-rom-maps.git) registered for path 'rom_maps/68k-mac-rom-maps'
Cloning into '/private/tmp/rom_fiend/rom_maps/68k-mac-rom-maps'...
Submodule path 'rom_maps/68k-mac-rom-maps': checked out 'b3c2a77bd58669f8ea6889e7f7ec2e8950472032'
Creating symlinks...
ln: /Users/demik/Library/Application Support/com.ridiculousfish.HexFiend/Templates: No such file or directory
ln: /Users/demik/Library/Application Support/com.ridiculousfish.HexFiend/Templates: No such file or directory
Done!

Can you check and create the Template directory if it's not there ?

 

[gm_stack]

It could serve as a reference for anyone to implement a real parser/ROM hacking tool in a traditional language or make improvements to existing tools.

Hmm, funny you should say that...

You're also right about the System ROM tables... I don't think I've found a way to pin them down other than "they're two of the three constant memory references in Ghidra's decompiler view of GetHardwareInfo". I don't think either will be likely to be loaded into a consistent register, and GetHardwareInfo is also splattered all over the ROM due to the many patches made to it...

I noticed BasiliskII had a function for finding the Universal table, when I was reading its source code - but it just finds the IIci table by searching for its expected values, then overwrites it with what it wants, forcing that machine to be selected at check time (a pretty typical strategy for it - it just patches everything it doesn't want to handle emulation of out of the ROM - not necessarily a bad strategy! )

 

[cheesestraws]

Very useful thank you. May I ask for a small improvement ?

Can you check and create the Template directory if it's not there ?

Stuck a PR in here: https://github.com/eharmon/rom_fiend/pull/1

 

[eharmon]

Very useful thank you. May I ask for a small improvement ?

Neither install.sh or Hex Friend is creating the Templates folder which gives this:

> ./install.sh
Updating submodules...
Submodule 'rom_maps/68k-mac-rom-maps' (https://github.com/cy384/68k-mac-rom-maps.git) registered for path 'rom_maps/68k-mac-rom-maps'
Cloning into '/private/tmp/rom_fiend/rom_maps/68k-mac-rom-maps'...
Submodule path 'rom_maps/68k-mac-rom-maps': checked out 'b3c2a77bd58669f8ea6889e7f7ec2e8950472032'
Creating symlinks...
ln: /Users/demik/Library/Application Support/com.ridiculousfish.HexFiend/Templates: No such file or directory
ln: /Users/demik/Library/Application Support/com.ridiculousfish.HexFiend/Templates: No such file or directory
Done!

Can you check and create the Template directory if it's not there ?

I should really add a `set -e` in there too... Out of curiosity, are you using the App Store version of Hex Fiend?

Stuck a PR in here: https://github.com/eharmon/rom_fiend/pull/1

Merged, thanks!

 

[demik]

Stuck a PR in here: https://github.com/eharmon/rom_fiend/pull/1

Thanks @cheesestraws

I should really add a `set -e` in there too... Out of curiosity, are you using the App Store version of Hex Fiend?

Merged, thanks!

Nope, downloaded from http://hexfiend.com/

 

[dougg3]

This is super cool! After I discovered the 475 ROM will boot a IIci as long as the IIci has a NuBus video card installed, I was planning on trying to hack the RBV driver into the LC 475 ROM to see if it would fully boot. I wasn't sure exactly where to start and I think this utility might be just what I needed to understand where things are!

 

[eharmon]

Nope, downloaded from http://hexfiend.com/

Strange, I'm surprised it didn't create the dir at launch! Anyway, fixed now .

This is super cool! After I discovered the 475 ROM will boot a IIci as long as the IIci has a NuBus video card installed, I was planning on trying to hack the RBV driver into the LC 475 ROM to see if it would fully boot. I wasn't sure exactly where to start and I think this utility might be just what I needed to understand where things are!

I think it should probably work if you copy the `Display_Video_Apple_RBV1` Display entries and backing data and shove them into Directory 127's entries. You might already know this, but copying Directory 127 wholesale to empty space and remapping the Super Directory's pointer to it should give you space to add all the entries. Then it's just a matter of correcting all the offsets to the original Directory 127 data and the newly added Display data. I say "just", cause it's quite a few offsets. Wouldn't be too crazy to write a tool to do it (and general purpose even...copy from one ROM to another!)

We should start a ROM hacking thread .

 

[Arbee]

So for reference, with the App Store version of Hex Fiend the path to install to is ~/Library/Containers/com.ridiculousfish.HexFiend/Data/Library/Application Support/com.ridiculousfish.HexFiend/Templates. Seriously.

With that out of the way, this template is extremely awesome. I wish it'd existed years ago.

 

[eharmon]

Some updates from the last few weeks:

- More System ROM header data is read.
- Resource Combo Flags are read correctly.
- System ROM versions are now extensively parsed.
- Old World PPC ROMs now properly read embedded DeclROM data.
- System ROM build dates are read when possible.

But last, the part I'm most interested in (and will probably start a new thread), I've added support for reading ROM Disk data -- not bbraun's, but the official Apple ROM disk system (EDisk) as used in the Classic. You can find more documentation here: https://wiki.preterhuman.net/HW_13_-_Macintosh_Portable_ROM_Expansion

 

[Arbee]

FWIW, the ROM version on the pre-Universal ROMs was not decimal as ROM Fiend currently displays. The 128 was "ROM 69", the Plus was "ROM 75", the SE was "ROM 76", and the IIx+IIcx+SE/30 was "ROM 78 rev 1.3". I've attached one document but you can see a few references in the SuperMario tree too.

 

[eharmon]

FWIW, the ROM version on the pre-Universal ROMs was not decimal as ROM Fiend currently displays. The 128 was "ROM 69", the Plus was "ROM 75", the SE was "ROM 76", and the IIx+IIcx+SE/30 was "ROM 78 rev 1.3". I've attached one document but you can see a few references in the SuperMario tree too.

Yeah, the versions are totally a mess and even official documentation doesn't agree with itself. Other technical bulletins use the decimals instead! So I've taken to displaying as many versions as possible, in all formats, with the latest changes on tree.

For instance, the 128k ROM is listed as "6.9", "69", "0x69", and "105", depending on source, both official and unofficial. (Confusingly, it's ALSO mentioned as 7.0, which is "officially true" but never encoded in the ROM itself). So I've listed all 4 different ways of referencing it:

"6.9 (105/0x69)" (the hex and non-hex forms have been collapsed for simplicity since they have the same value, and to distinguish from the decimal value)

Meanwhile the IIx ROM is specified as "7.8 (120/0x78)", no rev 1.3, because only it's DeclROM contains the "1.3" reference. So that's listed in the DeclROM section (I could copy that down to the System ROM section for ease-of-use, perhaps).

It gets even worse, later, where we introduce the ROM revision field with Universal ROMs, which I've listed in both version formats (as seen in the Flash ROM tool and raw hex). For instance, with the IIci:

ROM Version: "7.12 (124/0x7C)"
ROM Revision: "1.0f1 (0x10F1)"

Even worse, sometimes the Machine value is concatenated and you'll see 0x67C and the like, but that's definitely "wrong" as I've not seen it referenced that way in official documentation so I kept that as it's own value, for now.

What's correct? I'd argue all of them, because they're all documented somewhere.

 

[eharmon]

Yeah, the versions are totally a mess and even official documentation doesn't agree with itself. Other technical bulletins use the decimals instead! So I've taken to displaying as many versions as possible, in all formats, with the latest changes on tree.

For instance, the 128k ROM is listed as "6.9", "69", "0x69", and "105", depending on source, both official and unofficial. (Confusingly, it's ALSO mentioned as 7.0, which is "officially true" but never encoded in the ROM itself). So I've listed all 4 different ways of referencing it:



Meanwhile the IIx ROM is specified as "7.8 (120/0x78)", no rev 1.3, because only it's DeclROM contains the "1.3" reference. So that's listed in the DeclROM section (I could copy that down to the System ROM section for ease-of-use, perhaps).

It gets even worse, later, where we introduce the ROM revision field with Universal ROMs, which I've listed in both version formats (as seen in the Flash ROM tool and raw hex). For instance, with the IIci:



Even worse, sometimes the Machine value is concatenated and you'll see 0x67C and the like, but that's definitely "wrong" as I've not seen it referenced that way in official documentation so I kept that as it's own value, for now.

What's correct? I'd argue all of them, because they're all documented somewhere.

Oh and then there's the Pippin ROMs, which don't even follow the ROM Revision format correctly! They seem to encode "major.minor build" instead of "major.minor (release type) revision"!

 

[Arbee]

Yeah, external documentation was trying all kinds of stuff to prevent having to admit that "ROM 69" meant exactly what you think.

For IIci and later all of the internal documentation is consistent that the "Machine version" and "ROM version" are a 16-bit ROM series ID, either $067C (Jaws series, which eventually included the Terror, HORROR, and Kaos projects) or $077D (SuperMario series). The actual version for those is what ROM Fiend is calling the "ROM Release". It goes smoothly from 1.0F1 (IIci) to 3.2F2 (LC 580) for the $067C series and then resets to 1.0F3 for Q660AV/Q840AV and goes up to 4.5F3 for the Gossamer speedbump.

New World 1MB boot ROMs have a similar release field starting again at 1.0F1 for the Bondi iMac (1.1F4 is the oldest one currently dumped) to at least 5.15F2 (G5 1.6 GHz), which is the newest one currently dumped. They all contain the actual build date as well.

 

[Phipli]

New World 1MB boot ROMs have a similar release field starting again at 1.0F1 for the Bondi iMac (1.1F4 is the oldest one currently dumped) to at least 5.15F2 (G5 1.6 GHz), which is the newest one currently dumped. They all contain the actual build date as well.

Does the New World ROM continue to have SuperMario in it?

 

[Arbee]

The “Mac OS ROM” file is still based on SuperMario but the actual 1MB boot ROM on New World machines is just Open Firmware, hardware drivers, and support code.

 

[Phipli]

The “Mac OS ROM” file is still based on SuperMario but the actual 1MB boot ROM on New World machines is just Open Firmware, hardware drivers, and support code.

Ah, of course sorry, missed that you meant the boot ROM. Not paying attention properly.

 

[eharmon]

Yeah, external documentation was trying all kinds of stuff to prevent having to admit that "ROM 69" meant exactly what you think.

For IIci and later all of the internal documentation is consistent that the "Machine version" and "ROM version" are a 16-bit ROM series ID, either $067C (Jaws series, which eventually included the Terror, HORROR, and Kaos projects) or $077D (SuperMario series). The actual version for those is what ROM Fiend is calling the "ROM Release". It goes smoothly from 1.0F1 (IIci) to 3.2F2 (LC 580) for the $067C series and then resets to 1.0F3 for Q660AV/Q840AV and goes up to 4.5F3 for the Gossamer speedbump.

New World 1MB boot ROMs have a similar release field starting again at 1.0F1 for the Bondi iMac (1.1F4 is the oldest one currently dumped) to at least 5.15F2 (G5 1.6 GHz), which is the newest one currently dumped. They all contain the actual build date as well.

Ahh, for Jaws+ I can also show it as the "Series ID", then.

For the second set of versions, I called it "ROM Release" matching what seem to be Super Mario conventions, but open to suggestions.