Chapter 8. Console drivers

Table of Contents

8.1. wscons
8.1.1. wsdisplay
8.1.2. wskbd
8.1.3. wsmouse

8.1. wscons

Wscons is NetBSD's platform-independent workstation console driver. It handles complete abstraction of keyboards and mice. This means that you can plug in several keyboards or mice and they will be multiplexed onto a single terminal, but also that it can multiplex several virtual terminals onto one physical terminal.

Wscons support is enabled by default on most architectures. This can be done manually by adding wscons=YES to your /etc/rc.conf. Then configure the desired number of virtual consoles as described in Section 8.1.1.1, “Virtual consoles” and start wscons by entering sh /etc/rc.d/wscons start followed by sh /etc/rc.d/ttys restart. You can now switch virtual consoles by pressing Ctrl+Alt+Fn or similar, depending on the platform.

Wscons comprises three subsystems: wsdisplay, wskbd and wsmouse. These subsystems handle abstraction for all display, keyboard and mouse devices respectively. The following sections discuss the configuration of wscons per subsystem.

8.1.1. wsdisplay

This section will explain how to configure display and screen-related options.

8.1.1.1. Virtual consoles

The number of pre-allocated virtual console is controlled by the following kernel configuration option

options     WSDISPLAY_DEFAULTSCREENS=4

Other consoles can be added by enabling the relevant lines in the /etc/wscons.conf file: the comment mark (#) must be removed from the lines beginning with screen x. In the following example a fifth console is added to the four pre-allocated ones:

# screens to create
#       idx     screen  emul
#screen 0       -       vt100
screen  1       -       vt100
screen  2       -       vt100
screen  3       -       vt100
screen  4       -       -
#screen 4       80x25bf vt100
#screen 5       80x50   vt100

The /etc/rc.d/wscons script transforms each of the non commented lines in a call to the wsconscfg command: the columns become the parameters of the call. The idx column becomes the index parameter, the screen column becomes the -t type parameter (which defines the type of screen: rows and columns, number of colors, ...) and the emul column becomes the -e emul parameter, which defines the emulation. For example:

screen 3       -       vt100

becomes a call to:

wsconscfg -e vt100 3

Please note that it is possible to have a (harmless) conflict between the consoles pre-allocated by the kernel and the consoles allocated at boot time through /etc/wscons.conf. If during boot the system tries to allocate an already allocated screen, the following message will be displayed:

wsconscfg: WSDISPLAYIO_ADDSCREEN: Device busy

The solution is to comment out the offending lines in /etc/wscons.conf.

Note that while it is possible to delete a screen and add it with different settings, it is, technically speaking, not possible to actually modify the settings of a screen.

screen 0 cannot be deleted if used as system console. This implies that the setting of screen 0 cannot be changed in a running system, if used as system console.

The virtual console must also be active in /etc/ttys, so that NetBSD runs the getty(8) program to ask for login. For example:

console "/usr/libexec/getty Pc"         pc3     off secure
ttyE0   "/usr/libexec/getty Pc"         vt220   on secure
ttyE1   "/usr/libexec/getty Pc"         vt220   on secure
ttyE2   "/usr/libexec/getty Pc"         vt220   on secure
ttyE3   "/usr/libexec/getty Pc"         vt220   off secure
...

When starting up the X server, it will look for a virtual console with no getty(8) program running, e.g. one console should left as "off" in /etc/ttys. The line

ttyE3   "/usr/libexec/getty Pc"         vt220   off secure

of /etc/ttys is used by the X server for this purpose. To use a screen different from number 4, a parameter of the form vtn must be passed to the X server, where n is the number of the function key used to activate the screen for X.

For example, screen 7 could be enabled in /etc/wscons.conf and X could be started with vt8. If you use xdm you must edit /etc/X11/xdm/Xservers. For example:

:0 local /usr/X11R7/bin/X +kb dpms -bpp 16 dpms vt8
8.1.1.1.1. Getting rid of the message WSDISPLAYIO_ADDSCREEN: Device busy

This error message usually occurs when wsconscfg tries to add a screen which already exists. This occurs if you have a screen 0 line in your /etc/wscons.conf file, because the kernel always allocates a screen 0 as the console device. The error message is harmless in this case, and you can get rid of it by deleting (or commenting out) the screen 0 line.

8.1.1.2. 50 lines text mode with wscons

This mode is activated in the /etc/wscons.conf. The following line must be uncommented:

font ibm  -  8  ibm  /usr/share/pcvt/fonts/vt220l.808

Then the following lines must be modified:

#screen 0       80x50   vt100
screen  1       80x50   vt100
screen  2       80x50   vt100
screen  3       80x50   vt100
screen  4       80x50   vt100
screen  5       80x50   vt100
screen  6       80x50   vt100
screen  7       80x50   vt100

This configuration enables eight screens, which can be accessed with the key combination Ctrl-Alt-Fn (where n varies from 1 to 8); the corresponding devices are ttyE0..ttyE7. To enable them and get a login prompt, /etc/ttys must be modified:

ttyE0   "/usr/libexec/getty Pc"         vt220   on secure
ttyE1   "/usr/libexec/getty Pc"         vt220   on secure
ttyE2   "/usr/libexec/getty Pc"         vt220   on secure
ttyE3   "/usr/libexec/getty Pc"         vt220   on secure
ttyE4   "/usr/libexec/getty Pc"         vt220   on secure
ttyE5   "/usr/libexec/getty Pc"         vt220   on secure
ttyE6   "/usr/libexec/getty Pc"         vt220   on secure
ttyE7   "/usr/libexec/getty Pc"         vt220   on secure

screen 0 as system console can be set to another screen type at boot time on VGA displays. This is a kernel configuration option. If a non-80x25 setting is selected, it must be made sure that a usable font is compiled into the kernel, which would be an 8x8 one for 80x50.

There is a problem with many ATI graphics cards which don't implement the standard VGA font switching logics: These need another kernel option to make a nonstandard console font work.

An example set of kernel configuration options might be:

options VGA_CONSOLE_SCREENTYPE="\"80x50\""
options VGA_CONSOLE_ATI_BROKEN_FONTSEL
options FONT_VT220L8x8

8.1.1.3. Enabling framebuffer console

On many architectures, there is only one type of screen mode: a graphical framebuffer mode. On machines with VGA graphics cards, there is a second mode: textmode. This is an optimized mode specially made for displaying text. Hence, this is the default console mode for GENERIC kernels on architectures where the graphics card is typically a VGA card (i386, amd64).

However, you can enable a framebuffer on machines with VGA cards that support the VESA BIOS extension (VBE).

VESA framebuffer mode is configured during boot(8) using the vesa command.

8.1.1.4. Enabling scrollback on the console

You can enable scrolling back on wscons consoles by compiling the WSDISPLAY_SCROLLSUPPORT option into your kernel. Make sure you don't have option VGA_RASTERCONSOLE enabled at the same time though! See Chapter 34, Compiling the kernel for instructions on building a kernel.

When you have a kernel with options WSDISPLAY_SCROLLSUPPORT running, you can scroll up on the console by pressing LEFT SHIFT plus PAGE UP/DOWN. Please note that this may not work on your system console (ttyE0)!

8.1.1.5. Wscons and colors

8.1.1.5.1. Changing the color of kernel messages

It is possible to change the foreground and background color of kernel messages by setting the following options in kernel config files:

options WS_KERNEL_FG=WSCOL_xxx
options WS_KERNEL_BG=WSCOL_xxx

The WSCOL_xxx color constants are defined in src/sys/dev/wscons/wsdisplayvar.h.

You can easily customize many aspects of your display appearance: the colors used to print normal messages, the colors used to print kernel messages and the color used to draw a border around the screen.

All of these details can be changed either from kernel options or through the wsconsctl(8) utility; the latter may be preferable if you don't want to compile your own kernel, as the default options in GENERIC are suitable to get this tip working.

The following options can be set through wsconsctl(8):

  • border: The color of the screen border. Its respective kernel option is WSDISPLAY_BORDER_COLOR.

  • msg.default.attrs: The attributes used to print normal console messages. Its respective kernel options are WS_DEFAULT_COLATTR and WS_DEFAULT_MONOATTR (the former is used in color displays, while the latter is used in monochrome displays).

  • msg.default.bg: The background color used to print normal console messages. Its respective kernel option is WS_DEFAULT_BG.

  • msg.default.fg: The foreground color used to print normal console messages. Its respective kernel option is WS_DEFAULT_FG.

  • msg.kernel.attrs: The attributes used to print kernel messages and warnings. Its respective kernel options are WS_KERNEL_COLATTR and WS_KERNEL_MONOATTR (the former is used in color displays, while the latter is used in monochrome displays).

  • msg.kernel.bg: The background color used to print kernel messages and warnings. Its respective kernel option is WS_KERNEL_BG.

  • msg.kernel.fg: The foreground color used to print kernel messages and warnings. Its respective kernel option is WS_KERNEL_FG.

The values accepted as colors are: black, red, green, brown, blue, magenta, cyan and white. The attributes are a comma separated list of one or more flags, which can be: reverse, hilit, blink and/or underline.

For example, to emulate the look of one of those old Amstrad machines:

wsconsctl -d -w border=blue msg.default.bg=blue msg.default.fg=white msg.default.attrs=hilit

Or, to make your kernel messages appear red:

wsconsctl -d -w msg.kernel.fg=red

Note that, in older versions of NetBSD, only a subset of this functionality is available; more specifically, you can only change the kernel colors by changing kernel options, as explained above. Also note that not all drivers support these features, so you may not get correct results on all architectures.

8.1.1.5.2. Getting applications to use colors on the console

NetBSD uses the terminfo database to tell applications what the current terminal's capabilities are. For example, some terminals don't support colors, some don't support underlining (PC VGA terminals don't, for example) etc. The TERM environment variable tells the terminfo library the type of terminal. It then refers to its database for the options.

The default setting for TERM can be inspected by typing echo $TERM on the terminal of interest. Usually this is something like vt220. This terminal type doesn't support colors. On a typical PC console with 25 lines, you can change this value to wsvt25 instead, to get colors. This is done in the C shell (csh) by entering:

setenv TERM wsvt25

In a Bourne-compatible shell (sh, ksh), you can enter:

export TERM=wsvt25

If this does not work for you, you can try the ansi terminal type, which supports ANSI color codes. However, other functionality may be missing with this terminal type. You can have a look at the file /usr/share/misc/terminfo to see if you can find a useful match for your console type.

8.1.1.6. Loading alternate fonts

There are several fonts in /usr/share/wscons/fonts that can be loaded as console fonts. This can be done with the wsfontload(8) command, for example: wsfontload -N ibm -h 8 -e ibm /usr/share/wscons/fonts/vt220l.808. This command loads the IBM-encoded (-e ibm) font in the file vt2201.808 which has a height of eight pixels (-h 8). Name it ibm for later reference (-N ibm).

To actually display the font on the console, use the command wsconsctl -dw font=ibm.

If you want to edit a font, you can use the old pcvt utils that are available in the sysutils/pcvt-utils package.

8.1.2. wskbd

8.1.2.1. Keyboard mappings

Wscons also allows setting the keymap to map the keys on various national keyboards to the right characters. E.g. to set the keymap for an Italian keymap, run:

# wsconsctl -k -w encoding=it
encoding -> it

This setting will last until the next reboot. To make it permanent, add a encoding line to /etc/wscons.conf: it will be executed automatically the next time you reboot.

# cp /etc/wscons.conf /etc/wscons.conf.orig
# echo encoding it >>/etc/wscons.conf

Please be careful and type two > characters. If you type only one >, you will overwrite the file instead of adding a line. But that's why we always make backup files before touching critical files!

A full list of keyboard mappings and variants can be found in wskbd(4).

You can change the compiled in kernel default by adding options PCKBD_LAYOUT=KB_encoding where encoding is an uppercase entry from the list above (e.g.: PCKBD_LAYOUT=KB_FR). Variants can be bitwise or'd in (e.g.: PCKBD_LAYOUT=KB_US|KB_SWAPCTRLCAPS).

Configuring the keyboard layout under X is described elsewhere.

8.1.2.1.1. Hacking wscons to add a keymap

If your favourite keymap is not supported, you can start digging in src/sys/dev/wscons/wsksymdef.h and src/sys/dev/pckbport/wskbdmap_mfii.c to make your own. Be sure to send-pr a change-request PR with your work, so others can make use of it!

You can test your keymap by using wsconsctl instead of directly hacking the keymaps into the keyboard mapping file. For example, to say keycode 51 without any modifiers should map to a comma, with shift it should map to a question mark, with alt it should map to a semicolon and with both alt and shift it should map to colon, issue the following command:

wsconsctl -w "map += keycode 51=comma question semicolon colon"

8.1.2.2. Changing the keyboard repeat speed

Keyboard repeat speed can be tuned using the wsconsctl(8) utility. There are two variables of interest: repeat.del1, which specifies the delay before character repetition starts, and repeat.deln, which sets the delay between each character repetition (once started).

Let's see an example, assuming you want to accelerate keyboard speed. You could do, from the command line:

wsconsctl -w repeat.del1=300
wsconsctl -w repeat.deln=40

Or, if you want this to happen automatically every time you boot up the system, you could add the following lines to /etc/wscons.conf:

setvar repeat.del1=300
setvar repeat.deln=40

8.1.3. wsmouse

8.1.3.1. Serial mouse support

The wsmouse device (part of wscons) does not directly support serial mice. The moused(8) daemon is provided to read serial mouse data, convert it into wsmouse events and inject them in wscons' event queue, so the mouse can be used through the abstraction layer provided by wsmouse.

A typical use can be: moused -p /dev/tty00. This will try to determine the type of mouse connected to the first serial port and start reading its data. The moused(8) man page contains more examples.

8.1.3.2. Cut&paste on the console with wsmoused

It is possible to use the mouse on the wscons console to mark (cut) text with one mouse button, and insert (paste) it again with another button.

To do this, enable "wsmoused" in /etc/rc.conf, and start it:

# echo wsmoused=yes >>/etc/rc.conf
# sh /etc/rc.d/wsmoused start 

After that you can use the mouse to mark text with the left mouse button, and paste it with the right one. To tune the behaviour of wsmoused(8) see its manpage, which also describes the format of the wsmoused.conf(5) config file, an example of which can be found in /usr/share/examples/wsmoused.