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).