.\" $NetBSD: wscons.4,v 1.37 2018/01/13 23:43:46 wiz Exp $
.\"
.\" Copyright (c) 1999, 2004 The NetBSD Foundation, Inc.
.\" 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 NETBSD FOUNDATION, INC. 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 FOUNDATION 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 June 5, 2012
.Dt WSCONS 4
.Os
.Sh NAME
.Nm wscons
.Nd workstation console access
.Sh SYNOPSIS
.Cd "wsdisplay* at ..."
.Cd "wskbd*     at ... mux N"
.Cd "wsmouse*   at ... mux N"
.Pp
.Cd pseudo-device wsmux
.Pp
.Cd options WSEMUL_SUN
.Cd options WSEMUL_VT100
.Cd options WSEMUL_NO_DUMB
.Cd options WSEMUL_DEFAULT=\*qxxx\*q
.Pp
.Cd options WS_DEFAULT_FG=WSCOL_XXX
.Cd options WS_DEFAULT_BG=WSCOL_XXX
.Cd options WS_DEFAULT_COLATTR=\*q(WSATTR_XXX\ |\ WSATTR_YYY)\*q
.Cd options WS_DEFAULT_MONOATTR=\*q(WSATTR_XXX\ |\ WSATTR_YYY)\*q
.Cd options WS_KERNEL_FG=WSCOL_XXX
.Cd options WS_KERNEL_BG=WSCOL_XXX
.Cd options WS_KERNEL_COLATTR=\*q(WSATTR_XXX\ |\ WSATTR_YYY)\*q
.Cd options WS_KERNEL_MONOATTR=\*q(WSATTR_XXX\ |\ WSATTR_YYY)\*q
.Pp
.Cd options WSDISPLAY_COMPAT_PCVT
.Cd options WSDISPLAY_COMPAT_SYSCONS
.Cd options WSDISPLAY_COMPAT_USL
.Cd options WSCOMPAT_USL_SYNCTIMEOUT=nnn
.Cd options WSDISPLAY_COMPAT_RAWKBD
.Pp
.Cd options WSKBD_EVENT_AUTOREPEAT
.Cd options WSKBD_USONLY
.Sh DESCRIPTION
The
.Nm
driver provides support for machine independent access to the console.
.Pp
.Nm
is made of a number of cooperating modules, in particular
.Bl -bullet
.It
hardware support for display adapters, keyboards and mice, see
.Xr wsdisplay 4 ,
.Xr wskbd 4 ,
and
.Xr wsmouse 4
.It
input event multiplexor, see
.Xr wsmux 4
.It
terminal emulation modules (see below), and
.It
compatibility options to support control operations and other low-level
behaviour of existing terminal drivers (see below)
.El
.Ss Terminal emulations
.Nm
does not define its own set of terminal control sequences and special keyboard
codes in terms of
.Xr terminfo 5 .
Instead a
.Dq terminal emulation
is assigned to each virtual screen when the screen is created.
(See
.Xr wsconscfg 8 . )
Different terminal emulations can be active at the same time on one display.
The following choices are available:
.Bl -tag -width xxxxxx
.It dumb
This minimal terminal support is available unless the kernel option
.Cd options WSEMUL_NO_DUMB
was specified at build time.
No control sequences are supported besides the ASCII control characters.
The cursor is not addressable.
Only ASCII
keyboard codes will be delivered, cursor and functions keys do not work.
.It sun
The
.Dq sun
console emulation is available if
.Cd options WSEMUL_SUN
was specified at kernel build time.
It supports the control sequences of SUN
machine consoles and delivers its keyboard codes for function and
keypad keys in use.
This emulation is sufficient for full-screen applications.
.It vt100
is available with the kernel compile option
.Cd options WSEMUL_VT100 .
It provides the most commonly used functions of DEC VT100
terminals with some extensions introduced by the DEC VT220
and DEC VT320 models.
The features of the original VT100
which are not or not completely implemented are:
.Bl -bullet
.It
VT52 support, 132-column-mode, smooth scroll, light background, keyboard
autorepeat control, external printer support, keyboard locking,
newline/linefeed switching: Escape sequences related
to these features are ignored or answered with standard replies.
(DECANM, DECCOLM, DECSCLM, DECSCNM, DECARM, DECPFF, DECPEX, KAM, LNM)
.It
Function keys are not reprogrammable and fonts can not be downloaded.
DECUDK and DECDLD sequences will be ignored.
.It
Neither C1 control set characters will be recognized nor will 8-bit keyboard
codes be delivered.
.It
The
.Dq DEC supplemental graphic
font is approximated by the ISO-latin-1 font, though there are
subtle differences.
.It
The actual rendering quality depends on the underlying graphics hardware
driver.
Characters might be missing in the available fonts and be
substituted by more or less fitting replacements.
.Pp
Depending on the keyboard used, not all function keys might be available.
.El
.Pp
In addition to the plain VT100 functions are supported:
.Bl -bullet
.It
ANSI colors.
.It
Some VT220-like presentation state settings and -reports (DECRSPS), especially
tabulator settings.
.El
.Pp
In most applications,
.Nm
will work sufficiently as a VT220 emulator.
.El
.Pp
The
.Dv WSEMUL_DEFAULT
kernel option is used to select one of the described terminal options
as the default choice.
The default takes effect at kernel startup, i.e. for the operating
system console or additional screens allocated through the
.Dv WSDISPLAY_DEFAULTSCREENS
option (see
.Xr wsdisplay 4 ) ,
or if no emulation type was passed to the
.Xr wsconscfg 8
utility.
.Ss Compatibility options
These options allow X servers and other programs using low-level
console driver functions usually written specifically for other
console drivers to run on
.Nx
systems.
The options are in particular:
.Bl -tag -width xxxxxxxx
.It Cd WSDISPLAY_COMPAT_USL
Support the protocol for switches between multiple virtual screens on
one display as used by most PC-UNIX variants.
This is used by the
.Nx
.Xr wsconscfg 8
utility.
.It Cd WSDISPLAY_COMPAT_RAWKBD
Allows to get raw XT keyboard scancodes from PC keyboards as needed
by i386 X servers.
.It Cd WSDISPLAY_COMPAT_PCVT
Emulates enough of the
.Nx Ns /i386
.Dq pcvt
driver to make X servers work.
.It Cd WSDISPLAY_COMPAT_SYSCONS
Emulates enough of the
.Fx
.Dq syscons
driver to make X servers work.
Useful with
.Fx
binary emulation.
.El
.Pp
Linux/i386 X servers usually run successfully if the first two options are
enabled together with the
.Nx
Linux binary emulation.
.Pp
(To have programs looking for device special files of other console drivers
find the
.Nm
driver entry points, symlinks are a helpful measure.)
.Ss Other options
.Bl -tag -width xxxxxxxx -compact
.It Cd options WS_DEFAULT_FG=WSCOL_XXX
.It Cd options WS_DEFAULT_BG=WSCOL_XXX
.It Cd options WS_DEFAULT_COLATTR=\*q(WSATTR_XXX\ |\ WSATTR_YYY)\*q
.It Cd options WS_DEFAULT_MONOATTR=\*q(WSATTR_XXX\ |\ WSATTR_YYY)\*q
Make default console output appear in specific colors and attributes.
.Dv WS_DEFAULT_FG
and
.Dv WS_DEFAULT_BG
set the foreground and background used on color displays.
.Dv WS_DEFAULT_COLATTR
and
.Dv WS_DEFAULT_MONOATTR
are additional attribute flags used on color or monochrome displays,
respectively.
Whether the attributes
are supported or not depends on the actually used graphics adapter.
These options are ignored by the
.Dq dumb
terminal emulation.
.Pp
See
.Pa src/sys/dev/wscons/wsdisplayvar.h
for available
.Dv WSCOL_XXX
and
.Dv WSATTR_XXX
values.
.Pp
.It Cd options WS_KERNEL_FG=WSCOL_XXX
.It Cd options WS_KERNEL_BG=WSCOL_XXX
.It Cd options WS_KERNEL_COLATTR=\*q(WSATTR_XXX\ |\ WSATTR_YYY)\*q
.It Cd options WS_KERNEL_MONOATTR=\*q(WSATTR_XXX\ |\ WSATTR_YYY)\*q
Make console output originating from the kernel appear differently
than output from user level programs (via
.Pa /dev/console
or the specific tty
device like
.Pa /dev/ttyE0 ) .
Their meaning is the same as their
.Dv WS_DEFAULT_*
counterparts.
.Pp
.It Cd options WSCOMPAT_USL_SYNCTIMEOUT=nnn
The virtual screen switching protocol enabled by
.Dv WSDISPLAY_COMPAT_USL
uses a somewhat complex handshake protocol to pass control to user programs
such as X servers controlling a virtual screen.
In order to prevent a non-responsive
application from locking the whole console system,
a screen switch will be rolled
back after a 5 second timeout if the application does not respond.
This option can be used to specify in seconds a different timeout value.
.Pp
.It Cd options WSKBD_EVENT_AUTOREPEAT
If set, this option enables auto repeat even in event mode.
The auto repeat will generate key down events while the key is pressed.
.Pp
.It Cd options WSKBD_USONLY
In order to strip down the space usage of wscons,
all keymaps except the US english one can be removed from the kernel
with this option, which results in a space gain of about 10kB.
.El
.Sh SEE ALSO
.Xr wsdisplay 4 ,
.Xr wskbd 4 ,
.Xr wsmouse 4 ,
.Xr wsmux 4 ,
.Xr wsconscfg 8 ,
.Xr wsconsctl 8 ,
.Xr wsfontload 8 ,
.Xr wscons 9