NetBSD/share/man/man8/man8.i386/boot_console.8

.\"	$NetBSD: boot_console.8,v 1.13 2004/07/03 20:04:03 mycroft Exp $
.\"
.\" Copyright (c) 1997
.\" 	Matthias Drochner.  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 AND CONTRIBUTORS ``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 OR CONTRIBUTORS 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 July 3, 2004
.Os
.Dt BOOT_CONSOLE 8 i386
.Sh NAME
.Nm boot_console
.Nd selection of a console device in the i386 bootloader
.\"
.Sh DESCRIPTION
The
.Nx
i386 bootloader selects a console device for its user interaction and
passes information about it to the
.Nx
kernel.
When booting from the system BIOS, the console device and properties
are saved in the primary bootstrap by
.Xr installboot 8 .
For other boot procedures (such as
.Xr dosboot 8 )
the selection process is controlled by bootloader compile-time
options and system setup at the bootloader startup time.
The selection may be changed on-the-fly from within the bootloader.
.\"
.Ss Serial Console Options
The compile-time options (to be set in the booter's
.Dq Makefile )
are:
.Bl -ohang
.It Sy SUPPORT_SERIAL= Ns Fa policy
enables support for serial input/output.
By default this option is
not set and the standard PC keyboard and display are always used as the
console device.
See
.Sx Console Selection Policy
below for valid values of
.Fa policy .
.It Sy DIRECT_SERIAL
causes direct hardware access to be used for serial input / output.
With this option, software handshake (XON/XOFF) is used for flow
control.
Without this option, BIOS functions are employed for serial
port handling, which require hardware handshake lines to be completely
wired.
.It Sy CONSPEED= Ns Fa integer
sets the baud-rate for the serial console.
This option has only an effect when used in combination with the
.Dq Dv DIRECT_SERIAL
option above, otherwise, the default setting of 9600 baud is used.
The value of
.Fa integer
must be something that makes sense as a serial port baud rate.
.It Sy COMCONS_KEYPRESS
Require a character input within seven (7) seconds from serial console
device to be selected.
.El
.\"
.Ss Console Selection Policy
The actual policy for the console selection is determined by the value
of
.Dq Dv SUPPORT_SERIAL
The following options are available:
.Bl -ohang
.It Em CONSDEV_PC
Force use of the standard PC keyboard and display as the console.
.It Em CONSDEV_COM0 Li ... Em CONSDEV_COM3
Use the serial port with the corresponding BIOS number as the console.
No attempt is made to verify connectivity on the selected port.
If the port is not known to the BIOS, it falls back to
.Dq Dv CONSDEV_PC .
(Note: This feature can be deliberately used for console selection if
the serial ports have been disabled in the BIOS.)
.It Em CONSDEV_COM0KBD Li ... Em CONSDEV_COM3KBD
If the port is known to the BIOS, and output of a character to the port
succeeds (and if
.Dq Dv DIRECT_SERIAL
is defined the RS-232
.Dq "modem ready"
status is on after the character is output), the port is used as
console.
If the port is not known to the BIOS, or the test output fails, it falls back
to
.Dq Dv CONSDEV_PC .
.It Em CONSDEV_AUTO
Auto-select the console.
All serial ports known to the BIOS are probed in sequence.
If output of a character to the port succeeds (and if
.Dq Dv DIRECT_SERIAL
is defined the RS-232
.Dq "modem ready"
status is on after the character is output), the port is used as console.
If no serial port passes the check,
.Dq Dv CONSDEV_PC
is used.
The progress of the selection process is shown at the PC display as
digits corresponding to the serial port number currently probed.
.El
.\"
.Sh FILES
.Bl -tag -width /sys/arch/i386/stand/{bios,dos,net}boot/Makefile
.It Pa /sys/arch/i386/stand/{bios,dos,net}boot/Makefile
compile time options for the boot programs.
.El
.\"
.Sh SEE ALSO
.Xr console 4 ,
.Xr boot 8 ,
.Xr installboot 8
.\"
.Sh BUGS
The value of
.Dv SERIAL_POLICY
should be settable through a boot configuration option.
However traditionally there was no non-volatile storage available on the
PC platform.
This requires console auto-selection methods which can be
inconvenient and/or unstable in some situations.
The selection policy should be adapted to the local hardware configuration,
which might require code changes.
(Some BIOS versions, particularly those used on
large servers and in embedded and single-board industrial computers,
have integrated support for serial consoles.
The boot loader should query for these settings if possible.)
.Pp
The serial communication parameters (byte-size, parity, stop-bits) are
not settable (either at compile time or run time).
The default parameters are
.Dq "8 N 1" .
.Pp
The baud rate is not settable when using BIOS I/O.
It should be settable at compile time with
.Dq Dv CONSPEED
just as it is when using
.Dq Dv DIRECT_SERIAL .
The default speed is 9600 baud (the maximum for BIOS I/O).