3 .\" Kazutaka YOKOTA <yokota@zodiac.mech.utsunomiya-u.ac.jp>
4 .\" All rights reserved.
6 .\" Redistribution and use in source and binary forms, with or without
7 .\" modification, are permitted provided that the following conditions
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.
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.
35 .Nd the console driver
37 .Cd "options MAXCONS=N"
38 .Cd "options SC_ALT_MOUSE_IMAGE"
39 .Cd "options SC_CUT_SEPCHARS=_characters_"
40 .Cd "options SC_CUT_SPACES2TABS"
41 .Cd "options SC_DISABLE_KDBKEY"
42 .Cd "options SC_DISABLE_REBOOT"
43 .Cd "options SC_HISTORY_SIZE=N"
44 .Cd "options SC_MOUSE_CHAR=C"
45 .Cd "options SC_NO_CUTPASTE"
46 .Cd "options SC_NO_FONT_LOADING"
47 .Cd "options SC_NO_HISTORY"
48 .Cd "options SC_NO_PALETTE_LOADING"
49 .Cd "options SC_NO_SUSPEND_VTYSWITCH"
50 .Cd "options SC_NO_SYSMOUSE"
51 .Cd "options SC_PIXEL_MODE"
52 .Cd "options SC_TWOBUTTON_MOUSE"
53 .Cd "options SC_NORM_ATTR=_attribute_"
54 .Cd "options SC_NORM_REV_ATTR=_attribute_"
55 .Cd "options SC_KERNEL_CONS_ATTR=_attribute_"
56 .Cd "options SC_KERNEL_CONS_REV_ATTR=_attribute_"
57 .Cd "options SC_DFLT_FONT"
58 .Cd "makeoptions SC_DFLT_FONT=_font_name_"
62 .Pa /boot/device.hints :
63 .Cd hint.sc.0.at="isa"
64 .Cd hint.sc.0.vesa_mode=0x103
67 .Pa /boot/loader.conf :
72 driver provides multiple virtual terminals.
73 It resembles the SCO color console driver.
77 driver is implemented on top of the keyboard driver
79 and the video card driver
81 and so requires both of them to be configured in the system.
85 device defined in the system.
89 driver provides multiple virtual terminals which appear as if they were
91 One virtual terminal is considered current and exclusively
92 occupies the screen and the keyboard; the other virtual terminals
93 are placed in the background.
95 In order to use virtual terminals, they must be individually
100 will recognize them to be active and run
102 to let the user log in to the system.
103 By default, only the first eight virtual terminals are activated in
108 key and a switch key to switch between
110 The following table summarizes the correspondence between the switch
111 key and the virtual terminal.
112 .Bd -literal -offset indent
113 Alt-F1 ttyv0 Alt-F7 ttyv6 Shift-Alt-F1 ttyva
114 Alt-F2 ttyv1 Alt-F8 ttyv7 Shift-Alt-F2 ttyvb
115 Alt-F3 ttyv2 Alt-F9 ttyv8 Shift-Alt-F3 ttyvc
116 Alt-F4 ttyv3 Alt-F10 ttyv9 Shift-Alt-F4 ttyvd
117 Alt-F5 ttyv4 Alt-F11 ttyva Shift-Alt-F5 ttyve
118 Alt-F6 ttyv5 Alt-F12 ttyvb Shift-Alt-F6 ttyvf
121 You can also use the ``nscr'' key (usually the
123 key on the AT Enhanced keyboard) to cycle available virtual terminals.
125 The default number of available virtual terminals is 16.
126 This can be changed with the kernel configuration option
130 Note that the X server usually requires a virtual terminal for display
131 purposes, so at least one terminal must be left unused by
133 so that it can be used by the X server.
134 .Ss Key Definitions and Function Key Strings
137 driver, in conjunction with the keyboard driver, allows the user
138 to change key definitions and function key strings.
141 command will load a key definition file (known as ``keymap'' file),
142 dump the current keymap, and assign a string to a function key.
149 You may want to set the
152 .Pa /etc/rc.conf.local
153 to the desired keymap file so that it will be automatically loaded
154 when the system starts up.
156 For most modern video cards, e.g., VGA, the
158 driver and the video card driver allow the user to change
159 the font used on the screen.
162 command can be used to load a font file from
163 .Pa /usr/share/syscons/fonts .
165 The font comes in various sizes: 8x8, 8x14 and 8x16.
166 The 8x16 font is typically used for the VGA card in the
167 80-column-by-25-line mode.
168 Other video modes may require different font sizes.
169 It is better to always load all three sizes of the same font.
178 to the desired font files so that they will be automatically loaded
179 when the system starts up.
181 Optionally you can specify a particular font file as the default.
186 If your video card does not support software fonts, you may still be able
187 to achieve a similar effect by re-mapping the font built into your video card.
190 to load a screen map file which defines the mapping between character codes.
191 .Ss Mouse Support and Copy-and-Paste
192 You can use your mouse to copy text on the screen and paste it as if
193 it was typed by hand.
194 You must be running the mouse daemon
196 and enable the mouse cursor in the virtual terminal via
199 Pressing mouse button 1 (usually the left button) will start selection.
200 Releasing button 1 will end the selection process.
201 The selected text will be marked by inverting foreground and
203 You can press button 3 (usually the right button) to extend
205 The selected text is placed in the copy buffer and can be pasted
206 at the cursor position by pressing button 2 (usually the
207 middle button) as many times as you like.
209 If your mouse has only two buttons, you may want to use the
210 .Dv SC_TWOBUTTON_MOUSE
211 option below to make the right button to paste the text.
212 Alternatively you can make the mouse daemon
213 emulate the middle button.
220 driver allows the user to browse the output which has ``scrolled off''
221 the top of the screen.
223 Press the ``slock'' key (usually
229 on many keyboards) and the terminal is
230 in the ``scrollback'' mode.
231 It is indicated by the
234 Use the arrow keys, the
238 keys to scroll buffered terminal output.
239 Press the ``slock'' key again to get back to the normal terminal mode.
241 The size of the scrollback buffer can be set by the
243 option described below.
247 driver can be made to put up the screen saver if the current
248 virtual terminal is idle, that is, the user is not typing
249 on the keyboard nor moving the mouse.
255 .Sh DRIVER CONFIGURATION
256 .Ss Kernel Configuration Options
257 The following kernel configuration options control the
260 .Bl -tag -width MOUSE
262 This option sets the number of virtual terminals to
264 The default value is 16.
265 .It Dv SC_ALT_MOUSE_IMAGE
266 This option selects the alternative way of displaying the mouse cursor
267 in the virtual terminal.
268 It may be expensive for some video cards to draw the arrow-shaped
269 cursor, and you may want to try this option.
270 However, the appearance of the alternative mouse cursor may not be
272 Note that if you use the
273 .Dv SC_NO_FONT_LOADING
274 option then you must also use this option if you wish to be able to use
276 .It Dv SC_CUT_SEPCHARS=_characters_
277 This options specifies characters that will be looked for when the
278 driver searches for words boundaries when doing cut operation.
279 By default, its value is
281 \(em a space character.
282 .It Dv SC_CUT_SPACES2TABS
283 This options instructs the driver to convert leading spaces into tabs
284 when copying data into cut buffer.
285 This might be useful to preserve
286 indentation when copying tab-indented text.
287 .It Dv SC_DISABLE_KDBKEY
288 This option disables the ``debug'' key combination (by default, it is
291 .Dv Ctl-PrintScreen ) .
292 It will prevent users from
293 entering the kernel debugger (KDB) by pressing the key combination.
294 KDB will still be invoked when the kernel panics or hits a break point
295 if it is included in the kernel.
296 If this option is not defined, this behavior may be controlled at runtime
300 .Va hw.syscons.kbd_debug .
301 .It Dv SC_DISABLE_REBOOT
302 This option disables the ``reboot'' key (by default, it is
304 so that the casual user may not accidentally reboot the system.
305 If this option is not defined, this behavior may be controlled at runtime
309 .Va hw.syscons.kbd_reboot .
310 .It Dv SC_HISTORY_SIZE=N
311 Sets the size of back scroll buffer to
314 The default value is 100.
315 .It Dv SC_MOUSE_CHAR=C
317 .Dv SC_ALT_MOUSE_IMAGE
318 option above is specified, the
320 driver reserves four consecutive character codes in order to display the
321 mouse cursor in the virtual terminals in some systems.
322 This option specifies the first character code to
324 to be used for this purpose.
325 The default value is 0xd0.
326 A good candidate is 0x03.
328 Adds support for pixel (raster) mode console.
329 This mode is useful on some laptop computers, but less so on
330 most other systems, and it adds substantial amount of code to syscons.
331 If this option is NOT defined, you can reduce the kernel size a lot.
335 .It Dv SC_TWOBUTTON_MOUSE
336 If you have a two button mouse, you may want to add this option
337 to use the right button of the mouse to paste text.
339 .Sx Mouse Support and Copy-and-Paste
341 .It Dv SC_NORM_ATTR=_attribute_
342 .It Dv SC_NORM_REV_ATTR=_attribute_
343 .It Dv SC_KERNEL_CONS_ATTR=_attribute_
344 .It Dv SC_KERNEL_CONS_REV_ATTR=_attribute_
345 These options will set the default colors.
346 Available colors are defined in
347 .In machine/pc/display.h .
352 This option will specify the default font.
353 Available fonts are: iso, iso2, koi8-r, koi8-u, cp437, cp850, cp865,
355 16-line, 14-line and 8-line font data will be compiled in.
356 Without this option, the
358 driver will use whatever font is already loaded in the video card,
359 unless you explicitly load a software font at startup.
363 .It Dv SC_NO_SUSPEND_VTYSWITCH
364 This option, which is also available as
369 .Va hw.syscons.sc_no_suspend_vtswitch ,
370 disables switching between virtual terminals (graphics <-> text) during
371 suspend/resume (ACPI and APM).
372 Use this option if your system is freezing
373 when you are running X and trying to suspend.
376 The following options will remove some features from the
378 driver and save kernel memory.
379 .Bl -tag -width MOUSE
380 .It Dv SC_NO_CUTPASTE
381 This option disables ``copy and paste'' operation in virtual
383 .It Dv SC_NO_FONT_LOADING
386 driver can load software fonts on some video cards.
387 This option removes this feature.
388 Note that if you still wish to use
389 the mouse with this option then you must also use the
390 .Dv SC_ALT_MOUSE_IMAGE
393 This option disables back-scrolling in virtual terminals.
394 .\".It Dv SC_NO_PALETTE_LOADING
395 .It Dv SC_NO_SYSMOUSE
396 This option removes mouse support in the
401 will fail if this option is defined.
402 This option implies the
407 The following driver flags can be used to control the
410 Driver flags can be set with the
413 .Pa /boot/device.hints ,
414 or else at the loader prompt (see
416 .Bl -tag -width bit_0
417 .\".It bit 0 (VISUAL_BELL)
418 .\"Uses the ``visual'' bell.
419 .\"The screen will blink instead of generating audible sound.
420 .\".It bit 1,2 (CURSOR_TYPE)
421 .\"This option specifies the cursor appearance.
422 .\"Possible values are:
423 .\".Bl -tag -width TYPE -compact
425 .\"normal block cursor
427 .\"blinking block cursor
431 .\"blinking underline (aka destructive) cursor
433 .\".It bit 6 (QUIET_BELL)
434 .\"This option suppresses the bell, whether audible or visual,
435 .\"if it is rung in a background virtual terminal.
436 .It 0x0080 (VESAMODE)
437 This option puts the video card in the VESA mode specified by
438 .Pa /boot/device.hints
441 during kernel initialization.
442 Note that in order for this flag to work, the kernel must be
445 option explained above.
446 A list of the available mode can be obtained via
448 .\"Note also that the ``copy-and-paste'' function is not currently supported
449 .\"in this mode and the mouse pointer will not be displayed.
450 .It 0x0100 (AUTODETECT_KBD)
451 This option instructs the syscons driver to periodically scan
452 for a keyboard device if it is not currently attached to one.
453 Otherwise, the driver only probes for a keyboard once during bootup.
456 These settings can be entered at the
460 .Bl -tag -width indent
466 have been compiled into the kernel, the one to use for the system console can
467 be selected by setting this variable to
473 provides the default system console.
476 .Bl -tag -width /usr/share/syscons/xxxxyyyyzzz -compact
478 .It Pa /dev/consolectl
482 terminal initialization information
483 .It Pa /usr/share/syscons/fonts/*
485 .It Pa /usr/share/syscons/keymaps/*
487 .It Pa /usr/share/syscons/scrmaps/*
493 driver requires the keyboard driver and the video card driver,
494 the kernel configuration file should contain the following lines.
495 .Bd -literal -offset indent
503 You also need the following lines in
504 .Pa /boot/device.hints
506 .Bd -literal -offset indent
507 hint.atkbdc.0.at="isa"
508 hint.atkbdc.0.port="0x060"
509 hint.atkbd.0.at="atkbdc"
515 If you do not intend to load the splash image or use the screen saver,
516 the last line is not necessary, and can be omitted.
518 Note that the keyboard controller driver
520 is required by the keyboard driver
523 The following lines will set the default colors.
524 The normal text will be green on black background.
525 The reversed text will be yellow on green background.
526 Note that you cannot put any white space inside the quoted string,
527 because of the current implementation of
530 .Dl "options SC_NORM_ATTR=(FG_GREEN|BG_BLACK)"
531 .Dl "options SC_NORM_REV_ATTR=(FG_YELLOW|BG_GREEN)"
533 The following lines will set the default colors of the kernel message.
534 The kernel message will be printed bright red on black background.
535 The reversed message will be black on red background.
537 .Dl "options SC_KERNEL_CONS_ATTR=(FG_LIGHTRED|BG_BLACK)"
538 .Dl "options SC_KERNEL_CONS_REV_ATTR=(FG_BLACK|BG_RED)"
540 The following example adds the font files
547 .Dl "options SC_DFLT_FONT"
548 .Dl "makeoptions SC_DFLT_FONT=cp850"
573 driver first appeared in
579 driver was written by
580 .An S\(/oren Schmidt Aq sos@FreeBSD.org .
581 This manual page was written by
582 .An Kazutaka Yokota Aq yokota@FreeBSD.org .
584 The amount of data that is possible to insert from the cut buffer is limited
587 a system limit on the number of bytes that may be stored in the terminal
588 input queue - usually 1024 bytes
592 This manual page is incomplete and urgently needs revision.