xref: /freebsd/share/man/man4/syscons.4 (revision 7f3dea244c40159a41ab22da77a434d7c5b5e85a)
1.\"
2.\" Copyright (c) 1999
3.\" Kazutaka YOKOTA <yokota@zodiac.mech.utsunomiya-u.ac.jp>
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 as
11.\"    the first lines of this file unmodified.
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 AUTHOR ``AS IS'' AND ANY EXPRESS OR
17.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
18.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
19.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
20.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
21.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
22.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
23.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
24.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
25.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
26.\"
27.\" $FreeBSD$
28.\"
29.Dd June 30, 1999
30.Dt SYSCONS 4
31.Os FreeBSD
32.Sh NAME
33.Nm syscons ,
34.Nm sc
35.Nd
36the console driver
37.Sh SYNOPSIS
38.Cd "options MAXCONS=N"
39.Cd "options SC_ALT_MOUSE_IMAGE"
40.Cd "options SC_DISABLE_DDBKEY"
41.Cd "options SC_DISABLE_REBOOT"
42.Cd "options SC_HISTORY_SIZE=N"
43.Cd "options SC_MOUSE_CHAR=C"
44.Cd "options SC_NO_CUTPASTE"
45.Cd "options SC_NO_FONT_LOADING"
46.Cd "options SC_NO_HISTORY"
47.Cd "options SC_NO_PALETTE_LOADING"
48.Cd "options SC_NO_SYSMOUSE"
49.Cd "options SC_PIXEL_MODE"
50.Cd "options SC_DFLT_FONT"
51.Cd "makeoptions SC_DFLT_FONT"=\&"_font_name_\&"
52.Cd "device sc0 at isa?"
53.Sh DESCRIPTION
54The
55.Nm
56driver provides multiple virtual terminals.
57It resembles the SCO color console driver.
58.Pp
59The
60.Nm
61driver is implemented on top of the keyboard driver
62.Pq Xr atkbd 4
63and the video card driver
64.Pq Xr vga 4
65and so requires both of them to be configured in the system.
66.Pp
67There can be only one
68.Nm
69device defined in the system.
70.Ss Virtual Terminals
71The
72.Nm
73driver provides multiple virtual terminals which appear as if they were
74separate terminals.
75One virtual terminal is considered current and exclusively
76occupies the screen and the keyboard; the other virtual terminals
77are placed in the background.
78.Pp
79In order to use virtual terminals, they must be individually
80marked ``on'' in
81.Pa /etc/ttys
82so that
83.Xr getty 8
84will recognize them to be active and run
85.Xr login 1
86to let the user to login to the system.
87By default, only the first eight virtual terminals are activated in
88.Pa /etc/ttys .
89.Pp
90You press the
91.Em Alt
92key and a switch key to switch between
93virtual terminals.
94The following table summarizes the correspondence between the switch
95key and the virtual terminal.
96.Bd -literal -offset indent
97Alt-F1   ttyv0      Alt-F7   ttyv6      Shift-Alt-F1   ttyv10
98Alt-F2   ttyv1      Alt-F8   ttyv7      Shift-Alt-F2   ttyv11
99Alt-F3   ttyv2      Alt-F9   ttyv8      Shift-Alt-F3   ttyv12
100Alt-F4   ttyv3      Alt-F10  ttyv9      Shift-Alt-F4   ttyv13
101Alt-F5   ttyv4      Alt-F11  ttyv10     Shift-Alt-F5   ttyv14
102Alt-F6   ttyv5      Alt-F12  ttyv11     Shift-Alt-F6   ttyv15
103.Ed
104.Pp
105You can also use the ``nscr'' key (usually the
106.Em PrintScreen
107key on the AT Enhanced keyboard) to cycle available virtual terminals.
108.Pp
109The default number of available virtual terminals is 16.
110This can be changed by the kernel configuration option
111.Em MAXCONS
112(see below).
113.Pp
114Note that the X server usually requires a virtual terminal for display
115purposes, so at least one terminal must be left unused by
116.Xr getty 8
117so that it can be used by the X server.
118.Ss Key Definitions and Function Key Strings
119The
120.Nm
121driver, in conjunction with the keyboard driver, allows the user
122to change key definitions and function key strings.
123The
124.Xr kbdcontrol 1
125command will load a key definition file (known as ``keymap'' file),
126dump the current keymap, and assign a string to a function key.
127See
128.Xr keyboard 4
129and
130.Xr keymap 5
131for the keymap file.
132.Pp
133You may want to set the
134.Ar keymap
135variable in
136.Pa /etc/rc.conf.local
137to the desired keymap file so that it will be automatically loaded
138when the system starts up.
139.Ss Software Font
140For most modern video cards, e.g. VGA, the
141.Nm
142driver and the video card driver allow the user to change
143the font used on the screen.
144The
145.Xr vidcontrol 1
146command can be used to load a font file from
147.Pa /usr/share/syscons/fonts .
148.Pp
149The font comes in various sizes: 8x8, 8x14 and 8x16.
150The 8x16 font is typically used for the VGA card in the 80-column-
151by-25-line mode.
152Other video modes may require different size of font.
153It is better to always load these three sizes of the same font.
154.Pp
155You may set
156.Ar font8x8 ,
157.Ar font8x14
158and
159.Ar font8x16
160variables in
161.Pa /etc/rc.conf.local
162to the desired font files so that they will be automatically loaded
163when the system starts up.
164.Pp
165Optionally you can make a particular font file as the default font.
166See the
167.Em SC_DFLT_FONT
168option below.
169.Ss Screen Map
170If your video card does not support software font, you may still be able
171to have similar effect by re-mapping font hard-wired in the video card.
172Use
173.Xr vidcontrol 1
174to load a screen map file which defines mapping between character codes.
175.Ss Mouse Support and Copy-and-Paste
176You can use your mouse to copy text on the screen and paste it as if
177it is typed by hand.
178You must be running the mouse daemon
179.Xr moused 8
180and enable the mouse cursor in the virtual terminal via
181.Xr vidcontrol 1 .
182.Pp
183Pressing the mouse button 1 (usually the left button) will start selection.
184Releasing the button 1 will end the selection process.
185The selected text will be marked by inverting foreground and
186background colors.
187You can press the button 3 (usually the right button) to extend
188the selected region.
189The selected text is placed in the copy buffer and can be pasted
190at the cursor position by your pressing the button 2 (usually the
191middle button) as many times as you like.
192.Ss Back Scrolling
193The
194.Nm
195driver allows the user to browse the output which has ``scrolled off''
196from the top of the screen.
197.Pp
198Press the ``slock'' key (usually
199.Em ScrllLock
200and/or
201.Em Pause
202keys on many AT Enhanced keyboards) and the terminal is
203in the ``back scrolling'' mode.
204It is indicated by the
205.Em Scroll Lock
206LED.
207Use arrow keys,
208.Em Page Up/Down
209keys and
210.Em Home/End
211keys to scroll buffered terminal output.
212Press the ``slock'' key again to get back to the normal terminal mode.
213.Pp
214The size of the back-scroll buffer can be set by the
215.Em SC_HISTORY_SIZE
216option below.
217.Ss Screen Saver
218The
219.Nm
220driver can be made to put up the screen saver if the current
221virtual terminal is idle, that is, the user is not typing
222on the keyboard nor moving mouse.
223See
224.Xr splash 4
225and
226.Xr vidcontrol 1
227for more details.
228.Sh DRIVER CONFIGURATION
229.Ss Kernel Configuration Options
230The following kernel configuration options control the
231.Nm
232driver.
233.Bl -tag -width MOUSE
234.It Em MAXCONS=N
235This option sets the number of virtual terminals to
236.Fa N .
237The default value is 16.
238.It Em SC_ALT_MOUSE_IMAGE
239This option selects the alternative way of displaying the mouse cursor
240in the virtual terminal.
241It may be vastly costly for some video cards to draw the arrow-shaped
242cursor and you may want to try this option.
243However, the appearance of the alternative mouse cursor may not be
244very appealing.
245.It Em SC_DISABLE_DDBKEY
246This option disables the ``debug'' key (by default, it is
247.Em Alt-Esc ,
248or
249.Em Ctl-PrintScreen
250).
251It will prevent the user from
252entering the kernel debugger DDB by pressing the key combination.
253DDB will still be invoked when the kernel panics or hits a break point
254if it is included in the kernel.
255.It Em SC_DISABLE_REBOOT
256This option disables the ``reboot'' key (by default, it is
257.Em Ctl-Alt-Del
258), so that the casual user may not accidentally reboot the system.
259.It Em SC_HISTORY_SIZE=N
260Sets the size of back scroll buffer to
261.Fa N
262lines.
263The default value is 100.
264.It Em SC_MOUSE_CHAR=C
265Unless the
266.Em SC_ALT_MOUSE_IMAGE
267option above is specified, the
268The
269.Nm
270driver reserves four consecutive character codes in order to display the
271mouse cursor in the virtual terminals in some systems.
272This option specifies the first character code to
273.Fa C
274to be used for this purpose.
275The default value is 0xd0.
276A good candidate is 0x03.
277.It Em SC_PIXEL_MODE
278Adds support for pixel (raster) mode console.
279This mode is useful on some laptop computers, but less so on
280most other systems, and it adds substantial amount of code to syscons.
281If the this option is NOT defined, you can reduce the kernel size a lot.
282See the
283.Em VESA800X600
284flag below.
285.It Em SC_DFLT_FONT
286This option will specify the default font.
287Available fonts are: iso, iso2, koi8-r, cp437, cp850, cp865 and cp866.
28816-line, 14-line and 8-line font data will be compiled in.
289Without this option, the
290.Nm
291driver will use whatever font already loaded in the video card,
292unless you explicitly load software font at startup.
293See
294.Sx EXAMPLE
295below.
296.El
297.Pp
298The following options will remove some features from the
299.Nm
300driver and save kernel memory.
301.Bl -tag -width MOUSE
302.It Em SC_NO_CUTPASTE
303This option disables ``copy and paste'' operation in virtual
304terminals.
305.It Em SC_NO_FONT_LOADING
306The
307.Nm
308driver can load software font on some video cards.
309This option removes this feature.
310.It Em SC_NO_HISTORY
311This option disables back-scrolling in virtual terminals.
312.\".It Em SC_NO_PALETTE_LOADING
313.It Em SC_NO_SYSMOUSE
314This option removes mouse support in the
315.Nm
316driver.
317The mouse daemon
318.Xr moused 8
319will fail if this option is defined.
320This option implies the
321.Em SC_NO_CUTPASTE
322option too.
323.El
324.Ss Driver Flags
325The following driver flags can be used to control the
326.Nm
327driver.
328They can be set either in the kernel configuration file
329.Pq see Xr config 8 ,
330or else in the User Configuration Menu at boot
331time
332.Pq see Xr boot 8 .
333.Bl -tag -width bit_0
334.\".It bit 0 (VISUAL_BELL)
335.\"Uses the ``visual'' bell.
336.\"The screen will blink instead of generating audible sound.
337.\".It bit 1,2 (CURSOR_TYPE)
338.\"This option specifies the cursor appearance.
339.\"Possible values are:
340.\".Bl -tag -width TYPE -compact
341.\".It Em 0
342.\"normal block cursor
343.\".It Em 2
344.\"blinking block cursor
345.\".It Em 4
346.\"underline cursor
347.\".It Em 6
348.\"blinking underline (aka destructive) cursor
349.\".El
350.\".It bit 6 (QUIET_BELL)
351.\"This option suppresses the bell, whether audible or visual,
352.\"if it is rung in a background virtual terminal.
353.It bit 7 (VESA800X600)
354This option puts the video card in the VESA 800x600 dots, 16 color
355mode.
356It may be useful for laptop computers for which the 800x600 mode
357is otherwise unsupported by the X server.
358Note that in order for this flag to work, the kernel must be
359compiled with the
360.Em SC_PIXEL_MODE
361option explained above.
362.\"Note also that the ``copy-and-paste'' function is not currently supported
363.\"in this mode and the mouse pointer will not be displayed.
364.El
365.Sh FILES
366.Bl -tag -width /usr/share/syscons/xxxxyyyyzzz -compact
367.It Pa /dev/console
368.It Pa /dev/consolectl
369.It Pa /dev/ttyv?
370virtual terminals
371.It Pa /etc/ttys
372terminal initialization information
373.It Pa /usr/share/syscons/fonts/*
374font files
375.It Pa /usr/share/syscons/keymaps/*
376key map files
377.It Pa /usr/share/syscons/scrmaps/*
378screen map files
379.El
380.Sh EXAMPLE
381As the
382.Nm
383driver requires the keyboard driver and the video card driver,
384the kernel configuration file should contain the following lines.
385.Pp
386.Bd -literal -offset indent
387device atkbdc0 at isa? port IO_KBD
388device atkbd0 at atkbdc? irq 1
389device vga0 at isa? conflicts
390device sc0 at isa?
391
392pseudo-device splash
393.Ed
394.Pp
395If you do not intend to load the splash image or use the screen saver,
396the last line is not necessary, and can be omitted.
397.Pp
398Note that the keyboard controller driver
399.Nm atkbdc
400is required by the keyboard driver
401.Nm atkbd .
402.Pp
403The following example adds the font files
404.Pa cp850-8x16.fnt ,
405.Pa cp850-8x14.font
406and
407.Pa cp850-8x8.font
408to the kernel.
409.Pp
410.Dl "options SC_DFLT_FONT"
411.Dl "makeoptions SC_DFLT_FONT"=\&"cp850\&"
412.Dl "device sc0 at isa?
413.Pp
414.\".Sh DIAGNOSTICS
415.\".Sh CAVEATS
416.Sh BUGS
417This manual page is incomplete and urgently needs revision.
418.Sh SEE ALSO
419.Xr kbdcontrol 1 ,
420.Xr login 1 ,
421.Xr vidcontrol 1 ,
422.Xr atkbd 4 ,
423.Xr atkbdc 4 ,
424.Xr keyboard 4 ,
425.Xr screen 4 ,
426.Xr splash 4 ,
427.Xr ukbd 4 ,
428.Xr vga 4 ,
429.Xr keymap 5 ,
430.Xr rc.conf 5 ,
431.Xr screenmap 5 ,
432.Xr ttys 5 ,
433.Xr config 8 ,
434.Xr getty 8 ,
435.Xr kldload 8 ,
436.Xr moused 8 .
437.Sh HISTORY
438The
439.Nm
440driver first appeared in
441.Fx 1.0 .
442.Sh AUTHORS
443The
444.Nm
445driver was written by
446.An S�ren Schmidt Aq sos@FreeBSD.org .
447This manual page was written by
448.An Kazutaka Yokota Aq yokota@FreeBSD.org .
449