mirror of
https://github.com/dingusdev/dingusppc.git
synced 2024-12-26 09:29:28 +00:00
263 lines
12 KiB
Markdown
263 lines
12 KiB
Markdown
# Open Firmware in Power Macintosh
|
|
|
|
*compiled from various sources by Max Poliakovski.*
|
|
|
|
[Open Firmware](https://en.wikipedia.org/wiki/Open_Firmware) is a platform-independent
|
|
boot firmware architecture covered by an IEEE standard.
|
|
|
|
All PowerMacintosh computers run Open Firmware except the very first generation
|
|
that uses [Nubus](https://en.wikipedia.org/wiki/NuBus) instead of
|
|
[PCI](https://en.wikipedia.org/wiki/Peripheral_Component_Interconnect).
|
|
|
|
Open Firmware is used to perform hardware identification and initialization during
|
|
the booting process after power-on. It also provides a platform-independent
|
|
description of the attached devices available for operating systems.
|
|
In this respect, Open Firmware can be compared with [BIOS](https://en.wikipedia.org/wiki/BIOS),
|
|
widely used in the PC world.
|
|
|
|
Being based upon the [Forth programming language](https://en.wikipedia.org/wiki/Forth_(programming_language)),
|
|
Open Firmware offers an operating system, an interactive environment as well as a
|
|
programming language in one package. Its shell can be used as well by users for
|
|
controlling the boot enviroment as by developers for developing and debugging device
|
|
drivers.
|
|
|
|
This document focuses on various aspects of Apple's Open Firmware implementation
|
|
as found in various PowerMacintosh models.
|
|
|
|
## Open Firmware Versions
|
|
|
|
### Old World Macs
|
|
|
|
| ROM dump/Machine | BootROM codename | OF version | OF image offset |
|
|
|:------------------------------------:|:----------------:|:-------------:|:---------------:|
|
|
| Power Macintosh 7300/7600/8600/9600 | TNT | 1.0.5 | 0x330000 |
|
|
| Bandai Pippin | Pip | 1.0.5 | 0x330000 |
|
|
| Power Macintosh,Performa 6400 | Alchemy | 2.0 | 0x330000 |
|
|
| Power Macintosh G3 desktop | Gossamer | 2.0f1 | 0x320000 |
|
|
| PowerBook G3 Wallstreet v2 | GRX | 2.0.1 | 0x330000 |
|
|
| Power Macintosh 4400/7220 | Zanzibar | 2.0.2 | 0x330000 |
|
|
| Power Macintosh 6500 | Gazelle | 2.0.3 | 0x330000 |
|
|
| Power Macintosh G3 v3 | Gossamer | 2.4 | 0x320000 |
|
|
|
|
### NewWorld Macs
|
|
|
|
*TBD*
|
|
|
|
## Open Firmware image
|
|
|
|
### Old World Macs
|
|
|
|
Open Firmware in OldWorld Macs is stored in the monolithic 4MB ROM. Its hibernated
|
|
image is located at offset `0x320000` or `0x330000` from beginning of the ROM.
|
|
That corresponds to the physical address `0xFFF20000` or `0xFFF30000`, respectively.
|
|
|
|
The size of the Open Firmware image varies from 98KB (v1.0.5) to 172KB (v2.4).
|
|
|
|
Apple's Open Firmware image has the following structure:
|
|
|
|
| Section type | Architecture | Relative Size (v1.0.5) | Relative Size (v2.4) |
|
|
|:------------------:|:------------:|:----------------------:|:--------------------:|
|
|
| OF kernel | PowerPC | 26% | 18% |
|
|
| OF main code | FCode | 62% | 51% |
|
|
| OF device packages | FCode | 12% | 31% |
|
|
|
|
OF image is wrapped in the COFF container. At the start of the image, a COFF file
|
|
header and a section header are located. The following example parses the COFF
|
|
headers of the OF image from the Gossamer ROM v3:
|
|
|
|
```
|
|
org 0xFFF20000
|
|
|
|
; OF COFF file header
|
|
dc.w 0x1DF ; COFF magic
|
|
dc.w 1 ; number of sections
|
|
dc.l 'Gary' ; Gary Davidian's signature replaces time and date
|
|
dc.l 0 ; ptr to the symbol table
|
|
dc.l 0 ; number of entries in the symbol table
|
|
dc.w 0 ; size of the optional header
|
|
dc.w 0 ; flags
|
|
|
|
; OF COFF section header
|
|
dc.b '.text', 0, 0, 0 ; section name
|
|
dc.l 0 ; physical address
|
|
dc.l 0 ; virtual address
|
|
dc.l 0x2ADB0 ; section size in bytes (= 171KB)
|
|
dc.l 0x3C ; file offset to section data
|
|
dc.l 0 ; file offset to section relocations
|
|
dc.l 0 ; file offset to line number entries
|
|
dc.w 0 ; number of relocation entries
|
|
dc.w 0 ; number of line number entries
|
|
dc.l 0x20 ; section flags (this section contains executable code)
|
|
```
|
|
Right after the COFF section header, a vital OF kernel data structure called `StartVec`
|
|
is located. It contains among others several important offsets into the OF image
|
|
for finding all required OF parts. That's also the location HWInit passes control
|
|
to when invoking OF:
|
|
|
|
```
|
|
org 0xFFF2003C
|
|
|
|
; OF execution starts here
|
|
mflr r11 ; save return address to HWInit in R11
|
|
bl OF_kernel_start ; pass control to OF kernel
|
|
; LR will contain physical address of StartVec
|
|
|
|
; Begin of StartVec structure
|
|
; All offsets are from the beginning of the .text section (0xFFF2003C)
|
|
FFF20044 dc.l 0x7918 ; offset to the FCode stream of the OF main package
|
|
...
|
|
FFF2007C dc.l 0x28C48 ; offset to the last driver in the device packages
|
|
...
|
|
FFF20084 dc.l 0x7720 ; offset to the last Forth word descriptor of the kernel
|
|
|
|
```
|
|
|
|
This StartVec structure in ROM is not to be confused with the `@startvec` structure in RAM.
|
|
Open Firmware 2.4 lists the fields of `@startvec`:
|
|
|
|
```
|
|
0x488 0000 FF808000 >of.next 00001000
|
|
0x489 0004 FF808004 >of.dev-ven 00000000
|
|
0x48A 0008 FF808008 >of.class 00000000
|
|
0x48B 000C FF80800C >of.offset 00000000
|
|
0x48C 0010 FF808010 >of.fcode 00000000
|
|
0x48D 0008 FF808008 >imagesize 00000000
|
|
0x48E 000C FF80800C >'cold2 00000000
|
|
0x48F 0010 FF808010 >'map-page 00000000
|
|
0x490 0014 FF808014 >'map-io 00000000
|
|
0x491 0018 FF808018 >endiango FF808940
|
|
0x492 001C FF80801C >little? 00000000
|
|
0x493 0020 FF808020 >swizzle? 00000000
|
|
0x494 0024 FF808024 >real? 00000000
|
|
0x495 0028 FF808028 >rom-base FFF2003C
|
|
0x496 002C FF80802C >real_base 00400000
|
|
0x497 0030 FF808030 >virt_base FF800000
|
|
0x498 0034 FF808034 >real-vt-hd 004DFC00
|
|
0x499 0038 FF808038 >restart FFF201DC
|
|
0x49A 003C FF80803C >fcimage FFF27954
|
|
0x49B 0040 FF808040 >fcfiles FFF48C84
|
|
0x49C 0044 FF808044 >lasttoken 00000EB5
|
|
0x49D 0048 FF808048 >word-list FF85D4E8
|
|
0x49E 004C FF80804C >'ferror FF80D0B0 ferror
|
|
0x49F 0050 FF808050 >'(poplocals) FF80A350 (poplocals)
|
|
0x4A0 0054 FF808054 >'cold-load FF80F738 cold-load
|
|
0x4A1 0058 FF808058 >'cold-init FF818350 _cold-init
|
|
0x4A2 005C FF80805C >'quit FF8179A8 quit
|
|
0x4A3 0060 FF808060 >'abort FF811FA0 abort
|
|
0x4A4 0064 FF808064 >'syscatch FF819638 _syscatch
|
|
0x4A5 0068 FF808068 >'excp FF819338 _exception
|
|
0x4A6 006C FF80806C >'bp-done 00000000
|
|
0x4A7 0070 FF808070 >'step-done 00000000
|
|
0x4A8 0074 FF808074 >'mini-nub 00000000
|
|
0x4A9 0078 FF808078 >hwinitlr FFF04D50
|
|
0x4AA 007C FF80807C >hwinitiv 00000000
|
|
0x4AB 0080 FF808080 >hwinit3 00009000
|
|
0x4AC 0084 FF808084 >hwinit4 00009120
|
|
0x4AD 0088 FF808088 >hwinit8 FFF03058
|
|
0x4AE 008C FF80808C >hwinit9 F3060000
|
|
0x4AF 0090 FF808090 >sccac F3013020
|
|
0x4B0 0094 FF808094 >sccad F3013030
|
|
0x4B1 0098 FF808098 >ramsize 30000000
|
|
0x4B2 009C FF80809C >cpuclock 0DF092B0
|
|
0x4B3 00A0 FF8080A0 >busclock 03FB97A0
|
|
0x4B4 00A4 FF8080A4 >tbclock 00FEE5E8
|
|
0x4B5 00A8 FF8080A8 >here FF85D524
|
|
0x4B6 00AC FF8080AC >free-top FF8E0000
|
|
0x4B7 00B0 FF8080B0 >free-bot FF8D0000
|
|
0x4B8 00B4 FF8080B4 >#dsi-ints 00000000
|
|
0x4B9 00B8 FF8080B8 >#isi-ints 00000000
|
|
0x4BA 00BC FF8080BC >dl-buf FF8F0800
|
|
0x4BB 00C0 FF8080C0 >ttp800 FF8D6000
|
|
0x4BC 00C4 FF8080C4 >'cientry FF809E18 cientry
|
|
0x4BD 00C8 FF8080C8 >'cicall FF829498 cicall
|
|
0x4BE 00CC FF8080CC >'my-self FF80D8D0
|
|
0x4BF 00D0 FF8080D0 >'<sc-int> 00409D10
|
|
0x4C0 00D4 FF8080D4 >ofregsv FF8DFA00 ^-720600
|
|
0x4C1 00D8 FF8080D8 >ciregsv FF8DF800
|
|
0x4C2 00DC FF8080DC >ofregsr 004DFA00
|
|
0x4C3 00E0 FF8080E0 >ciregsr 004DF800
|
|
0x4C4 00E4 FF8080E4 >intvectv FF8DF600
|
|
0x4C5 00E8 FF8080E8 >intvectr 004DF600
|
|
0x4C6 00EC FF8080EC >regsvalid? FF808000
|
|
0x4C7 00F0 FF8080F0 >ciwords FF82A3D0
|
|
0x4C8 00F4 FF8080F4 >htab 004E0000
|
|
0x4C9 00F8 FF8080F8 >keepbat2? 00000000
|
|
0x4CA 00FC FF8080FC >keepbat3? 00000000
|
|
0x4CB 0100 FF808100 >rp FF800800
|
|
0x4CC 0104 FF808104 >dp FF800400
|
|
0x4CD 0108 FF808108 >fp FF801000
|
|
0x4CE 010C FF80810C >lp FF800C00
|
|
0x4CF 0110 FF808110 >ep FF801800
|
|
0x4D0 0114 FF808114 >ttp FF804000
|
|
0x4D1 0118 FF808118 >tib FF801C00
|
|
0x4D2 011C FF80811C >noname FF802000
|
|
0x4D3 0120 FF808120 >dec-ints 00000000
|
|
0x4D4 0124 FF808124 >dec-msec 00004141
|
|
0x4D5 0128 FF808128 >r13-31 FFF03078
|
|
```
|
|
|
|
The above is produced by this:
|
|
|
|
```
|
|
: dump_fields { addr fcodestart fcodeend ; token }
|
|
cr fcodeend 1+ fcodestart do
|
|
i ." 0x" 3 u.r space
|
|
i get-token drop -> token
|
|
0 token execute 4 u.r space
|
|
addr token execute dup 8 u.r space
|
|
token name.
|
|
#out @ d# 42 < if d# 42 #out @ - spaces then
|
|
@ dup 8 u.r space
|
|
\ check if the field might point to a xt token and if so, output its name
|
|
dup @startvec u> if
|
|
dup dup xt>hdr 4+ dup c@ + 8 + -8 and = if name. else drop then
|
|
else drop then
|
|
cr
|
|
loop
|
|
;
|
|
|
|
: dumpstartvec
|
|
@startvec 488 4d5 dump_fields ;
|
|
|
|
dumpstartvec
|
|
```
|
|
|
|
### Open Firmware internals
|
|
|
|
Apple's Open Firmware contains a small kernel implemented in the native PowerPC code. This kernel performs the following actions:
|
|
|
|
* set up memory translation for OF execution
|
|
* relocate itself from ROM to RAM
|
|
* initialize Forth runtime environment
|
|
* recompile OF main image from FCode to native PPC code
|
|
* pass control to recompiled OF that starts building the device tree
|
|
* process low-level exceptions
|
|
|
|
## Open Firmware and the Macintosh boot process
|
|
|
|
### Old World Macs
|
|
|
|
1. In response to power coming on, HWInit code in the Power Macintosh ROM performs initialization of the memory controller and the basic I/O facilities as well as some self-testing. After that, the startup chime is played.
|
|
2. HWInit passes control to Open Firmware kernel that prepares OF execution from RAM. OF builds the **device tree** - a platform-independent description of the attached HW.
|
|
3. OF returns control to HWInit that initializes several low-level data structures required by the Nanokernel.
|
|
4. HWInit passes control to the Nanokernel that initializes the native execution enviroment and the 68k emulator.
|
|
5. 68k emulator executes the start-up code in the Macintosh ROM that initializes various managers.
|
|
6. The device tree generated by the Open Firmware in step 2 is imported by the Expansion Bus Manager initialization code and stored in the **NameRegistry**.
|
|
7. An operating system is located and loaded.
|
|
|
|
### New World Macs
|
|
|
|
*TBD*
|
|
|
|
## Open Firmware bugs
|
|
|
|
Apple OF is known to contain numerous bugs. The following table lists some recently discrovered bugs, not mentioned elsewhere.
|
|
|
|
| OF version affected | Bug description |
|
|
|:-------------------:|-----------------|
|
|
| 2.0f1, 2.4 | A numerical overflow in `um/mod` used by `get-usecs-60x` causes the OF console to become unresponsive after approx. 71 minutes. You have to restart your computer once the bug is triggered. |
|
|
| 1.0.5 | /chaos/control `fill-rectangle` is ( ? color y x w h -- ) instead of ( color x y w h -- ) |
|
|
| 2.4 | string literal buffers `"` on the command line are 256 bytes but will overflow if you enter more than 256 bytes. |
|
|
|
|
`get-inherited-property notes.txt` discusses known bugs regarding get-inherited-property and map-in in Open Firmware 1.0.5.
|