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