.\"	$OpenBSD: boot_cats.8,v 1.5 2004/12/27 16:41:12 miod Exp $
.\"
.\" Copyright (c) 2004, Miodrag Vallat.
.\" 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. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\"
.\" 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 13, 2004
.Dt BOOT_CATS 8 cats
.Os
.Sh NAME
.Nm boot_cats
.Nd CATS system bootstrapping procedures
.Sh DESCRIPTION
.Ss System startup
When powered on, after a panic, or if the system is rebooted via
.Xr reboot 8
or
.Xr shutdown 8 ,
the Cyclone or ABLE firmware will proceed to its initialization,
and will try to boot an operating system if autoboot is enabled.
Cyclone firmware must be upgraded to ABLE before
.Ox
can be run.
.Ss Boot process options
The ABLE firmware will attempt to boot the commandline stored in the
.Em boot.cmd
environment variable, such as
.Dq (hd0)bsd -f .
Autoboot is enabled by setting the
.Em boot.auto
environment variable to
.Sq true ,
and will start after
.Em boot.timeout
seconds.
.Pp
The kernel can be passed arguments on the commandline.
The expected syntax for
.Ox
kernel parameters is one or more option letters from the following list,
prefixed by a dash
.Pq - :
.Bl -tag -width "XXX" -offset indent -compact
.Pp
.It Cm a
Prompt for the root filesystem device after the devices have been configured.
.It Cm c
Enter the
.Dq User Kernel Configuration
mode upon startup
.Pq Xr boot_config 8 .
.It Cm d
Enter the debugger,
.Xr ddb 4 ,
as soon as the kernel console has been initialized.
.It Cm f
Use the
.Xr footbridge 4
serial port
.Pq Xr fcom 4
as the console.
.It Cm s
Boot the system single-user.
.It Cm v
Use the
.Xr vga 4
graphics display as the console, if available.
.El
.Ss Abnormal system termination
In case of system crashes, the kernel will usually enter the kernel
debugger,
.Xr ddb 4 ,
unless it is not present in the kernel, or it is disabled via the
.Em ddb.panic
sysctl.
Upon leaving ddb, or if ddb was not entered, the kernel will halt the system
if it was still in device configuration phase, or attempt a dump to the
configured dump device, if possible.
The crash dump will then be recovered by
.Xr savecore 8
during the next multi-user boot cycle.
It is also possible to force other behaviours from ddb.
.Sh FILES
.Bl -tag -width /bsd.rd -compact
.It Pa /bsd
default system kernel
.It Pa /bsd.rd
standalone installation kernel, suitable for disaster recovery
.El
.Sh SEE ALSO
.Xr ddb 4 ,
.Xr boot_config 8 ,
.Xr halt 8 ,
.Xr init 8 ,
.Xr reboot 8 ,
.Xr savecore 8 ,
.Xr shutdown 8
.Sh CAVEATS
.Tn ABLE
is not able to access or boot off
.Ox
FFS partitions on some disks.
This can be helped by forcing smaller disk access, by setting the
.Em ide.multi-limit
nvram variable to a small integer value.
A value of
.Ar 1
ought to work in all cases.