1.\" $NetBSD: wscons.4,v 1.31 2012/06/05 08:49:16 abs Exp $ 2.\" 3.\" Copyright (c) 1999, 2004 The NetBSD Foundation, Inc. 4.\" All rights reserved. 5.\" 6.\" Redistribution and use in source and binary forms, with or without 7.\" modification, are permitted provided that the following conditions 8.\" are met: 9.\" 1. Redistributions of source code must retain the above copyright 10.\" notice, this list of conditions and the following disclaimer. 11.\" 2. Redistributions in binary form must reproduce the above copyright 12.\" notice, this list of conditions and the following disclaimer in the 13.\" documentation and/or other materials provided with the distribution. 14.\" 15.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS 16.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED 17.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 18.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS 19.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 20.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 21.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 22.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 23.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 24.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 25.\" POSSIBILITY OF SUCH DAMAGE. 26.\" 27.Dd June 5, 2012 28.Dt WSCONS 4 29.Os 30.Sh NAME 31.Nm wscons 32.Nd workstation console access 33.Sh SYNOPSIS 34.Cd options WSEMUL_SUN 35.Cd options WSEMUL_VT100 36.Cd options WSEMUL_NO_DUMB 37.Cd options WSEMUL_DEFAULT=\&"xxx\&" 38.Cd options WS_DEFAULT_FG=WSCOL_XXX 39.Cd options WS_DEFAULT_BG=WSCOL_XXX 40.Cd options WS_DEFAULT_COLATTR=\&"(WSATTR_XXX | WSATTR_YYY)" 41.Cd options WS_DEFAULT_MONOATTR=\&"(WSATTR_XXX | WSATTR_YYY)" 42.Cd options WS_KERNEL_FG=WSCOL_XXX 43.Cd options WS_KERNEL_BG=WSCOL_XXX 44.Cd options WS_KERNEL_COLATTR=\&"(WSATTR_XXX | WSATTR_YYY)" 45.Cd options WS_KERNEL_MONOATTR=\&"(WSATTR_XXX | WSATTR_YYY)" 46.Cd options WSCOMPAT_USL_SYNCTIMEOUT=nnn 47.Cd options WSDISPLAY_COMPAT_PCVT 48.Cd options WSDISPLAY_COMPAT_SYSCONS 49.Cd options WSDISPLAY_COMPAT_USL 50.Cd options WSDISPLAY_COMPAT_RAWKBD 51.Cd options WSKBD_EVENT_AUTOREPEAT 52.Cd options WSKBD_USONLY 53.Pp 54.Cd "wsdisplay* at ..." 55.Cd "wskbd* at ... mux N" 56.Cd "wsmouse* at ... mux N" 57.Pp 58.Cd pseudo-device wsmux N 59.Sh DESCRIPTION 60The 61.Nm 62driver provides support for machine independent access to the console. 63.Pp 64.Nm 65is made of a number of cooperating modules, in particular 66.Bl -bullet 67.It 68hardware support for display adapters, keyboards and mice, see 69.Xr wsdisplay 4 , 70.Xr wskbd 4 , and 71.Xr wsmouse 4 72.It 73input event multiplexor, see 74.Xr wsmux 4 75.It 76terminal emulation modules (see below), and 77.It 78compatibility options to support control operations and other low-level 79behaviour of existing terminal drivers (see below) 80.El 81.Ss Terminal emulations 82.Nm 83does not define its own set of terminal control sequences and special keyboard 84codes in terms of 85.Xr terminfo 5 . 86Instead a 87.Dq terminal emulation 88is assigned to each virtual screen when the screen is created. 89(See 90.Xr wsconscfg 8 . ) 91Different terminal emulations can be active at the same time on one display. 92The following choices are available: 93.Bl -tag -width xxxxxx 94.It dumb 95This minimal terminal support is available unless the kernel option 96.Cd options WSEMUL_NO_DUMB 97was specified at build time. 98No control sequences are supported besides the ASCII control characters. 99The cursor is not addressable. 100Only ASCII 101keyboard codes will be delivered, cursor and functions keys do not work. 102.It sun 103The 104.Dq sun 105console emulation is available if 106.Cd options WSEMUL_SUN 107was specified at kernel build time. 108It supports the control sequences of 109.Tn SUN 110machine consoles and delivers its keyboard codes for function and 111keypad keys in use. 112This emulation is sufficient for full-screen applications. 113.It vt100 114is available with the kernel compile option 115.Cd options WSEMUL_VT100 . 116It provides the most commonly used functions of 117.Tn DEC VT100 118terminals with some extensions introduced by the 119.Tn DEC VT220 120and 121.Tn DEC VT320 122models. 123The features of the original 124.Tn VT100 125which are not or not completely implemented are: 126.Bl -bullet 127.It 128.Tn VT52 129support, 132-column-mode, smooth scroll, light background, keyboard 130autorepeat control, external printer support, keyboard locking, 131newline/linefeed switching: Escape sequences related 132to these features are ignored or answered with standard replies. 133(DECANM, DECCOLM, DECSCLM, DECSCNM, DECARM, DECPFF, DECPEX, KAM, LNM) 134.It 135Function keys are not reprogrammable and fonts can not be downloaded. 136DECUDK and DECDLD sequences will be ignored. 137.It 138Neither C1 control set characters will be recognized nor will 8-bit keyboard 139codes be delivered. 140.It 141The 142.Dq DEC supplemental graphic 143font is approximated by the ISO-latin-1 font, though there are 144subtle differences. 145.It 146The actual rendering quality depends on the underlying graphics hardware 147driver. 148Characters might be missing in the available fonts and be 149substituted by more or less fitting replacements. 150.Pp 151Depending on the keyboard used, not all function keys might be available. 152.El 153.Pp 154In addition to the plain 155.Tn VT100 156functions are supported: 157.Bl -bullet 158.It 159ANSI colors. 160.It 161Some 162.Tn VT220 163-like presentation state settings and -reports (DECRSPS), especially 164tabulator settings. 165.El 166.Pp 167In most applications, 168.Nm 169will work sufficiently as a 170.Tn VT220 171emulator. 172.El 173.Pp 174The 175.Va WSEMUL_DEFAULT 176kernel option is used to select one of the described terminal options 177as the default choice. 178The default takes effect at kernel startup, i.e. for the operating 179system console or additional screens allocated through the 180.Va WSDISPLAY_DEFAULTSCREENS 181option (see 182.Xr wsdisplay 4 ) , 183or if no emulation type was passed to the 184.Xr wsconscfg 8 185utility. 186.Ss Compatibility options 187these options allow X servers and other programs using low-level 188console driver functions usually written specifically for other 189console drivers to run on 190.Nx 191systems. 192The options are in particular: 193.Bl -tag -width xxxxxxxx 194.It Cd WSDISPLAY_COMPAT_USL 195Support the protocol for switches between multiple virtual screens on 196one display as used by most PC-UNIX variants. 197This is used by the 198.Nx 199.Xr wsconscfg 8 200utility. 201.It Cd WSDISPLAY_COMPAT_RAWKBD 202Allows to get raw XT keyboard scancodes from PC keyboards as needed 203by i386 X servers. 204.It Cd WSDISPLAY_COMPAT_PCVT 205Emulates enough of the 206.Nx Ns /i386 207.Dq pcvt 208driver to make X servers work. 209.It Cd WSDISPLAY_COMPAT_SYSCONS 210Emulates enough of the 211.Fx 212.Dq syscons 213driver to make X servers work. 214Useful with 215.Fx 216binary emulation. 217.El 218.Pp 219Linux/i386 X servers usually run successfully if the first two options are 220enabled together with the 221.Nx 222Linux binary emulation. 223.Pp 224(To have programs looking for device special files of other console drivers 225find the 226.Nm 227driver entry points, symlinks are a helpful measure.) 228.Ss Other options 229.Bl -tag -width xxxxxxxx 230.It Cd options WS_DEFAULT_FG=WSCOL_XXX , 231.It Cd options WS_DEFAULT_BG=WSCOL_XXX , 232.It Cd options \&WS_DEFAULT_COLATTR="(WSATTR_XXX | WSATTR_YYY)" 233and 234.It Cd options \&WS_DEFAULT_MONOATTR="(WSATTR_XXX | WSATTR_YYY)" 235allow to make default console output appear in specific colors and 236attributes. 237.Dq WS_DEFAULT_FG 238and 239.Dq WS_DEFAULT_BG 240set the foreground / background used on color displays. 241The 242.Dq WSCOL_XXX 243arguments are colors as defined in 244.Pa src/sys/dev/wscons/wsdisplayvar.h . 245.Dq WS_DEFAULT_COLATTR 246and 247.Dq WS_DEFAULT_MONOATTR 248are additional attribute flags used on color or monochrome displays, 249respectively. 250The arguments are defined in the same header file. 251Whether the attributes 252are supported or not depends on the actually used graphics adapter. 253These options are ignored by the 254.Dq dumb 255terminal emulation. 256.It Cd options WS_KERNEL_FG=WSCOL_XXX , 257.It Cd options WS_KERNEL_BG=WSCOL_XXX , 258.It Cd options \&WS_KERNEL_COLATTR="(WSATTR_XXX | WSATTR_YYY)" 259and 260.It Cd options \&WS_KERNEL_MONOATTR="(WSATTR_XXX | WSATTR_YYY)" 261allow to make console output originating from the kernel appear differently 262than output from user level programs (via 263.Pa /dev/console 264or the specific tty 265device like 266.Pa /dev/ttyE0 ) . 267Their meaning is the same as their 268.Sq WS_DEFAULT_* 269counterparts. 270.It Cd options WSCOMPAT_USL_SYNCTIMEOUT=nnn 271The virtual screen switching protocol enabled by 272.Dq WSDISPLAY_COMPAT_USL 273uses a somewhat complex handshake protocol to pass control to user programs 274such as X servers controlling a virtual screen. 275In order to prevent a non-responsive 276application from locking the whole console system, 277a screen switch will be rolled 278back after a 5 second timeout if the application does not respond. 279This option can be used to specify in seconds a different timeout value. 280.It Cd options WSKBD_EVENT_AUTOREPEAT 281If set, this option enables auto repeat even in event mode. 282The auto repeat will generate key down events while the key is pressed. 283.It Cd options WSKBD_USONLY 284In order to strip down the space usage of wscons, 285all keymaps except the US english one can be removed from the kernel 286with this option, which results in a space gain of about 10kB. 287.El 288.Sh SEE ALSO 289.Xr wsdisplay 4 , 290.Xr wskbd 4 , 291.Xr wsmouse 4 , 292.Xr wsmux 4 , 293.Xr wsconscfg 8 , 294.Xr wsconsctl 8 , 295.Xr wsfontload 8 , 296.Xr wscons 9 297