1.\" $NetBSD: ofwboot.8,v 1.18 2024/06/09 05:42:59 tsutsui Exp $ 2.\" 3.\" Copyright (c) 2001 The NetBSD Foundation, Inc. 4.\" All rights reserved. 5.\" 6.\" This code is derived from software contributed to The NetBSD Foundation 7.\" by Makoto Fujiwara, Thomas Klausner, and Michael Wolfson. 8.\" 9.\" Redistribution and use in source and binary forms, with or without 10.\" modification, are permitted provided that the following conditions 11.\" are met: 12.\" 1. Redistributions of source code must retain the above copyright 13.\" notice, this list of conditions and the following disclaimer. 14.\" 2. Redistributions in binary form must reproduce the above copyright 15.\" notice, this list of conditions and the following disclaimer in the 16.\" documentation and/or other materials provided with the distribution. 17.\" 18.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS 19.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED 20.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 21.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS 22.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 23.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 24.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 25.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 26.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 27.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 28.\" POSSIBILITY OF SUCH DAMAGE. 29.\" 30.Dd June 9, 2024 31.Dt OFWBOOT 8 macppc 32.Os 33.Sh NAME 34.Nm ofwboot , 35.Nm ofwboot.elf , 36.Nm ofwboot.xcf 37.Nd Open Firmware boot command 38.Sh SYNOPSIS 39.Nm ofwboot 40.Sh DESCRIPTION 41Open Firmware is a FORTH-like command interpreter started by the BootROM after 42the power-on self test (POST). 43This command interpreter allows the user flexibility in choosing how their 44machine boots an operating system. 45.Nx 46uses Open Firmware to initialize 47many of the devices in a system and uses it to load the primary bootloader, 48.Nm ofwboot . 49.Pp 50The information in this man page should only serve as a guideline for users. 51.Tn Apple 52has made many revisions to Open Firmware, and the earlier versions 53had many problems and inconsistencies. 54You may find that a boot command that works on one model will not work 55on another. 56.Pp 57In this man page, only one Open Firmware command will be described, 58.Ic boot , 59because it is used to pass arguments to 60.Nm ofwboot . 61The Open Firmware 62.Ic boot 63command takes up to three arguments: 64.Bd -literal -offset indent 65.Ic boot Oo Ar boot-device Oo Ar boot-file Oc Oc Op Ar options 66.Ed 67.Pp 68where 69.Pp 70.Bl -tag -width ".Ar boot-device" -offset indent -compact 71.It Ar boot-device 72primary bootloader location 73.It Ar boot-file 74kernel location 75.It Ar options 76flags passed to the kernel (see below) 77.El 78.Ss boot-device 79The first argument, 80.Ar boot-device , 81actually designates the primary bootloader location and its name in the 82form: 83.Bd -literal -offset indent 84.Sm off 85.Ar device Ic \&: Oo Ar partition-num Oc Op \&, \e Ar bootloader-filename 86.Sm on 87.Ed 88.Pp 89A typical example, from a PowerBook (FireWire), is 90.Pp 91.Dl /pci@f2000000/mac-io@17/ata-4@1f000/@0:9,\eofwboot.xcf 92.Pp 93Note that colon 94.Pq Ql \&: 95delimits the device to the left, and comma 96.Pq Ql \&, 97separates the bootloader filename from the first part. 98For Open Firmware versions before 3, the primary bootloader is installed 99in partition 100.Dq zero , 101and it is not necessary to specify the 102.Ar bootloader-filename . 103For Open Firmware version 3, you must specify the bootloader filename. 104.Pp 105Open Firmware stores aliases to common devices in 106.Tn NVRAM . 107In the example the above, 108.Pa /pci@f2000000/mac-io@17/ata-4@1f000/@0 109is the path on a PowerBook 110(FireWire) to the built-in 111.Tn ATA Ns /100 112hard drive. 113Use the 114.Ic devalias 115command in Open Firmware to print out a list of common device names on a 116particular model. 117The 118.Ar boot-device 119above could then be simplified to: 120.Pp 121.Dl hd:9,\eofwboot.xcf 122.Pp 123.Ar bootloader-filename 124is usually 125.Nm ofwboot.xcf . 126See also the 127.Sx FILES 128section for further discussion. 129.Pp 130If 131.Ar boot-device 132is omitted from the 133.Ic boot 134command, the Open Firmware variable 135.Ev boot-device 136is used. 137.Ss boot-file 138It may be necessary to specify the 139.Ar boot-file 140if Open Firmware does not know where to find the kernel. 141The default is to load the file named 142.Pa netbsd 143on partition 144.Dq Pa a 145from the device used to load the primary bootloader. 146.Pp 147For systems with 148Open Firmware versions less than 3 which are set up using 149.Ic sysinst , 150the 151.Ar boot-file 152argument is not necessary. 153Systems with Open Firmware version 3 may need to specify the 154.Ar boot-file . 155.Pp 156The syntax is similar to the 157.Ar boot-device 158argument: 159.Bd -literal -offset indent 160.Sm off 161.Oo Ar boot-file-device Ic \&: Ar partition-num\^ Ic \&/ Oc Op Ar kernel-name 162.Sm on 163.Ed 164.Pp 165This is a little different, since a kernel-name may be specified without 166listing a 167.Ar boot-file-device 168and 169.Ar partition-num . 170Additionally, a 171.Ar boot-file-device 172and 173.Ar partition-num 174may need to be specified, while using the default 175.Ar kernel-name . 176.Pp 177If no 178.Ar kernel-name 179is specified, the primary bootloader will try to find kernels named either 180.Pa netbsd 181or 182.Pa netbsd.gz 183on the boot-device or (if specified) boot-file-device. 184.Ss options 185Possible options are: 186.Bl -tag -width Fl 187.It Fl a 188ask for the boot device 189.It Fl s 190single-user mode boot 191.It Fl d 192debug mode 193.It Cm exit 194exit to Open Firmware after processing arguments 195.El 196.Sh ENVIRONMENT 197If set, the following Open Firmware variables will be used to determine which 198.Ar boot-device 199and 200.Ar boot-file 201Open Firmware should use when booting a system. 202If the user specifies arguments on the command line, these values 203are overridden. 204.Bl -tag -width Ev 205.It Ev boot-device 206used as the first argument 207.It Ev boot-file 208used as the second argument 209.It Ev auto-boot? 210setting this variable to 211.Ic false 212will present the user with an Open Firmware command prompt after power-on 213reset. 214A value of 215.Ic true 216will automatically boot the system using the variables 217.Ev boot-device 218and 219.Ev boot-file . 220(This is not really related to the boot command, but is included for 221completeness.) 222.El 223.Pp 224To restore these variables to their default values, use the 225.Ic set-default 226Open Firmware command: 227.Pp 228.Dl set-default boot-device 229.Sh FILES 230The three files 231.Nm ofwboot , 232.Nm ofwboot.elf , 233and 234.Nm ofwboot.xcf 235are the same program, in different executable formats. 236.Bl -tag -width ".Pa ofwboot.xcf" 237. 238.It Pa ofwboot 239.Nm 240is installed via 241.Xr installboot 8 242on systems with Open Firmware versions less than 3. 243It is not necessary to specify this file name on the Open Firmware 244.Ic boot 245command, as it is stored in a special location in the 246.Nx 247partition that is marked 248.Dq bootable 249in the Apple partition map entry. 250The bootable partition can be specified as partition 251.Dq zero . 252For example, the following command might be used to boot from a SCSI device 253with ID 2: 254.Ic "0 >boot scsi-int/sd@2:0" . 255. 256.It Pa ofwboot.xcf 257.Nm ofwboot.xcf 258is in XCOFF format. 259This file is used on all Open Firmware 3 systems, and on Open Firmware 260systems prior to 3 when the bootloader is not installed in partition 261.Dq zero , 262such as from an ISO-9660 format CD-ROM. 263. 264.It Pa ofwboot.elf 265.Nm ofwboot.elf 266is in 267.Xr elf 5 268format and only functions on systems with Open Firmware version 3. 269To avoid confusion, all users should be using 270.Nm ofwboot.xcf , 271as 272.Nm ofwboot.elf 273offers no additional functionality. 274It is only included for historical reasons. 275. 276.It Pa boot.fs 277This 1.44 MB disk image contains everything necessary to boot and install 278.Nx . 279It includes the partition 280.Dq zero 281bootloader 282.Nm ( ofwboot ) , 283an INSTALL kernel (with limited device drivers), and the 284.Ic sysinst 285utility in a RAM disk. 286Since Open Firmware does not care what media 287files are loaded from, only whether they are supported and in the correct 288format, this disk image may be placed on media other than floppy disks, such 289as hard drives or Zip disks. 290Use 291.Xr dd 1 292on Unix, or 293.Ic DiskCopy 294on MacOS 9.1 or later, or 295.Ic suntar 296on any MacOS version to copy this image onto the media. 297. 298.It Pa netbsd 299production kernel, using the GENERIC set of devices which supports almost all 300hardware available for this platform. 301. 302.It Pa netbsd_GENERIC_MD.gz 303GENERIC kernel (the same as 304.Ar netbsd ) , 305with RAM disk and 306.Ic sysinst 307included. 308. 309.It Pa NetBSD-{RELEASE}-macppc.iso 310bootable CD-ROM image for all supported systems. 311Usually located at 312.Pa https://cdn.NetBSD.org/pub/NetBSD/images/{RELEASE}/ 313.El 314.Sh EXAMPLES 315.Pp 316In the following examples 317.Ql "0\~>\~" 318is the Open Firmware prompt. 319.Bl -item 320. 321.It 322Boot the default installation into single user mode. 323.Dl 0 > boot -s 324. 325.It 326Boot an Open Firmware 3 system, with 327.Ar netbsd 328installed on partition 329.Dq Pa a : 330.Dl 0 > boot hd:,\eofwboot.xcf 331. 332.It 333Boot the kernel named 334.Pa netbsd.new 335from partition 336.Dq Pa a 337of the hard disk into 338.Xr ddb 4 339using 340.Tn ELF 341version of 342.Nm 343from the USB flash drive: 344.Dl 0 > boot usb0/disk:,\eofwboot.elf hd/netbsd.new -d 345or 346.Dl 0 > boot usb1/disk:,\eofwboot.elf hd/netbsd.new -d 347Note: You can check which usb device name should be used by 348.Dq Ic devalias 349and 350.Dq Ic dev usb0 ls 351commands etc. 352. 353.It 354Boot from bootable CD-ROM of 355.Nx 356release with Open Firmware 3 or higher: 357.Dl 0 > boot cd:,\eofwboot.xcf 358. 359.It 360Boot from bootable CD-ROM (internal SCSI, id=3) of 361.Nx 362release with Open Firmware versions prior to 3: 363.Dl 0 > boot scsi/sd@3:0 364. 365.It 366Boot from a USB flash drive containing a bootable CD-ROM ISO image of 367.Nx 368release with Open Firmware 3 or higher: 369.Dl 0 > boot usb0/disk@1:3,\eofwboot.xcf 370or 371.Dl 0 > boot usb1/disk@1:3,\eofwboot.xcf 372Note: The partition number 373.Dq Pa 3 374is an ISO9660/HFS hybrid partition specified by the Apple partition map 375in the macppc CD ISO image of 376.Nx 377release. 378. 379.It 380Boot from floppy disk: 381.Dl 0 > boot fd:0 382. 383.It 384Boot from network, with bootps, 385.Xr bootptab 5 , 386.Xr tftpd 8 , 387and 388.Xr nfsd 8 389server available: 390.Dl 0 > boot enet:0 391. 392.It 393Boot from network, but use internal root partition of second drive: 394.Dl 0 > boot enet:0 ultra1:0 395. 396.It 397Boot MacOS, looking for the first available bootable disk: 398.Dl 0 > boot hd:,\e\e:tbxi 399. 400.It 401Boot MacOS X residing on partition 10: 402.Dl 0 > boot hd:10,\e\e:tbxi 403. 404.El 405.Sh ERRORS 406.Bd -unfilled 407DEFAULT CATCH!, code=FF00300 at %SRR0: FF80AD38 %SRR1: 00001070 408.Ed 409Could be 410.Dq device not found 411or I/O errors on the device. 412The numbers are just for example. 413If the error is caused by I/O errors (especially on CD boot), 414retrying the same command after restarting Open Firmware by 415.Ic reset-all 416command might help. 417.Bd -unfilled 418CLAIM failed 419.Ed 420Open Firmware got errors on memory allocation ops etc. 421This could also happen by buggy Open Firmware implementation, or improper 422.Ev real-base 423variable settings. 424.Bd -unfilled 425Can't LOAD from this device 426.Ed 427Open Firmware found the device, but it is not supported by 428.Ic load . 429.Bd -unfilled 4300 > boot yy:0/netbsd 431RESETing to change Configuration! 432.Ed 433.Ar yy:0 434doesn't exist, so Open Firmware ignores the string and uses the 435default parameters to boot MacOS; the MacOS boot routine then clears 436some of the Open Firmware variables. 437.Bd -unfilled 4380 > boot ata/ata-disk@0:9 specified partition is not bootable 439 ok 440.Ed 441As it says. 442.Bd -unfilled 4430 > boot ata/ata-disk@0:0 444>> NetBSD/macppc OpenFirmware Boot, Revision 1.3 445>> (root@nazuha, Fri Jun 8 22:21:55 JST 2001) 446no active package3337696/ 447.Ed 448and hangs: See the real-base part in the FAQ. 449.Pp 450Note: It is recommended to restart Open Firmware by 451.Ic reset-all 452command if you get these Open Firmware errors, 453to avoid further unexpected random errors. 454.Sh SEE ALSO 455.Xr installboot 8 456.Pp 457.Pa INSTALL.html 458.Pp 459.Lk https://www.NetBSD.org/ports/macppc/faq.html "NetBSD/macppc Frequently Asked Questions" 460.Pp 461.Lk https://www.NetBSD.org/ports/macppc/partitioning.html "NetBSD/macppc Partitioning HOW-TO" 462.Pp 463.Lk https://www.NetBSD.org/ports/macppc/models.html "NetBSD/macppc Model Support" 464.Pp 465.Lk https://www.NetBSD.org/docs/network/netboot/ "Diskless NetBSD HOW-TO" 466.Sh STANDARDS 467.St -ieee1275-94 468.Sh BUGS 469.Nm 470can only boot from devices recognized by Open Firmware. 471.Pp 472Early PowerMacintosh systems (particularly the 7500) seem to have problems 473with netbooting. 474Adding an arp entry at the tftp server with 475.Pp 476.Dl arp -s booting-host-name its-ethernet-address 477.Pp 478may resolve this problem (see 479.Xr arp 8 ) . 480.Pp 481Once boot failed, 482.Bd -literal -offset indent 4830 > boot CLAIM failed 484 ok 485.Ed 486.Pp 487successive boots may not be possible. 488You need to type 489.Ic reset-all 490or power-cycle to re-initialize Open Firmware. 491