OFWBOOT(8) (macppc)

OFWBOOT(8) | System Manager's Manual (macppc) | OFWBOOT(8)

# NAME

`ofwboot`, `ofwboot.elf`, `ofwboot.xcf` — Open Firmware boot command

# SYNOPSIS

`ofwboot` |

# DESCRIPTION

Open Firmware is a FORTH-like command interpreter started by the BootROM after the power-on self test (POST). This command interpreter allows the user flexibility in choosing how their machine boots an operating system. NetBSD uses Open Firmware to initialize many of the devices in a system and uses it to load the primary bootloader, `ofwboot`.

The information in this man page should only serve as a guideline for users. Apple has made many revisions to Open Firmware, and the earlier versions had many problems and inconsistencies. You may find that a boot command that works on one model will not work on another.

In this man page, only one Open Firmware command will be described, `boot`, because it is used to pass arguments to `ofwboot`. The Open Firmware `boot` command takes up to three arguments:

    boot [boot-device [boot-file]] [options]

where

boot-device
  primary bootloader location
boot-file
  kernel location
options
  flags passed to the kernel (see below)

## boot-device

The first argument, boot-device, actually designates the primary bootloader location and its name in the form:

    device:[partition-num][,\bootloader-filename]

A typical example, from a PowerBook (FireWire), is

`/pci@f2000000/mac-io@17/ata-4@1f000/@0:9,\ofwboot.xcf`

Note that colon (‘`:`’) delimits the device to the left, and comma (‘`,`’) separates the bootloader filename from the first part. For Open Firmware versions before 3, the primary bootloader is installed in partition “zero”, and it is not necessary to specify the bootloader-filename. For Open Firmware version 3, you must specify the bootloader filename.

Open Firmware stores aliases to common devices in NVRAM. In the example the above, /pci@f2000000/mac-io@17/ata-4@1f000/@0 is the path on a PowerBook (FireWire) to the built-in ATA/100 hard drive. Use the `devalias` command in Open Firmware to print out a list of common device names on a particular model. The boot-device above could then be simplified to:

`hd:9,\ofwboot.xcf`

bootloader-filename is usually `ofwboot.xcf`. See also the FILES section for further discussion.

If boot-device is omitted from the `boot` command, the Open Firmware variable `boot-device` is used.

## boot-file

It may be necessary to specify the boot-file if Open Firmware does not know where to find the kernel. The default is to load the file named netbsd on partition “a” from the device used to load the primary bootloader.

For systems with Open Firmware versions less than 3 which are set up using `sysinst`, the boot-file argument is not necessary. Systems with Open Firmware version 3 may need to specify the boot-file.

The syntax is similar to the boot-device argument:

    [boot-file-device:partition-num/][kernel-name]

This is a little different, since a kernel-name may be specified without listing a boot-file-device and partition-num. Additionally, a boot-file-device and partition-num may need to be specified, while using the default kernel-name.

If no kernel-name is specified, the primary bootloader will try to find kernels named either netbsd or netbsd.gz on the boot-device or (if specified) boot-file-device.

## options

Possible options are:

`-a`
  ask for the boot device
`-s`
  single-user mode boot
`-d`
  debug mode
`exit`
  exit to Open Firmware after processing arguments

# ENVIRONMENT

If set, the following Open Firmware variables will be used to determine which boot-device and boot-file Open Firmware should use when booting a system. If the user specifies arguments on the command line, these values are overridden.

`boot-device`
  used as the first argument
`boot-file`
  used as the second argument
`auto-boot?`
  setting this variable to `false` will present the user with an Open Firmware command prompt after power-on reset. A value of `true` will automatically boot the system using the variables `boot-device` and `boot-file`. (This is not really related to the boot command, but is included for completeness.)

To restore these variables to their default values, use the `set-default` Open Firmware command:

`set-default boot-device`

# FILES

The three files `ofwboot`, `ofwboot.elf`, and `ofwboot.xcf` are the same program, in different executable formats.

ofwboot
  `ofwboot` is installed via installboot(8) on systems with Open Firmware versions less than 3. It is not necessary to specify this file name on the Open Firmware `boot` command, as it is stored in a special location in the NetBSD partition that is marked “bootable” in the Apple partition map entry. The bootable partition can be specified as partition “zero”. For example, the following command might be used to boot from a SCSI device with ID 2: `0 >boot scsi-int/sd@2:0`.
ofwboot.xcf
  `ofwboot.xcf` is in XCOFF format. This file is used on all Open Firmware 3 systems, and on Open Firmware systems prior to 3 when the bootloader is not installed in partition “zero”, such as from an ISO-9660 format CD-ROM.
ofwboot.elf
  `ofwboot.elf` is in elf(5) format and only functions on systems with Open Firmware version 3. To avoid confusion, all users should be using `ofwboot.xcf`, as `ofwboot.elf` offers no additional functionality. It is only included for historical reasons.
boot.fs
  This 1.44 MB disk image contains everything necessary to boot and install NetBSD. It includes the partition “zero” bootloader (`ofwboot`), an INSTALL kernel (with limited device drivers), and the `sysinst` utility in a RAM disk. Since Open Firmware does not care what media files are loaded from, only whether they are supported and in the correct format, this disk image may be placed on media other than floppy disks, such as hard drives or Zip disks. Use dd(1) on Unix, or `DiskCopy` on MacOS 9.1 or later, or `suntar` on any MacOS version to copy this image onto the media.
netbsd
  production kernel, using the GENERIC set of devices which supports almost all hardware available for this platform.
netbsd_GENERIC_MD.gz
  GENERIC kernel (the same as netbsd), with RAM disk and `sysinst` included.
NetBSD-{RELEASE}-macppc.iso
  bootable CD-ROM image for all supported systems. Usually located at https://cdn.NetBSD.org/pub/NetBSD/images/{RELEASE}/

# EXAMPLES

In the following examples ‘`0 >` ’ is the Open Firmware prompt.

- Boot the default installation into single user mode.
  `0 > boot -s`
- Boot an Open Firmware 3 system, with netbsd installed on partition “a”:
  `0 > boot hd:,\ofwboot.xcf`
- Boot the kernel named netbsd.new from partition “a” of the hard disk into ddb(4) using ELF version of `ofwboot` from the USB flash drive:
  `0 > boot usb0/disk:,\ofwboot.elf hd/netbsd.new -d`
  or
  `0 > boot usb1/disk:,\ofwboot.elf hd/netbsd.new -d`
  Note: You can check which usb device name should be used by “`devalias`” and “`dev usb0 ls`” commands etc.
- Boot from bootable CD-ROM of NetBSD release with Open Firmware 3 or higher:
  `0 > boot cd:,\ofwboot.xcf`
- Boot from bootable CD-ROM (internal SCSI, id=3) of NetBSD release with Open Firmware versions prior to 3:
  `0 > boot scsi/sd@3:0`
- Boot from a USB flash drive containing a bootable CD-ROM ISO image of NetBSD release with Open Firmware 3 or higher:
  `0 > boot usb0/disk@1:3,\ofwboot.xcf`
  or
  `0 > boot usb1/disk@1:3,\ofwboot.xcf`
  Note: The partition number “3” is an ISO9660/HFS hybrid partition specified by the Apple partition map in the macppc CD ISO image of NetBSD release.
- Boot from floppy disk:
  `0 > boot fd:0`
- Boot from network, with bootps, bootptab(5), tftpd(8), and nfsd(8) server available:
  `0 > boot enet:0`
- Boot from network, but use internal root partition of second drive:
  `0 > boot enet:0 ultra1:0`
- Boot MacOS, looking for the first available bootable disk:
  `0 > boot hd:,\\:tbxi`
- Boot MacOS X residing on partition 10:
  `0 > boot hd:10,\\:tbxi`

# ERRORS

    DEFAULT CATCH!, code=FF00300 at %SRR0: FF80AD38 %SRR1: 00001070

Could be “device not found” or I/O errors on the device. The numbers are just for example. If the error is caused by I/O errors (especially on CD boot), retrying the same command after restarting Open Firmware by `reset-all` command might help.

    CLAIM failed

Open Firmware got errors on memory allocation ops etc. This could also happen by buggy Open Firmware implementation, or improper `real-base` variable settings.

    Can't LOAD from this device

Open Firmware found the device, but it is not supported by `load`.

    0 > boot yy:0/netbsd
    RESETing to change Configuration!

yy:0 doesn't exist, so Open Firmware ignores the string and uses the default parameters to boot MacOS; the MacOS boot routine then clears some of the Open Firmware variables.

    0 > boot ata/ata-disk@0:9 specified partition is not bootable
     ok

As it says.

    0 > boot ata/ata-disk@0:0
    >> NetBSD/macppc OpenFirmware Boot, Revision 1.3
    >> (root@nazuha, Fri Jun  8 22:21:55 JST 2001)
    no active package3337696/

and hangs: See the real-base part in the FAQ.

Note: It is recommended to restart Open Firmware by `reset-all` command if you get these Open Firmware errors, to avoid further unexpected random errors.

# SEE ALSO

installboot(8)

INSTALL.html

NetBSD/macppc Frequently Asked Questions

NetBSD/macppc Partitioning HOW-TO

NetBSD/macppc Model Support

Diskless NetBSD HOW-TO

# STANDARDS

IEEE Std 1275-1994 (“Open Firmware”)

# BUGS

`ofwboot` can only boot from devices recognized by Open Firmware.

Early PowerMacintosh systems (particularly the 7500) seem to have problems with netbooting. Adding an arp entry at the tftp server with

`arp -s booting-host-name its-ethernet-address`

may resolve this problem (see arp(8)).

Once boot failed,

    0 > boot CLAIM failed
     ok

successive boots may not be possible. You need to type `reset-all` or power-cycle to re-initialize Open Firmware.

June 9, 2024 | NetBSD 11.0