.\"	$NetBSD: boot.8,v 1.7 2017/02/17 22:30:28 christos Exp $
.\"
.\" Copyright (c) 2006 Stephen M. Rumble
.\" All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. The name of the author may not be used to endorse or promote products
.\"    derived from this software without specific prior written permission.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
.\"
.Dd February 17, 2017
.Dt BOOT 8 sgimips
.Os
.Sh NAME
.Nm boot
.Nd sgimips system bootstrapping procedures
.Sh DESCRIPTION
.Tn Silicon Graphics
MIPS-based computers all feature essentially similar firmware systems.
However, as of the Indigo R4x00 series (IP20), quasi-
.Tn ARCS
(Advanced RISC Computing Specification) compatible features are also present.
All known PROM implementations support loading executables from disk
devices, as well as from the network via BOOTP and TFTP.
.Sh Disk Booting
.Tn SGI
provides a small filesystem at the beginning of each bootable disk called
a Volume Header, which contains a boot loader and other standalone utilities.
Booting
.Nx
requires that we write our bootloader into to the volume header using
.Xr sgimips/sgivol 8 .
.Pp
Once a bootloader is present in the volume header, it may be executed
directly by the PROM either manually, or at boot time using the
.Dq OSLoader
PROM environment variable.
The
.Nx
bootloader will obtain the kernel filename to boot from the PROM or EEPROM.
This is specified by setting the PROM environment variable
.Dq OSLoadFilename
to an appropriate value.
For instance,
.Dq /netbsd.ecoff .
.Pp
For example, the following will configure the PROM to use the bootloader
.Dq aoutboot
to load the kernel
.Dq netbsd.old
.Pp
.Dl Ic setenv OSLoader aoutboot
.Dl Ic setenv OSLoadFilename netbsd.old
.Sh Network Booting
The system firmware will obtain an IP address, TFTP server address, and an
optional filename from the BOOTP server and download it via TFTP.
The PROM's configurable network address environment variable
.Dq netaddr
must match the address provided by the BOOTP server.
.Pp
An example BOOTP entry for
.Xr dhcpd 8
follows:
.Pp
.Bd -unfilled -offset indent
	host indigo3k {
		hardware ethernet 08:00:69:42:42:42;
		fixed-address 192.168.0.2;
		option host-name "indigo3k.foo";
		#filename "/netbsd.ecoff";
		next-server 192.168.0.1;
		option root-path "/export/indigo3k/root";
		server-name "192.168.0.1";
	}
.Ed
.Pp
To boot a kernel named
.Dq netbsd.ecoff
the user would type:
.Dl Ic boot -f bootp():/netbsd.ecoff
.Pp
See
.Xr dhcpd.conf 5
for more information on configuring
.Xr dhcpd 8
as a BOOTP server.
.Sh SEE ALSO
.Xr dhcpd.conf 5 ,
.Xr dhcpd 8 ,
.Xr sgimips/sgivol 8
.Sh CAVEATS
Some older PROM revisions do not support loading of ELF images.
The build system automatically prepares ECOFF versions, which are
correctly interpreted.
.Sh BUGS
.Nx
does not support booting from disk on systems lacking an ARCS-compatible
firmware (presently supported systems include Personal Iris and Indigo R3000).
It is possible to work around this by creating a sufficiently large volume
header and placing the kernel in it, or by network booting.
.Pp
Some firmware revisions have a bug, which precludes them from communicating
with TFTP servers using ports above 32767.
When using
.Nx
as the TFTP server, this problem may be worked around as follows:
.Pp
.Dl Ic sysctl -w net.inet.ip.anonportmin=20000
.Dl Ic sysctl -w net.inet.ip.anonportmax=32767
.Pp
Another bug exists in some firmware revisions, which precludes the PROM from
communicating with TFTP servers that employ PMTU (Path MTU) discovery.
This bug may be worked around by disabling PMTU on the TFTP server.
This does not presently affect
.Nx
servers.
.Pp
This man page is horribly incomplete.