[hfs-user] Re: HFS-Plus and Wrappers

Shantonu Sen ssen@apple.com
Thu, 2 May 2002 03:55:19 -0400

(I will probably get rejected from the lists I'm not on. If you are on multiple lists, please forward as appropriate)

On Thursday, May 2, 2002, at 02:46 AM, Entwicklung wrote:

>                    Recently there was a bit of discussion on HFS-Wrappers on
> the hfs-user mailing list and how it allows a computer with HFS (but no HFS
> Plus support) to start up or display a ReadMe to the user to improve the
> user-experience.

The HFS Wrapper is used to boot various Mac OS's on Old World machines. It serves no purpose on New World machines (except people with Dual G4's running Mac OS 7, probably ;-) ) More info below

> The tech. notes (TN 1150: HFS Plus Volume Format) says that the HFS wrapper
> volume contains five files in the root folder - a ReadMe, System and Finder,
> Desktop DB and Desktop DF.

Contains is probably a strong word. It happens to contain the above files. The System file is needed for Old World booting. The Finder is probably there to present a cohesive "System Folder" to old Mac OS's, in case they start freaking out because of a straw System file. For Mac OS X-created wrappers, the Finder file is 0 bytes (in data and resource forks) with the correct type/creator (FNDR/MACS).

> I'm a third-party developer creating an HFS-Plus volume (non-bootable)
> interested in extending the functionality of my HFS-Plus volume to include a
> Wrapper as well. I want to know whether:

Unfortunately, a wrapper alone will not get you close to bootability for Old World machines. For OS 9 (both old and new world), you will need to also set the boot blocks (the first 1KB of the filesystem). For Mac OS X, you would be set.

> 3) is there any documentation from Apple which describes how this ReadMe file
> is stored up in the Wrapper's catalog (I gathered it's not hidden) in order to
> function as expected ?... reverse-engineering
> can be painful sometimes..

It's just a file. You might learn a lot be reading the code for newfs_hfs in the diskdev_cmds project of Darwin. It shows how it creates the readme (the text is statically compiled into the newfs_hfs binary).

You might also be interested in checking out the bless-2 tag of the bless project from Dariwn CVS. In particular, look at bless/libbless/HFSWrapper/BLMountHFSWrapper.c and friends, which are basically abstractions that read the MDB, toggle the mdb->drEmbedSigWord to be  kHFSSigWord, and writes it back out. Subsequent mounts of the volume will end up actually mounting the wrapper. Coming soon to an OS near you will be the capability of mounting the wrapper as part of mount_hfs, which will require new diskdev_cmds and xnu builds.

So, what is the System file doing there, and what does it do?

No Old World machine shipped with the ability to parse HFS+ volumes. However, Mac OS 8.6 (?) and later could boot from HFS+. How was that possible? Basically, the Mac OS ROM (which lived in actual ROM) would see the boot volume and find this HFS Wrapper thingy, which looked like an ordinary HFS volume. It would load the System file at that point, however, the System file in the wrapper is not a full OS System. It's just enough of a stub to add code to provide a bare-bones, read-only HFS+ implementation. This would go into the embedded HFS+ volume, read the HFS+ Volume Header and catalog, find the blessed folder, navigate to it, and load up the real System file. The real system file has the full-fledged read-write HFS+ volume code, at which point the OS can start it's thing. For Old World machines, if you want it to run OS 9, you need a wrapper, and unless you know better, use the apple-provided stub system file (licensing withstanding. I don't know those issues).

Does this apply to OS X/Darwin? To some extent yes. Apple Install CDs (Both commercial Mac OS X and the Darwin 1.4.1 distribution) have custom system files in the wrapper that patch Open Firmware to teach it how to boot Mac OS X and trigger a reboot. This is essentially how you can hold 'C' on an Old World machine and get it to boot a Mac OS X CD. The patches are similar (identical?) to the ones used to boot A/UX, and essentially tell Open Firmware to look in the partition map for disk block offsets containing executable code that should be used in the bootstrapping of the OS. After this code is loaded the booting process is pretty similar between old world and new world.

Do you need this System file to boot Mac OS X on Old World computers? strictly no, if they have already been patched. But if PRAM is zapped for some reason, you might want your volume to repatch OF.