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 32.Sh NAME 33.Nm syscons , 34.Nm sc 35.Nd the console driver 36.Sh SYNOPSIS 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_DDBKEY" 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_SYSMOUSE" 50.Cd "options SC_PIXEL_MODE" 51.Cd "options SC_TWOBUTTON_MOUSE" 52.Cd "options SC_NORM_ATTR=_attribute_" 53.Cd "options SC_NORM_REV_ATTR=_attribute_" 54.Cd "options SC_KERNEL_CONS_ATTR=_attribute_" 55.Cd "options SC_KERNEL_CONS_REV_ATTR=_attribute_" 56.Cd "options SC_DFLT_FONT" 57.Cd "makeoptions SC_DFLT_FONT=_font_name_" 58.Cd "device sc" 59.Pp 60In 61.Pa /boot/device.hints : 62.Cd hint.sc.0.at="isa" 63.Sh DESCRIPTION 64The 65.Nm 66driver provides multiple virtual terminals. 67It resembles the SCO color console driver. 68.Pp 69The 70.Nm 71driver is implemented on top of the keyboard driver 72.Pq Xr atkbd 4 73and the video card driver 74.Pq Xr vga 4 75and so requires both of them to be configured in the system. 76.Pp 77There can be only one 78.Nm 79device defined in the system. 80.Ss Virtual Terminals 81The 82.Nm 83driver provides multiple virtual terminals which appear as if they were 84separate terminals. 85One virtual terminal is considered current and exclusively 86occupies the screen and the keyboard; the other virtual terminals 87are placed in the background. 88.Pp 89In order to use virtual terminals, they must be individually 90marked ``on'' in 91.Pa /etc/ttys 92so that 93.Xr getty 8 94will recognize them to be active and run 95.Xr login 1 96to let the user to login to the system. 97By default, only the first eight virtual terminals are activated in 98.Pa /etc/ttys . 99.Pp 100You press the 101.Dv Alt 102key and a switch key to switch between 103virtual terminals. 104The following table summarizes the correspondence between the switch 105key and the virtual terminal. 106.Bd -literal -offset indent 107Alt-F1 ttyv0 Alt-F7 ttyv6 Shift-Alt-F1 ttyv10 108Alt-F2 ttyv1 Alt-F8 ttyv7 Shift-Alt-F2 ttyv11 109Alt-F3 ttyv2 Alt-F9 ttyv8 Shift-Alt-F3 ttyv12 110Alt-F4 ttyv3 Alt-F10 ttyv9 Shift-Alt-F4 ttyv13 111Alt-F5 ttyv4 Alt-F11 ttyv10 Shift-Alt-F5 ttyv14 112Alt-F6 ttyv5 Alt-F12 ttyv11 Shift-Alt-F6 ttyv15 113.Ed 114.Pp 115You can also use the ``nscr'' key (usually the 116.Dv PrintScreen 117key on the AT Enhanced keyboard) to cycle available virtual terminals. 118.Pp 119The default number of available virtual terminals is 16. 120This can be changed by the kernel configuration option 121.Dv MAXCONS 122(see below). 123.Pp 124Note that the X server usually requires a virtual terminal for display 125purposes, so at least one terminal must be left unused by 126.Xr getty 8 127so that it can be used by the X server. 128.Ss Key Definitions and Function Key Strings 129The 130.Nm 131driver, in conjunction with the keyboard driver, allows the user 132to change key definitions and function key strings. 133The 134.Xr kbdcontrol 1 135command will load a key definition file (known as ``keymap'' file), 136dump the current keymap, and assign a string to a function key. 137See 138.Xr keyboard 4 139and 140.Xr kbdmap 5 141for the keymap file. 142.Pp 143You may want to set the 144.Ar keymap 145variable in 146.Pa /etc/rc.conf.local 147to the desired keymap file so that it will be automatically loaded 148when the system starts up. 149.Ss Software Font 150For most modern video cards, e.g. VGA, the 151.Nm 152driver and the video card driver allow the user to change 153the font used on the screen. 154The 155.Xr vidcontrol 1 156command can be used to load a font file from 157.Pa /usr/share/syscons/fonts . 158.Pp 159The font comes in various sizes: 8x8, 8x14 and 8x16. 160The 8x16 font is typically used for the VGA card in the 80-column- 161by-25-line mode. 162Other video modes may require different size of font. 163It is better to always load these three sizes of the same font. 164.Pp 165You may set 166.Ar font8x8 , 167.Ar font8x14 168and 169.Ar font8x16 170variables in 171.Pa /etc/rc.conf.local 172to the desired font files so that they will be automatically loaded 173when the system starts up. 174.Pp 175Optionally you can make a particular font file as the default font. 176See the 177.Dv SC_DFLT_FONT 178option below. 179.Ss Screen Map 180If your video card does not support software font, you may still be able 181to have similar effect by re-mapping font hard-wired in the video card. 182Use 183.Xr vidcontrol 1 184to load a screen map file which defines mapping between character codes. 185.Ss Mouse Support and Copy-and-Paste 186You can use your mouse to copy text on the screen and paste it as if 187it is typed by hand. 188You must be running the mouse daemon 189.Xr moused 8 190and enable the mouse cursor in the virtual terminal via 191.Xr vidcontrol 1 . 192.Pp 193Pressing the mouse button 1 (usually the left button) will start selection. 194Releasing the button 1 will end the selection process. 195The selected text will be marked by inverting foreground and 196background colors. 197You can press the button 3 (usually the right button) to extend 198the selected region. 199The selected text is placed in the copy buffer and can be pasted 200at the cursor position by your pressing the button 2 (usually the 201middle button) as many times as you like. 202.Pp 203If your mouse has only two buttons, you may want to use the 204.Dv SC_TWOBUTTON_MOUSE 205option below to make the right button to paste the text. 206Alternatively you can make the mouse daemon 207to emulate the middle button. 208See the man page for 209.Xr moused 8 210for more details. 211.Ss Back Scrolling 212The 213.Nm 214driver allows the user to browse the output which has ``scrolled off'' 215from the top of the screen. 216.Pp 217Press the ``slock'' key (usually 218.Dv ScrllLock 219and/or 220.Dv Pause 221keys on many AT Enhanced keyboards) and the terminal is 222in the ``back scrolling'' mode. 223It is indicated by the 224.Dv Scroll Lock 225LED. 226Use arrow keys, 227.Dv Page Up/Down 228keys and 229.Dv Home/End 230keys to scroll buffered terminal output. 231Press the ``slock'' key again to get back to the normal terminal mode. 232.Pp 233The size of the back-scroll buffer can be set by the 234.Dv SC_HISTORY_SIZE 235option below. 236.Ss Screen Saver 237The 238.Nm 239driver can be made to put up the screen saver if the current 240virtual terminal is idle, that is, the user is not typing 241on the keyboard nor moving mouse. 242See 243.Xr splash 4 244and 245.Xr vidcontrol 1 246for more details. 247.Sh DRIVER CONFIGURATION 248.Ss Kernel Configuration Options 249The following kernel configuration options control the 250.Nm 251driver. 252.Bl -tag -width MOUSE 253.It Dv MAXCONS=N 254This option sets the number of virtual terminals to 255.Fa N . 256The default value is 16. 257.It Dv SC_ALT_MOUSE_IMAGE 258This option selects the alternative way of displaying the mouse cursor 259in the virtual terminal. 260It may be vastly costly for some video cards to draw the arrow-shaped 261cursor and you may want to try this option. 262However, the appearance of the alternative mouse cursor may not be 263very appealing. 264Note that if you use the 265.Dv SC_NO_FONT_LOADING 266option then you must also use this option if you wish to be able to use 267the mouse. 268.It Dv SC_CUT_SEPCHARS=_characters_ 269This options specifies characters that will be looked for when the 270driver searches for words boundaries when doing cut operation. 271By default, its value is 272.Qq Li \ex20 273\(em a space character. 274.It Dv SC_CUT_SPACES2TABS 275This options instructs the driver to convert leading spaces into tabs 276when copying data into cut buffer. 277This might be useful to preserve 278indentation when copying tab-indented text. 279.It Dv SC_DISABLE_DDBKEY 280This option disables the ``debug'' key (by default, it is 281.Dv Alt-Esc , 282or 283.Dv Ctl-PrintScreen ) . 284It will prevent the user from 285entering the kernel debugger DDB by pressing the key combination. 286DDB will still be invoked when the kernel panics or hits a break point 287if it is included in the kernel. 288.It Dv SC_DISABLE_REBOOT 289This option disables the ``reboot'' key (by default, it is 290.Dv Ctl-Alt-Del ) , 291so that the casual user may not accidentally reboot the system. 292.It Dv SC_HISTORY_SIZE=N 293Sets the size of back scroll buffer to 294.Fa N 295lines. 296The default value is 100. 297.It Dv SC_MOUSE_CHAR=C 298Unless the 299.Dv SC_ALT_MOUSE_IMAGE 300option above is specified, the 301The 302.Nm 303driver reserves four consecutive character codes in order to display the 304mouse cursor in the virtual terminals in some systems. 305This option specifies the first character code to 306.Fa C 307to be used for this purpose. 308The default value is 0xd0. 309A good candidate is 0x03. 310.It Dv SC_PIXEL_MODE 311Adds support for pixel (raster) mode console. 312This mode is useful on some laptop computers, but less so on 313most other systems, and it adds substantial amount of code to syscons. 314If this option is NOT defined, you can reduce the kernel size a lot. 315See the 316.Dv VESA800X600 317flag below. 318.It Dv SC_TWOBUTTON_MOUSE 319If you have a two button mouse, you may want to add this option 320to use the right button of the mouse to paste text. 321See 322.Sx Mouse Support and Copy-and-Paste 323above. 324.It Dv SC_NORM_ATTR=_attribute_ 325.It Dv SC_NORM_REV_ATTR=_attribute_ 326.It Dv SC_KERNEL_CONS_ATTR=_attribute_ 327.It Dv SC_KERNEL_CONS_REV_ATTR=_attribute_ 328These options will set the default colors. 329Available colors are defined in 330.Pa /usr/include/machine/pc/display.h . 331See 332.Sx EXAMPLES 333below. 334.It Dv SC_DFLT_FONT 335This option will specify the default font. 336Available fonts are: iso, iso2, koi8-r, koi8-u, cp437, cp850, cp865, 337cp866 and cp866u. 33816-line, 14-line and 8-line font data will be compiled in. 339Without this option, the 340.Nm 341driver will use whatever font already loaded in the video card, 342unless you explicitly load software font at startup. 343See 344.Sx EXAMPLES 345below. 346.El 347.Pp 348The following options will remove some features from the 349.Nm 350driver and save kernel memory. 351.Bl -tag -width MOUSE 352.It Dv SC_NO_CUTPASTE 353This option disables ``copy and paste'' operation in virtual 354terminals. 355.It Dv SC_NO_FONT_LOADING 356The 357.Nm 358driver can load software font on some video cards. 359This option removes this feature. 360Note that if you still wish to use 361the mouse with this option then you must also use the 362.Dv SC_ALT_MOUSE_IMAGE 363option. 364.It Dv SC_NO_HISTORY 365This option disables back-scrolling in virtual terminals. 366.\".It Dv SC_NO_PALETTE_LOADING 367.It Dv SC_NO_SYSMOUSE 368This option removes mouse support in the 369.Nm 370driver. 371The mouse daemon 372.Xr moused 8 373will fail if this option is defined. 374This option implies the 375.Dv SC_NO_CUTPASTE 376option too. 377.El 378.Ss Driver Flags 379The following driver flags can be used to control the 380.Nm 381driver. 382They can be set either in 383.Pa /boot/device.hints , 384or else at the loader prompt (see 385.Xr loader 8 ) . 386.Bl -tag -width bit_0 387.\".It bit 0 (VISUAL_BELL) 388.\"Uses the ``visual'' bell. 389.\"The screen will blink instead of generating audible sound. 390.\".It bit 1,2 (CURSOR_TYPE) 391.\"This option specifies the cursor appearance. 392.\"Possible values are: 393.\".Bl -tag -width TYPE -compact 394.\".It Dv 0 395.\"normal block cursor 396.\".It Dv 2 397.\"blinking block cursor 398.\".It Dv 4 399.\"underline cursor 400.\".It Dv 6 401.\"blinking underline (aka destructive) cursor 402.\".El 403.\".It bit 6 (QUIET_BELL) 404.\"This option suppresses the bell, whether audible or visual, 405.\"if it is rung in a background virtual terminal. 406.It 0x0080 (VESA800X600) 407This option puts the video card in the VESA 800x600 dots, 16 color 408mode. 409It may be useful for laptop computers for which the 800x600 mode 410is otherwise unsupported by the X server. 411Note that in order for this flag to work, the kernel must be 412compiled with the 413.Dv SC_PIXEL_MODE 414option explained above. 415.\"Note also that the ``copy-and-paste'' function is not currently supported 416.\"in this mode and the mouse pointer will not be displayed. 417.It 0x0100 (AUTODETECT_KBD) 418This option instructs the syscons driver to periodically scan 419for a keyboard device if it is not currently attached to one. 420Otherwise, the driver only probes for a keyboard once during bootup. 421.El 422.Sh FILES 423.Bl -tag -width /usr/share/syscons/xxxxyyyyzzz -compact 424.It Pa /dev/console 425.It Pa /dev/consolectl 426.It Pa /dev/ttyv? 427virtual terminals 428.It Pa /etc/ttys 429terminal initialization information 430.It Pa /usr/share/syscons/fonts/* 431font files 432.It Pa /usr/share/syscons/keymaps/* 433key map files 434.It Pa /usr/share/syscons/scrmaps/* 435screen map files 436.El 437.Sh EXAMPLES 438As the 439.Nm 440driver requires the keyboard driver and the video card driver, 441the kernel configuration file should contain the following lines. 442.Pp 443.Bd -literal -offset indent 444device atkbdc 445device atkbd 446device vga 447device sc 448 449device splash 450.Ed 451You also need the following lines in 452.Pa /boot/device.hints 453for these drivers. 454.Bd -literal -offset indent 455hint.atkbdc.0.at="isa" 456hint.atkbdc.0.port="0x060" 457hint.atkbd.0.at="atkbdc" 458hint.atkbd.0.irq="1" 459hint.vga.0.at="isa" 460hint.sc.0.at="isa" 461.Ed 462.Pp 463If you do not intend to load the splash image or use the screen saver, 464the last line is not necessary, and can be omitted. 465.Pp 466Note that the keyboard controller driver 467.Nm atkbdc 468is required by the keyboard driver 469.Nm atkbd . 470.Pp 471The following lines will set the default colors. 472The normal text will be green on black background. 473The reversed text will be yellow on green background. 474Note that you cannot put any white space inside the quoted string, 475because of the current implementation of 476.Xr config 8 . 477.Pp 478.Dl "options SC_NORM_ATTR=(FG_GREEN|BG_BLACK) 479.Dl "options SC_NORM_REV_ATTR=(FG_YELLOW|BG_GREEN) 480.Pp 481The following lines will set the default colors of the kernel message. 482The kernel message will be printed bright red on black background. 483The reversed message will be black on red background. 484.Pp 485.Dl "options SC_KERNEL_CONS_ATTR=(FG_LIGHTRED|BG_BLACK) 486.Dl "options SC_KERNEL_CONS_REV_ATTR=(FG_BLACK|BG_RED) 487.Pp 488The following example adds the font files 489.Pa cp850-8x16.fnt , 490.Pa cp850-8x14.font 491and 492.Pa cp850-8x8.font 493to the kernel. 494.Pp 495.Dl "options SC_DFLT_FONT" 496.Dl "makeoptions SC_DFLT_FONT=cp850 497.Dl "device sc" 498.Pp 499.\".Sh DIAGNOSTICS 500.Sh CAVEATS 501Amount of data that is possible to insert from the cut buffer is limited 502by the 503.Brq Dv MAX_INPUT , 504a system limit on the number of bytes that may be stored in the terminal 505input queue - usually 1024 bytes 506(see 507.Xr termios 4 ) . 508.Sh BUGS 509This manual page is incomplete and urgently needs revision. 510.Sh SEE ALSO 511.Xr kbdcontrol 1 , 512.Xr login 1 , 513.Xr vidcontrol 1 , 514.Xr atkbd 4 , 515.Xr atkbdc 4 , 516.Xr keyboard 4 , 517.Xr screen 4 , 518.Xr splash 4 , 519.Xr ukbd 4 , 520.Xr vga 4 , 521.Xr kbdmap 5 , 522.Xr rc.conf 5 , 523.Xr ttys 5 , 524.Xr config 8 , 525.Xr getty 8 , 526.Xr kldload 8 , 527.Xr moused 8 528.Sh HISTORY 529The 530.Nm 531driver first appeared in 532.Fx 1.0 . 533.Sh AUTHORS 534.An -nosplit 535The 536.Nm 537driver was written by 538.An S\(/oren Schmidt Aq sos@FreeBSD.org . 539This manual page was written by 540.An Kazutaka Yokota Aq yokota@FreeBSD.org . 541