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