|
@@ -0,0 +1,535 @@
|
|
|
+.TH 9BOOT 8
|
|
|
+.SH NAME
|
|
|
+9boot, 9bootpbs, 9load, 9loadusb \- 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
|
|
|
+Details follow.
|
|
|
+.SS "Loading these bootstraps"
|
|
|
+.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 location
|
|
|
+.B 0x7C00
|
|
|
+(31K).
|
|
|
+.I 9boot
|
|
|
+begins execution at virtual address
|
|
|
+.B 0x80007C00
|
|
|
+and reads a
|
|
|
+.IR plan.ini (8)
|
|
|
+file from
|
|
|
+.B /cfg/pxe
|
|
|
+via PXE,
|
|
|
+then loads the named
|
|
|
+.I bootfile
|
|
|
+via PXE,
|
|
|
+using each ethernet in sequence,
|
|
|
+at the entry address specified by the header,
|
|
|
+usually virtual
|
|
|
+.BR 0xF0100020 .
|
|
|
+After loading, control is passed to the entry location.
|
|
|
+.PP
|
|
|
+.I 9load
|
|
|
+is a similar bootstrap program,
|
|
|
+run by the PC partition boot sector program (PBS),
|
|
|
+which usually resides in the first
|
|
|
+sector of the active partition.
|
|
|
+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.
|
|
|
+.PP
|
|
|
+.I 9load
|
|
|
+begins execution at virtual address
|
|
|
+.B 0x80010000
|
|
|
+(physical 64K) and
|
|
|
+loads the
|
|
|
+.I bootfile
|
|
|
+at the entry address specified by the header,
|
|
|
+usually virtual
|
|
|
+.BR 0xF0100020 .
|
|
|
+After loading, control is passed to the entry location.
|
|
|
+.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)).
|
|
|
+.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 compressed with
|
|
|
+.IR gzip (1).
|
|
|
+In all cases,
|
|
|
+the uncompressed kernel must be in Plan 9 boot image or ELF 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 Kernel loading
|
|
|
+.I 9boot
|
|
|
+is initially loaded by the PXE BIOS at physical address
|
|
|
+.BR 0x7C00 .
|
|
|
+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 and used as a
|
|
|
+.IR plan9.ini .
|
|
|
+.PP
|
|
|
+.I 9load
|
|
|
+differs slightly in operation from
|
|
|
+.IR 9boot .
|
|
|
+It is initially loaded by a partition boot sector at physical address
|
|
|
+.BR 0x10000 .
|
|
|
+In order to find configuration information,
|
|
|
+.I 9load
|
|
|
+searches all units on devices
|
|
|
+.\" .BR fd
|
|
|
+.\" and
|
|
|
+.BI sd Cn \fR
|
|
|
+(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 .
|
|
|
+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 .
|
|
|
+This option is overridden by a command-line argument.
|
|
|
+.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
|
|
|
+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
|
|
|
+.BI sd Cn \fR
|
|
|
+FAT partitions for a kernel
|
|
|
+(any file named
|
|
|
+.B 9pc*
|
|
|
+or
|
|
|
+.BR 9k8* )
|
|
|
+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 command-line argument or
|
|
|
+.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 from:"
|
|
|
+prompt.
|
|
|
+.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.
|
|
|
+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 your
|
|
|
+.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
|
|
|
+.I 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/pcboot
|
|
|
+.PD 0
|
|
|
+.TP
|
|
|
+.B /sys/src/boot/pc
|
|
|
+first-stage disk boot sectors
|
|
|
+.TP
|
|
|
+.B /sys/src/9/pcboot
|
|
|
+.TP
|
|
|
+.B /sys/src/9/pc
|
|
|
+.PD
|
|
|
+.SH "SEE ALSO"
|
|
|
+.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.
|