Fix the swab* macros.

[yaboot.git] / man / bootstrap.8

.\" Hey Emacs! This file is -*- nroff -*- source.
.\" NewWorld section written by Ethan Benson OldWorld section taken
.\" from bootstrap(8) from the quik package.
.\"
.TH BOOTSTRAP 8 "28 April 2001" "GNU/Linux PowerPC" "System Manager's Manual"
.SH NAME
.B bootstrap
\- Disk boot process for PowerMac GNU/Linux
.SH DESCRIPTION
This man page describes the \fBbootstrap\fR process for both OldWorld and
NewWorld PowerMacs.  OldWorld PowerMacs all have a hardware MacOS ROM
and the case is beige in color.  NewWorld PowerMacs do not have a hardware
MacOS ROM, and are in colored, translucent cases.  All G3s in colored
cases are NewWorld, as are all G4s and later.  This man page is
divided into three sections, OLDWORLD, NEWWORLD, and IBM.  Please read the
section appropriate to your hardware.
.SH OLDWORLD
The process of booting PowerMac/Linux from a disk starts with Open
Firmware loading the boot block from the first bootable partition of
the boot disk into memory.  The user specifies which device is to be
the boot disk by setting the \fBboot-device\fR environment variable to
the Open Firmware name of the boot disk, or by giving it as an
explicit argument to the Open Firmware \fBboot\fR command.  OldWorld
PowerMacs typically do not require \fBbootstrap\fR partitions like
NewWorld PowerMacs do.

Open Firmware then transfers control to the first-stage bootstrap
(\fBfirst.b\fR), located at the beginning of the boot block.  The boot
block also contains the list of block numbers for the second-stage
bootstrap.  \fBFirst.b\fR reads these blocks into memory, thus loading
the second-stage bootstrap.

The task of the second-stage bootstrap (\fBsecond.b\fR) is to load the
Linux kernel into memory and pass it any arguments given by the user.
\fBSecond.b\fR can also be used for loading other programs, such as
diagnostic programs or other operating systems, as long as they are
present as an ELF binary in an ext2 filesystem.

\fBSecond.b\fR gets two string values from Open Firmware,
called \fIbootpath\fR and \fIbootargs\fR.  \fIBootpath\fR is the Open
Firmware name of the boot disk (i.e., the device that the first-stage
bootstrap was loaded from).  If Open Firmware auto-booted, or if the
\fBboot\fR command was given without arguments, then \fIbootpath\fR
and \fIbootargs\fR are set to the values of the \fBboot-device\fR and
\fBboot-file\fR variables, respectively.  If the \fBboot\fR command
was given with arguments, the first argument becomes \fIbootpath\fR
and any subsequent arguments are saved in \fIbootargs\fR.

\fBSecond.b\fR uses the Open Firmware input and output devices for
communicating with the user.  By default, the modem port is used for
both, but this can be changed by setting the Open Firmware
\fBinput-device\fR and \fBoutput-device\fR variables.

\fBSecond.b\fR starts by printing a message to indicate
that it has started, and then reads the configuration file.  By
default, the configuration file is \fB/etc/quik.conf\fR(5) on the same
partition as the boot block, but this can be overridden with \fBquik\fR(8).
The configuration file must be on the same disk as the boot block.
The format of the configuration file is described in \fBquik.conf\fR(5).

Then \fBsecond.b\fR prints its \fBboot:\fR prompt and waits for the
user to type a command line.  Normally the configuration file
specifies a timeout, and if the user does not type anything within
that period of time, \fBsecond.b\fR proceeds using the \fIbootargs\fR
value as the command line.  If the timeout value is 0, \fBsecond.b\fR
will always use the \fIbootargs\fR value, ignoring anything the user
types.  This can be useful when a modem is connected to the
modem port.

Having obtained a command line, \fBsecond.b\fR takes the first word
(whitespace-separated) as the name of the program to load.  Any
remaining words on the line become arguments to be passed to the
program when it is loaded.  If the command line is empty,
\fBsecond.b\fR uses the value of the \fBdefault\fR keyword in the
configuration file, or failing that, the first program specified in
the configuration file.

The configuration file can specify several alternative programs to
load (referred to as \fIimages\fR in the configuration file syntax),
along with shorthand labels for them and extra arguments to be
prepended to those specified by the user.  The program name given in
the command line can be either an explicit path name or a shorthand
label.  If it is a shorthand label, the configuration file gives the
corresponding path name.

Path names are of the form

.RS
.RI [ device\fB: ][ partno ]\fB/ filepath
.RE

where \fIdevice\fR is the Open Firmware name of the disk, \fIpartno\fR
is the (decimal) number of the partition on that disk, and
\fIfilepath\fR is the path to the file in the ext2 filesystem on that
partition.  The default for \fIdevice\fR is \fIbootpath\fR, and the
default for \fIpartno\fR is the first bootable partition on
\fIdevice\fR.  Alternatively, the \fB/\fIfilepath\fR section can be
replaced by a span of 512-byte blocks to load using the syntax
.BI [ start - end ]
where \fIstart\fR and \fIend\fR are decimal block numbers.

\fBSecond.b\fR will attempt to open the file identified by the path
name and load it into memory as an ELF binary.  If the file cannot be
found, or if it is not an ELF binary, \fBsecond.b\fR will print an
error message and print its \fBboot:\fR prompt again.  In this case
there is no timeout and \fBsecond.b\fR does not use the \fIbootargs\fR
value.

Once \fBsecond.b\fR has loaded the program into memory, it transfers
control to it, passing it the list of arguments.
.SH NEWWORLD
The process of booting so called NewWorld PowerMacs from disk starts
with OpenFirmware first attempting to execute the file specified in
the \fIboot-device\fR variable.  Unlike older versions of OpenFirmware
the NewWorld version will not attempt to read a boot sector.  By
default OpenFirmware attempts to load a file with HFS file type
\*(lqtbxi\*(rq in the \*(lqblessed\*(rq directory from each partition
of each disk OpenFirmware is aware of, the first partition/disk that
is found to be bootable is booted immediately.

.BR Ybin (8)
configures a \fBbootstrap\fR partition to pass all of OpenFirmware's
tests to determine if the partition is considered to be bootable or
not.  The boot script is given file type \*(lqtbxi\*(rq and the root
directory is marked as \*(lqblessed\*(rq, the blessing is important
because OpenFirmware will immediately consider a partition unbootable
if no directory is marked as blessed (you can still manually execute a
loader such as \fByaboot\fR(8) with OpenFirmware even without a blessed
directory but it will not happen automatically).

The MacOS System Folder is always marked as blessed, this is required
for MacOS as well as OpenFirmware.  The MacOS System Folder also
contains its own boot loader which has the tbxi file type, this makes
installing \fByaboot\fR(8) onto a MacOS partition is difficult.  The only way
to install \fByaboot\fR(8) on a MacOS boot partition is to modify
OpenFirmware to boot the CHRP script directly.  Given this it is
highly recommended that you create a dedicated \fBbootstrap\fR
partition for \fByaboot\fR(8).

Since OpenFirmware boots the first partition it finds to be bootable
it is important that the \fBbootstrap\fR partition be first on the
disk before any MacOS partition, otherwise MacOS will be booted
instead of a dual boot menu used with \fByaboot\fR(8).

The \fBbootstrap\fR partition should also NOT be mountable by MacOS,
the reason is MacOS will (almost always) closely inspect any blessed
directories to make sure its real MacOS, if it is not satisfied that
the contents are a real copy of MacOS it will unbless the directory,
resulting in OpenFirmware no longer considering it bootable.  The best
way to protect against this is to create the \fBbootstrap\fR partition
with the partition type \*(lqApple_Bootstrap\*(rq which OpenFirmware
accepts as a valid HFS partition, but MacOS will ignore and refuse to
mount.  The \fBbootstrap\fR partition need not be any larger then
800K.  800K is the minimum size of an HFS filesystem, and is much more
then enough for this purpose.  You need not, and should not keep
kernels on this partition, \fByaboot\fR(8) will load them from your
ext2fs root partition just fine, as well as from any HFS or HFS+
partitions (\fByaboot\fR(8) uses OpenFirmware's HFS+ filesystem support).

To create the \fBbootstrap\fR partition, use GNU \fBparted\fR(8) or
\fBmac-fdisk\fR(8) to create a partiton of type \*(lqApple_Bootstrap\*(rq.
This is documented better in \fBmac-fdisks-basics\fR
(http://penguinppc.org/usr/ybin/doc/mac-fdisk-basics.shtml).

The \fBbootstrap\fR need not and should not be mounted anywhere on
your filesystem, especially not on top of /boot.  \fBYaboot\fR(8) is
able to load the kernels from the ext2fs root partition so that is
where they should be kept.

OpenFirmware maintains a hierarchy of all the hardware it is aware of.
To access or specify a boot device you must use the OpenFirmware path.
For example: the path to a SCSI hard disk partition might look like
this: /pci@80000000/pci-bridge@d/ADPT,2930CU@2/@2:2 . The first part,
pci@80000000, shows that the target device is accessed through the PCI
bus.  The next part is the PCI bridge, the next is the name of the SCSI host
adapter installed (this name is provided by a BootROM on the card
itself), and after that is the SCSI ID number.  The colon delimits the
device from partition specification, so the last 2 means the second
partition of this device.  After the partition number we can specify
pathnames to files in two ways: lazy and absolute. The \*(lq,\*(rq delimits
the OpenFirmware path from the location of the bootfile.  \*(lq,\e\e:tbxi\*(rq
specifies the file that has a HFS file type of
\*(lqtbxi\*(rq in the blessed directory.  If there is not blessed
directory this will fail.  The second is to specify a absolute
pathname to an arbitrary file on the disk, example: 2:,yaboot would
load the file named \*(lqyaboot\*(rq in the root directory of the
filesystem.  It is possible to load files in subdirectories but
OpenFirmware does not always do this reliably, and any special
characters such as an embedded space must be expressed like %20 (for a
space) the directory separator used by OpenFirmware is the backslash
\e.  Example: 2:,\eboot\eyaboot. Determining the OpenFirmware path to
a given device is unfortunately not a trivial task.  If you are using
the built in ATA hard disk you can use the alias \*(lqhd:\*(rq.

\fBYbin\fR also includes a utility \fBofpath\fR(8) which can in most
cases find the OpenFirmware device path from a unix device node (ie
/dev/hda2).

In addition to binary executables OpenFirmware can also execute a CHRP
script.  This is somewhat similar to a shell script.  A CHRP script is
useful to create simple boot menus, among other things.  CHRP scripts
are divided into sections in a way similar to HTML.  Here is a basic
example of a CHRP script used as a wrapper to \fByaboot\fR(8) (since
OpenFirmware will only load a file with type \*(lqtbxi\*(rq if it is a
CHRP script).
.IP
.nf
<CHRP-BOOT>
<COMPATIBLE>
MacRISC
</COMPATIBLE>
<DESCRIPTION>
GNU/Linux PowerPC bootloader
</DESCRIPTION>
<BOOT-SCRIPT>
boot hd:,\\\\yaboot
</BOOT-SCRIPT>
</CHRP-BOOT>
.fi
.P
The \fICOMPATIBLE\fR section defines what machines this script is
compatible with, if the machine name encoded into the ROM does not
match one of these entries OpenFirmware will print out a lot of
incomprehensible junk and fail to load the script.  The
\fIDESCRIPTION\fR is ignored by OpenFirmware as far as I know.  The
\fIBOOT-SCRIPT\fR section is where arbitrary OpenFirmware Forth
commands may go.  They are executed the same way as you would enter
them on the OpenFirmware command line.  The entire script is wrapped
with the \fICHRP-BOOT\fR tags so that such a script may be attached as
a header to a binary file.  Much more complicated and elaborate CHRP
scripts are possible but that is beyond the scope of this document.

\fBYbin\fR as of version 0.17 includes a more robust script that is
automatically configured with the correct OpenFirmware paths based on
/etc/yaboot.conf.  This new script need not and should not be edited
by the user.

If you have G4 hardware then your OpenFirmware may already have a
graphical boot selector built in. This selector can be accessed by
holding down the option key when booting the machine.  You should see
a screen with buttons for each bootable partition.  The current
version (as of \fBybin\fR(8) 0.13) of ofboot includes a badge icon,
the button with a penguin icon is your \fBbootstrap\fR partition.  If
you decide to use this built in selector you really do not need to use
a CHRP script that provides a boot menu. Thanks to Nicholas Humfrey
for creating the Badge icon.
.SH IBM
IBM hardware such as the RS/6000 require msdos style partition tables.
In order to boot from the disk they require a type 0x41 PReP Boot
\fBbootstrap\fR partition large enough to hold the bootloader
(typically \fByaboot\fR(8)).  The bootloader is copied onto the raw
partition as there is no filesystem.  This is done either with \fBdd\fR(1)
or \fBmkofboot\fR(8).
.SH BUGS
OpenFirmware
.SH AUTHORS
\fBybin\fR, and the NEWWORLD, and IBM sections of this man page
written by Ethan Benson <erbenson@alaska.net>
.P
The OLDWORLD section of this man page was taken from the \fBquik\fR(8)
package, which was written by Paul Mackerras.
.P
.B yaboot
was written by Benjamin Herrenschmidt <benh@kernel.crashing.org>.
.SH SEE ALSO
.BR dd (1),
.BR mkofboot (8),
.BR ofpath (8),
.BR quik (8),
.BR quik.conf (5),
.BR yaboot (8),
.BR ybin (8).