term% cat index.txt 9BOOT(8) System Manager's Manual 9BOOT(8)
NAME
9boot, 9bootpbs, 9load, 9loadusb, pbs - PC bootstrap programs
SYNOPSIS
none
DESCRIPTION
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 386 or amd64
kernel and start it.
9bootpbs, 9load and 9loadusb are less-commonly-used variants that re‐
side in a FAT file system under the name and bootstrap Plan 9.
9bootpbs is like 9boot but it can be started by a partition boot sector
(PBS), as can 9load and 9loadusb. It is intended to PXE boot older ma‐
chines without working PXE ROMs. 9load and 9loadusb read FAT file sys‐
tems. 9loadusb will use only the BIOS's device drivers, and thus can
load from FAT file systems on USB devices. In contrast, 9load will not
use BIOS device drivers and cannot read USB devices.
This profusion of loaders is unfortunate, but at least they are com‐
piled 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.
These programs are run automatically by the boot procedures described
below; they cannot be run directly by hand. There are two bootstrap
sequences:
- PXE BIOS, 9boot, kernel
- BIOS, MBR, disk partition PBS, 9load, kernel
In summary, Plan 9 is usually booted on a PC by using a PXE-capable
BIOS to boot 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 prepared using format to install the appropriate files
and bootstrap sectors (see prep(8)).
Details follow.
Kernel loading
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 9boot at physical address 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 0 and 0x80000000. Only devices
which can be automatically configured, e.g. most PCI ethernet adapters,
will be recognised. If the file /cfg/pxe/ether can be located via a
DHCP server, where ether is the lower-case MAC address of a recognised
ethernet adapter, the contents are obtained by TFTP and used as a
plan9.ini(8). 9boot then loads the bootfile named within via TFTP,
trying each ethernet in sequence, at the entry address specified by the
kernel executable's header, usually virtual 0xF0100020. After loading,
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 amd64 kernels
expect Multiboot headers.
Some options in plan9.ini are used by 9boot:
console
baud Specifies the console device and baud rate if not a display.
ethern Ethernet interfaces. These can be used to load the bootfile over
a network.
bootfile=bootfile
Specifies the bootfile.
bootfile=manual
After determining which devices are available for loading from,
enter prompt mode.
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
0x10000(64K); it begins execution at virtual address 0x80010000. In
order to find configuration information, 9load searches all units on
devices sd?[0-9]* (all sd devices), for a file called plan9.ini (see
plan9.ini(8)) on a FAT partition named dos or 9fat. If one is found,
searching stops and the file is read into memory at physical address
0x1200 where it can be found later by any loaded bootfile.
When the search for plan9.ini is done, 9load proceeds to determine
which bootfile to load. If there was no bootfile option, 9load
searches sd?[0-9]* FAT partitions for a kernel (any file named 9pc*,
9k8* or 9k10*) and if it finds exactly one kernel in a given FAT parti‐
tion, chooses it. 9load then attempts to load the bootfile.
9load prints the list of available devices and enters prompt mode on
encountering any error or if directed to do so by a bootfile=manual op‐
tion. In prompt mode, the user is required to type a bootfile in re‐
sponse to the prompt.
Bootfile
The bootfile can be specified to these programs as a bootfile= entry in
plan9.ini, or if booting from the ethernet, by a BOOTP server (see Ker‐
nel loading below). If loading with 9load, the bootfile may be a Plan
9 boot image compressed with gzip(1). In all cases, the uncompressed
kernel must be in Plan 9 boot image, ELF or ELF64 format. If the
plan9.ini file contains multiple bootfile= entries, these programs will
present a numerical menu of the choices; type the corresponding number
to select an entry.
The format of the bootfile name is device!file or device!parti‐
tion!file. If !file is omitted, the default for the particular device
is used. Supported devices are
ethern Ethernet, 9boot only. N specifies the Ethernet device number.
If a partition is specified, it is taken to be the name of a
host machine from which to load the kernel.
sdCn Normal disk, 9load only. The device name format is described in
sd(3). A partition must be given and must normally name a par‐
tition containing a FAT file system. It is common for Plan 9
partitions to contain a small FAT file system for configuration.
By convention, this partition is called 9fat. There is no de‐
fault partition, but if file is omitted, 9load will load a ker‐
nel directly from the named partition without any interpretation
of a file system.
biosn USB or other BIOS device, 9loadusb only. 9load loads from a FAT
file system on the first LBA device in the BIOS's list of de‐
vices to try to boot from, using the BIOS INT 13 calls also used
by pbslba. It does not understand any form of partition table;
see the EXAMPLES in prep(8) for how to format such a device.
sdBn USB or other BIOS device's partition, 9loadusb only. A special
case of sdCn that uses biosn to read from a FAT file system.
Boot Sectors
A copy of the Plan 9 PBS is kept in /386/pbs, but due to the ``cylin‐
der-head-sector'' (CHS) addressing mode of old BIOSes, it can only op‐
erate up to 8.5GB into the disk. Plan 9 partitions further into the
disk can only be booted using /386/pbslba, and then only if the ma‐
chine's BIOS supports linear block addressing (LBA) mode for disk
transfers.
When booting from disk, the BIOS loads the first sector of the medium
at location 0x7C00. In the case of a disk, it is the master boot
record (MBR). The MBR copies itself to address 0x600, finds the active
partition and loads its PBS at address 0x7C00. A copy of the Plan 9
MBR is kept in /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 /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 operat‐
ing systems, and (modulo the large disk constraints just described)
non-Plan-9 MBRs are suitable for booting Plan 9.
Other facilities and caveats
9load parses the master boot record and Plan 9 partition tables (see
prep(8)), leaving partitioning information appended to the in-memory
contents of plan9.ini for the bootfile. This is used by sd(3) to ini‐
tialize partitions so that may be read for NVRAM contents or fossil(4)
or kfs(4) file systems can be mounted as the root file system. On ISO
9660 CDs, 9load treats the contents of a file named /bootdisk.img as a
9fat partition, and it is assumed to contain the image of a FAT file
system. A more extensive partitioning is typically done by fdisk and
prep as part of termrc or cpurc (see cpurc(8)). 9boot cannot parse
partition tables, as it lacks disk drivers, so add to the machine's
/cfg/pxe file, per plan9.ini(8), if needed.
A control-P character typed at any time on the console causes 9boot to
perform a hardware reset (Ctrl-Alt-Del can also be used on a PC key‐
board).
9load must be contiguously allocated on the disk. See dossrv(4) for
information on ensuring this.
FILES
/386 these programs reside here
/cfg/pxe
directory of configuration (plan9.ini) files on your TFTP server
FAT-filesystem:\9load
FAT-filesystem:\plan9.ini
SOURCE
/sys/src/boot/pc
first-stage disk boot sectors (MBR, PBS)
/sys/src/9/pcboot
PC-bootstrap-specific source
/sys/src/9/^(pc port ip)
common kernel source
SEE ALSO
8l(1), cons(3), booting(8), dhcpd(8), fshalt(8), mkusbboot(8),
plan9.ini(8), prep(8)
BUGS
Some of the work done by 9boot is duplicated by the loaded kernel, but
usually by the same source code.
bios and sdB usually only work on the first LBA device in the BIOS's
list of boot devices, if they work at all.
USB keyboards will only work with 9boot if the BIOS emulates a PS/2
keyboard (and that is enabled).
9BOOT(8)