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