xref: /freebsd/share/man/man4/vt.4 (revision f126890ac5386406dadf7c4cfa9566cbb56537c5)
1.\" Copyright (c) 2014 Warren Block
2.\" All rights reserved.
3.\"
4.\" Redistribution and use in source and binary forms, with or without
5.\" modification, are permitted provided that the following conditions
6.\" are met:
7.\" 1. Redistributions of source code must retain the above copyright
8.\"    notice, this list of conditions and the following disclaimer.
9.\" 2. Redistributions in binary form must reproduce the above copyright
10.\"    notice, this list of conditions and the following disclaimer in the
11.\"    documentation and/or other materials provided with the distribution.
12.\"
13.\" THIS SOFTWARE IS PROVIDED BY THE AUTHORS AND CONTRIBUTORS ``AS IS'' AND
14.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
15.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
16.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHORS OR CONTRIBUTORS BE LIABLE
17.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
18.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
19.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
20.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
21.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
22.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
23.\" SUCH DAMAGE.
24.\"
25.Dd May 8, 2023
26.Dt "VT" 4
27.Os
28.Sh NAME
29.Nm vt
30.Nd virtual terminal console driver
31.Sh SYNOPSIS
32.Cd "options TERMINAL_KERN_ATTR=_attribute_"
33.Cd "options TERMINAL_NORM_ATTR=_attribute_"
34.Cd "options VT_MAXWINDOWS=N"
35.Cd "options VT_ALT_TO_ESC_HACK=1"
36.Cd "options VT_TWOBUTTON_MOUSE"
37.Cd "options VT_FB_MAX_WIDTH=X"
38.Cd "options VT_FB_MAX_HEIGHT=Y"
39.Cd "options SC_NO_CUTPASTE"
40.Cd "device vt"
41.Pp
42In
43.Xr loader.conf 5 :
44.Cd hw.vga.textmode=1
45.Cd hw.vga.acpi_ignore_no_vga=1
46.Cd kern.vty=vt
47.Cd kern.vt.color.<colornum>.rgb="<colorspec>"
48.Cd kern.vt.fb.default_mode="<X>x<Y>"
49.Cd kern.vt.fb.modes.<connector>="<X>x<Y>"
50.Cd screen.font="<X>x<Y>"
51.Pp
52In
53.Xr loader.conf 5 or
54.Xr sysctl.conf 5 :
55.Cd kern.vt.kbd_halt=1
56.Cd kern.vt.kbd_poweroff=1
57.Cd kern.vt.kbd_reboot=1
58.Cd kern.vt.kbd_debug=1
59.Cd kern.vt.kbd_panic=0
60.Cd kern.vt.enable_altgr=0
61.Cd kern.vt.enable_bell=1
62.Sh DESCRIPTION
63The
64.Nm
65device provides multiple virtual terminals with an extensive feature
66set:
67.Bl -item -offset indent
68.It
69Unicode UTF-8 text with double-width characters.
70.It
71Large font maps in graphics mode, including support for Asian
72character sets.
73.It
74Graphics-mode consoles.
75.It
76Integration with
77KMS
78.Pq Kernel Mode Setting
79video drivers for switching between the
80.Em X Window System
81and virtual terminals.
82.El
83.Ss Virtual Terminals
84Multiple virtual terminals are provided on a single computer.
85Up to sixteen virtual terminals can be defined.
86A single virtual terminal is connected to the screen and keyboard
87at a time.
88Key combinations are used to select a virtual terminal.
89Alt-F1 through Alt-F12 correspond to the first twelve virtual terminals.
90If more than twelve virtual terminals are created, Shift-Alt-F1 through
91Shift-Alt-F4 are used to switch to the additional terminals.
92.Ss Copying and Pasting Text with a Mouse
93Copying and pasting text from the screen with a mouse is supported.
94Press and hold down mouse button 1, usually the left button, while
95moving the mouse to select text.
96Selected text is highlighted with reversed foreground and background
97colors.
98To select more text after releasing mouse button 1, press mouse button
993, usually the right button.
100To paste text that has been selected, press mouse button 2, usually the
101middle button.
102The text is entered as if it were typed at the keyboard.
103The
104.Dv VT_TWOBUTTON_MOUSE
105kernel option can be used with mice that only have two buttons.
106Setting this option makes the second mouse button into the
107paste button.
108See
109.Xr moused 8
110for more information.
111.Ss Scrolling Back
112Output that has scrolled off the screen can be reviewed by pressing the
113Scroll Lock key, then scrolling up and down with the arrow keys.
114The Page Up and Page Down keys scroll up or down a full screen at a
115time.
116The Home and End keys jump to the beginning or end of the scrollback
117buffer.
118When finished reviewing, press the Scroll Lock key again to return to
119normal use.
120Some laptop keyboards lack a Scroll Lock key, and use a special function key
121sequence (such as Fn + K) to access Scroll Lock.
122.Sh DRIVER CONFIGURATION
123.Ss Kernel Configuration Options
124These kernel options control the
125.Nm
126driver.
127.Bl -tag -width MAXCONS
128.It Dv TERMINAL_NORM_ATTR= Ns Pa attribute
129.It Dv TERMINAL_KERN_ATTR= Ns Pa attribute
130These options change the default colors used for normal and kernel
131text.
132Available colors are defined in
133.In sys/terminal.h .
134See
135.Sx EXAMPLES
136below.
137.It Dv VT_MAXWINDOWS=N
138Set the number of virtual terminals to be created to
139.Fa N .
140The value defaults to 12.
141.It Dv VT_ALT_TO_ESC_HACK=1
142When the Alt key is held down while pressing another key, send an ESC
143sequence instead of the Alt key.
144.It Dv VT_TWOBUTTON_MOUSE
145If defined, swap the functions of mouse buttons 2 and 3.
146In effect, this makes the right-hand mouse button perform a paste.
147These options are checked in the order shown.
148.It Dv SC_NO_CUTPASTE
149Disable mouse support.
150.It VT_FB_MAX_WIDTH=X
151Set the maximum width to
152.Fa X .
153.It VT_FB_MAX_HEIGHT=Y
154Set the maximum height to
155.Fa Y .
156.El
157.Sh BACKWARDS COMPATIBILITY
158Several options are provided for compatibility with the previous
159console device,
160.Xr sc 4 .
161These options will be removed in a future
162.Fx
163version.
164.Bl -column -offset indent ".Sy vt VT_TWOBUTTON_MOUSE" ".Sy SC_TWOBUTTON_MOUSE"
165.It Sy vt Option Name Ta Sy sc Option Name
166.It Dv TERMINAL_KERN_ATTR Ta Dv SC_KERNEL_CONS_ATTR
167.It Dv TERMINAL_NORM_ATTR Ta Dv SC_NORM_ATTR
168.It Dv VT_TWOBUTTON_MOUSE Ta Dv SC_TWOBUTTON_MOUSE
169.It Dv VT_MAXWINDOWS Ta Dv MAXCONS
170.It none Ta Dv SC_NO_CUTPASTE
171.El
172.Sh START-UP OPERATION WITH X86 BIOS SYSTEMS
173The computer BIOS starts in text mode, and
174the
175.Fx
176.Xr loader 8
177runs, loading the kernel.
178If
179.Va hw.vga.textmode
180is set, the system remains in text mode.
181Otherwise,
182.Nm
183switches to 640x480x16 VGA mode using
184.Cm vt_vga .
185If a KMS
186.Pq Kernel Mode Setting
187video driver is available, the display is switched to high resolution
188and the KMS driver takes over.
189When a KMS driver is not available,
190.Cm vt_vga
191remains active.
192.Sh LOADER TUNABLES
193These settings can be entered at the
194.Xr loader 8
195prompt or in
196.Xr loader.conf 5 .
197.Bl -tag -width indent
198.It Va hw.vga.textmode
199Set to 1 to use virtual terminals in text mode instead of graphics mode.
200Features that require graphics mode, like loadable fonts, will be
201disabled.
202.Pp
203If a KMS driver is loaded the console will switch to (and remain in)
204graphics mode.
205.It Va hw.vga.acpi_ignore_no_vga
206Set to 1 to force the usage of the VGA driver regardless of whether
207ACPI IAPC_BOOT_ARCH signals no VGA support.
208Can be used to workaround firmware bugs in the ACPI tables.
209Note no VGA support is only acknowledged when running virtualized.
210There is too many broken firmware that wrongly reports no VGA support on
211physical hardware.
212.It Va kern.vty
213Set this value to
214.Ql vt
215or
216.Ql sc
217to choose a specific system console, overriding the default.
218The
219.Pa GENERIC
220kernel uses
221.Nm
222when this value is not set.
223.It Va kern.vt.color. Ns Ar colornum Ns Va .rgb
224Set this value to override default palette entry for color
225.Pa colornum
226which should be in a range from 0 to 15 inclusive.
227The value should be either a comma-separated triplet of
228red, green, and blue values in a range from 0 to 255 or
229HTML-like hex triplet.
230See
231.Sx EXAMPLES
232below.
233.Pp
234Note: The
235.Nm
236VGA hardware driver does not support palette configuration.
237.It Va kern.vt.fb.default_mode
238Set this value to a graphic mode to override the default mode picked by the
239.Nm
240backend.
241The mode is applied to all output connectors.
242This is currently only supported by the
243.Cm vt_fb
244backend when it is paired with a KMS video driver.
245.It Va kern.vt.fb.modes. Ns Pa connector_name
246Set this value to a graphic mode to override the default mode picked by the
247.Nm
248backend.
249This mode is applied to the output connector
250.Pa connector_name
251only.
252It has precedence over
253.Va kern.vt.fb.default_mode .
254The names of available connector names can be found in
255.Xr dmesg 8
256after loading the KMS driver.
257It will contain a list of connectors and their associated tunables.
258This is currently only supported by the
259.Cm vt_fb
260backend when it is paired with a KMS video driver.
261.It Va screen.font
262Set this value to the base name of the desired font file located in
263.Pa /boot/fonts .
264Fonts can be converted for use with
265.Xr vtfontcvt 8 .
266.El
267.Sh KEYBOARD SYSCTL TUNABLES
268These settings control whether certain special key combinations are enabled or
269ignored.
270The specific key combinations can be configured by using a
271.Xr keymap 5
272file.
273.Pp
274These settings can be entered at the
275.Xr loader 8
276prompt or in
277.Xr loader.conf 5
278and can also be changed at runtime with the
279.Xr sysctl 8
280command.
281.Bl -tag -width indent
282.It Va kern.vt.enable_altgr
283Enable AltGr key (do not assume right Alt key as Alt).
284.It Va kern.vt.kbd_halt
285Enable halt keyboard combination.
286.It Va kern.vt.kbd_poweroff
287Enable power off key combination.
288.It Va kern.vt.kbd_reboot
289Enable reboot key combination, usually Ctrl+Alt+Del.
290.It Va kern.vt.kbd_debug
291Enable debug request key combination, usually Ctrl+Alt+Esc.
292.It Va kern.vt.kbd_panic
293Enable panic key combination.
294.El
295.Sh OTHER SYSCTL TUNABLES
296These settings can be entered at the
297.Xr loader 8
298prompt, set in
299.Xr loader.conf 5 ,
300or changed at runtime with
301.Xr sysctl 8 .
302.Bl -tag -width indent
303.It Va kern.vt.enable_bell
304Enable the terminal bell.
305.El
306.Sh FILES
307.Bl -tag -width /usr/share/vt/keymaps/* -compact
308.It Pa /dev/console
309.It Pa /dev/consolectl
310.It Pa /dev/ttyv*
311virtual terminals
312.It Pa /etc/ttys
313terminal initialization information
314.It Pa /usr/share/vt/fonts/*.fnt
315console fonts
316.It Pa /usr/share/vt/keymaps/*.kbd
317keyboard layouts
318.El
319.Sh DEVCTL MESSAGES
320.Bl -column "System" "Subsystem" "1234567" -compact
321.Sy "System" Ta Sy "Subsystem" Ta Sy "Type" Ta Sy "Description"
322.It Li VT Ta BELL Ta RING Ta
323Notification that the console bell has rung.
324.El
325.Pp
326.Bl -column "Variable" "Meaning" -compact
327.Sy "Variable" Ta Sy "Meaning"
328.It Li duration_ms Ta Length of time the bell was requested to ring in milliseconds.
329.It Li enabled Ta true or false indicating whether or not the bell was administratively enabled when rung.
330.It Li hushed Ta true or false indicating whether or not the bell was quieted by the user when rung.
331.It Li hz Ta Tone that was requested in Hz.
332.El
333.Sh EXAMPLES
334This example changes the default color of normal text to green on a
335black background, or black on a green background when reversed.
336Note that white space cannot be used inside the attribute string
337because of the current implementation of
338.Xr config 8 .
339.Pp
340.Dl "options TERMINAL_NORM_ATTR=(FG_GREEN|BG_BLACK)"
341.Pp
342This line changes the default color of kernel messages to be bright red
343on a black background, or black on a bright red background when reversed.
344.Pp
345.Dl "options TERMINAL_KERN_ATTR=(FG_LIGHTRED|BG_BLACK)"
346.Pp
347To set a 1024x768 mode on all output connectors, put the following line in
348.Pa /boot/loader.conf :
349.Pp
350.Dl kern.vt.fb.default_mode="1024x768"
351.Pp
352To set a 800x600 only on a laptop builtin screen, use the following line instead:
353.Pp
354.Dl kern.vt.fb.modes.LVDS-1="800x600"
355.Pp
356The connector name was found in
357.Xr dmesg 8 :
358.Pp
359.Dl info: [drm] Connector LVDS-1: get mode from tunables:
360.Dl info: [drm]   - kern.vt.fb.modes.LVDS-1
361.Dl info: [drm]   - kern.vt.fb.default_mode
362.Pp
363To set black and white colors of console palette
364.Pp
365.Dl kern.vt.color.0.rgb="10,10,10"
366.Dl kern.vt.color.15.rgb="#f0f0f0"
367.Pp
368Load the 8x16 font in
369.Xr loader.conf 5
370from
371.Pa /boot/fonts/*.fnt[.gz]
372at boot:
373.Pp
374.Dl screen.font="8x16"
375.Sh SEE ALSO
376.Xr kbdcontrol 1 ,
377.Xr login 1 ,
378.Xr vidcontrol 1 ,
379.Xr atkbd 4 ,
380.Xr atkbdc 4 ,
381.Xr kbdmux 4 ,
382.Xr keyboard 4 ,
383.Xr screen 4 ,
384.Xr splash 4 ,
385.Xr syscons 4 ,
386.Xr ukbd 4 ,
387.Xr kbdmap 5 ,
388.Xr loader.conf 5 ,
389.Xr rc.conf 5 ,
390.Xr ttys 5 ,
391.Xr config 8 ,
392.Xr getty 8 ,
393.Xr kldload 8 ,
394.Xr moused 8 ,
395.Xr vtfontcvt 8
396.Sh HISTORY
397The
398.Nm
399driver first appeared in
400.Fx 9.3 .
401.Sh AUTHORS
402.An -nosplit
403The
404.Nm
405device driver was developed by
406.An \&Ed Schouten Aq Mt ed@FreeBSD.org ,
407.An \&Ed Maste Aq Mt emaste@FreeBSD.org ,
408and
409.An Aleksandr Rybalko Aq Mt ray@FreeBSD.org ,
410with sponsorship provided by the
411.Fx
412Foundation.
413This manual page was written by
414.An Warren Block Aq Mt wblock@FreeBSD.org .
415.Sh CAVEATS
416Paste buffer size is limited by the system value
417.Brq Dv MAX_INPUT ,
418the number of bytes that can be stored in the terminal
419input queue, usually 1024 bytes
420(see
421.Xr termios 4 ) .
422