[src/trunk]: src/share/man/man8/man8.alpha Complete rework of this man page t...

[fair <fair%NetBSD.org@localhost>]

details:   https://anonhg.NetBSD.org/src/rev/8295c19b9bf7
branches:  trunk
changeset: 546532:8295c19b9bf7
user:      fair <fair%NetBSD.org@localhost>
date:      Thu May 01 09:15:56 2003 +0000

description:
Complete rework of this man page to explain SRM enough to boot an
alpha. This is to answer PR 20557.

diffstat:

 share/man/man8/man8.alpha/boot.8 |  318 +++++++++++++++++++++++++++++++++++---
 1 files changed, 293 insertions(+), 25 deletions(-)

diffs (truncated from 371 to 300 lines):

diff -r bd7b30ee837d -r 8295c19b9bf7 share/man/man8/man8.alpha/boot.8
--- a/share/man/man8/man8.alpha/boot.8  Thu May 01 09:05:56 2003 +0000
+++ b/share/man/man8/man8.alpha/boot.8  Thu May 01 09:15:56 2003 +0000
@@ -1,4 +1,4 @@
-.\" $NetBSD: boot.8,v 1.6 2003/04/25 04:19:15 fair Exp $
+.\" $NetBSD: boot.8,v 1.7 2003/05/01 09:15:56 fair Exp $
 .\"
 .\" Copyright (c) 1999 Christopher G. Demetriou
 .\" All rights reserved.
@@ -70,19 +70,297 @@
 .\"
 .\"     @(#)boot_hp300.8        8.2 (Berkeley) 4/19/94
 .\"
-.Dd April 5, 1999
+.Dd April 28, 2003
 .Dt BOOT 8 alpha
 .Os
 .Sh NAME
 .Nm boot
 .Nd Alpha system bootstrapping procedures
 .Sh DESCRIPTION
-When the
+.Tn DEC
+.Tn Alpha
+systems can have either of two different firmware systems:
+.Tn ARC
+.Pq a.k.a. Tn AlphaBIOS ,
+and
+.Tn SRM .
+Some
+.Tn Alpha
+systems have both in their flash
+.Tn RAM
+and can switch between them on command.
+.Tn ARC
+is used to boot Microsoft Windows NT for
+.Tn Alpha .
+.Tn SRM
+is used to boot
+.Tn OpenVMS
+and
+.Tn Ultrix .
+.Nx
+requires
+.Tn SRM .
+.Pp
+.Tn SRM
+can boot from supported local storage devices, e.g.
+.Tn IDE
+disks or
+.Tn CD-ROM
+drives,
+.Tn SCSI
+disks or
+.Tn CD-ROM
+drives, and floppy drives.
+.Tn SRM
+can also netboot via supported
+.Tn Ethernet
+interfaces, using
+.Tn BOOTP
+or
+.Tn MOP .
+The particular capabilities of
+.Tn SRM
+will vary from system to system.
+.Pp
+When
+.Tn SRM
+boots the system, it performs a Power On Self Test
+.Pq Tn POST ,
+probes the system busses to identify devices, and initializes them.
+.Tn SRM
+includes an x86 instruction emulator in order to run the
+.Tn BIOS
+initialization routines found in the
+.Tn PROM
+of any video cards found.
+In this way, most generic
+.Tn PCI
+video cards can work in
+.Tn Alpha
+systems that have
+.Tn PCI
+bus slots.
+.Pp
+.Tn SRM
+then examines the state of one of several variables:
+.Ev auto_action .
+If the value of
+.Ev auto_action
+is
+.Qq halt
+then
+.Tn SRM will stop, print its prompt:
+.Qq \*[Gt]\*[Gt]\*[Gt]
+and wait for commands to be entered on the console.
+If the value of
+.Ev auto_action
+is
+.Qq boot
+then
+.Tn SRM
+will automatically boot the operating system specified by
+various non-volatile environment variables.
+.Pp
+.Tn SRM
+device names are not the same as in
+.Nx ,
+e.g.
+.Sy ewa0
+is a
+.Tn DEC
+.Qq tulip
+.Tn Ethernet
+interface,
+.Sy dka0
+is a
+.Tn SCSI
+disk on a recognized controller,
+.Sy dqa0
+is an
+.Tn IDE
+disk on a recognized controller.
+The
+.Ic show device
+command will list all the devices that
+.Tn SRM
+can boot from.
+.Ss SRM Commands
+.Tn SRM
+is somewhat
+.Ux Ns No -like
+in that it incorporates a simple pipe and I/O redirection,
+which allows command sequences like:
+.Pp
+.Bd -literal -offset indent
+show config | more
+show * | more
+.Ed
+.Pp
+An essential but incomplete list of
+.Tn SRM
+commands follows:
+.\" .Pp
+.\" .Bl -tag -width "boot [-file filename] [-flags value] [-protocols enet_protocol] [device]"
+.\" .It Ic boot Oo Fl file Ar filename Oc Oo Fl flags Ar value Oc Oo Fl protocols Ar enet_protocol Oc Op Ar device
+.Pp
+.Ic boot
+.Op Fl file Ar filename
+.Op Fl flags Ar value
+.\" .Op Fl protocols Ar enet_protocol
+.Op Ar device
+.Pp
+Boot an operating system.
+The default arguments for this command are taken from the
+.Tn SRM
+environment variables:
+.Pp
+.Bl -tag -compact -width "boot_osflags" -offset indent
+.It Ev boot_file
+filename to boot.
+.It Ev boot_osflags
+flags to pass to the secondary bootstrap.
+.It Ev bootdef_dev
+default boot device.
+.El
+.\" .It Ic help Op Ar command
+.Pp
+.Ic help Op Ar command
+.Pp
+Invoke the
+.Tn SRM
+help system.
+.\" .It Ic set Ar variable Ar value
+.Pp
+.Ic set Ar variable Ar value
+.Pp
+Set an
+.Tn SRM
+variable, e.g.
+.Bd -literal -offset indent
+set auto_action boot
+set bootdef_dev dka0
+set ewa0_mode auto
+.Ed
+.\" .It Ic show Ar variable or subsystem
+.Pp
+.Ic show Ar variable or subsystem
+.Pp
+Show
+.Tn SRM
+variables and values, or show system state or configuration.
+If a wildcard is used, then all matching
+.Tn SRM
+variables are shown, e.g.
+.Pp
+.Bl -tag -width "show device" -compact -offset indent
+.It Ic show b*
+will display all variables whose names begin with
+.Em b .
+.It Ic show config
+will display the complete system configuration.
+.It Ic show device
+will display all bootable devices.
+.El
+.\" .El
+.Ss SRM Variables
+.Bl -tag -width "ew*0_protocols"
+.It Ev auto_action
+What
+.Tn SRM
+will do at system startup or reset:
+.Bl -tag -width boot
+.It Ar boot
+automatically boot the operating system.
+.It Ar halt
+after
+.Tn POST
+prompt the user on the console for commands to execute.
+.El
+.Pp
+Some
+.Tn Alpha
+systems
+.Pq e.g. Tn AlphaServer 800
+have a
+.Qq halt
+switch, which if set, will override the action of this variable, and cause
+.Tn SRM
+to stop after
+.Tn POST
+and prompt the user for commands to execute.
+.It Ev bootdef_dev
+The default boot device, e.g.
+.Sy dka0 ,
+.Sy dqa0 .
+The
+.Ic show device
+command will list the available and recognized bootable devices.
+.It Ev boot_file
+The file to boot from, i.e. netbsd.
+.It Ev boot_osflags
+The flag passed to the bootstrap software:
+.Bl -tag -width "XXXX"
+.It Sy a
+multi-user mode boot.
+.It Sy i
+the
+.Nx
+secondary boot program will stop and prompt for the file to boot.
+.It Sy q
+boot quietly.
+.It Sy s
+single-user mode boot.
+.El
+.It Ev console
+What type of console device
+.Tn SRM
+and
+.Nx
+will use:
+.Bl -tag -width "graphics"
+.It Ar graphics
+use a video card for output, and a
+.Tn PC
+keyboard for input.
+.It Ar serial
+use the first serial port for console.
+.El
+.Pp
+Just as with
+.Tn Sun
+systems,
+.Tn Alpha
+systems will use the first serial port as a console if there is no
+keyboard plugged into the keyboard port, even if
+.Ev console
+is set to
+.Qq graphics .
+.It Ev ew*0_mode
+the media and speed for
+.Tn DEC
+.Qq tulip
+Ethernet interfaces
+.Po
+e.g.
+.Tn DECchip
+21040, 21140, 21143
+.Pc ;
+values are: auto, BNC, AUI, Twisted-Pair, FastFD
+.Pq Fast Full Duplex .
+.It Ev ew*0_protocols
+the protocol to use when netbooting, i.e. MOP
+.Pq Maintenance Operations Protocol ,
+or BOOTP.
+.El
+.Ss After bootstrap
+.Pp
+Once the