9BOOT(8)                                                 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 down-
          load (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 reside in a FAT file system under the name `9load' 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 machines without
          working PXE ROMs.  9load and 9loadusb read FAT file systems.
          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 compiled from the same source.  The division into sepa-
          rate 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 pro-
          gram, typically the kernel, on a PC.  It is run by the PXE

     9BOOT(8)                                                 9BOOT(8)

          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 con-
          tents 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 avail-
                           able for loading from, enter prompt mode.

          9load is a similar bootstrap program, loaded by the PC par-
          tition boot sector program (PBS), which usually resides in
          the first sector of the active disk partition.  It is ini-
          tially 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 partition, 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 option.  In prompt mode, the user is

     9BOOT(8)                                                 9BOOT(8)

          required to type a bootfile in response to the `Boot'
          `from:' prompt.

        Bootfile
          The bootfile can be specified to these programs as a
          bootfile= entry in plan9.ini, or if booting from the ether-
          net, by a BOOTP server (see Kernel loading below).  If load-
          ing with 9load, the bootfile may be a Plan 9 boot image com-
          pressed 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!partition!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 partition containing a FAT file
                  system.  It is common for Plan 9 partitions to con-
                  tain a small FAT file system for configuration.  By
                  convention, this partition is called 9fat.  There is
                  no default partition, but if file is omitted, 9load
                  will load a kernel 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 devices 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
          ``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
          /386/pbslba, and then only if the machine's BIOS supports

     9BOOT(8)                                                 9BOOT(8)

          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 pre-
          sent.  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.

        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 initialize 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 con-
          tain the image of a FAT file system.  A more extensive par-
          titioning 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 `readparts=' 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 keyboard).

          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

     9BOOT(8)                                                 9BOOT(8)

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