1.\" $NetBSD: ofwboot.8,v 1.9 2008/04/30 13:10:58 martin 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 August 18, 2001 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.Pp 65.Ic boot 66.Op Ar boot-device Op Ar boot-file 67.Op Ar options 68.Bl -tag -width boot-device -compact 69.It Ar boot-device 70primary bootloader location 71.It Ar boot-file 72kernel location 73.It Ar options 74flags passed to the kernel (see below) 75.El 76.Ss boot-device 77The first argument, 78.Ar boot-device , 79actually designates the primary bootloader location and its name in the 80form: 81.Dl boot-device:[partition-num],[bootloader-filename] 82A typical example, from a PowerBook (FireWire), is 83.Dl /pci@f2000000/mac-io@17/ata-4@1f000/@0:9,ofwboot.xcf 84.\" XXX: can't use Dq or Pq with : or , 85Note that colon (`:') delimits the device to the left, and comma (`,') 86separates the boot loader filename from the first part. 87For Open Firmware versions before 3, the primary bootloader is installed 88in partition 89.Dq zero , 90and it is not necessary to specify the bootloader-filename. 91For Open Firmware version 3, you must specify the bootloader-filename. 92.Pp 93Open Firmware stores aliases to common devices in NVRAM. 94In the example above, 95.Pa /pci@f2000000/mac-io@17/ata-4@1f000/@0 96is the path on a PowerBook 97(FireWire) to the built-in ATA/100 hard drive. 98Use the 99.Ic devalias 100command in Open Firmware to print out a list of common device names on a 101particular model. 102The command above could then be simplified to: 103.Dl hd:9,ofwboot.xcf 104.Pp 105.Ar boot-loader-file-name 106is usually 107.Nm ofwboot.xcf . 108(See also the 109.Sx FILES 110section for further discussion.) 111.Pp 112If omitted, the Open Firmware variable 113.Va boot-device 114is used. 115.Ss boot-file 116It may be necessary to specify the 117.Ar boot-file 118if Open Firmware does not know where to find the kernel. 119The default is to load the file named 120.Nm netbsd 121on partition 122.Dq Pa a 123from the device used to load the primary bootloader. 124.Pp 125For systems with 126Open Firmware versions less than 3 which are set up using 127.Ic sysinst , 128the 129.Ar boot-file 130argument is not necessary. 131Systems with Open Firmware version 3 may need to specify the 132.Ar boot-file . 133.Pp 134The syntax is similar to the 135.Ar boot-device 136argument: 137.Dl [boot-file-device:partition-num/][kernel-name] 138This is a little different, since a kernel-name may be specified without 139listing a boot-file-device and partition-num. 140Additionally, a boot-file-device and partition-num may need to be 141specified, while using the default kernel-name. 142.Pp 143If no kernel-name is specified, the primary bootloader will try to find 144kernels named either 145.Ar netbsd 146or 147.Ar netbsd.gz 148on the boot-device or (if specified) boot-file-device. 149.Ss options 150Possible options are: 151.Bl -tag -width xxxxx -compact 152.It Fl a 153ask for the boot device 154.It Fl s 155single-user mode boot 156.It Fl d 157debug mode 158.It Ar exit 159exit to Open Firmware after processing arguments 160.El 161.Sh ENVIRONMENT 162If set, the following Open Firmware variables will be used to determine which 163.Ar boot-device 164and 165.Ar boot-file 166Open Firmware should use when booting a system. 167If the user specifies arguments on the command line, these values 168are overridden. 169.Bl -tag -width boot-device -compact 170.It Va boot-device 171used as the first argument 172.It Va boot-file 173used as the second argument 174.It Va auto-boot? 175setting this variable to 176.Ar false 177will present the user with an Open Firmware command prompt after power-on 178reset. 179A value of 180.Ar true 181will automatically boot the system using the variables 182.Va boot-device 183and 184.Va boot-file . 185(This is not really related to the boot command, but is included for 186completeness.) 187.El 188To restore these variables to their default values, use the 189.Ic set-default 190Open Firmware command: 191.Ic set-default Ar boot-device 192.Sh FILES 193The three files 194.Nm ofwboot , 195.Nm ofwboot.elf , 196and 197.Nm ofwboot.xcf 198are the same program, in different executable formats. 199.Bl -tag -width ofwboot.xcf 200.It ofwboot 201.Nm 202is installed via 203.Xr installboot 8 204on systems with Open Firmware versions less than 3. 205It is not necessary to specify this file name, as it is stored in a special 206location on the disk, partition 207.Dq zero . 208For example, the following command might be used to boot from a SCSI device 209with ID 2: 210.Ic "0 \*[Gt]boot scsi-int/sd@2:0" . 211.It ofwboot.xcf 212.Nm ofwboot.xcf 213is in XCOFF format. 214This file is used on all Open Firmware 3 systems, and on Open Firmware 215systems prior to 3 when the bootloader is not installed in partition 216.Dq zero , 217such as from an ISO-9660 format CD-ROM. 218.It ofwboot.elf 219.Nm ofwboot.elf 220is in 221.Xr elf 5 222format and only functions on systems with Open Firmware version 3. 223To avoid confusion, all users should be using 224.Nm ofwboot.xcf , 225as 226.Nm ofwboot.elf 227offers no additional functionality. 228It is only included for historical reasons. 229.It boot.fs 230This 1.44 MB disk image contains everything necessary to boot and install 231.Nx . 232It includes the partition 233.Dq zero 234bootloader 235.Nm ( ofwboot ) , 236an INSTALL kernel (with limited device drivers), and the 237.Ic sysinst 238utility in a RAM disk. 239Since Open Firmware does not care what media 240files are loaded from, only whether they are supported and in the correct 241format, this disk image may be placed on media other than floppy disks, such 242as hard drives or Zip disks. 243Use 244.Xr dd 1 245on Unix, or 246.Ic DiskCopy 247on MacOS 9.1 or later, or 248.Ic suntar 249on any MacOS version to copy this image onto the media. 250.It netbsd 251production kernel, using the GENERIC set of devices which supports almost all 252hardware available for this platform. 253.It netbsd_GENERIC_MD.gz 254GENERIC kernel (the same as 255.Ar netbsd ) , 256with RAM disk and 257.Ic sysinst 258included. 259.It macppccd.iso 260bootable CDROM image for all supported systems. 261Usually located at 262.Pa ftp://ftp.NetBSD.org/pub/NetBSD/iso/{RELEASE}/macppccd.iso 263.El 264.Sh EXAMPLES 265.Bl -item 266.It 267Boot an Open Firmware 3 system, with 268.Ar netbsd 269installed on partition 270.Dq Pa a : 271.Bd -unfilled 2720 \*[Gt] boot hd:,ofwboot.xcf 273.Ed 274.It 275Boot into single user mode: 276.Bd -unfilled 2770 \*[Gt] boot hd:,ofwboot.xcf netbsd -s 278.Ed 279.It 280Boot from bootable CDROM with Open Firmware 3 or higher: 281.Bd -unfilled 2820 \*[Gt] boot cd:,\eofwboot.xcf netbsd.macppc 283.Ed 284.It 285Boot from bootable CDROM (internal SCSI, id=3) of 286.Nx 1.5 287release with Open Firmware versions prior to 3: 288.Bd -unfilled 2890 \*[Gt] boot scsi/sd@3:0,OFWBOOT.XCF NETBSD.MACPPC 290.Ed 291.It 292Boot from floppy disk: 293.Bd -unfilled 2940 \*[Gt] boot fd:0 295.Ed 296.It 297Boot from network, with bootps, 298.Xr bootptab 5 , 299.Xr tftpd 8 , 300and 301.Xr nfsd 8 302server available: 303.Bd -unfilled 3040 \*[Gt] boot enet:0 305.Ed 306.It 307Boot from network, but use internal root partition of second drive: 308.Bd -unfilled 3090 \*[Gt] boot enet:0 ultra1:0 310.Ed 311.It 312Boot MacOS, looking for the first available bootable disk: 313.Bd -unfilled 3140 \*[Gt] boot hd:,\e\e:tbxi 315.Ed 316.It 317Boot MacOS X residing on partition 10: 318.Bd -unfilled 3190 \*[Gt] boot hd:10,\e\e:tbxi 320.Ed 321.El 322.Sh ERRORS 323.Bd -unfilled 324DEFAULT CATCH!, code=FF00300 at %SRR0: FF80AD38 %SRR1: 00001070 325.Ed 326Could be 327.Dq device not found 328or I/O errors on the device. 329The numbers are just for example. 330.Bd -unfilled 331Can't LOAD from this device 332.Ed 333Open Firmware found the device, but it is not supported by 334.Ic load . 335.Bd -unfilled 3360 \*[Gt] boot yy:0/netbsd 337RESETing to change Configuration! 338.Ed 339.Ar yy:0 340doesn't exist, so Open Firmware ignores the string and uses the 341default parameters to boot MacOS; the MacOS boot routine then clears 342some of the Open Firmware variables. 343.Bd -unfilled 3440 \*[Gt] boot ata/ata-disk@0:9 specified partition is not bootable 345 ok 346.Ed 347As it says. 348.Bd -unfilled 3490 \*[Gt] boot ata/ata-disk@0:0 350\*[Gt]\*[Gt] NetBSD/macppc OpenFirmware Boot, Revision 1.3 351\*[Gt]\*[Gt] (root@nazuha, Fri Jun 8 22:21:55 JST 2001) 352no active package3337696/ 353.Ed 354and hangs: See the real-base part in the FAQ. 355.\" .Bd -unfilled 356.\" 0 > boot yy 357.\" >> NetBSD/macppc OpenFirmware Boot, Revision 1.3 358.\" >> (root@nazuha, Fri Jun 8 22:21:55 JST 2001) 359.\" no active packageopen yy: Device not configured 360.\" open ata/ata-disk@0/yy: Device not configured 361.\" Boot: 362.\" .Ed 363.Sh SEE ALSO 364.Xr installboot 8 365.Pp 366.Pa INSTALL.html 367.br 368.Pa http://www.NetBSD.org/ports/macppc/faq.html 369.br 370.Pa http://www.NetBSD.org/docs/network/netboot/ 371.Sh STANDARDS 372.St -ieee1275-94 373.Sh BUGS 374.Nm 375can only boot from devices recognized by Open Firmware. 376.Pp 377Early PowerMacintosh systems (particularly the 7500) seem to have problems 378with netbooting. 379Adding an arp entry at the tftp server with 380.Dl arp -s booting-host-name its-ethernet-address 381may resolve this problem (see 382.Xr arp 8 ) . 383.Pp 384.Bd -unfilled 3850 \*[Gt] boot CLAIM failed 386 ok 387.Ed 388Once boot failed, successive boots may not be possible. 389You need to type 390.Ic reset-all 391or power-cycle to initialize Open Firmware. 392