Difference between revisions of "Open Firmware"
From MorphOS Library
| Line 149: | Line 149: | ||
ff9e1f88: /mouse@1 | ff9e1f88: /mouse@1 | ||
ff9e2230: /interface@2</nowiki> | ff9e2230: /interface@2</nowiki> | ||
| − | |||
=== Listing Files === | === Listing Files === | ||
Revision as of 15:14, 24 January 2019
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 can add temporary user defined devaliases.
0 > devalias dh /pci@f4000000/ata-6@d/disk@0
nvalias command stores a devalias in nvramrc. To survive a reboot ("reset-all") variable use-nvramrc? needs to be set to true.
0 > nvalias dh /pci@f4000000/ata-6@d/disk@0
"nvunalias" deletes an alias.
0 > nvalias 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.
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