share/man/man4/wscons.4

   1 .\" $NetBSD: wscons.4,v 1.27 2005/05/04 10:54:51 augustss 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 May 4, 2005
  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
  60 The
  61 .Nm
  62 driver provides support for machine independent access to the console.
  63 .Pp
  64 .Nm
  65 is made of a number of cooperating modules, in particular
  66 .Bl -bullet
  67 .It
  68 hardware support for display adapters, keyboards and mice, see
  69 .Xr wsdisplay 4 ,
  70 .Xr wskbd 4 , and
  71 .Xr wsmouse 4
  72 .It
  73 input event multiplexor, see
  74 .Xr wsmux 4
  75 .It
  76 terminal emulation modules (see below), and
  77 .It
  78 compatibility options to support control operations and other low-level
  79 behaviour of existing terminal drivers (see below)
  80 .El
  81 .Ss Terminal emulations
  82 .Nm
  83 does not define its own set of terminal control sequences and special keyboard
  84 codes in terms of
  85 .Xr termcap 5 .
  86 Instead a
  87 .Dq terminal emulation
  88 is assigned to each virtual screen when the screen is created. (See
  89 .Xr wsconscfg 8 . )
  90 Different terminal emulations can be active at the same time on one display.
  91 The following choices are available:
  92 .Bl -tag -width xxxxxx
  93 .It dumb
  94 This minimal terminal support is available unless the kernel option
  95 .Cd options WSEMUL_NO_DUMB
  96 was specified at build time. No control sequences are supported besides
  97 the ASCII control characters. The cursor is not addressable. Only ASCII
  98 keyboard codes will be delivered, cursor and functions keys do not work.
  99 .It sun
 100 The
 101 .Dq sun
 102 console emulation is available if
 103 .Cd options WSEMUL_SUN
 104 was specified at kernel build time. It supports the control sequences of
 105 .Tn SUN
 106 machine consoles and delivers its keyboard codes for function and
 107 keypad keys in use.
 108 This emulation is sufficient for full-screen applications.
 109 .It vt100
 110 is available with the kernel compile option
 111 .Cd options WSEMUL_VT100 .
 112 It provides the most commonly used functions of
 113 .Tn DEC VT100
 114 terminals with some extensions introduced by the
 115 .Tn DEC VT220
 116 and
 117 .Tn DEC VT320
 118 models. The features of the original
 119 .Tn VT100
 120 which are not or not completely implemented are:
 121 .Bl -bullet
 122 .It
 123 .Tn VT52
 124 support, 132-column-mode, smooth scroll, light background, keyboard
 125 autorepeat control, external printer support, keyboard locking,
 126 newline/linefeed switching: Escape sequences related
 127 to these features are ignored or answered with standard replies.
 128 (DECANM, DECCOLM, DECSCLM, DECSCNM, DECARM, DECPFF, DECPEX, KAM, LNM)
 129 .It
 130 Function keys are not reprogrammable and fonts can not be downloaded.
 131 DECUDK and DECDLD sequences will be ignored.
 132 .It
 133 Neither C1 control set characters will be recognized nor will 8-bit keyboard
 134 codes be delivered.
 135 .It
 136 The
 137 .Dq DEC supplemental graphic
 138 font is approximated by the ISO-latin-1 font, though there are
 139 subtle differences.
 140 .It
 141 The actual rendering quality depends on the underlying graphics hardware
 142 driver. Characters might be missing in the available fonts and be
 143 substituted by more or less fitting replacements.
 144 .Pp
 145 Depending on the keyboard used, not all function keys might be available.
 146 .El
 147 .Pp
 148 In addition to the plain
 149 .Tn VT100
 150 functions are supported:
 151 .Bl -bullet
 152 .It
 153 ANSI colors.
 154 .It
 155 Some
 156 .Tn VT220
 157 -like presentation state settings and -reports (DECRSPS), especially
 158 tabulator settings.
 159 .El
 160 .Pp
 161 In most applications,
 162 .Nm
 163 will work sufficiently as a
 164 .Tn VT220
 165 emulator.
 166 .El
 167 .Pp
 168 The
 169 .Va WSEMUL_DEFAULT
 170 kernel option is used to select one of the described terminal options
 171 as the default choice. The default takes effect at kernel startup, i.e.
 172 for the operating system console or additional screens allocated
 173 through the
 174 .Va WSDISPLAY_DEFAULTSCREENS
 175 option (see
 176 .Xr wsdisplay 4 ) ,
 177 or if no emulation type was passed to the
 178 .Xr wsconscfg 8
 179 utility.
 180 .Ss Compatibility options
 181 these options allow X servers and other programs using low-level
 182 console driver functions which were written specifically for other
 183 console drivers to run on
 184 .Nx
 185 systems. The options are in particular:
 186 .Bl -tag -width xxxxxxxx
 187 .It Cd WSDISPLAY_COMPAT_USL
 188 Support the protocol for switches between multiple virtual screens on
 189 one display as used by most PC-UNIX variants.
 190 .It Cd WSDISPLAY_COMPAT_RAWKBD
 191 Allows to get raw XT keyboard scancodes from PC keyboards as needed
 192 by i386 X servers.
 193 .It Cd WSDISPLAY_COMPAT_PCVT
 194 Emulates enough of the
 195 .Nx Ns /i386
 196 .Dq pcvt
 197 driver to make X servers work.
 198 .It Cd WSDISPLAY_COMPAT_SYSCONS
 199 Emulates enough of the
 200 .Fx
 201 .Dq syscons
 202 driver to make X servers work. Useful with
 203 .Fx
 204 binary emulation.
 205 .El
 206 .Pp
 207 Linux/i386 X servers usually run successfully if the first two options are
 208 enabled together with the
 209 .Nx
 210 Linux binary emulation.
 211 .Pp
 212 (To have programs looking for device special files of other console drivers
 213 find the
 214 .Nm
 215 driver entry points, symlinks are a helpful measure.)
 216 .Ss Other options
 217 .Bl -tag -width xxxxxxxx
 218 .It Cd options WS_DEFAULT_FG=WSCOL_XXX ,
 219 .It Cd options WS_DEFAULT_BG=WSCOL_XXX ,
 220 .It Cd options \&WS_DEFAULT_COLATTR="(WSATTR_XXX | WSATTR_YYY)"
 221 and
 222 .It Cd options \&WS_DEFAULT_MONOATTR="(WSATTR_XXX | WSATTR_YYY)"
 223 allow to make default console output appear in specific colors and
 224 attributes.
 225 .Dq WS_DEFAULT_FG
 226 and
 227 .Dq WS_DEFAULT_BG
 228 set the foreground / background used on color displays. The
 229 .Dq WSCOL_XXX
 230 arguments are colors as defined in
 231 .Pa src/sys/dev/wscons/wsdisplayvar.h .
 232 .Dq WS_DEFAULT_COLATTR
 233 and
 234 .Dq WS_DEFAULT_MONOATTR
 235 are additional attribute flags used on color or monochrome displays,
 236 respectively.
 237 The arguments are defined in the same header file.
 238 Whether the attributes
 239 are supported or not depends on the actually used graphics adapter.
 240 These options are ignored by the
 241 .Dq dumb
 242 terminal emulation.
 243 .It Cd options WS_KERNEL_FG=WSCOL_XXX ,
 244 .It Cd options WS_KERNEL_BG=WSCOL_XXX ,
 245 .It Cd options \&WS_KERNEL_COLATTR="(WSATTR_XXX | WSATTR_YYY)"
 246 and
 247 .It Cd options \&WS_KERNEL_MONOATTR="(WSATTR_XXX | WSATTR_YYY)"
 248 allow to make console output originating from the kernel appear differently
 249 than output from user level programs (via
 250 .Pa /dev/console
 251 or the specific tty
 252 device like
 253 .Pa /dev/ttyE0 ) .
 254 Their meaning is the same as their
 255 .Sq WS_DEFAULT_*
 256 counterparts.
 257 .It Cd options WSCOMPAT_USL_SYNCTIMEOUT=nnn
 258 The virtual screen switching protocol enabled by
 259 .Dq WSDISPLAY_COMPAT_USL
 260 uses a somewhat complex handshake protocol to pass control to user programs
 261 such as X servers controlling a virtual screen. In order
 262 to prevent a non-responsive
 263 application from locking the whole console system,
 264 a screen switch will be rolled
 265 back after a 5 second timeout if the application does not respond.
 266 This option can be used to specify in seconds a different timeout value.
 267 .It Cd options WSKBD_EVENT_AUTOREPEAT
 268 If set, this option enables auto repeat even in event mode.
 269 The auto repeat will generate key down events while the key is pressed.
 270 .It Cd options WSKBD_USONLY
 271 In order to strip down the space usage of wscons,
 272 all keymaps except the US english one can be removed from the kernel
 273 with this option, which results in a space gain of about 10kB.
 274 .El
 275 .Sh SEE ALSO
 276 .Xr wsdisplay 4 ,
 277 .Xr wskbd 4 ,
 278 .Xr wsmouse 4 ,
 279 .Xr wsmux 4 ,
 280 .Xr wsconscfg 8 ,
 281 .Xr wsconsctl 8 ,
 282 .Xr wsfontload 8 ,
 283 .Xr wscons 9