harvey/sys/man/8/9boot

.TH 9BOOT 8
.SH NAME
9boot, 9bootpbs, 9load, 9loadusb, pbs \- PC bootstrap programs
.SH SYNOPSIS
.I none
.SH DESCRIPTION
.I 9boot
is a specialized Plan 9 kernel loaded by
the PXE download (BOOTP/DHCP followed by TFTP)
found in any reasonable Ethernet card's BIOS; it bootstraps Plan 9 by using
PXE to load another
.B 386
or
.B amd64
kernel and start it.
.PP
.IR 9bootpbs ,
.I 9load
and
.I 9loadusb
are less-commonly-used variants
that reside in a FAT file system under the name
.L 9load
and bootstrap Plan 9.
.I 9bootpbs
is like
.I 9boot
but it can be started by a partition boot sector (PBS),
as can
.I 9load
and
.IR 9loadusb .
It is intended to PXE boot older machines without working PXE ROMs.
.I 9load
and
.I 9loadusb
read FAT file systems.
.I 9loadusb
will use only the BIOS's device drivers,
and thus can load from FAT file systems on USB devices.
In contrast,
.I 9load
will
.I not
use BIOS device drivers and cannot read USB devices.
.PP
This profusion of loaders is unfortunate, but at least they
are compiled from the same source.
The division into separate programs is dictated by the need to fit
within the first 640K of memory
and the need to avoid intermixing BIOS and non-BIOS disk access.
.PP
These programs are run automatically by the boot procedures described below;
they cannot be run directly by hand.
There are two bootstrap sequences:
.IP \- 3
PXE BIOS,
.IR 9boot ,
kernel
.IP \-
BIOS, MBR, disk partition PBS,
.IR 9load ,
kernel
.\" .IP \-
.\" BIOS, floppy PBS,
.\" .IR 9load ,
.\" kernel
.PP
In summary,
Plan 9 is usually booted on a PC
by using a PXE-capable BIOS to boot
.I 9boot
directly over the ethernet.
File servers that must be able to boot when other machines are down
boot directly from a Plan 9 disk partition
.\" or boot floppy
prepared using
.B format
to install the appropriate files and bootstrap sectors
(see
.IR prep (8)).
.PP
Details follow.
.SS Kernel loading
.I 9boot
is a bootstrap program that loads and starts a program,
typically the kernel, on a PC.
It is run by the PXE boot ROM of a PC,
which loads
.I 9boot
at physical address
.B 0x7C00
(31K).
When it starts running,
it switches to 32-bit mode.
It then double maps the first 16Mb of physical memory to
virtual addresses
.B 0
and
.BR 0x80000000 .
Only devices which can be automatically configured,
e.g. most PCI ethernet adapters,
will be recognised.
If the file
.BI /cfg/pxe/ ether
can be located via a DHCP server,
where
.I ether
is the lower-case MAC address of a recognised ethernet adapter,
the contents are obtained by TFTP and used as a
.IR plan9.ini (8).
.I 9boot
then loads the
.I bootfile
named within via TFTP,
trying each ethernet in sequence,
at the entry address specified by the kernel executable's header,
usually virtual
.BR 0xF0100020 .
After loading,
.I 9boot
creates a Gnu Multiboot header in low memory for
the benefit of the loaded kernel
and
control is passed to the entry location
in 32-bit protected mode, even for 64-bit kernels.
So far, only
.B amd64
kernels expect Multiboot headers.
.PP
Some options in
.B plan9.ini
are used by
.IR 9boot :
.TF bootfile=manual
.TP
.B console
.TP
.B baud
Specifies the console device and baud rate if not a display.
.TP
.BI ether n
Ethernet interfaces. These can be used to load the
.I bootfile
over a network.
.TP
.BI bootfile= bootfile
Specifies the
.IR bootfile .
.ig
.TP
.B bootfile=auto
Default.
.TP
.B bootfile=local
Like
.IR auto ,
but do not attempt to load over the network.
..
.TP
.B bootfile=manual
After determining which devices are available for loading from,
enter prompt mode.
.PD
.PP
.I 9load
is a similar bootstrap program,
loaded by the PC partition boot sector program (PBS),
which usually resides in the first
sector of the active disk partition.
It is initially loaded at physical address
.BR 0x10000 (64K);
it begins execution at virtual address
.BR 0x80010000 .
In order to find configuration information,
.I 9load
searches all units on devices
.\" .BR fd
.\" and
.B sd?[0-9]*
(all
.B sd
devices),
for a file called
.\" .B plan9\eplan9.ini
.\" or
.B plan9.ini
(see
.IR plan9.ini (8))
on a FAT partition named
.B dos
or
.BR 9fat .
If one is found, searching stops and the file is read into memory
at physical address
.B 0x1200
where it can be found later by any loaded
.IR bootfile .
.PP
When the search for
.B plan9.ini
is done,
.I 9load
proceeds to determine which bootfile to load.
If there was no
.I bootfile
option,
.I 9load
searches
.B sd?[0-9]*
FAT partitions for a kernel
(any file named
.BR 9pc* ,
.B 9k8*
or
.BR 9k10* )
and if it finds exactly one kernel in a given FAT partition,
chooses it.
.I 9load
then attempts to load the
.IR bootfile .
.ig
unless
the
.B bootfile=manual
option was given, in which case prompt mode is entered immediately.
..
.ig
If the default device is
.BR fd ,
.I 9load
will prompt the user for input before proceeding with the
default bootfile load after 5 seconds;
this prompt is omitted if a
.I bootfile
option
was given.
..
.PP
.I 9load
prints the list of available
.IR device s
and
enters prompt mode on encountering any error
or if directed to do so by a
.B bootfile=manual
option.
In prompt mode, the user is required to type
a
.IB bootfile
in response to the
.L Boot
.L from:
prompt.
.br
.ne 4
.SS Bootfile
The
.I bootfile
can be specified to these programs as a
.B bootfile=
entry in
.IR plan9.ini ,
or if booting from the ethernet, by a BOOTP server
(see
.B Kernel
.B loading
below).
If loading with
.IR 9load ,
the
.I bootfile
may be a Plan 9 boot image compressed with
.IR gzip (1).
In all cases,
the uncompressed kernel must be in Plan 9 boot image, ELF or ELF64 format.
If the
.B plan9.ini
file contains multiple
.B bootfile=
entries,
these programs will present a numerical menu of the choices; type
the corresponding number to select an entry.
.PP
The format of the
.I bootfile
name is
.IB device ! file
or
.IB device ! partition ! file\f1.
If
.BI ! file
is omitted, the default for the particular
.I device
is used.
Supported
.I devices
are
.TF \fLethern
.PD
.TP
.BI ether n
Ethernet,
.I 9boot
only.
.I N
specifies the Ethernet device number.
If a
.I partition
is specified, it is taken to be the name of a host machine
from which to load the kernel.
.TP
.BI sd Cn
Normal disk,
.I 9load
only.
The device name format is described in
.IR sd (3).
A
.I partition
must be given and must normally
name a partition containing a FAT file system.
.\" The name
.\" .B dos
.\" refers to the first DOS partition on a given device.
It is common for Plan 9 partitions to contain a small
FAT file system for configuration.
By convention, this partition is called
.BR 9fat .
There is no default partition,
but if
.I file
is omitted,
.I 9load
will load a kernel directly from the named partition
without any interpretation of a file system.
.
.ig
.TP
.BI fd n
An MS-DOS floppy disk,
.I 9load
only.
.I N
specifies the floppy drive, either
0 or 1.
The
.I bootfile
is the contents of the MS-DOS
.IR file .
There is no default file.
For compatibility with normal disks, a
.I partition
may be given, but only
.B dos
is recognized:
.BI fd0!dos! file\f1.
..
.
.TP
.BI bios n
USB or other BIOS device,
.IR 9loadusb
only.
.I 9load
loads from a FAT file system on
the first LBA device
in the BIOS's list of devices to try to boot from,
using the BIOS INT 13 calls also used by
.IR pbslba .
It does not understand any form of partition table;
see the
.B EXAMPLES
in
.IR prep (8)
for how to format such a device.
.TP
.BI sdB n
USB or other BIOS device's partition,
.IR 9loadusb
only.
A special case of
.BI sd Cn
that uses
.BI bios n
to read from a FAT file system.
.SS Boot Sectors
A copy of the Plan 9 PBS is kept in
.BR /386/pbs ,
but due to the ``cylinder-head-sector'' (CHS) addressing mode of old BIOSes, it can only
operate up to 8.5GB into the disk.
Plan 9 partitions further into the disk
can only be booted using
.BR /386/pbslba ,
and then only if the machine's BIOS supports
linear block addressing (LBA) mode for disk transfers.
.PP
When booting from disk,
.\" or floppy,
the BIOS loads the
first sector of the medium at location
.BR 0x7C00 .
In the case of a disk, it is the master boot record (MBR).
.\" In the case of a floppy, this is the PBS.
The MBR copies itself to address
.BR 0x600 ,
finds the active partition and loads its PBS at address
.BR 0x7C00 .
A copy of the Plan 9 MBR is kept in
.BR /386/mbr ;
some commercial MBRs cannot read sectors
past 2GB.
The Plan 9 MBR can read sectors up to 8.5GB into
the disk, and further if the BIOS supports LBA.
The single file
.B /386/mbr
detects whether the BIOS supports LBA and
acts appropriately, defaulting to CHS mode
when LBA is not present.
The PBSs cannot do this due to code size limitations.
The Plan 9 MBR is suitable for booting non-Plan-9
operating systems,
and (modulo the large disk constraints just described)
non-Plan-9 MBRs are suitable for booting Plan 9.
.br
.ne 4
.SS Other facilities and caveats
.I 9load
parses the master boot record and Plan 9 partition tables
(see
.IR prep (8)),
leaving partitioning information appended to the
in-memory contents of
.I plan9.ini
for the
.IR bootfile .
This is used by
.IR sd (3)
to initialize partitions so that
may be read for NVRAM contents or
.IR fossil (4)
or
.IR kfs (4)
file systems can be mounted as the root file system.
On ISO 9660 CDs,
.I 9load
treats the contents of a file named
.B /bootdisk.img
as a 
.B 9fat
partition,
and it is assumed to contain the image of a FAT file system.
A more extensive partitioning is typically done by
.I fdisk
and
.I prep
as part of
.I termrc
or
.I cpurc
(see
.IR cpurc (8)).
.I 9boot
cannot parse partition tables,
as it lacks disk drivers, so add
.L readparts=
to the machine's
.B /cfg/pxe
file, per
.IR plan9.ini (8),
if needed.
.PP
A
control-P
character typed at any time on the console causes
.B 9boot
to perform a hardware reset
(Ctrl-Alt-Del can also be used on a PC keyboard).
.PP
.I 9load
must be contiguously allocated on
the disk.
See
.IR dossrv (4)
for information on ensuring this.
.SH FILES
.TF /cfg/pxe
.TP
.B /386
these programs reside here
.TP
.BI /cfg/pxe
directory of configuration
.RI ( plan9.ini )
files on your TFTP server
.PP
.IB "FAT-filesystem" :\e9load
.br
.IB "FAT-filesystem" :\eplan9.ini
.\" .br
.\" .IB "FAT-filesystem" :\eplan9\eplan9.ini
.SH SOURCE
.TF "/sys/src/9/^(pc port ip)"
.PD 0
.TP
.B /sys/src/boot/pc
first-stage disk boot sectors (MBR, PBS)
.TP
.B /sys/src/9/pcboot
PC-bootstrap-specific source
.TP
.B /sys/src/9/^(pc port ip)
common kernel source
.PD
.SH "SEE ALSO"
.IR 8l (1),
.IR cons (3),
.IR booting (8),
.IR dhcpd (8),
.IR fshalt (8),
.IR mkusbboot (8),
.IR plan9.ini (8),
.IR prep (8)
.SH BUGS
Some of the work done by
.I 9boot
is duplicated by the loaded kernel,
but usually by the same source code.
.PP
.B bios
and
.B sdB
usually only work on the first LBA device in the BIOS's list of boot devices,
if they work at all.
.PP
USB keyboards will only work with
.I 9boot
if the BIOS emulates a PS/2 keyboard (and that is enabled).