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