Difference between revisions of "Open Firmware"
From MorphOS Library
m |
|||
| (28 intermediate revisions by 3 users not shown) | |||
| Line 1: | Line 1: | ||
== Preface == | == Preface == | ||
| − | '''Open Firmware''' ('''OF''') is a computer firmware system, similar to BIOS on PC, found in all MorphOS compatible Macs. Pegasos, Pegasos II, and Efika also have an Open Firmware based | + | '''Open Firmware''' ('''OF''') is a computer firmware system, similar to the BIOS on a PC, found in all MorphOS compatible Macs. The Pegasos, Pegasos II, and Efika also have an Open Firmware based hardware implementation, but with small differences to Mac firmware. |
| − | Open Firmware | + | Open Firmware uses a Command-Line based user interface, which can be used to control booting and other processes. This tutorial focuses on useful tips and tricks when using the user interface by way of specific examples. The examples were tested on PowerPC Macs, but may also work under bPlan machines to some extent. |
| − | Output texts in | + | Output texts in these examples have been truncated in most cases to show only the information of interest. |
| − | + | == Accessing the User Interface == | |
| − | == | + | Hold down the '''Command-Option-O-F''' key combination on a Mac keyboard, though the '''Option''' key is sometimes marked as '''Alt''' - with a symbol/icon below it, or press the '''Win-Alt-O-F''' key combination on a PC Windows keyboard while booting the machine. Release the keys only after you see the Open Firmware prompt display on a grey background. |
| − | Hold down the '''Command-Option-O-F''' key combination on a Mac keyboard or the '''Win-Alt-O-F''' key combination on a PC keyboard while booting the machine. Release the keys only after you see the Open Firmware prompt on a grey background. | ||
<nowiki> | <nowiki> | ||
| Line 23: | Line 22: | ||
ok | ok | ||
| − | 0 > _ | + | 0 > _</nowiki> |
| − | </nowiki> | ||
| − | |||
| − | |||
| − | + | If the machine boots to an installed OS instead of the OF prompt, reboot and try again. It may help to connect the keyboard directly to the machine's USB port, not via a USB hub. The keys don't have to be pressed immediately when powering the machine on, but promptly after hearing the startup sound (if it has not been disabled) or as the machine triggers access to the optical drive. | |
| + | Open Firmware uses the '''US keyboard layout''', tips for typing using other keyboards can be found within the [http://www.morphos.de/guide/usb-boot#section5 official MorphOS USB boot guide]. | ||
== Useful Commands == | == Useful Commands == | ||
| Line 35: | Line 32: | ||
* '''reset-all''' - Resets the machine to the power-on state and reboots | * '''reset-all''' - Resets the machine to the power-on state and reboots | ||
* '''shut-down''' - Shuts down the machine | * '''shut-down''' - Shuts down the machine | ||
| − | * '''load <file> <args>''' - Loads an OF code file (ELF binary image like MorphOS boot.img or Forth script | + | * '''load <file> <args>''' - Loads an OF code file (e.g. ELF binary image like MorphOS boot.img or Forth script) into memory |
* '''go''' - Runs/boots the loaded file | * '''go''' - Runs/boots the loaded file | ||
* '''boot <file> <args>''' - Loads an OF code file and boots it | * '''boot <file> <args>''' - Loads an OF code file and boots it | ||
* '''printenv''' - Prints environment variable values | * '''printenv''' - Prints environment variable values | ||
* '''setenv''' - Sets environment variable values | * '''setenv''' - Sets environment variable values | ||
| − | * '''devalias''' - Displays a list of ''aliases'' for devices ( | + | * '''devalias''' - Displays a list of ''aliases'' for devices (similar to ''assigns'' on MorphOS) |
* '''.properties''' - Displays a list of properties for the selected device | * '''.properties''' - Displays a list of properties for the selected device | ||
* '''ls''' - Displays contents of the current path in the device tree | * '''ls''' - Displays contents of the current path in the device tree | ||
| Line 46: | Line 43: | ||
* '''dev''' - Selects a device (using either the alias or absolute/relative device tree path) | * '''dev''' - Selects a device (using either the alias or absolute/relative device tree path) | ||
* '''dir''' - Lists files on a partition | * '''dir''' - Lists files on a partition | ||
| − | |||
== Environment Variables == | == Environment Variables == | ||
| Line 54: | Line 50: | ||
0 > printenv | 0 > printenv | ||
-------------- Partition: common -------- Signature: 0x70 --------------- | -------------- Partition: common -------- Signature: 0x70 --------------- | ||
| − | little-endian? | + | little-endian? false false |
real-mode? false false | real-mode? false false | ||
auto-boot? true true | auto-boot? true true | ||
skip-netboot? false false | skip-netboot? false false | ||
| − | </nowiki> | + | use-nvramrc? false false</nowiki> |
| − | The first value in the list is the current value and the second value is the default value. It's quite rare that you | + | The first value in the list is the current value and the second value is the default value. It's quite rare that you need to change these values, but it's interesting to learn more about your computer nevertheless. |
| − | One common | + | One common choice is to speed up Startup Manager (the boot menu you see when booting with the option/alt key pressed) by disabling the netboot option. So, let's change that, as an example, and check that we succeeded. |
<nowiki> | <nowiki> | ||
| Line 68: | Line 64: | ||
0 > printenv skip-netboot? | 0 > printenv skip-netboot? | ||
-------------- Partition: common -------- Signature: 0x70 --------------- | -------------- Partition: common -------- Signature: 0x70 --------------- | ||
| − | skip-netboot? true false | + | skip-netboot? true false</nowiki> |
| − | </nowiki> | ||
| − | |||
== Examining Devices == | == Examining Devices == | ||
| − | The ''dev'' command selects a device to be examined, and ''.properties'', ''ls'', and ''dir'' commands can be used to print information | + | The ''dev'' command selects a device to be examined, and ''.properties'', ''ls'', and ''dir'' commands can be used to print information about the selected device. '''Note''' that it depends on the device type if these commands will print something. ''dir'' only works for devices containing a filesystem, and such like. |
=== Listing Aliases === | === Listing Aliases === | ||
| − | A special ''/aliases'' device contains information about shortcuts (aliases) to different hardware devices. Let's see few examples how to | + | A special ''/aliases'' device contains information about shortcuts (aliases) to different hardware devices. Let's see a few examples of how to show that information. |
The device can be selected with the ''dev'' command and then the aliases can be listed with the ''.properties'' command: | The device can be selected with the ''dev'' command and then the aliases can be listed with the ''.properties'' command: | ||
| Line 92: | Line 86: | ||
hd /pci@f4000000/ata-6@d/disk@0 | hd /pci@f4000000/ata-6@d/disk@0 | ||
cd /pci@f4000000/ata-6@d/disk@1 | cd /pci@f4000000/ata-6@d/disk@1 | ||
| − | ud /pci@f2000000/usb@15,1/disk@1 | + | ud /pci@f2000000/usb@15,1/disk@1</nowiki> |
| − | </nowiki> | ||
| − | The commands can be | + | The commands can also be input combined, on a single line: |
<nowiki> | <nowiki> | ||
0 > dev /aliases .properties | 0 > dev /aliases .properties | ||
| Line 108: | Line 101: | ||
hd /pci@f4000000/ata-6@d/disk@0 | hd /pci@f4000000/ata-6@d/disk@0 | ||
cd /pci@f4000000/ata-6@d/disk@1 | cd /pci@f4000000/ata-6@d/disk@1 | ||
| − | ud /pci@f2000000/usb@15,1/disk@1 | + | ud /pci@f2000000/usb@15,1/disk@1</nowiki> |
| − | </nowiki> | ||
There's also a shorter ''devalias'' command available on most firmware versions, and it does the same as the previous example: | There's also a shorter ''devalias'' command available on most firmware versions, and it does the same as the previous example: | ||
| Line 124: | Line 116: | ||
hd /pci@f4000000/ata-6@d/disk@0 | hd /pci@f4000000/ata-6@d/disk@0 | ||
cd /pci@f4000000/ata-6@d/disk@1 | cd /pci@f4000000/ata-6@d/disk@1 | ||
| − | ud /pci@f2000000/usb@15,1/disk@1 | + | ud /pci@f2000000/usb@15,1/disk@1</nowiki> |
| − | </nowiki> | ||
| − | |||
=== Other Useful Properties === | === Other Useful Properties === | ||
| Line 137: | Line 127: | ||
Power Macintosh | Power Macintosh | ||
| − | serial-number SX0 | + | serial-number SX0</nowiki> |
| − | </nowiki> | ||
The ''enet'' device shows the MAC address of the computer. ''00:11:24:e3:66:66'' in this case: | The ''enet'' device shows the MAC address of the computer. ''00:11:24:e3:66:66'' in this case: | ||
| Line 147: | Line 136: | ||
name ethernet | name ethernet | ||
device_type network | device_type network | ||
| − | local-mac-address 001124e3 6666 | + | local-mac-address 001124e3 6666</nowiki> |
| − | </nowiki> | ||
| − | |||
=== Listing Devices === | === Listing Devices === | ||
| − | The ''ls'' command lists devices found | + | The ''ls'' command lists devices found in the current device in the device tree: |
<nowiki> | <nowiki> | ||
0 > dev usb1 ls | 0 > dev usb1 ls | ||
| Line 159: | Line 146: | ||
ff9e1c48: /keyboard@0 | ff9e1c48: /keyboard@0 | ||
ff9e1f88: /mouse@1 | ff9e1f88: /mouse@1 | ||
| − | ff9e2230: /interface@2 | + | ff9e2230: /interface@2</nowiki> |
| − | </nowiki> | ||
| − | |||
=== Listing Files === | === Listing Files === | ||
| Line 173: | Line 158: | ||
* ''path'' is a path in the filesystem, the directory delimiter is \ and the same character is also used to access the root directory | * ''path'' is a path in the filesystem, the directory delimiter is \ and the same character is also used to access the root directory | ||
| − | Listing the root (\) directory from the default partition on the default HD (this is usually the Boot: partition on a MorphOS system). The "," character could be omitted in certain cases, but it's safer to type | + | Listing the root (\) directory from the default partition on the default HD (this is usually the Boot: partition on a MorphOS system). The "," character could be omitted in certain cases, but it's safer to type that as well: |
<nowiki> | <nowiki> | ||
| − | 0 > dir hd:,\ | + | 0 > dir hd:,\</nowiki> |
| − | </nowiki> | ||
Listing the root directory from the first partition on the (default) HD: | Listing the root directory from the first partition on the (default) HD: | ||
<nowiki> | <nowiki> | ||
| − | 0 > dir hd:1,\ | + | 0 > dir hd:1,\</nowiki> |
| − | </nowiki> | ||
Listing the root directory from a CD: | Listing the root directory from a CD: | ||
<nowiki> | <nowiki> | ||
| − | 0 > dir cd:,\ | + | 0 > dir cd:,\</nowiki> |
| − | </nowiki> | ||
| − | Listing a | + | Listing a sub-directory from a CD: |
<nowiki> | <nowiki> | ||
| − | 0 > dir cd:,\mac_ppc32 | + | 0 > dir cd:,\mac_ppc32</nowiki> |
| − | </nowiki> | ||
Listing the root directory from a USB mass storage device found in the usb1 device (use the previously mentioned ''ls'' command to find the correct device): | Listing the root directory from a USB mass storage device found in the usb1 device (use the previously mentioned ''ls'' command to find the correct device): | ||
<nowiki> | <nowiki> | ||
| − | 0 > dir usb1/disk@1:,\ | + | 0 > dir usb1/disk@1:,\</nowiki> |
| − | </nowiki> | + | |
| + | Newer firmware versions create the ''ud'' alias for a USB mass storage device connected to the machine (if it's been connected prior to starting the OF interface), so this does the same as the previous example: | ||
| + | <nowiki> | ||
| + | 0 > dir ud:,\</nowiki> | ||
| + | |||
| + | == Adding Custom Devaliases == | ||
| + | The ''devalias'' command adds temporary user defined devaliases. | ||
| + | |||
| + | <nowiki> | ||
| + | 0 > devalias dh /pci@f4000000/ata-6@d/disk@0</nowiki> | ||
| + | |||
| + | ''nvvalias'' stores a devalias in NVRAMRC. Variable ''use-nvramrc?'' needs to be set to true in order to execute NVRAMRC script at startup. | ||
| + | |||
| + | <nowiki> | ||
| + | 0 > nvalias dh /pci@f4000000/ata-6@d/disk@0</nowiki> | ||
| + | |||
| + | ''nvunalias'' deletes an alias. | ||
| − | |||
<nowiki> | <nowiki> | ||
| − | 0 > | + | 0 > nvunalias dh</nowiki> |
| − | </nowiki> | ||
| + | You can replace existing devaliases with your own ones. Removing them will revert to original values. | ||
== Booting MorphOS == | == Booting MorphOS == | ||
=== Basics === | === Basics === | ||
| − | To boot into MorphOS, Open Firmware has to load a MorphOS boot image file, which is usually named as ''boot.img''. The boot image contains the MorphOS kernel and core drivers, so it's | + | To boot into MorphOS, Open Firmware has to load a MorphOS boot image file, which is usually named as ''boot.img''. The boot image contains the MorphOS kernel and core drivers, so it's basically comparable to the Amiga's Kickstart. Open Firmware just loads and boots the file, and the rest is handled by MorphOS itself after that. In case of errors, it's important to distinguish if loading of the boot image failed or does the error occur at a later stage. |
| − | The ''boot.img'' file usually resides on a special HFS formatted ''Boot:'' partition on Macs, or on a partition that has a filesystem known | + | The ''boot.img'' file usually resides on a special HFS formatted ''Boot:'' partition on Macs, or on a partition that has a filesystem known to Open Firmware in any case. The ''Boot:'' partition only contains a few Open Firmware related files and isn't used for anything else than to get the kernel loaded by the machine itself. How MorphOS sees the partition isn't important and it can even be unmounted from a MorphOS point of view. MorphOS itself is booted from a partition containing a MorphOS compatible [[Filesystems|filesystem]] and MorphOS system files in it, and this partition is usually named as "System:" and the SYS: '''assign''' points to it as well. |
| − | When booting manually from OF, you'll see some output lines on screen. There are two important lines | + | When booting manually from OF, you'll see some output lines on screen. There are two important lines that tell you the boot stage. This can be demonstrated well with the ''load'' and ''go'' commands. |
Type in this line (if you have a MorphOS installation on your HD): | Type in this line (if you have a MorphOS installation on your HD): | ||
| + | |||
0 > load hd:,\boot.img | 0 > load hd:,\boot.img | ||
| − | + | ||
And you'll see output like this: | And you'll see output like this: | ||
<nowiki> | <nowiki> | ||
| Line 221: | Line 218: | ||
Loading ELF | Loading ELF | ||
ok | ok | ||
| − | 0 > _ | + | 0 > _</nowiki> |
| − | </nowiki> | ||
| − | "Loading ELF" tells that the file has been found and loaded. | + | "Loading ELF" tells you that the file has been found and loaded. |
The file can be booted with the ''go'' command then: | The file can be booted with the ''go'' command then: | ||
<nowiki> | <nowiki> | ||
0 > go | 0 > go | ||
| − | DO-QUIESCE finished_ | + | DO-QUIESCE finished_</nowiki> |
| − | </nowiki> | ||
| − | "DO-QUIESCE finished" indicates that the file has been booted and machine is running under MorphOS | + | "DO-QUIESCE finished" indicates that the file has been booted and the machine is now running under MorphOS. Problems after that stage are MorphOS related, and if the MorphOS boot image doesn't appear soon, then MorphOS might not have found a device or image to boot from, or there might be driver or compatibility issues. MorphOS reset keys (Ctrl-Lcmd-Rcmd, Fn-alt-alt) also work at this stage even if there are any other problems halting the boot process. |
A shorter, and usual, way to boot is to use the ''boot'' command, which combines both ''load'' and ''go'' commands. | A shorter, and usual, way to boot is to use the ''boot'' command, which combines both ''load'' and ''go'' commands. | ||
| − | The previous example can be | + | The previous example can be achieved with this single line: |
| − | 0 > boot hd:,\boot.img | + | <nowiki> |
| − | + | 0 > boot hd:,\boot.img</nowiki> | |
| − | And the output | + | |
| + | And the output should then look like this: | ||
<nowiki> | <nowiki> | ||
0 > boot hd:,\boot.img load-size=16e8fc adler32=bd628950 | 0 > boot hd:,\boot.img load-size=16e8fc adler32=bd628950 | ||
| Line 245: | Line 241: | ||
Loading ELF | Loading ELF | ||
| − | DO-QUIESCE finished_ | + | DO-QUIESCE finished_</nowiki> |
| − | </nowiki> | ||
| − | |||
=== Boot Arguments === | === Boot Arguments === | ||
| − | Several boot arguments can be given to the ''boot.img'' file by adding them to the end of a ''load'' or ''boot'' line. More detailed explanations of | + | Several boot arguments can be given to the ''boot.img'' file by adding them to the end of a ''load'' or ''boot'' line. More detailed explanations of these arguments can be found from '''Docs/Booting MorphOS.txt''' and '''Docs/PegasosFirmware.txt''' files on your MorphOS system or the installation CD, but let's cover the most useful booting related ones here. Note that Sam460ex/cr and AmigaOne X5000 systems don't use Open Firmware, but the boot arguments can be given on them too by setting an environment variable in their [[Tips_and_Tricks#MorphOS_Boot_Arguments_on_U-boot_Systems | U-boot console]]. |
| − | Without arguments MorphOS boots a device that is bootable and has the highest boot priority set. Note that this only applies to partitions that contain a MorphOS compatible bootable [[Filesystems|filesystem]]. If a MorphOS installation CD is inserted, it usually has a higher priority than bootable partitions on the HD. The HDConfig tool can be used to set partitions bootable and alter their boot priorities, but it's unnecessary to change these settings | + | Without arguments MorphOS boots a device that is bootable and has the highest boot priority set. '''Note''' that this only applies to partitions that contain a MorphOS compatible bootable [[Filesystems|filesystem]]. If a MorphOS installation CD is inserted, it usually has a higher priority than bootable partitions on the HD. The HDConfig tool can be used to set partitions bootable and alter their boot priorities, but usually it's unnecessary to change these settings. |
| − | The syntax for arguments is '''argument=value''', but the equals sign can be replaced with a space character. The arguments can be given in a longer or shorter | + | The syntax for arguments is '''argument=value''', but the equals sign can be replaced with a space character. The arguments can be given in a longer or shorter, in parenthesis '''()''' format. |
| − | * '''bootdevice (bd)''' - Overrides boot priorities and boots from a given partition. The partition name must be given in the form MorphOS sees it as a '''device name''' (volume names don't work), and the trailing ":" character can be omitted. For example, "bootdevice=dh1" works, but "bootdevice=System" doesn't. | + | * '''bootdevice (bd)''' - Overrides boot priorities and boots from a given partition. The partition name must be given in the form MorphOS sees it as a '''device name''' (volume names don't work), and the trailing ":" character can be omitted. For example, "bootdevice=dh1" works, but "bootdevice=System" doesn't.[[File:MorphOS-BootMenu.png|thumb|MorphOS bootmenu]] |
* '''bootimage (bi)''' - Boots the MorphOS system from an ISO image file, which is placed on a partition that is accessible with the built-in filesystems of the boot.img ('''FAT, SFS, FFS, PFS3, CDFS'''). A full MorphOS style path must be given to the argument, but use '''device names''' instead of volume names again. For example, "bootimage=umsd0:morphos-3.11.iso", "bootimage=dh2:morphos-3.11.iso". | * '''bootimage (bi)''' - Boots the MorphOS system from an ISO image file, which is placed on a partition that is accessible with the built-in filesystems of the boot.img ('''FAT, SFS, FFS, PFS3, CDFS'''). A full MorphOS style path must be given to the argument, but use '''device names''' instead of volume names again. For example, "bootimage=umsd0:morphos-3.11.iso", "bootimage=dh2:morphos-3.11.iso". | ||
* '''bootmenu (bm)''' - Boots into the MorphOS bootmenu where you can change display settings, see information about devices, or boot without startup-sequence. The same bootmenu can be accessed by pressing the '''shift''' key during the MorphOS boot process. Pressing the '''v''' key in the bootmenu toggles between the default resolution and a 640x480@60Hz VESA mode, and that can be useful in case of display issues. The '''space''' toggles between multiple monitors instead. | * '''bootmenu (bm)''' - Boots into the MorphOS bootmenu where you can change display settings, see information about devices, or boot without startup-sequence. The same bootmenu can be accessed by pressing the '''shift''' key during the MorphOS boot process. Pressing the '''v''' key in the bootmenu toggles between the default resolution and a 640x480@60Hz VESA mode, and that can be useful in case of display issues. The '''space''' toggles between multiple monitors instead. | ||
| − | |||
=== Examples === | === Examples === | ||
==== Booting from CD ==== | ==== Booting from CD ==== | ||
| − | MorphOS documentation | + | MorphOS documentation's usual advice is to boot the machine with the ''c'' key pressed, but that method can sometimes be unreliable for one reason or another, so you might end up in a situation where a boot image has been loaded from a HD and the actual system from a CD, which results in an error if the boot image and the CD aren't from the same MorphOS version. A more reliable way is to boot into the Startup Manager menu on Macs by holding the ''alt'' (''option'') key at boot, and select the CD from that graphical boot menu. Pressing the F12 key in the menu will eject the CD. |
| − | + | As well as the previously mentioned methods, there are other ways to boot a CD from the Open Firmware prompt. | |
To boot any inserted CD that is bootable on Macs: | To boot any inserted CD that is bootable on Macs: | ||
| Line 288: | Line 281: | ||
1416944 07/04/2018 04:03:02 boot UNIX bootsam_ppc4x0.img | 1416944 07/04/2018 04:03:02 boot UNIX bootsam_ppc4x0.img | ||
01/01/1904 00:00:00 *mac_ppc32 | 01/01/1904 00:00:00 *mac_ppc32 | ||
| − | 01/01/1904 00:00:00 mac_ppc64 | + | 01/01/1904 00:00:00 mac_ppc64</nowiki> |
| − | </nowiki> | ||
| − | As you can see, there are several different boot images for different architectures. ''boot.img'' is for Pegasos II and others are easy to guess. Boot images for Macs are located in | + | As you can see, there are several different boot images for different architectures. ''boot.img'' is for Pegasos II and others are easy to guess. Boot images for Macs are located in sub-directories, ''mac_ppc32'' contains the ''boot.img'' file for G4 Macs and ''mac_ppc64'' for G5 Macs. The ''blessed'' directory is marked with an asterisk. |
| − | If we | + | If we wanted to boot the CD on a G5 Mac: |
<nowiki> | <nowiki> | ||
0 > dir cd:,\mac_ppc64 | 0 > dir cd:,\mac_ppc64 | ||
| Line 302: | Line 294: | ||
ok | ok | ||
| − | 0 > boot cd:,\mac_ppc64\boot.img bd cd0 | + | 0 > boot cd:,\mac_ppc64\boot.img bd cd0</nowiki> |
| − | </nowiki> | ||
cd0: is the default CD device on MorphOS and it can be given as a bootdevice argument. The system would most likely boot from the CD even without this argument, because of the previously mentioned boot priorities. | cd0: is the default CD device on MorphOS and it can be given as a bootdevice argument. The system would most likely boot from the CD even without this argument, because of the previously mentioned boot priorities. | ||
| Line 315: | Line 306: | ||
On a G4 Mac you could also use the ''blessed'' directory as a shortcut: | On a G4 Mac you could also use the ''blessed'' directory as a shortcut: | ||
0 > boot cd:,\\boot.img bm | 0 > boot cd:,\\boot.img bm | ||
| − | |||
==== Booting MorphOS ISO from USB ==== | ==== Booting MorphOS ISO from USB ==== | ||
| − | The [http://www.morphos.de/guide/usb-boot Official MorphOS USB Boot & Installation / Update Guide] describes the basics of | + | The [http://www.morphos.de/guide/usb-boot Official MorphOS USB Boot & Installation / Update Guide] describes the basics of USB booting, but let's cover a few special cases here. If you can't access your FAT formatted USB stick, refer to the official guide on how to re-format it in a compatible way. Some Macs can be more picky about the format than others, and the same stick, that works in G4 Macs, might not work in a G5 Mac, etc., but it usually helps if you format it as advised in the official guide. If you still have issues with USB stick detection in OF or can't format the stick properly, this section of the tutorial provides some alternative methods to get a system booted. |
| − | The following examples assume that you have a '''correct boot image file''' (named as ''boot.img'' here) and a '''MorphOS ISO image file''' (named as ''morphos.iso'' here, remember that official MorphOS downloads have different names!) on a '''FAT formatted USB stick''', which is plugged in before | + | The following examples assume that you have a '''correct boot image file''' (named as ''boot.img'' here) and a '''MorphOS ISO image file''' (named as ''morphos.iso'' here, remember that official MorphOS downloads have different names!) on a '''FAT formatted USB stick''', which is plugged in before starting the OF user interface. The boot.img file can be obtained from a MorphOS installation CD/ISO, but remember that G4 and G5 Macs are stored in different directories (mac_ppc32 vs mac_ppc64). The files may be named differently too, there's no problem if you want to keep different versions around and boot whichever you want. You could have ''boot310.img'' and ''morphos310.iso'' as a bootable backup, for instance. |
So, the basic idea is to boot the system from an ISO image without burning it or extracting files from it. This can be achieved by giving the ISO image location to the boot image with the ''bootimage'' argument. | So, the basic idea is to boot the system from an ISO image without burning it or extracting files from it. This can be achieved by giving the ISO image location to the boot image with the ''bootimage'' argument. | ||
| Line 328: | Line 318: | ||
MorphOS itself creates a ''umsd0:'' device for the USB mass storage device and our ISO file is found from this device when the boot.img has been loaded. | MorphOS itself creates a ''umsd0:'' device for the USB mass storage device and our ISO file is found from this device when the boot.img has been loaded. | ||
| − | If you have | + | If you have recent enough Open Firmware, booting the ISO file from a USB stick is easy: |
0 > boot ud:,\boot.img bi umsd0:morphos.iso | 0 > boot ud:,\boot.img bi umsd0:morphos.iso | ||
| − | + | ||
If that doesn't work, try to list the contents of the USB stick to find out if it's in a compatible format: | If that doesn't work, try to list the contents of the USB stick to find out if it's in a compatible format: | ||
0 > dir ud:,\ | 0 > dir ud:,\ | ||
| − | If you don't have the ''ud'' alias, you'll have to search usb* aliases for a correct path in the OF tree. List the aliases again or just start trying to list usb0, usb1, etc devices until you find a device containing '''disk''' in its name, and that | + | If you don't have the ''ud'' alias, you'll have to search usb* aliases for a correct path in the OF tree. List the aliases again or just start trying to list usb0, usb1, etc., devices until you find a device containing '''disk''' in its name, and that will reveal the full path to the USB stick, which can be used instead of the ''ud'' alias. |
<nowiki> | <nowiki> | ||
| Line 346: | Line 336: | ||
1501436 07-04-2018 04:03:02 boot.img | 1501436 07-04-2018 04:03:02 boot.img | ||
ok | ok | ||
| − | 0 > boot usb1/disk@1:,\boot.img bi umsd0:morphos.iso | + | 0 > boot usb1/disk@1:,\boot.img bi umsd0:morphos.iso</nowiki> |
| − | </nowiki> | ||
If the stick is connected to a USB hub, the path just gets deeper in the OF tree: | If the stick is connected to a USB hub, the path just gets deeper in the OF tree: | ||
| Line 354: | Line 343: | ||
ff9e1650: /hub@1 | ff9e1650: /hub@1 | ||
ff9e1860: /disk@4 | ff9e1860: /disk@4 | ||
| − | 0 > boot usb1/hub@1/disk@4:,\boot.img bi umsd0:morphos.iso | + | 0 > boot usb1/hub@1/disk@4:,\boot.img bi umsd0:morphos.iso</nowiki> |
| − | </nowiki> | ||
| − | If a USB stick isn't | + | If a USB stick isn't recognised by Open Firmware, but it's accessible from MorphOS itself and you don't want to re-format it, you could copy the boot.img to a Mac partition on the HD, but still load the ISO image from the USB stick. The Mac partition can be an existing OSX installation (HFS+ formatted partition) or previous MorphOS installation (the HFS formatted Boot partition), for instance. The ISO image itself can't be loaded from an HFS partition, because MorphOS kernel (boot.img) doesn't have HFS support built-in. HFS support is loaded from filesystem level at the later stage when you boot MorphOS, but as OF recognises HFS partitions, boot.img can be loaded from them. |
List the contents of the partitions until you find the correct partition where you copied the new boot.img file. | List the contents of the partitions until you find the correct partition where you copied the new boot.img file. | ||
| Line 373: | Line 361: | ||
1501436 07-04-2018 04:03:02 ???? UNIX boot.img | 1501436 07-04-2018 04:03:02 ???? UNIX boot.img | ||
ok | ok | ||
| − | 0 > boot hd:2,\boot.img bi umsd0:morphos.iso | + | 0 > boot hd:2,\boot.img bi umsd0:morphos.iso</nowiki> |
| − | </nowiki> | ||
Latest revision as of 12:12, 1 December 2020
Contents
Preface
Open Firmware (OF) is a computer firmware system, similar to the BIOS on a PC, found in all MorphOS compatible Macs. The Pegasos, Pegasos II, and Efika also have an Open Firmware based hardware implementation, but with small differences to Mac firmware.
Open Firmware uses a Command-Line based user interface, which can be used to control booting and other processes. This tutorial focuses on useful tips and tricks when using the user interface by way of specific examples. The examples were tested on PowerPC Macs, but may also work under bPlan machines to some extent.
Output texts in these examples have been truncated in most cases to show only the information of interest.
Accessing the User Interface
Hold down the Command-Option-O-F key combination on a Mac keyboard, though the Option key is sometimes marked as Alt - with a symbol/icon below it, or press the Win-Alt-O-F key combination on a PC Windows keyboard while booting the machine. Release the keys only after you see the Open Firmware prompt display on a grey background.
Apple PowerBook5,9 4.9.6f0 BootROM built on 10/05/05 at 16:45:50 Copyright 1994-2005 Apple Computer, Inc. All Rights Reserved. Welcome to Open Firmware, the system time and date is: 07/24/2018 21:07:11 To continue booting, type "mac-boot" and press return. To shut down, type "shut-down" and press return. Release keys to continue! ok 0 > _
If the machine boots to an installed OS instead of the OF prompt, reboot and try again. It may help to connect the keyboard directly to the machine's USB port, not via a USB hub. The keys don't have to be pressed immediately when powering the machine on, but promptly after hearing the startup sound (if it has not been disabled) or as the machine triggers access to the optical drive.
Open Firmware uses the US keyboard layout, tips for typing using other keyboards can be found within the official MorphOS USB boot guide.
Useful Commands
- mac-boot - Continues booting from the current OF state
- reset-all - Resets the machine to the power-on state and reboots
- shut-down - Shuts down the machine
- load <file> <args> - Loads an OF code file (e.g. ELF binary image like MorphOS boot.img or Forth script) into memory
- go - Runs/boots the loaded file
- boot <file> <args> - Loads an OF code file and boots it
- printenv - Prints environment variable values
- setenv - Sets environment variable values
- devalias - Displays a list of aliases for devices (similar to assigns on MorphOS)
- .properties - Displays a list of properties for the selected device
- ls - Displays contents of the current path in the device tree
- pwd - Displays the current path within the device tree
- dev - Selects a device (using either the alias or absolute/relative device tree path)
- dir - Lists files on a partition
Environment Variables
Use the printenv command to list all environment variable values.
0 > printenv -------------- Partition: common -------- Signature: 0x70 --------------- little-endian? false false real-mode? false false auto-boot? true true skip-netboot? false false use-nvramrc? false false
The first value in the list is the current value and the second value is the default value. It's quite rare that you need to change these values, but it's interesting to learn more about your computer nevertheless.
One common choice is to speed up Startup Manager (the boot menu you see when booting with the option/alt key pressed) by disabling the netboot option. So, let's change that, as an example, and check that we succeeded.
0 > setenv skip-netboot? true 0 > printenv skip-netboot? -------------- Partition: common -------- Signature: 0x70 --------------- skip-netboot? true false
Examining Devices
The dev command selects a device to be examined, and .properties, ls, and dir commands can be used to print information about the selected device. Note that it depends on the device type if these commands will print something. dir only works for devices containing a filesystem, and such like.
Listing Aliases
A special /aliases device contains information about shortcuts (aliases) to different hardware devices. Let's see a few examples of how to show that information.
The device can be selected with the dev command and then the aliases can be listed with the .properties command:
0 > dev /aliases 0 > .properties name aliases pci0 /pci@f0000000 agp /pci@f0000000 pci1 /pci@f2000000 pci2 /pci@f4000000 usb0 /pci@f2000000/@15 usb1 /pci@f2000000/@15,1 usb2 /pci@f2000000/@15,2 hd /pci@f4000000/ata-6@d/disk@0 cd /pci@f4000000/ata-6@d/disk@1 ud /pci@f2000000/usb@15,1/disk@1
The commands can also be input combined, on a single line:
0 > dev /aliases .properties name aliases pci0 /pci@f0000000 agp /pci@f0000000 pci1 /pci@f2000000 pci2 /pci@f4000000 usb0 /pci@f2000000/@15 usb1 /pci@f2000000/@15,1 usb2 /pci@f2000000/@15,2 hd /pci@f4000000/ata-6@d/disk@0 cd /pci@f4000000/ata-6@d/disk@1 ud /pci@f2000000/usb@15,1/disk@1
There's also a shorter devalias command available on most firmware versions, and it does the same as the previous example:
0 > devalias name aliases pci0 /pci@f0000000 agp /pci@f0000000 pci1 /pci@f2000000 pci2 /pci@f4000000 usb0 /pci@f2000000/@15 usb1 /pci@f2000000/@15,1 usb2 /pci@f2000000/@15,2 hd /pci@f4000000/ata-6@d/disk@0 cd /pci@f4000000/ata-6@d/disk@1 ud /pci@f2000000/usb@15,1/disk@1
Other Useful Properties
.properties on the root device shows the computer specs:
0 > dev / .properties
model PowerBook5,9
compatible PowerBook5,9
MacRISC3
Power Macintosh
serial-number SX0
The enet device shows the MAC address of the computer. 00:11:24:e3:66:66 in this case:
0 > dev enet .properties vendor-id 0000106b device-id 0000006b name ethernet device_type network local-mac-address 001124e3 6666
Listing Devices
The ls command lists devices found in the current device in the device tree:
0 > dev usb1 ls ff9e1650 /disk@1 ff9e1a28: /device@2 ff9e1c48: /keyboard@0 ff9e1f88: /mouse@1 ff9e2230: /interface@2
Listing Files
If a device (disk) contains a supported filesystem (HFS(+), FAT, ISO9660), its contents can be listed with the dir command.
Syntax of the dir command is: dir disk:partition,path
- disk is a device path to a disk, aliases can be used here and the delimiter in the device tree is /
- partition is a partition number (starting from 1), the default partition is used if left blank
- path is a path in the filesystem, the directory delimiter is \ and the same character is also used to access the root directory
Listing the root (\) directory from the default partition on the default HD (this is usually the Boot: partition on a MorphOS system). The "," character could be omitted in certain cases, but it's safer to type that as well:
0 > dir hd:,\
Listing the root directory from the first partition on the (default) HD:
0 > dir hd:1,\
Listing the root directory from a CD:
0 > dir cd:,\
Listing a sub-directory from a CD:
0 > dir cd:,\mac_ppc32
Listing the root directory from a USB mass storage device found in the usb1 device (use the previously mentioned ls command to find the correct device):
0 > dir usb1/disk@1:,\
Newer firmware versions create the ud alias for a USB mass storage device connected to the machine (if it's been connected prior to starting the OF interface), so this does the same as the previous example:
0 > dir ud:,\
Adding Custom Devaliases
The devalias command adds temporary user defined devaliases.
0 > devalias dh /pci@f4000000/ata-6@d/disk@0
nvvalias stores a devalias in NVRAMRC. Variable use-nvramrc? needs to be set to true in order to execute NVRAMRC script at startup.
0 > nvalias dh /pci@f4000000/ata-6@d/disk@0
nvunalias deletes an alias.
0 > nvunalias dh
You can replace existing devaliases with your own ones. Removing them will revert to original values.
Booting MorphOS
Basics
To boot into MorphOS, Open Firmware has to load a MorphOS boot image file, which is usually named as boot.img. The boot image contains the MorphOS kernel and core drivers, so it's basically comparable to the Amiga's Kickstart. Open Firmware just loads and boots the file, and the rest is handled by MorphOS itself after that. In case of errors, it's important to distinguish if loading of the boot image failed or does the error occur at a later stage.
The boot.img file usually resides on a special HFS formatted Boot: partition on Macs, or on a partition that has a filesystem known to Open Firmware in any case. The Boot: partition only contains a few Open Firmware related files and isn't used for anything else than to get the kernel loaded by the machine itself. How MorphOS sees the partition isn't important and it can even be unmounted from a MorphOS point of view. MorphOS itself is booted from a partition containing a MorphOS compatible filesystem and MorphOS system files in it, and this partition is usually named as "System:" and the SYS: assign points to it as well.
When booting manually from OF, you'll see some output lines on screen. There are two important lines that tell you the boot stage. This can be demonstrated well with the load and go commands.
Type in this line (if you have a MorphOS installation on your HD):
0 > load hd:,\boot.img
And you'll see output like this:
0 > load hd:,\boot.img load-size=16e8fc adler32=bd628950 Loading ELF ok 0 > _
"Loading ELF" tells you that the file has been found and loaded.
The file can be booted with the go command then:
0 > go DO-QUIESCE finished_
"DO-QUIESCE finished" indicates that the file has been booted and the machine is now running under MorphOS. Problems after that stage are MorphOS related, and if the MorphOS boot image doesn't appear soon, then MorphOS might not have found a device or image to boot from, or there might be driver or compatibility issues. MorphOS reset keys (Ctrl-Lcmd-Rcmd, Fn-alt-alt) also work at this stage even if there are any other problems halting the boot process.
A shorter, and usual, way to boot is to use the boot command, which combines both load and go commands.
The previous example can be achieved with this single line:
0 > boot hd:,\boot.img
And the output should then look like this:
0 > boot hd:,\boot.img load-size=16e8fc adler32=bd628950 Loading ELF DO-QUIESCE finished_
Boot Arguments
Several boot arguments can be given to the boot.img file by adding them to the end of a load or boot line. More detailed explanations of these arguments can be found from Docs/Booting MorphOS.txt and Docs/PegasosFirmware.txt files on your MorphOS system or the installation CD, but let's cover the most useful booting related ones here. Note that Sam460ex/cr and AmigaOne X5000 systems don't use Open Firmware, but the boot arguments can be given on them too by setting an environment variable in their U-boot console.
Without arguments MorphOS boots a device that is bootable and has the highest boot priority set. Note that this only applies to partitions that contain a MorphOS compatible bootable filesystem. If a MorphOS installation CD is inserted, it usually has a higher priority than bootable partitions on the HD. The HDConfig tool can be used to set partitions bootable and alter their boot priorities, but usually it's unnecessary to change these settings.
The syntax for arguments is argument=value, but the equals sign can be replaced with a space character. The arguments can be given in a longer or shorter, in parenthesis () format.
- bootdevice (bd) - Overrides boot priorities and boots from a given partition. The partition name must be given in the form MorphOS sees it as a device name (volume names don't work), and the trailing ":" character can be omitted. For example, "bootdevice=dh1" works, but "bootdevice=System" doesn't.
- bootimage (bi) - Boots the MorphOS system from an ISO image file, which is placed on a partition that is accessible with the built-in filesystems of the boot.img (FAT, SFS, FFS, PFS3, CDFS). A full MorphOS style path must be given to the argument, but use device names instead of volume names again. For example, "bootimage=umsd0:morphos-3.11.iso", "bootimage=dh2:morphos-3.11.iso".
- bootmenu (bm) - Boots into the MorphOS bootmenu where you can change display settings, see information about devices, or boot without startup-sequence. The same bootmenu can be accessed by pressing the shift key during the MorphOS boot process. Pressing the v key in the bootmenu toggles between the default resolution and a 640x480@60Hz VESA mode, and that can be useful in case of display issues. The space toggles between multiple monitors instead.
Examples
Booting from CD
MorphOS documentation's usual advice is to boot the machine with the c key pressed, but that method can sometimes be unreliable for one reason or another, so you might end up in a situation where a boot image has been loaded from a HD and the actual system from a CD, which results in an error if the boot image and the CD aren't from the same MorphOS version. A more reliable way is to boot into the Startup Manager menu on Macs by holding the alt (option) key at boot, and select the CD from that graphical boot menu. Pressing the F12 key in the menu will eject the CD.
As well as the previously mentioned methods, there are other ways to boot a CD from the Open Firmware prompt.
To boot any inserted CD that is bootable on Macs:
0 > boot cd:,\\:tbxi
"\\" will look for a blessed directory on a device (you can list it by dir cd:,\\ or dir hd:,\\, for instance) and :tbxi looks for files of type tbxi (Toolbox image). This does practically the same thing as booting with the c key or booting from the Startup Manager menu, but you also see the output lines from OF (especially the "Loading ELF" & "DO-QUIESCE finished" lines) if you need some debug output.
Another way to boot the MorphOS installation CD from the OF prompt is to locate a correct boot image file from the CD and boot it with some boot arguments.
List the contents of the CD:
0 > dir cd:,\
Volume: MorphOSBoot
Size/ GMT File/Dir
bytes date time TYPE CRTR Name
94 07/04/2018 04:54:42 ???? ???? .morphosid
2287135 07/04/2018 04:03:02 boot UNIX boot.img
1454648 07/04/2018 04:03:02 boot UNIX bootcyrusplus.img
2201986 07/04/2018 04:03:02 boot UNIX bootefika.img
2286039 07/04/2018 04:03:02 boot UNIX bootpeg1.img
1416944 07/04/2018 04:03:02 boot UNIX bootsam_ppc4x0.img
01/01/1904 00:00:00 *mac_ppc32
01/01/1904 00:00:00 mac_ppc64
As you can see, there are several different boot images for different architectures. boot.img is for Pegasos II and others are easy to guess. Boot images for Macs are located in sub-directories, mac_ppc32 contains the boot.img file for G4 Macs and mac_ppc64 for G5 Macs. The blessed directory is marked with an asterisk.
If we wanted to boot the CD on a G5 Mac:
0 > dir cd:,\mac_ppc64
Size/ GMT File/Dir
bytes date time TYPE CRTR Name
1499688 07/04/2018 04:03:02 boot UNIX boot.img
ok
0 > boot cd:,\mac_ppc64\boot.img bd cd0
cd0: is the default CD device on MorphOS and it can be given as a bootdevice argument. The system would most likely boot from the CD even without this argument, because of the previously mentioned boot priorities.
To boot into the MorphOS boot menu on a G5 Mac:
0 > boot cd:,\mac_ppc64\boot.img bm
And the same for a G4 Mac:
0 > boot cd:,\mac_ppc32\boot.img bm
On a G4 Mac you could also use the blessed directory as a shortcut:
0 > boot cd:,\\boot.img bm
Booting MorphOS ISO from USB
The Official MorphOS USB Boot & Installation / Update Guide describes the basics of USB booting, but let's cover a few special cases here. If you can't access your FAT formatted USB stick, refer to the official guide on how to re-format it in a compatible way. Some Macs can be more picky about the format than others, and the same stick, that works in G4 Macs, might not work in a G5 Mac, etc., but it usually helps if you format it as advised in the official guide. If you still have issues with USB stick detection in OF or can't format the stick properly, this section of the tutorial provides some alternative methods to get a system booted.
The following examples assume that you have a correct boot image file (named as boot.img here) and a MorphOS ISO image file (named as morphos.iso here, remember that official MorphOS downloads have different names!) on a FAT formatted USB stick, which is plugged in before starting the OF user interface. The boot.img file can be obtained from a MorphOS installation CD/ISO, but remember that G4 and G5 Macs are stored in different directories (mac_ppc32 vs mac_ppc64). The files may be named differently too, there's no problem if you want to keep different versions around and boot whichever you want. You could have boot310.img and morphos310.iso as a bootable backup, for instance.
So, the basic idea is to boot the system from an ISO image without burning it or extracting files from it. This can be achieved by giving the ISO image location to the boot image with the bootimage argument.
Some firmware versions create a ud alias, which points to a USB mass storage device connected to the computer. List the aliases to find out if it's been created.
MorphOS itself creates a umsd0: device for the USB mass storage device and our ISO file is found from this device when the boot.img has been loaded.
If you have recent enough Open Firmware, booting the ISO file from a USB stick is easy:
0 > boot ud:,\boot.img bi umsd0:morphos.iso
If that doesn't work, try to list the contents of the USB stick to find out if it's in a compatible format:
0 > dir ud:,\
If you don't have the ud alias, you'll have to search usb* aliases for a correct path in the OF tree. List the aliases again or just start trying to list usb0, usb1, etc., devices until you find a device containing disk in its name, and that will reveal the full path to the USB stick, which can be used instead of the ud alias.
0 > dev usb0 ls ok 0 > dev usb1 ls ff9e1650: /disk@1 0 > dir usb1/disk@1:,\ Volume: USB 258048000 07-24-2018 18:34:24 morphos.iso 1501436 07-04-2018 04:03:02 boot.img ok 0 > boot usb1/disk@1:,\boot.img bi umsd0:morphos.iso
If the stick is connected to a USB hub, the path just gets deeper in the OF tree:
0 > dev usb1 ls ff9e1650: /hub@1 ff9e1860: /disk@4 0 > boot usb1/hub@1/disk@4:,\boot.img bi umsd0:morphos.iso
If a USB stick isn't recognised by Open Firmware, but it's accessible from MorphOS itself and you don't want to re-format it, you could copy the boot.img to a Mac partition on the HD, but still load the ISO image from the USB stick. The Mac partition can be an existing OSX installation (HFS+ formatted partition) or previous MorphOS installation (the HFS formatted Boot partition), for instance. The ISO image itself can't be loaded from an HFS partition, because MorphOS kernel (boot.img) doesn't have HFS support built-in. HFS support is loaded from filesystem level at the later stage when you boot MorphOS, but as OF recognises HFS partitions, boot.img can be loaded from them.
List the contents of the partitions until you find the correct partition where you copied the new boot.img file.
0 > dir hd:1,\
MAC-PARTS: specified MAC partition is not valid can't OPEN the DIR device
ok
0 > dir hd:2,\
Volume: OSX
Size/ GMT File/Dir
bytes date time TYPE CRTR Name
07/22/2017 07:27:40 Applications
09/27/2016 09:59:40 bin
1501436 07-04-2018 04:03:02 ???? UNIX boot.img
ok
0 > boot hd:2,\boot.img bi umsd0:morphos.iso