Fix incorrect comparision in get_params
[yaboot.git] / man / bootstrap.8
1 .\" Hey Emacs! This file is -*- nroff -*- source.
2 .\" NewWorld section written by Ethan Benson OldWorld section taken
3 .\" from bootstrap(8) from the quik package.
4 .\"
5 .TH BOOTSTRAP 8 "28 April 2001" "GNU/Linux PowerPC" "System Manager's Manual"
6 .SH NAME
7 .B bootstrap
8 \- Disk boot process for PowerMac GNU/Linux
9 .SH DESCRIPTION
10 This man page describes the \fBbootstrap\fR process for both OldWorld and
11 NewWorld PowerMacs.  OldWorld PowerMacs all have a hardware MacOS ROM
12 and the case is beige in color.  NewWorld PowerMacs do not have a hardware
13 MacOS ROM, and are in colored, translucent cases.  All G3s in colored
14 cases are NewWorld, as are all G4s and later.  This man page is
15 divided into three sections, OLDWORLD, NEWWORLD, and IBM.  Please read the
16 section appropriate to your hardware.
17 .SH OLDWORLD
18 The process of booting PowerMac/Linux from a disk starts with Open
19 Firmware loading the boot block from the first bootable partition of
20 the boot disk into memory.  The user specifies which device is to be
21 the boot disk by setting the \fBboot-device\fR environment variable to
22 the Open Firmware name of the boot disk, or by giving it as an
23 explicit argument to the Open Firmware \fBboot\fR command.  OldWorld
24 PowerMacs typically do not require \fBbootstrap\fR partitions like
25 NewWorld PowerMacs do.
26
27 Open Firmware then transfers control to the first-stage bootstrap
28 (\fBfirst.b\fR), located at the beginning of the boot block.  The boot
29 block also contains the list of block numbers for the second-stage
30 bootstrap.  \fBFirst.b\fR reads these blocks into memory, thus loading
31 the second-stage bootstrap.
32
33 The task of the second-stage bootstrap (\fBsecond.b\fR) is to load the
34 Linux kernel into memory and pass it any arguments given by the user.
35 \fBSecond.b\fR can also be used for loading other programs, such as
36 diagnostic programs or other operating systems, as long as they are
37 present as an ELF binary in an ext2 filesystem.
38
39 \fBSecond.b\fR gets two string values from Open Firmware,
40 called \fIbootpath\fR and \fIbootargs\fR.  \fIBootpath\fR is the Open
41 Firmware name of the boot disk (i.e., the device that the first-stage
42 bootstrap was loaded from).  If Open Firmware auto-booted, or if the
43 \fBboot\fR command was given without arguments, then \fIbootpath\fR
44 and \fIbootargs\fR are set to the values of the \fBboot-device\fR and
45 \fBboot-file\fR variables, respectively.  If the \fBboot\fR command
46 was given with arguments, the first argument becomes \fIbootpath\fR
47 and any subsequent arguments are saved in \fIbootargs\fR.
48
49 \fBSecond.b\fR uses the Open Firmware input and output devices for
50 communicating with the user.  By default, the modem port is used for
51 both, but this can be changed by setting the Open Firmware
52 \fBinput-device\fR and \fBoutput-device\fR variables.
53
54 \fBSecond.b\fR starts by printing a message to indicate
55 that it has started, and then reads the configuration file.  By
56 default, the configuration file is \fB/etc/quik.conf\fR(5) on the same
57 partition as the boot block, but this can be overridden with \fBquik\fR(8).
58 The configuration file must be on the same disk as the boot block.
59 The format of the configuration file is described in \fBquik.conf\fR(5).
60
61 Then \fBsecond.b\fR prints its \fBboot:\fR prompt and waits for the
62 user to type a command line.  Normally the configuration file
63 specifies a timeout, and if the user does not type anything within
64 that period of time, \fBsecond.b\fR proceeds using the \fIbootargs\fR
65 value as the command line.  If the timeout value is 0, \fBsecond.b\fR
66 will always use the \fIbootargs\fR value, ignoring anything the user
67 types.  This can be useful when a modem is connected to the
68 modem port.
69
70 Having obtained a command line, \fBsecond.b\fR takes the first word
71 (whitespace-separated) as the name of the program to load.  Any
72 remaining words on the line become arguments to be passed to the
73 program when it is loaded.  If the command line is empty,
74 \fBsecond.b\fR uses the value of the \fBdefault\fR keyword in the
75 configuration file, or failing that, the first program specified in
76 the configuration file.
77
78 The configuration file can specify several alternative programs to
79 load (referred to as \fIimages\fR in the configuration file syntax),
80 along with shorthand labels for them and extra arguments to be
81 prepended to those specified by the user.  The program name given in
82 the command line can be either an explicit path name or a shorthand
83 label.  If it is a shorthand label, the configuration file gives the
84 corresponding path name.
85
86 Path names are of the form
87
88 .RS
89 .RI [ device\fB: ][ partno ]\fB/ filepath
90 .RE
91
92 where \fIdevice\fR is the Open Firmware name of the disk, \fIpartno\fR
93 is the (decimal) number of the partition on that disk, and
94 \fIfilepath\fR is the path to the file in the ext2 filesystem on that
95 partition.  The default for \fIdevice\fR is \fIbootpath\fR, and the
96 default for \fIpartno\fR is the first bootable partition on
97 \fIdevice\fR.  Alternatively, the \fB/\fIfilepath\fR section can be
98 replaced by a span of 512-byte blocks to load using the syntax
99 .BI [ start - end ]
100 where \fIstart\fR and \fIend\fR are decimal block numbers.
101
102 \fBSecond.b\fR will attempt to open the file identified by the path
103 name and load it into memory as an ELF binary.  If the file cannot be
104 found, or if it is not an ELF binary, \fBsecond.b\fR will print an
105 error message and print its \fBboot:\fR prompt again.  In this case
106 there is no timeout and \fBsecond.b\fR does not use the \fIbootargs\fR
107 value.
108
109 Once \fBsecond.b\fR has loaded the program into memory, it transfers
110 control to it, passing it the list of arguments.
111 .SH NEWWORLD
112 The process of booting so called NewWorld PowerMacs from disk starts
113 with OpenFirmware first attempting to execute the file specified in
114 the \fIboot-device\fR variable.  Unlike older versions of OpenFirmware
115 the NewWorld version will not attempt to read a boot sector.  By
116 default OpenFirmware attempts to load a file with HFS file type
117 \*(lqtbxi\*(rq in the \*(lqblessed\*(rq directory from each partition
118 of each disk OpenFirmware is aware of, the first partition/disk that
119 is found to be bootable is booted immediately.
120
121 .BR Ybin (8)
122 configures a \fBbootstrap\fR partition to pass all of OpenFirmware's
123 tests to determine if the partition is considered to be bootable or
124 not.  The boot script is given file type \*(lqtbxi\*(rq and the root
125 directory is marked as \*(lqblessed\*(rq, the blessing is important
126 because OpenFirmware will immediately consider a partition unbootable
127 if no directory is marked as blessed (you can still manually execute a
128 loader such as \fByaboot\fR(8) with OpenFirmware even without a blessed
129 directory but it will not happen automatically).
130
131 The MacOS System Folder is always marked as blessed, this is required
132 for MacOS as well as OpenFirmware.  The MacOS System Folder also
133 contains its own boot loader which has the tbxi file type, this makes
134 installing \fByaboot\fR(8) onto a MacOS partition is difficult.  The only way
135 to install \fByaboot\fR(8) on a MacOS boot partition is to modify
136 OpenFirmware to boot the CHRP script directly.  Given this it is
137 highly recommended that you create a dedicated \fBbootstrap\fR
138 partition for \fByaboot\fR(8).
139
140 Since OpenFirmware boots the first partition it finds to be bootable
141 it is important that the \fBbootstrap\fR partition be first on the
142 disk before any MacOS partition, otherwise MacOS will be booted
143 instead of a dual boot menu used with \fByaboot\fR(8).
144
145 The \fBbootstrap\fR partition should also NOT be mountable by MacOS,
146 the reason is MacOS will (almost always) closely inspect any blessed
147 directories to make sure its real MacOS, if it is not satisfied that
148 the contents are a real copy of MacOS it will unbless the directory,
149 resulting in OpenFirmware no longer considering it bootable.  The best
150 way to protect against this is to create the \fBbootstrap\fR partition
151 with the partition type \*(lqApple_Bootstrap\*(rq which OpenFirmware
152 accepts as a valid HFS partition, but MacOS will ignore and refuse to
153 mount.  The \fBbootstrap\fR partition need not be any larger then
154 800K.  800K is the minimum size of an HFS filesystem, and is much more
155 then enough for this purpose.  You need not, and should not keep
156 kernels on this partition, \fByaboot\fR(8) will load them from your
157 ext2fs root partition just fine, as well as from any HFS or HFS+
158 partitions (\fByaboot\fR(8) uses OpenFirmware's HFS+ filesystem support).
159
160 To create the \fBbootstrap\fR partition, use GNU \fBparted\fR(8) or
161 \fBmac-fdisk\fR(8) to create a partiton of type \*(lqApple_Bootstrap\*(rq.
162 This is documented better in \fBmac-fdisks-basics\fR
163 (http://penguinppc.org/usr/ybin/doc/mac-fdisk-basics.shtml).
164
165 The \fBbootstrap\fR need not and should not be mounted anywhere on
166 your filesystem, especially not on top of /boot.  \fBYaboot\fR(8) is
167 able to load the kernels from the ext2fs root partition so that is
168 where they should be kept.
169
170 OpenFirmware maintains a hierarchy of all the hardware it is aware of.
171 To access or specify a boot device you must use the OpenFirmware path.
172 For example: the path to a SCSI hard disk partition might look like
173 this: /pci@80000000/pci-bridge@d/ADPT,2930CU@2/@2:2 . The first part,
174 pci@80000000, shows that the target device is accessed through the PCI
175 bus.  The next part is the PCI bridge, the next is the name of the SCSI host
176 adapter installed (this name is provided by a BootROM on the card
177 itself), and after that is the SCSI ID number.  The colon delimits the
178 device from partition specification, so the last 2 means the second
179 partition of this device.  After the partition number we can specify
180 pathnames to files in two ways: lazy and absolute. The \*(lq,\*(rq delimits
181 the OpenFirmware path from the location of the bootfile.  \*(lq,\e\e:tbxi\*(rq
182 specifies the file that has a HFS file type of
183 \*(lqtbxi\*(rq in the blessed directory.  If there is not blessed
184 directory this will fail.  The second is to specify a absolute
185 pathname to an arbitrary file on the disk, example: 2:,yaboot would
186 load the file named \*(lqyaboot\*(rq in the root directory of the
187 filesystem.  It is possible to load files in subdirectories but
188 OpenFirmware does not always do this reliably, and any special
189 characters such as an embedded space must be expressed like %20 (for a
190 space) the directory separator used by OpenFirmware is the backslash
191 \e.  Example: 2:,\eboot\eyaboot. Determining the OpenFirmware path to
192 a given device is unfortunately not a trivial task.  If you are using
193 the built in ATA hard disk you can use the alias \*(lqhd:\*(rq.
194
195 \fBYbin\fR also includes a utility \fBofpath\fR(8) which can in most
196 cases find the OpenFirmware device path from a unix device node (ie
197 /dev/hda2).
198
199 In addition to binary executables OpenFirmware can also execute a CHRP
200 script.  This is somewhat similar to a shell script.  A CHRP script is
201 useful to create simple boot menus, among other things.  CHRP scripts
202 are divided into sections in a way similar to HTML.  Here is a basic
203 example of a CHRP script used as a wrapper to \fByaboot\fR(8) (since
204 OpenFirmware will only load a file with type \*(lqtbxi\*(rq if it is a
205 CHRP script).
206 .IP
207 .nf
208 <CHRP-BOOT>
209 <COMPATIBLE>
210 MacRISC
211 </COMPATIBLE>
212 <DESCRIPTION>
213 GNU/Linux PowerPC bootloader
214 </DESCRIPTION>
215 <BOOT-SCRIPT>
216 boot hd:,\\\\yaboot
217 </BOOT-SCRIPT>
218 </CHRP-BOOT>
219 .fi
220 .P
221 The \fICOMPATIBLE\fR section defines what machines this script is
222 compatible with, if the machine name encoded into the ROM does not
223 match one of these entries OpenFirmware will print out a lot of
224 incomprehensible junk and fail to load the script.  The
225 \fIDESCRIPTION\fR is ignored by OpenFirmware as far as I know.  The
226 \fIBOOT-SCRIPT\fR section is where arbitrary OpenFirmware Forth
227 commands may go.  They are executed the same way as you would enter
228 them on the OpenFirmware command line.  The entire script is wrapped
229 with the \fICHRP-BOOT\fR tags so that such a script may be attached as
230 a header to a binary file.  Much more complicated and elaborate CHRP
231 scripts are possible but that is beyond the scope of this document.
232
233 \fBYbin\fR as of version 0.17 includes a more robust script that is
234 automatically configured with the correct OpenFirmware paths based on
235 /etc/yaboot.conf.  This new script need not and should not be edited
236 by the user.
237
238 If you have G4 hardware then your OpenFirmware may already have a
239 graphical boot selector built in. This selector can be accessed by
240 holding down the option key when booting the machine.  You should see
241 a screen with buttons for each bootable partition.  The current
242 version (as of \fBybin\fR(8) 0.13) of ofboot includes a badge icon,
243 the button with a penguin icon is your \fBbootstrap\fR partition.  If
244 you decide to use this built in selector you really do not need to use
245 a CHRP script that provides a boot menu. Thanks to Nicholas Humfrey
246 for creating the Badge icon.
247 .SH IBM
248 IBM hardware such as the RS/6000 require msdos style partition tables.
249 In order to boot from the disk they require a type 0x41 PReP Boot
250 \fBbootstrap\fR partition large enough to hold the bootloader
251 (typically \fByaboot\fR(8)).  The bootloader is copied onto the raw
252 partition as there is no filesystem.  This is done either with \fBdd\fR(1)
253 or \fBmkofboot\fR(8).
254 .SH BUGS
255 OpenFirmware
256 .SH AUTHORS
257 \fBybin\fR, and the NEWWORLD, and IBM sections of this man page
258 written by Ethan Benson <erbenson@alaska.net>
259 .P
260 The OLDWORLD section of this man page was taken from the \fBquik\fR(8)
261 package, which was written by Paul Mackerras.
262 .P
263 .B yaboot
264 was written by Benjamin Herrenschmidt <benh@kernel.crashing.org>.
265 .SH SEE ALSO
266 .BR dd (1),
267 .BR mkofboot (8),
268 .BR ofpath (8),
269 .BR quik (8),
270 .BR quik.conf (5),
271 .BR yaboot (8),
272 .BR ybin (8).