Subject: ofwboot man page 2nd draft
To: None <port-macppc@netbsd.org>
From: Henry B. Hotz <hotz@jpl.nasa.gov>
List: port-macppc
Date: 11/03/2000 17:56:24
Please note that I have still said more than I know in a few places.

I don't think bootpath and bootargs are supported in OF 1.0.5 so I 
don't understand where they might come from.  Can anyone comment?

I have incorporated most of MW's comments, and some of Bob Nestor's.

---------------------------

NAME
	ofwboot

SYNOPSIS
	boot {promdev[@addr][:part],}ofwboot.xcf exit
	boot {promdev[@addr][:part],}ofwboot.xcf -{a|s|d}[a|s|d...]
	boot {promdev[@addr][:part],}ofwboot.xcf
		[[promdev[{:|,}partition]]/]filename[ a|s|d...]

DESCRIPTION
	ofwboot is the primary boot loader for the Macintosh PowerPC 
port of NetBSD.  It depends on Open Firmware for it's I/O to read the 
NetBSD kernel.  If promdev is a SCSI disk then addr is the SCSI id. 
If the command line options are missing or invalid it will read Open 
Firmware environment variables to get its options as described under 
ENVIRONMENT.  If it still can't load a file then the -a option is 
forced.

	The options are:
	-a	Print ``Boot:'' and read input, which overrides and 
has the same syntax as the other options.

	-s	Boot only to single-user mode.

	-d	Use kdb.

	exit	Quit back to Open Firmware.

	In addition a filename can be given followed by the above 
option letters without the `-' flag.  It can be a full path for some 
versions of Open Firmware on some filesystem types.  It can be 
preceded by an Open Firmware device path including unit number.  The 
partition number will be deleted on Open Firmware versions 1 and 2, 
and will be forced to zero on Open Firmware 3 or greater.

	The specific devices which can be specified for promdev vary 
according to machine configuration.  A complete list for a given 
machine can be gotten by typing ``dev / ls'' at the Open Firmware 
command line.  In addition aliases are defined for frequently used 
devices and can be listed with ``devalias''.  Common aliases to use 
for booting include fd, hd, cd, enet, scsi-int, and ide0, but will 
depend on the machine.

ENVIRONMENT
	Open Firmware environment variables can be displayed with 
printenv (no arguments) and set with setenv (same as under csh) from 
the Open Firmware command line.  Booting MacOS or booting with 
cmd-opt-P-R held down resets them to their default values.

	The following variables are relevant:

	auto-boot?	If true Open Firmware will immediately run 
the command in boot-command on startup.  If false Open Firmware will 
stop with a command line prompt.  Note that the -a option may not 
work correctly if set true.

	boot-command	The command to run at startup if auto-boot? 
is true.  Usually just ``boot''.

	boot-device	The default device to load from if not given 
as an argument to ofwboot.  If empty then defaults to the device 
ofwboot was loaded from.

	boot-file	The file to load if not given as an argument 
to ofwboot.  If empty then defaults to ``/netbsd''.

	To boot successfully you may also need to set load-base, 
real-base, nvramrc, and perhaps other variables.  In particular 
load-base should be, but may not be set from the program header.

EXAMPLES
	To load ofwboot from an MS-DOS floppy (on a machine with a 
floppy drive) and then load boot-file from boot-device and boot to 
single-user mode:

	boot fd:1,ofwboot.xcf -s

	To boot ofwboot on a G4 from an appropriate CD-ROM and then 
have it query for different boot arguments:

	boot cd,ofwboot.xcf -a

	To boot from an appropriately configured PowerMac 7500, or 
8500 internal hard disk with SCSI id 0 you need the following 
environment variables set:

	boot-device	scsi-int/sd@0:0
	boot-file				(empty that is)

BUGS
	Apple's implementation of Open Firmware has more bugs than we 
can document here and booting on a PowerMac depends on working around 
all the ones we can find on each version.  Even getting access to the 
Open Firmware command line is difficult on some machines.  There are 
probably bugs in ofwboot too but they're minor in comparison.

SEE ALSO
	intro(9), install(8), the FAQ for the MacPPC port, IEEE 
standard 1275 Open Firmware.

HISTORY
	ofwboot first appeared in the Open Firmware port of NetBSD 
1.3.  It was first released in the MacPPC port of NetBSD 1.4.

Signature held pending an ISO 9000 compliant
signature design and approval process.
h.b.hotz@jpl.nasa.gov, or hbhotz@oxy.edu