File:  [NetBSD Developer Wiki] / wikisrc / guide / cons.mdwn
Revision 1.1: download - view: text, annotated - select for diffs
Thu Mar 7 00:14:15 2013 UTC (13 months, 1 week ago) by jdf
Branches: MAIN
CVS tags: HEAD
cons Guide -> wiki

# Console drivers

In NetBSD versions before 1.4 the user could choose between two different
drivers for screen and keyboard, pccons (specific for i386) and pcvt. In NetBSD
1.4 the new wscons multiplatform driver appeared, which has substituted the
previous drivers.

## 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.

The capabilities of wscons can vary depending on the port. Starting with NetBSD
4.0, almost all ports have full support for most capabilities wscons has to
offer. If you are using a non-mainstream architecture, please see the
port-specific FAQ if wscons seems to lack features.

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
[[Virtual consoles|guide/cons#wscons-wsdisplay-vt]] 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+F*n* 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.

### wsdisplay

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

#### Virtual consoles

The number of pre-allocated virtual console is controlled by the following
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 `rc.wscons` script transforms each of the non commented lines in a call to
the
[wsconscfg(8)](http://netbsd.gw.com/cgi-bin/man-cgi?wsconscfg+8+NetBSD-current)
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)](http://netbsd.gw.com/cgi-bin/man-cgi?getty+8+NetBSD-5.0.1+i386)
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)](http://netbsd.gw.com/cgi-bin/man-cgi?getty+8+NetBSD-5.0.1+i386)
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 `vt#` must be passed to the X
server, where `#` 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/X11R6/bin/X +kb dpms -bpp 16 dpms vt8

For xdm3d the path is different: `/usr/X11R6/share/xdm3d/Xservers`.

##### Getting rid of the message `WSDISPLAYIO_ADDSCREEN: Device busy`

This error message usually occurs when wsconscfg tries to add a screen which
already exists. One time this occurs is 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.

#### 50 lines text mode with wscons

A text mode with 50 lines can be used starting with version 1.4.1 of NetBSD.
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-F#` (where `#` varies from 1 to 8); the corresponding
devices are `ttyE0` to `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

#### 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).

Starting in NetBSD 6.0 ,
[vesafb(4)](http://netbsd.gw.com/cgi-bin/man-cgi?vesafb+4+NetBSD-5.0.1+i386) has
been replaced with
[genfb(4)](http://netbsd.gw.com/cgi-bin/man-cgi?genfb+4+NetBSD-5.0.1+i386). VESA
framebuffer mode is configured during
[boot(8)](http://netbsd.gw.com/cgi-bin/man-cgi?boot+8+NetBSD-5.0.1+i386) using
the `vesa` command.

To enable support for this mode in NetBSD 4.x and 5.x, uncomment the following
lines in the kernel configuration file:

    # VESA framebuffer console
    options     KVM86           # required for vesabios
    vesabios*   at vesabiosbus?
    vesafb*     at vesabios?
    options     VESAFB_WIDTH=640
    options     VESAFB_HEIGHT=480
    options     VESAFB_DEPTH=8
    options     VESAFB_PM       # power management support
    wsdisplay*  at vesafb? console ?

Beginning in NetBSD 4.0, if you have a VIA Unichrome-family graphics device, you
can enable the following instead:

    # VIA Unichrome framebuffer console
    unichromefb*    at pci? dev ? function ?
    wsdisplay*  at unichromefb?

#### 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
[[Compiling the kernel|guide/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`)!

#### wscons and colors

##### 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`](http://cvsweb.NetBSD.org/bsdweb.cgi/src/sys/dev/wscons/wsdisplayvar.h?rev=HEAD&content-type=text/x-cvsweb-markup).

Starting from NetBSD 3.0, 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)](http://netbsd.gw.com/cgi-bin/man-cgi?wsconsctl+8+NetBSD-5.0.1+i386)
utility; the later 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)](http://netbsd.gw.com/cgi-bin/man-cgi?wsconsctl+8+NetBSD-5.0.1+i386):

 * `border`: The color of the screen border. Its respective kernel option is
   `WSDISPLAY_BORDER_COLOR`.
instructions on building a kernel.
 * `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 later
   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 later
   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.

##### Getting applications to use colors on the console

NetBSD uses the termcap 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 termcap 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/termcap` to see
if you can find a useful match for your console type.

#### 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)](http://netbsd.gw.com/cgi-bin/man-cgi?wsfontload+8+NetBSD-5.0.1+i386)
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`](http://ftp.NetBSD.org/pub/pkgsrc/current/pkgsrc/sysutils/pcvt-utils/README.html)
package.

### wskbd

#### 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 can be found in
`/usr/src/sys/dev/wscons/wsksymdef.h`:

 * `be` - Belgian
 * `de` - German
 * `dk` - Danish
 * `es` - Spanish
 * `fi` - Finnish
 * `fr` - French
 * `gr` - Greek
 * `hu` - Hungarian
 * `it` - Italian
 * `jp` - Japanese
 * `no` - Norwegian
 * `pl` - Polish
 * `pt` - Portuguese
 * `ru` - Russian
 * `sf` - Swiss French
 * `sg` - Swiss German
 * `sv` - Swedish
 * `ua` - Ukrainian
 * `uk` - UK-English
 * `us` - US-English

There are also several "variants" that can be used to modify a map:

 * `declk`
 * `dvorak`
 * `iopener`
 * `lk401`
 * `metaesc`
 * `nodead`
 * `swapctrlcaps`

`dvorak` uses the Dvorak keyboard layout. `swapctrlcaps` switches the functions
of the Caps Lock and Left Control keys. `iopener` is for the nonstandard
keyboard layout on the Netpliance i-opener and makes F1 into Escape and F2
through F12 into F1 through F11. These can be combined with another map by
appending a dot and then the variant name, for example, `us.iopener`. Multiple
variants can be combined, such as `us.dvorak.swapctrlcaps`. Note that not all
combinations are allowed.

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 (eg: `PCKBD_LAYOUT=KB_FR`). Variants can be bitwise or'd in (eg:
`PCKBD_LAYOUT=KB_US|KB_SWAPCTRLCAPS`).

Configuring the keyboard layout under X is described
[elsewhere](http://www.NetBSD.org/docs/x/#x-keyboard-maps).

##### Hacking wscons to add a keymap

If your favourite keymap is not supported, you can start digging in
[`src/sys/dev/wscons/wsksymdef.h`](http://cvsweb.NetBSD.org/bsdweb.cgi/src/sys/dev/wscons/wsksymdef.h?rev=HEAD&content-type=text/x-cvsweb-markup)
and
[`src/sys/dev/pckbport/wskbdmap_mfii.c`](http://cvsweb.NetBSD.org/bsdweb.cgi/src/sys/dev/pckbport/wskbdmap_mfii.c?rev=HEAD&content-type=text/x-cvsweb-markup)
to make your own. Be sure to
[send-pr](http://www.NetBSD.org/support/send-pr.html#submitting) 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"

#### Changing the keyboard repeat speed

Keyboard repeat speed can be tuned using the
[wsconsctl(8)](http://netbsd.gw.com/cgi-bin/man-cgi?wsconsctl+8+NetBSD-5.0.1+i386)
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

### wsmouse

#### Serial mouse support

The wsmouse device (part of wscons) does not directly support serial mice. The
[moused(8)](http://netbsd.gw.com/cgi-bin/man-cgi?moused+8+NetBSD-5.0.1+i386)
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)](http://netbsd.gw.com/cgi-bin/man-cgi?moused+8+NetBSD-5.0.1+i386) man
page contains more examples.

#### 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)](http://netbsd.gw.com/cgi-bin/man-cgi?wsmoused+8+NetBSD-5.0.1+i386)
see its manpage, which also describes the format of the
[wsmoused.conf(5)](http://netbsd.gw.com/cgi-bin/man-cgi?wsmoused.conf+5+NetBSD-5.0.1+i386)
config file, an example of which can be found in `/usr/share/examples/wsmoused`.


CVSweb for NetBSD wikisrc <wikimaster@NetBSD.org> software: FreeBSD-CVSweb