Skip to content

ROMs as BinHex (.hqx): SysEnabler restored, both boot-verified

Choose a tag to compare

View all tags
@UnexpectedBomb UnexpectedBomb released this 07 Aug 21:26
· 10 commits to main since this release
hqx-reissue
17bec9a

Both ROMs are back, and this time each one was booted on real hardware before being published.

The ROMs originally attached here did not start up. They carried a vers resource so Get Info would name the build, and that resource broke startup: a Mac OS ROM's resource fork is the System Enabler's resource fork, so a vers (1) there describes the enabler rather than our build, and the System left parts of itself uninstalled. The full explanation is kept below.

That resource is gone, the build tool now refuses to produce a ROM containing one, and both files below have started their respective machines.

Files

your machine ROM helper
Power Mac G4 MDD + PCI USB 2.0 card USB2_PathA_MacOSROM_h21r.hqx USB2_Activate_n4g.bin
Mac mini G4 (on-board USB 2.0) USB2_MiniROM_VBLfix_m3r.hqx USB2_Activate_n4g.bin 
a68bebbb60f33b1f2d5c900d32187ae1  USB2_PathA_MacOSROM_h21r.hqx
ce926e4b2e33ef899928a6b07d3a308d  USB2_MiniROM_VBLfix_m3r.hqx
753912b5fd731bea015dfbe954b861f4  USB2_Activate_n4g.bin

The drivers inside are byte-for-byte the ones already validated as h21 and m3. Only the packaging changed: the ROM's resource fork is preserved, so the 185 KB SysEnabler that earlier .bin releases silently dropped is present.

Installing

Decode the .hqx with StuffIt Expander on the Mac, which preserves the resource fork. Do not route it through a tool or file server that drops forks.

Then boot from a CD or another volume to swap Mac OS ROM, since you cannot replace the one you are booted from. Keep your original.

Mac mini owners, read this

The mini ROM also carries an experimental fix for the mini's OS 9 startup freeze, and that fix does not work reliably. This is not a new caveat, and it was demonstrated again while verifying this very release: the ROM booted correctly and then hit a frozen cursor at startup, which the app fixed.

Install the VBLFix app from the VBL fix project in Startup Items, and treat it as required rather than optional. With it in place, a boot the ROM misses becomes a few seconds of frozen cursor that clears itself.

If you would rather not have the experimental display patch at all, run scripts/build-rom-hqx.py against your own mini ROM and you get only the USB 2.0 driver.

Identifying which ROM you have

Get Info will not tell you, and that is deliberate: the version resource that would have shown it is exactly what stopped machines booting. For now the build name lives in the filename only. Surfacing it safely is an open problem.

Building your own

python3 scripts/build-rom-hqx.py "Mac OS ROM" mybuild "Mac OS ROM (USB2).hqx"

It injects the driver, emits BinHex so your ROM's resource fork survives, refuses to write a ROM whose SysEnabler came out empty, and refuses to write one carrying a vers (1). Your input ROM needs its resource fork intact; unar on the desktop, or StuffIt/BinHex on the Mac, will preserve it.

The withdrawal notice and the original notes follow, kept as a record.

⚠️ The ROMs in this release have been WITHDRAWN. They did not boot.

If you flashed USB2_PathA_MacOSROM_h21r.hqx or USB2_MiniROM_VBLfix_m3r.hqx and your machine will not start up, that is our fault and it is fixable. See "Recovering" below.

Both ROM files have been removed from this release. The helper app, USB2_Activate_n4g.bin, is unaffected and is still attached.

What went wrong

These ROMs carried a vers resource so that Get Info would tell you which build you were running. That resource broke startup.

A Mac OS ROM's resource fork is the System Enabler's resource fork, and a vers (1) resource is a file's own version. Adding one told the System that the enabler was version 1.0.0, which is a statement about the enabler rather than about our build. A mis-described enabler leaves parts of the system uninstalled.

The symptom is a dialog reading "No File System Access modules could be found in your System folder. Therefore, the Foreign File Access software was not installed.", then the Starting Up screen, then a grey screen and a hang.

Nothing else about the ROM was wrong. It was verified resource by resource against a stock ROM with nothing damaged, lost or altered. The fault was entirely that one added resource, and an otherwise identical ROM built without it boots normally.

This was shipped without being booted first, which is the real mistake. The fix is already made and verified at the desk, but it will not be published until it has actually started a machine.

Recovering, if you flashed one

You cannot swap Mac OS ROM while booted from the System Folder that contains it, so:

  1. Boot from an OS 9 CD, or from another volume with a System Folder.
  2. Put your original Mac OS ROM back into the System Folder (the one you were told to keep).
  3. Restart.

If you no longer have your original, the ROM in the m3 release will boot. It has the older packaging defect described in that release's notes (a missing SysEnabler), but it starts up normally and it is a safe place to sit until the corrected ROMs are published.

What happens next

Corrected ROMs are built and verified locally: same validated drivers, resource fork intact, and no version resource. They will be attached here once they have been boot-tested on real hardware.

Watch this release, or build your own from source in the meantime:

python3 scripts/build-rom-hqx.py "Mac OS ROM" mybuild "Mac OS ROM (USB2).hqx"

That script now refuses to produce a ROM containing the resource that caused this.

Original release notes follow.

Corrective release. If you flashed a ROM from n13 or m3, please re-flash from here.

What was wrong

Every Mac OS ROM released before this one was missing a 185 KB component called SysEnabler, and that was our packaging's fault rather than anything you did.

Those ROMs shipped as MacBinary .bin. The wrapper we used built its own small resource fork, which replaced the ROM's real one, and SysEnabler lives in that fork. It affects USB2_PathA_MacOSROM_n13.bin, USB2_PathA_MacOSROM_h21.bin and USB2_MiniROM_VBLfix_m3.bin.

They all boot, which is why this went unnoticed for months.

The symptom, if you have been seeing it

An intermittent frozen mouse cursor during startup, and the machine responding to keyboard and mouse only every few seconds. On our own MDD that hit roughly half of all boots. With SysEnabler restored, the same machine booted six times out of six with no freezing and no stutter.

Six clean boots is encouraging, not proof. If you were living with this and blaming your hardware, we would genuinely like to know whether this changes it.

What is different

Packaging only. ROMs are now BinHex .hqx, which carries both forks intact. The drivers are byte-for-byte the same ones already validated: the MDD ROM carries h21's driver and the mini ROM carries m3's.

Each ROM also now stamps its build name, so Get Info tells you which ROM is actually installed.

Files

your machine ROM helper
Power Mac G4 MDD + PCI USB 2.0 card USB2_PathA_MacOSROM_h21r.hqx USB2_Activate_n4g.bin
Mac mini G4 (on-board USB 2.0) USB2_MiniROM_VBLfix_m3r.hqx USB2_Activate_n4g.bin
anything else build your own, see below USB2_Activate_n4g.bin 
f207fb26bae5169fd0a5a511b0445318  USB2_PathA_MacOSROM_h21r.hqx
ec29b7bf6dc323b74f5bd5cca93f595d  USB2_MiniROM_VBLfix_m3r.hqx
753912b5fd731bea015dfbe954b861f4  USB2_Activate_n4g.bin

The helper is unchanged, so if you already have n4g in Startup Items you do not need to replace it.

Installing

Decode the .hqx with StuffIt Expander on the Mac. That preserves the resource fork, which is the entire point of this release. Do not route it through a tool or a file server that drops forks, or you will recreate the original problem.

Then, as before: boot from a CD or another volume to swap Mac OS ROM, because you cannot replace the one you are booted from. Keep your original.

Building your own

If you patch your own ROM, use the new script rather than the bare injector:

python3 scripts/build-rom-hqx.py "Mac OS ROM" mybuild "Mac OS ROM (USB2).hqx"

It injects the driver, stamps the build name for Get Info, emits BinHex, and refuses to write a ROM whose SysEnabler came out empty. Your input ROM needs its resource fork intact; unar on the desktop, or StuffIt/BinHex on the Mac, will preserve it.

Mac mini owners

Unchanged from the previous release, and still important: this ROM also carries an experimental fix for the mini's OS 9 startup freeze which has been observed not to prevent that freeze reliably. Run the VBLFix app from the VBL fix project in Startup Items as well, and treat that as required. Details are in the README.

Assets 5
Loading