===== Introduction =====

vt(4) is the virtual terminal console driver implementation (also known as the "Newcons" project) which replaces syscons(4), adding the following features:

  * Unicode support.
  * Double-width character support for CJK characters.
  * Bigger font maps (because of the use of graphics mode).
  * Better use of graphics modes, enabling more appealing graphical boot experiences.

It was added to CURRENT in [[https://cgit.freebsd.org/src/commit/?id=27cf7d04ef5416dc7fcbf43bc8147463b0d87848|r259016]] (2013-12-05) and enabled by default in GENERIC for amd64 and i386 architectures in [[https://svnweb.freebsd.org/changeset/base/268045|r268045]] (2014-06-30).

===== syscons(4) Comparison =====

vt(4) currently has the following features compared to syscons:un

Note: Additional vt(4) features will be implemented; this table does not represent the end goal for vt(4).

^ Feature ^ syscons(4) ^ vt(4) ^
| splash screen support | Yes | Limited (see [[MateuszPiotrowski/ImproveVtSplashScreenSupport|ImproveVtSplashScreenSupport]]) |
| ASCII encoding | Yes | Yes |
| UTF-8 encoding | No | Yes |
| Encodings other than ASCII/UTF-8 | Yes | No |
| Double-width characters (for CJK) | No | Yes |
| VGA text mode font changing | Yes | No |
| VGA vesa | Yes | Limited (vt_vbefb supports the mode set by the loader) |
| screensaver | Yes | No |
| Kernel Modesetting (KMS) integration | No | Yes |
| More than 256 distinct characters on screen | No | Yes |
| support for hardware mouse cursors | Yes | No |

===== Testing =====

==== i386/amd64 ====

The ''%%vt%%'' and ''%%vt_vga%%'' devices are enabled by default; if using a custom kernel make sure they are included. The ''%%sc%%'' and ''%%vga%%'' devices may be omitted.

<code>
#device        vga             # VGA video card driver
#device        sc
device         vt
device         vt_vga
</code>

To test vt(4) with KMS on Intel driver

<code>
kldload i915kms
</code>

For ATI/AMD Radeon drivers

<code>
kldload radeonkms
</code>

''%%vt_vga%%'' defaults to graphics mode.  A loader tunable ''%%hw.vga.textmode%%'' can be set to use text mode instead.  To enable text mode add the following to /boot/loader.conf:

<code>
hw.vga.textmode=1
</code>

==== PowerPC ====

vt(4) is enabled by default in GENERIC in -CURRENT.

===== Font Support =====

The vtfontcvt(8) tool can convert BDF and HEX format font files for use by the vt(4) console.

For example, a 16x32 version of the terminus font can be created as follows:
  - Obtain the latest [[http://sourceforge.net/projects/terminus-font/files/latest/download?source=files|Terminus font distribution]] and extract it
  - Convert it to a vt(4) .fnt file:

<code>
% vtfontcvt -w 16 -h 32 ter-u32n.bdf ter-u32b.bdf ter-u32.fnt
</code>

  - Load it from a console window:

<code>
% vidcontrol -f ter-u32.fnt
</code>

===== TODO =====

^ Feature ^ Status ^
| Generic terminal layer for the kernel | DONE |
| Core of the vt driver, screen buffering, drawing, etc | DONE |
| Make the keyboard layer accept Unicode | DONE |
| Migrate syscons to xterm, to ease switching between vt(4) and syscons | DONE |
| Make kernel mode setting work: to be investigated. | DONE |
| Scrollback | Works |
| Moused support | Works |
| kbdcontrol(1) | In progress: PR 204837 |
| +--- kbdmap load | Works. |
| +--- kbdmux control | Works. |
| kbdmap(1) front end | Works. |
| vidcontrol(1) | In progress |
| +--- Font load | Works |
| +--- Font console attributes | Works |
| +--- Colormap | Not yet |
| +--- Clear history | Done (r361601, PR 224436) |
| +--- CONS_BLANKTIME | Not implemented: PR 233356 |
| vidfont(1) front end | DONE |
| Switch to text when required | Works |
| ddb(4) debugger | Works |
| Integration with X11 | Works |
| vt(4) man page | DONE |
| double width character support | Done |
| CJK fonts [[Newcons/Fonts]] | In progress |
| UTF-8 keymaps | DONE |
| Update %%FreeBSD%% Handbook | Unstarted |
| Keyboard and char map support for other than Unicode UTF-8 | Unstarted |
| Font setting from loader (at kernel start) | Unstarted |
| //Architecture / Hardware Specific// ||
| amd64 | Works (VGA/i915kms/radeonkms) |
| ARM | Works Framebuffer. |
| arm64 | Unknown |
| i386 | Works (VGA/i915kms/radeonkms) |
| MIPS | Works |
| PPC | Works |
| SPARC | Works |
| VGA driver that supports at least 80x25 text mode and 640x480 graphics mode | DONE |
| VESA driver | Limited functionality (mode switch only by loader) |
| Graphics driver that works with Intel and ATI/AMD | DONE |
| i386/amd64 nvidia driver | Works |
| Xbox framebuffer driver (as a test, because it's easy to do so) | DONE |
| DRM notification on panic/reboot/shutdown/debugger | DONE |
| Screen saver | Unstarted |

===== Known Issues =====

Search for PRs tagged with the [[https://bugs.freebsd.org/bugzilla/buglist.cgi?keywords=vt&list_id=28354&resolution=---|vt keyword]]
  * No support for non-UTF-8 charmap (e.g. ru_RU.KOI8-R).
  * Limited support for modesetting.
    * [[http://svnweb.freebsd.org/base?view=revision&revision=274031|Partly fixed]] with a KMS driver (''%%i915kms%%'' or ''%%radeonkms%%''): one can set a mode by putting this in ''%%/boot/loader.conf%%'':

<code>
kern.vt.fb.default_mode="1024x768"
</code>

  * No support for several vidcontrol(1) features.
  * No support for VGA text mode loadable fonts.
  * No support for moused(8) in VGA text mode.
  * No support for vgl(3).
  * No support for DPMS.
  * No support for splash(4).
  * Support only 16 colors.
  * Pre-loading i915kms.ko/radeonkms.ko disables video output from the point of time these video drivers are attached until interrupt threads are enabled way later. This makes kernel panics during boot undebugable.
  * Machines with at least certain Intel Ivy Bridge hardware may reliably panic when pre-loading i915kms.ko (but work when loading i915kms.ko after boot). Please submit a PR with details if you reproduce this.
  * Machines with at least certain Radeon ARUBA hardware may reliably panic when loading radeonkms.ko after boot (but work when pre-loading radeonkms.ko). Please submit a PR with details if you reproduce this.
  * If drm2 have 2+ outputs, it decides to use too big a window, which is not fully visible on one or both screens.
  * Console output with at least VGA in graphics mode or via i915kms.ko/radeonkms.ko still is remarkably slow, especially compared to syscons(4) with VGA text mode.
  * Having text marked for copy and paste and then launching something that clears the screen, f. e. vi(1), leaves the region of previous text still marked.
  * [[https://github.com/SkunkOS/SkunkInstall/discussions/4|Why Skunk in some cases uses the SC console instead of the VT newcons console · Discussion #4 · SkunkOS/SkunkInstall]]

===== Fixed Issues =====
  * No mouse terminal events yet (terminal char sequence for app notification on mouse event).
  * (looks like) Failure mode with incorrect mix of options (e.g. vt w/ vga) is not obvious
  * Scrolling / refresh is very slow on some hardware
  * Newcons w/ gallant12x22 font does not clear the screen properly: http://people.freebsd.org/~emaste/newcons/gallant.png
  * Newcons locks up w/ gallant12x22 font in VirtualBox
  * When resuming from suspend, switching back from ttyv0 may cause a kernel panic (vt_switch_timer).  To disable the vt switch, add kern.vt.suspendswitch=0 in loader.conf.
    * http://lists.freebsd.org/pipermail/freebsd-current/2013-December/047175.html
    * http://lists.freebsd.org/pipermail/freebsd-current/2014-March/048857.html
  * No beep in X
    * [[http://www.freebsd.org/cgi/query-pr.cgi?pr=189170|kern/189170]]
    * [[http://svnweb.freebsd.org/base?view=revision&revision=265442|r265442]]
    * [[http://svnweb.freebsd.org/base?view=revision&revision=265546|r265546]]
  * vidcontrol -S on/off (enable/disable vty switch) does not work
    * [[http://svnweb.freebsd.org/base?view=revision&revision=266540|r266540]]
  * Scrollback fails on vty0 (others work)
  * VGA driver produces corrupted output with fonts other than 8 pixels wide. [[https://bugs.freebsd.org/191591|pr191591]]
  * Switch to vty0 on panic/reboot/shutdown/debugger fails from X (works from other VTs)
    * e.g. ''%%sysctl debug.kdb.enter=1%%'' from xterm
    * [[http://svnweb.freebsd.org/base?view=revision&revision=270705|r270705]]
  * X crash on Unicode input (some mistake with enabling RAW kbd mode) [[https://bugs.freebsd.org/191459|pr191459]]
  * Control keys mishandled on entry to ddb. For instance, use Ctrl+Alt+Esc to enter debugger, then 'c'. Ctrl and/or Alt are still active.
  * The text cursor may end up in the middle of kernel messages after loading a kernel video driver ([[http://svnweb.freebsd.org/base?view=revision&revision=273932|r273932]]).
  * PS/2 keyboard might fail in X - add ''%%kbdmux%%'' to kernel config (see [[http://lists.freebsd.org/pipermail/freebsd-current/2014-March/048917.html|freebsd-current posting]]) ([[http://svnweb.freebsd.org/base?view=revision&revision=273973|r273973]]).
  * No support for configurable history size (even compile-time) ([[http://svnweb.freebsd.org/base?view=revision&revision=274117|274117]]).
  * The keymap selection in the installer doesn't work properly ([[https://bugs.freebsd.org/bugzilla/show_bug.cgi?id=193656]]).
    * [[https://svnweb.freebsd.org/changeset/base/282898|r282898]], [[https://svnweb.freebsd.org/changeset/base/282902|r282902]], [[https://svnweb.freebsd.org/changeset/base/282905|r282905]], [[https://svnweb.freebsd.org/changeset/base/282914|r282914]]
  * The screen isn't cleared at boot in some cases ([[https://bugs.freebsd.org/bugzilla/show_bug.cgi?id=191564]]).
    * [[https://svnweb.freebsd.org/changeset/base/286667|r286667]], [[https://svnweb.freebsd.org/changeset/base/286723|r286723]]
  * kbdmux control [[http://bugs.freebsd.org/191306|pr191306]])
  * During output of large amounts of text certain fractions repeatedly are incorrecly displayed as marked text. (PR211922)

===== Credits =====
Significant contributors to vt(4) include:
  * [[WarrenBlock|Warren Block]]
  * [[StefanEsser|StefanEsser]]
  * [[EdMaste|Ed Maste]]
  * [[JeanSébastienPédron|Jean-Sébastien Pédron]]
  * [[EdSchouten|Ed Schouten]]
  * [[AleksandrRybalko|Aleksandr Rybalko]]
  * [[NathanWhitehorn|Nathan Whitehorn]]

----

{{tag>Project}}