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 log in 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 with 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 16180-column-by-25-line mode. 162Other video modes may require different font sizes. 163It is better to always load all 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 172to the desired font files so that they will be automatically loaded 173when the system starts up. 174.Pp 175Optionally you can specify a particular font file as the default. 176See the 177.Dv SC_DFLT_FONT 178option below. 179.Ss Screen Map 180If your video card does not support software fonts, you may still be able 181to achieve a similar effect by re-mapping the font built into your video card. 182Use 183.Xr vidcontrol 1 184to load a screen map file which defines the 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 was 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 mouse button 1 (usually the left button) will start selection. 194Releasing button 1 will end the selection process. 195The selected text will be marked by inverting foreground and 196background colors. 197You can press 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 pressing 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 207emulate 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'' 215the top of the screen. 216.Pp 217Press the ``slock'' key (usually 218.Dv ScrllLock 219/ 220.Dv Scroll Lock 221or 222.Dv Pause 223on many keyboards) and the terminal is 224in the ``scrollback'' mode. 225It is indicated by the 226.Dv Scroll Lock 227LED. 228Use the arrow keys, the 229.Dv Page Up/Down 230keys and the 231.Dv Home/End 232keys to scroll buffered terminal output. 233Press the ``slock'' key again to get back to the normal terminal mode. 234.Pp 235The size of the scrollback buffer can be set by the 236.Dv SC_HISTORY_SIZE 237option described below. 238.Ss Screen Saver 239The 240.Nm 241driver can be made to put up the screen saver if the current 242virtual terminal is idle, that is, the user is not typing 243on the keyboard nor moving the mouse. 244See 245.Xr splash 4 246and 247.Xr vidcontrol 1 248for more details. 249.Sh DRIVER CONFIGURATION 250.Ss Kernel Configuration Options 251The following kernel configuration options control the 252.Nm 253driver. 254.Bl -tag -width MOUSE 255.It Dv MAXCONS=N 256This option sets the number of virtual terminals to 257.Fa N . 258The default value is 16. 259.It Dv SC_ALT_MOUSE_IMAGE 260This option selects the alternative way of displaying the mouse cursor 261in the virtual terminal. 262It may be expensive for some video cards to draw the arrow-shaped 263cursor, and you may want to try this option. 264However, the appearance of the alternative mouse cursor may not be 265very appealing. 266Note that if you use the 267.Dv SC_NO_FONT_LOADING 268option then you must also use this option if you wish to be able to use 269the mouse. 270.It Dv SC_CUT_SEPCHARS=_characters_ 271This options specifies characters that will be looked for when the 272driver searches for words boundaries when doing cut operation. 273By default, its value is 274.Qq Li \ex20 275\(em a space character. 276.It Dv SC_CUT_SPACES2TABS 277This options instructs the driver to convert leading spaces into tabs 278when copying data into cut buffer. 279This might be useful to preserve 280indentation when copying tab-indented text. 281.It Dv SC_DISABLE_DDBKEY 282This option disables the ``debug'' key combination (by default, it is 283.Dv Alt-Esc , 284or 285.Dv Ctl-PrintScreen ) . 286It will prevent users from 287entering the kernel debugger (DDB) by pressing the key combination. 288DDB will still be invoked when the kernel panics or hits a break point 289if it is included in the kernel. 290.It Dv SC_DISABLE_REBOOT 291This option disables the ``reboot'' key (by default, it is 292.Dv Ctl-Alt-Del ) , 293so that the casual user may not accidentally reboot the system. 294.It Dv SC_HISTORY_SIZE=N 295Sets the size of back scroll buffer to 296.Fa N 297lines. 298The default value is 100. 299.It Dv SC_MOUSE_CHAR=C 300Unless the 301.Dv SC_ALT_MOUSE_IMAGE 302option above is specified, the 303.Nm 304driver reserves four consecutive character codes in order to display the 305mouse cursor in the virtual terminals in some systems. 306This option specifies the first character code to 307.Fa C 308to be used for this purpose. 309The default value is 0xd0. 310A good candidate is 0x03. 311.It Dv SC_PIXEL_MODE 312Adds support for pixel (raster) mode console. 313This mode is useful on some laptop computers, but less so on 314most other systems, and it adds substantial amount of code to syscons. 315If this option is NOT defined, you can reduce the kernel size a lot. 316See the 317.Dv VESA800X600 318flag below. 319.It Dv SC_TWOBUTTON_MOUSE 320If you have a two button mouse, you may want to add this option 321to use the right button of the mouse to paste text. 322See 323.Sx Mouse Support and Copy-and-Paste 324above. 325.It Dv SC_NORM_ATTR=_attribute_ 326.It Dv SC_NORM_REV_ATTR=_attribute_ 327.It Dv SC_KERNEL_CONS_ATTR=_attribute_ 328.It Dv SC_KERNEL_CONS_REV_ATTR=_attribute_ 329These options will set the default colors. 330Available colors are defined in 331.Pa /usr/include/machine/pc/display.h . 332See 333.Sx EXAMPLES 334below. 335.It Dv SC_DFLT_FONT 336This option will specify the default font. 337Available fonts are: iso, iso2, koi8-r, koi8-u, cp437, cp850, cp865, 338cp866 and cp866u. 33916-line, 14-line and 8-line font data will be compiled in. 340Without this option, the 341.Nm 342driver will use whatever font is already loaded in the video card, 343unless you explicitly load a software font at startup. 344See 345.Sx EXAMPLES 346below. 347.El 348.Pp 349The following options will remove some features from the 350.Nm 351driver and save kernel memory. 352.Bl -tag -width MOUSE 353.It Dv SC_NO_CUTPASTE 354This option disables ``copy and paste'' operation in virtual 355terminals. 356.It Dv SC_NO_FONT_LOADING 357The 358.Nm 359driver can load software fonts on some video cards. 360This option removes this feature. 361Note that if you still wish to use 362the mouse with this option then you must also use the 363.Dv SC_ALT_MOUSE_IMAGE 364option. 365.It Dv SC_NO_HISTORY 366This option disables back-scrolling in virtual terminals. 367.\".It Dv SC_NO_PALETTE_LOADING 368.It Dv SC_NO_SYSMOUSE 369This option removes mouse support in the 370.Nm 371driver. 372The mouse daemon 373.Xr moused 8 374will fail if this option is defined. 375This option implies the 376.Dv SC_NO_CUTPASTE 377option too. 378.El 379.Ss Driver Flags 380The following driver flags can be used to control the 381.Nm 382driver. 383They can be set either in 384.Pa /boot/device.hints , 385or else at the loader prompt (see 386.Xr loader 8 ) . 387.Bl -tag -width bit_0 388.\".It bit 0 (VISUAL_BELL) 389.\"Uses the ``visual'' bell. 390.\"The screen will blink instead of generating audible sound. 391.\".It bit 1,2 (CURSOR_TYPE) 392.\"This option specifies the cursor appearance. 393.\"Possible values are: 394.\".Bl -tag -width TYPE -compact 395.\".It Dv 0 396.\"normal block cursor 397.\".It Dv 2 398.\"blinking block cursor 399.\".It Dv 4 400.\"underline cursor 401.\".It Dv 6 402.\"blinking underline (aka destructive) cursor 403.\".El 404.\".It bit 6 (QUIET_BELL) 405.\"This option suppresses the bell, whether audible or visual, 406.\"if it is rung in a background virtual terminal. 407.It 0x0080 (VESA800X600) 408This option puts the video card in the VESA 800x600 pixel, 16 color 409mode. 410It may be useful for laptop computers for which the 800x600 mode 411is otherwise unsupported by the X server. 412Note that in order for this flag to work, the kernel must be 413compiled with the 414.Dv SC_PIXEL_MODE 415option explained above. 416.\"Note also that the ``copy-and-paste'' function is not currently supported 417.\"in this mode and the mouse pointer will not be displayed. 418.It 0x0100 (AUTODETECT_KBD) 419This option instructs the syscons driver to periodically scan 420for a keyboard device if it is not currently attached to one. 421Otherwise, the driver only probes for a keyboard once during bootup. 422.El 423.Sh FILES 424.Bl -tag -width /usr/share/syscons/xxxxyyyyzzz -compact 425.It Pa /dev/console 426.It Pa /dev/consolectl 427.It Pa /dev/ttyv? 428virtual terminals 429.It Pa /etc/ttys 430terminal initialization information 431.It Pa /usr/share/syscons/fonts/* 432font files 433.It Pa /usr/share/syscons/keymaps/* 434key map files 435.It Pa /usr/share/syscons/scrmaps/* 436screen map files 437.El 438.Sh EXAMPLES 439As the 440.Nm 441driver requires the keyboard driver and the video card driver, 442the kernel configuration file should contain the following lines. 443.Pp 444.Bd -literal -offset indent 445device atkbdc 446device atkbd 447device vga 448device sc 449 450device splash 451.Ed 452You also need the following lines in 453.Pa /boot/device.hints 454for these drivers. 455.Bd -literal -offset indent 456hint.atkbdc.0.at="isa" 457hint.atkbdc.0.port="0x060" 458hint.atkbd.0.at="atkbdc" 459hint.atkbd.0.irq="1" 460hint.vga.0.at="isa" 461hint.sc.0.at="isa" 462.Ed 463.Pp 464If you do not intend to load the splash image or use the screen saver, 465the last line is not necessary, and can be omitted. 466.Pp 467Note that the keyboard controller driver 468.Nm atkbdc 469is required by the keyboard driver 470.Nm atkbd . 471.Pp 472The following lines will set the default colors. 473The normal text will be green on black background. 474The reversed text will be yellow on green background. 475Note that you cannot put any white space inside the quoted string, 476because of the current implementation of 477.Xr config 8 . 478.Pp 479.Dl "options SC_NORM_ATTR=(FG_GREEN|BG_BLACK) 480.Dl "options SC_NORM_REV_ATTR=(FG_YELLOW|BG_GREEN) 481.Pp 482The following lines will set the default colors of the kernel message. 483The kernel message will be printed bright red on black background. 484The reversed message will be black on red background. 485.Pp 486.Dl "options SC_KERNEL_CONS_ATTR=(FG_LIGHTRED|BG_BLACK) 487.Dl "options SC_KERNEL_CONS_REV_ATTR=(FG_BLACK|BG_RED) 488.Pp 489The following example adds the font files 490.Pa cp850-8x16.fnt , 491.Pa cp850-8x14.font 492and 493.Pa cp850-8x8.font 494to the kernel. 495.Pp 496.Dl "options SC_DFLT_FONT" 497.Dl "makeoptions SC_DFLT_FONT=cp850 498.Dl "device sc" 499.Pp 500.\".Sh DIAGNOSTICS 501.Sh CAVEATS 502The Amount of data that is possible to insert from the cut buffer is limited 503by the 504.Brq Dv MAX_INPUT , 505a system limit on the number of bytes that may be stored in the terminal 506input queue - usually 1024 bytes 507(see 508.Xr termios 4 ) . 509.Sh BUGS 510This manual page is incomplete and urgently needs revision. 511.Sh SEE ALSO 512.Xr kbdcontrol 1 , 513.Xr login 1 , 514.Xr vidcontrol 1 , 515.Xr atkbd 4 , 516.Xr atkbdc 4 , 517.Xr keyboard 4 , 518.Xr screen 4 , 519.Xr splash 4 , 520.Xr ukbd 4 , 521.Xr vga 4 , 522.Xr kbdmap 5 , 523.Xr rc.conf 5 , 524.Xr ttys 5 , 525.Xr config 8 , 526.Xr getty 8 , 527.Xr kldload 8 , 528.Xr moused 8 529.Sh HISTORY 530The 531.Nm 532driver first appeared in 533.Fx 1.0 . 534.Sh AUTHORS 535.An -nosplit 536The 537.Nm 538driver was written by 539.An S\(/oren Schmidt Aq sos@FreeBSD.org . 540This manual page was written by 541.An Kazutaka Yokota Aq yokota@FreeBSD.org . 542