[Debootloaders-miboot] reimplementation of the boot block

[Piotras]

I'm attaching the boot block specification for reference.


Regards,

Piotr Krysiuk
-------------- next part --------------
    Boot block specification for Apple Macintosh
    version 1.1


  This document was written as part of the project to provide "clean-room"
  implementation of compatible boot block for Apple Macintosh. The actual
  software should be implemented by person who didn't inspect internals of
  original boot block. This is to ensure that the resulting implementation
  does not infringe Apple copyrights.

  Publicly available documentation of the boot block seems to be limited to
  [1] and does not contain all the details necessary to reimplement it. This
  specification is based on reverse engineering of existing boot block
  (size=1024, sha1=8e7528cb9f438b91b3948c061fdb9895f616e46e). I examined
  interfaces refereed by this boot block and checked if their specification is
  publicly available from Apple [2,3]. Where missing information seems
  important, I provided it in the first section. The second section describes
  actual boot block interface, calling convention for next stage boot loader
  (I will refer to is as "second stage") and actual functionality of the boot
  block.



1 Undocumented interfaces


1.1 Boot block header

  The structure of boot block header is documented by Apple as BootBlkHdr [1].
  However Apple documentation does not provide safe ("default") values for all
  the fields of this structure. I also discovered some discrepancies between
  analyzed boot block and the documentation.

  The following table enumerates fields for which Apple didn't document default
  values. Provided values where extracted from analyzed boot block.

    +----------------+----------------+
    | field          | value          |
    +----------------+----------------+
    | bbPageFlags    |              0 |
    | bbCntFCBs      |             10 |
    | bb128KSHeap    |          17152 |
    | bb256KSHeap    |          32768 |
    | bbSysHeapSize  |         131072 |
    | filler         |       not used |
    | bbSysHeapExtra |       not used |
    | bbSysHeapFract |       not used |
    +----------------+----------------+

  The version word of analyzed boot block is 0x4418, which should not be
  legal according to Apple documentation. Also capitalization of "MacsBug"
  differs from documentation.


1.2 ROM traps

  _InitFS
  parameter:
    d0 - number of FCBs to allocate
  result:
    d0 - error code (not sure)

  _InitEvents
  parameter:
    d0 - number of event queue elements
  result:
    d0 - error code (not sure)


1.3 ROM entry points

  For some ROM versions, the analyzed boot block can pass control to one of
  two undocumented ROM entry points. First (I will refer to it as
  "boot_succeed") is called when:
    * second stage does not exist or
    * second stage returns success.
  The other entry point ("boot_failed") is called on error.

  boot_failed
  parameter:
    d0 - error code (possibly)
    d7 - memory block as received by boot block (possibly)

  The addresses of these entry points depend on machine ID and are provided in
  the table bellow. The entry point values are relative to ROM base address.

    +----------------+----------------+----------------+
    | machine ID     | boot_succeed   | boot_failed    |
    +----------------+----------------+----------------+
    |         0x0075 |         0x0a44 |         0x0b82 |
    |         0x0276 |         0x090e |         0x0a52 |
    |         0x0178 |         0x0f1c |         0x11ae |
    |         0x037a |         0x30e6 |         0x336e |
    |         0x067c |         0x1d96 |         0x203e |
    +----------------+----------------+----------------+


2 Specification

  The boot block should be implemented in Motorola 68000 assembly. When
  running on PowerPC-based Macs, it will be executed under software emulator.
  The implementation should minimize usage of stack space.


2.1 Boot block interface

  The boot block calling convention used by ROM depends on ROM version. The
  memory block allocated by ROM and passed to boot block is (likely) big
  enought to store necessary paramters required for ROM calls. The boot block
  is free to clobber registers a0, a1, d0, d1 and d6. Also there is no need
  to restore registers a3, a4 and d7.

  For 64K ROMs
  parameter:
    do not make any assumptions
  result:
    n/a

  For ROM versions refereed in section 1.3
  parameter:
    a7 + 4 - start of memory block that can be used by boot loader
  results:
    n/a

  For other ROM versions
  parameter:
    [a7] - value of return address
    d7 - start of memory block that can be used by boot loader
  result:
    d0 - error code (safe bet)


2.2 Second stage interface

  parameters (possibly, but unlikely incomplete):
    [a7 - 4] - value of return address; required for miboot compatibility,
        usually second stage is not supposed to return
    a3 - handle to resource containing second stage
    a4 - parameter stored in second entry of the FndrInfo
    d7 - memory block as received by boot block
  result:
    d0 - error code (safe bet)


2.3 Boot block functionality

  When executed on machine with 64K ROM, report system error dsNoPatch and
  make sure to never return.

  When executed on Mac with machine ID 0x0075, set the starting address of
  application heap zone to starting address of system heap zone increased by
  bbSysHeapSize. Also initialize TheZone to starting address of system heap
  zone.

  Then initialize SysResName, FinderName, ScrapName and ScrapTag with values
  from the boot block header.

  Then execute trap _InitFS passing as parameter number of FCBs as specified
  in the boot block header.

  Then execute trap _InitEvents passing as parameter number of event queue
  elements as specified in the boot block header.

  Then mount boot drive.

  Then check if directory ID of the blessed folder is specified in Master
  Directory Block and if so change default directory to it.

  Then reinitialize the resource manager; report error dsSystemFileErr, if it
  fails.

  Then get the second stage stored as data of "boot" resource with id 2;
  report success if the resource does not exist.

  Then pass control to the second stage (see section 2.2 for calling
  convention); report its error code if it returns.

  To report success:
    * when executed on machine with one of ROMs specified in section 1.3, pass
      control to boot_success;
    * for other machines return to caller passing zero as error code.
  In both cases remove the return address from the stack.

  If an error occurred after boot drive was mounted, but before control was
  passed to the second stage, the drive should be unmounted.

  To report error:
    * when executed on machine with one of ROMs specified in section 1.3, pass
      control to boot_error (see section 1.3 for calling convention);
    * for other machines return to caller passing non-zero error code.
  In both cases remove the return address from the stack.


References

  [1] Inside Macintosh: Files
      Chapter 2 - File Manager, Data Organization on Volumes, Boot Blocks
      http://developer.apple.com/documentation/mac/Files/Files-101.html
  [2] Mac OS 8 and 9 Developer Documentation
      http://developer.apple.com/documentation/macos8/mac8.html
  [3] UniversalInterfaces version 3.4.2
      ftp://ftp.apple.com/developer/Development_Kits/UniversalInterfaces3.4.2.img.bin
  [4] Mac Almanac II, version 1.0
      http://www.mac.linux-m68k.org/devel/macalmanac.php