1.\" $NetBSD: ofwboot.8,v 1.5 2003/02/10 13:36:00 grant 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.\" 3. All advertising materials mentioning features or use of this software 18.\" must display the following acknowledgement: 19.\" This product includes software developed by the NetBSD 20.\" Foundation, Inc. and its contributors. 21.\" 4. Neither the name of The NetBSD Foundation nor the names of its 22.\" contributors may be used to endorse or promote products derived 23.\" from this software without specific prior written permission. 24.\" 25.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS 26.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED 27.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 28.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS 29.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 30.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 31.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 32.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 33.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 34.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 35.\" POSSIBILITY OF SUCH DAMAGE. 36.\" 37.Dd August 18, 2001 38.Dt OFWBOOT 8 macppc 39.Os 40.Sh NAME 41.Nm ofwboot , 42.Nm ofwboot.elf , 43.Nm ofwboot.xcf 44.Nd Open Firmware boot command 45.Sh SYNOPSIS 46.Nm ofwboot 47.Sh DESCRIPTION 48Open Firmware is a FORTH-like command interpreter started by the BootROM after 49the power-on self test (POST). 50This command interpreter allows the user flexibility in choosing how their 51machine boots an operating system. 52.Nx 53uses Open Firmware to initialize 54many of the devices in a system and uses it to load the primary bootloader, 55.Nm ofwboot . 56.Pp 57The information in this man page should only serve as a guideline for users. 58.Tn Apple 59has made many revisions to Open Firmware, and the earlier versions 60had many problems and inconsistencies. 61You may find that a boot command that works on one model will not work 62on another. 63.Pp 64In this man page, only one Open Firmware command will be described, 65.Ic boot , 66because it is used to pass arguments to 67.Nm ofwboot . 68The Open Firmware 69.Ic boot 70command takes up to three arguments: 71.Pp 72.Ic boot 73.Op Ar boot-device Op Ar boot-file 74.Op Ar options 75.Bl -tag -width boot-device -compact 76.It Ar boot-device 77primary bootloader location 78.It Ar boot-file 79kernel location 80.It Ar options 81flags passed to the kernel (see below) 82.El 83.Ss boot-device 84The first argument, 85.Ar boot-device , 86actually designates the primary bootloader location and its name in the 87form: 88.Dl boot-device:[partition-num],[bootloader-filename] 89A typical example, from a PowerBook (FireWire), is 90.Dl /pci@f2000000/mac-io@17/ata-4@1f000/@0:9,ofwboot.xcf 91.\" XXX: can't use Dq or Pq with : or , 92Note that colon (`:') delimits the device to the left, and comma (`,') 93separates the boot loader filename from the first part. 94For Open Firmware versions before 3, the primary bootloader is installed 95in partition 96.Dq zero , 97and it is not necessary to specify the bootloader-filename. 98For Open Firmware version 3, you must specify the bootloader-filename. 99.Pp 100Open Firmware stores aliases to common devices in NVRAM. 101In the example above, 102.Pa /pci@f2000000/mac-io@17/ata-4@1f000/@0 103is the path on a PowerBook 104(FireWire) to the built-in ATA/100 hard drive. 105Use the 106.Ic devalias 107command in Open Firmware to print out a list of common device names on a 108particular model. 109The command above could then be simplified to: 110.Dl hd:9,ofwboot.xcf 111.Pp 112.Ar boot-loader-file-name 113is usually 114.Nm ofwboot.xcf . 115(See also the 116.Sx FILES 117section for further discussion.) 118.Pp 119If omitted, the Open Firmware variable 120.Va boot-device 121is used. 122.Ss boot-file 123It may be necessary to specify the 124.Ar boot-file 125if Open Firmware does not know where to find the kernel. 126The default is to load the file named 127.Nm netbsd 128on partition 129.Pa Dq a 130from the device used to load the primary bootloader. 131.Pp 132For systems with 133Open Firmware versions less than 3 which are set up using 134.Ic sysinst , 135the 136.Ar boot-file 137argument is not necessary. 138Systems with Open Firmware version 3 may need to specify the 139.Ar boot-file . 140.Pp 141The syntax is similar to the 142.Ar boot-device 143argument: 144.Dl [boot-file-device:partition-num/][kernel-name] 145This is a little different, since a kernel-name may be specified without 146listing a boot-file-device and partition-num. 147Additionally, a boot-file-device and partition-num may need to be 148specified, while using the default kernel-name. 149.Pp 150If no kernel-name is specified, the primary bootloader will try to find 151kernels named either 152.Ar netbsd 153or 154.Ar netbsd.gz 155on the boot-device or (if specified) boot-file-device. 156.Ss options 157Possible options are: 158.Bl -tag -width xxxxx -compact 159.It Fl a 160ask for the boot device 161.It Fl s 162single-user mode boot 163.It Fl d 164debug mode 165.It Ar exit 166exit to Open Firmware after processing arguments 167.El 168.Sh ENVIRONMENT 169If set, the following Open Firmware variables will be used to determine which 170.Ar boot-device 171and 172.Ar boot-file 173Open Firmware should use when booting a system. 174If the user specifies arguments on the command line, these values 175are overridden. 176.Bl -tag -width boot-device -compact 177.It Va boot-device 178used as the first argument 179.It Va boot-file 180used as the second argument 181.It Va auto-boot? 182setting this variable to 183.Ar false 184will present the user with an Open Firmware command prompt after power-on 185reset. 186A value of 187.Ar true 188will automatically boot the system using the variables 189.Va boot-device 190and 191.Va boot-file . 192(This is not really related to the boot command, but is included for 193completeness.) 194.El 195To restore these variables to their default values, use the 196.Ic set-default 197Open Firmware command: 198.Ic set-default Ar boot-device 199.Sh FILES 200The three files 201.Nm ofwboot , 202.Nm ofwboot.elf , 203and 204.Nm ofwboot.xcf 205are the same program, in different executable formats. 206.Bl -tag -width ofwboot.xcf 207.It ofwboot 208.Nm 209is installed via 210.Xr installboot 8 211on systems with Open Firmware versions less than 3. 212It is not necessary to specify this file name, as it is stored in a special 213location on the disk, partition 214.Dq zero . 215For example, the following command might be used to boot from a SCSI device 216with ID 2: 217.Ic "0 \*[Gt]boot Ar scsi-int/sd@2:0" . 218.It ofwboot.xcf 219.Nm ofwboot.xcf 220is in XCOFF format. 221This file is used on all Open Firmware 3 systems, and on Open Firmware 222systems prior to 3 when the bootloader is not installed in partition 223.Dq zero , 224such as from an ISO-9660 format CD-ROM. 225.It ofwboot.elf 226.Nm ofwboot.elf 227is in 228.Xr elf 5 229format and only functions on systems with Open Firmware version 3. 230To avoid confusion, all users should be using 231.Nm ofwboot.xcf , 232as 233.Nm ofwboot.elf 234offers no additional functionality. 235It is only included for historical reasons. 236.It boot.fs 237This 1.44 MB disk image contains everything necessary to boot and install 238.Nx . 239It includes the partition 240.Dq zero 241bootloader 242.Nm ( ofwboot ) , 243an INSTALL kernel (with limited device drivers), and the 244.Ic sysinst 245utility in a RAM disk. 246Since Open Firmware does not care what media 247files are loaded from, only whether they are supported and in the correct 248format, this disk image may be placed on media other than floppy disks, such 249as hard drives or Zip disks. 250Use 251.Xr dd 1 252on Unix, or 253.Ic DiskCopy 254on MacOS 9.1 or later, or 255.Ic suntar 256on any MacOS version to copy this image onto the media. 257.It netbsd 258production kernel, using the GENERIC set of devices which supports almost all 259hardware available for this platform. 260.It netbsd_GENERIC_MD.gz 261GENERIC kernel (the same as 262.Ar netbsd ) , 263with RAM disk and 264.Ic sysinst 265included. 266.It macppccd.iso 267bootable CDROM image for all supported systems. 268Usually located at 269.Pa ftp://ftp.netbsd.org/pub/NetBSD/iso/{RELEASE}/macppccd.iso 270.El 271.Sh EXAMPLES 272.Bl -item 273.It 274Boot an Open Firmware 3 system, with 275.Ar netbsd 276installed on partition 277.Pa Dq a : 278.Bd -unfilled 2790 \*[Gt] boot hd:,ofwboot.xcf 280.Ed 281.It 282Boot into single user mode: 283.Bd -unfilled 2840 \*[Gt] boot hd:,ofwboot.xcf netbsd -s 285.Ed 286.It 287Boot from bootable CDROM with Open Firmware 3 or higher: 288.Bd -unfilled 2890 \*[Gt] boot cd:,\eofwboot.xcf netbsd.macppc 290.Ed 291.It 292Boot from bootable CDROM (internal SCSI, id=3) of 293.Nx 1.5 294release with Open Firmware versions prior to 3: 295.Bd -unfilled 2960 \*[Gt] boot scsi/sd@3:0,OFWBOOT.XCF NETBSD.MACPPC 297.Ed 298.It 299Boot from floppy disk: 300.Bd -unfilled 3010 \*[Gt] boot fd:0 302.Ed 303.It 304Boot from network, with bootps, 305.Xr bootptab 5 , 306.Xr tftpd 8 , 307and 308.Xr nfsd 8 309server available: 310.Bd -unfilled 3110 \*[Gt] boot enet:0 312.Ed 313.It 314Boot from network, but use internal root partition of second drive: 315.Bd -unfilled 3160 \*[Gt] boot enet:0 ultra1:0 317.Ed 318.It 319Boot MacOS, looking for the first available bootable disk: 320.Bd -unfilled 3210 \*[Gt] boot hd:,\e\e:tbxi 322.Ed 323.It 324Boot MacOS X residing on partition 10: 325.Bd -unfilled 3260 \*[Gt] boot hd:10,\e\e:tbxi 327.Ed 328.El 329.Sh ERRORS 330.Bd -unfilled 331DEFAULT CATCH!, code=FF00300 at %SRR0: FF80AD38 %SRR1: 00001070 332.Ed 333Could be 334.Dq device not found 335or I/O errors on the device. 336The numbers are just for example. 337.Bd -unfilled 338Can't LOAD from this device 339.Ed 340Open Firmware found the device, but it is not supported by 341.Ic load . 342.Bd -unfilled 3430 \*[Gt] boot yy:0/netbsd 344RESETing to change Configuration! 345.Ed 346.Ar yy:0 347doesn't exist, so Open Firmware ignores the string and uses the 348default parameters to boot MacOS; the MacOS boot routine then clears 349some of the Open Firmware variables. 350.Bd -unfilled 3510 \*[Gt] boot ata/ata-disk@0:9 specified partition is not bootable 352 ok 353.Ed 354As it says. 355.Bd -unfilled 3560 \*[Gt] boot ata/ata-disk@0:0 357\*[Gt]\*[Gt] NetBSD/macppc OpenFirmware Boot, Revision 1.3 358\*[Gt]\*[Gt] (root@nazuha, Fri Jun 8 22:21:55 JST 2001) 359no active package3337696/ 360.Ed 361and hangs: See the real-base part in the FAQ. 362.\" .Bd -unfilled 363.\" 0 > boot yy 364.\" >> NetBSD/macppc OpenFirmware Boot, Revision 1.3 365.\" >> (root@nazuha, Fri Jun 8 22:21:55 JST 2001) 366.\" no active packageopen yy: Device not configured 367.\" open ata/ata-disk@0/yy: Device not configured 368.\" Boot: 369.\" .Ed 370.Sh SEE ALSO 371.Xr installboot 8 372.Pp 373.Pa INSTALL.html 374.br 375.Pa http://www.netbsd.org/Ports/macppc/faq.html 376.br 377.Pa http://www.netbsd.org/Documentation/network/netboot/ 378.Sh STANDARDS 379IEEE 1275 for OpenFirmware 380.Sh BUGS 381.Nm 382can only boot from devices recognized by Open Firmware. 383.Pp 384Early PowerMacintosh systems (particularly the 7500) seem to have problems 385with netbooting. 386Adding an arp entry at the tftp server with 387.Dl arp -s booting-host-name its-ethernet-address 388may resolve this problem (see 389.Xr arp 8 ) . 390.Pp 391.Bd -unfilled 3920 \*[Gt] boot CLAIM failed 393 ok 394.Ed 395Once boot failed, successive boots may not be possible. 396You need to type 397.Ic reset-all 398or power-cycle to initialize Open Firmware. 399