Annotation of wikisrc/guide/cons.mdwn, revision 1.2

1.2     ! jdf         1: **Contents**
        !             2: 
        !             3: [[!toc levels=3]]
        !             4: 
1.1       jdf         5: # Console drivers
                      7: In NetBSD versions before 1.4 the user could choose between two different
                      8: drivers for screen and keyboard, pccons (specific for i386) and pcvt. In NetBSD
                      9: 1.4 the new wscons multiplatform driver appeared, which has substituted the
                     10: previous drivers.
                     12: ## wscons
                     14: Wscons is NetBSD's platform-independent workstation console driver. It handles
                     15: complete abstraction of keyboards and mice. This means that you can plug in
                     16: several keyboards or mice and they will be multiplexed onto a single terminal,
                     17: but also that it can multiplex several virtual terminals onto one physical
                     18: terminal.
                     20: The capabilities of wscons can vary depending on the port. Starting with NetBSD
                     21: 4.0, almost all ports have full support for most capabilities wscons has to
                     22: offer. If you are using a non-mainstream architecture, please see the
                     23: port-specific FAQ if wscons seems to lack features.
                     25: Wscons support is enabled by default on most architectures. This can be done
                     26: manually by adding `wscons=YES` to your `/etc/rc.conf`. Then configure the
                     27: desired number of virtual consoles as described in
                     28: [[Virtual consoles|guide/cons#wscons-wsdisplay-vt]] and start wscons by entering
                     29: `sh /etc/rc.d/wscons start` followed by `sh /etc/rc.d/ttys restart`. You can
                     30: now switch virtual consoles by pressing Ctrl+Alt+F*n* or similar, depending on
                     31: the platform.
                     33: wscons comprises three subsystems: wsdisplay, wskbd and wsmouse. These
                     34: subsystems handle abstraction for all display, keyboard and mouse devices
                     35: respectively. The following sections discuss the configuration of wscons per
                     36: subsystem.
                     38: ### wsdisplay
                     40: This section will explain how to configure display and screen-related options.
                     42: #### Virtual consoles
                     44: The number of pre-allocated virtual console is controlled by the following
                     45: option:
                     47:     options     WSDISPLAY_DEFAULTSCREENS=4
                     49: Other consoles can be added by enabling the relevant lines in the
                     50: `/etc/wscons.conf` file: the comment mark (`#`) must be removed from the lines
                     51: beginning with `screen x`. In the following example a fifth console is added to
                     52: the four pre-allocated ones:
                     54:     # screens to create
                     55:     #       idx     screen  emul
                     56:     #screen 0       -       vt100
                     57:     screen 1        -       vt100
                     58:     screen 2        -       vt100
                     59:     screen 3        -       vt100
                     60:     screen  4       -       -
                     61:     #screen 4       80x25bf vt100
                     62:     #screen 5       80x50   vt100
                     64: The `rc.wscons` script transforms each of the non commented lines in a call to
                     65: the
                     66: [wsconscfg(8)](
                     67: command: the columns become the parameters of the call. The `idx` column becomes
                     68: the `index` parameter, the `screen` column becomes the `-t type` parameter
                     69: (which defines the type of screen: rows and columns, number of colors, ...) and
                     70: the `emul` column becomes the `-e emul` parameter, which defines the emulation.
                     71: For example:
                     73:     screen 3       -       vt100
                     75: becomes a call to:
                     77:     wsconscfg -e vt100 3
                     79: Please note that it is possible to have a (harmless) conflict between the
                     80: consoles pre-allocated by the kernel and the consoles allocated at boot time
                     81: through `/etc/wscons.conf`. If during boot the system tries to allocate an
                     82: already allocated screen, the following message will be displayed:
                     84:     wsconscfg: WSDISPLAYIO_ADDSCREEN: Device busy
                     86: The solution is to comment out the offending lines in `/etc/wscons.conf`.
                     88: Note that while it is possible to delete a screen and add it with different
                     89: settings, it is, technically speaking, not possible to actually modify the
                     90: settings of a screen.
                     92: `screen 0` cannot be deleted if used as system console. This implies that the
                     93: setting of screen 0 cannot be changed in a running system, if used as system
                     94: console.
                     96: The virtual console must also be active in `/etc/ttys`, so that NetBSD runs the
                     97: [getty(8)](
                     98: program to ask for login. For example:
                    100:     console "/usr/libexec/getty Pc"         pc3     off secure
                    101:     ttyE0   "/usr/libexec/getty Pc"         vt220   on secure
                    102:     ttyE1   "/usr/libexec/getty Pc"         vt220   on secure
                    103:     ttyE2   "/usr/libexec/getty Pc"         vt220   on secure
                    104:     ttyE3   "/usr/libexec/getty Pc"         vt220   off secure
                    105:     ...
                    107: When starting up the X server, it will look for a virtual console with no
                    108: [getty(8)](
                    109: program running, e.g. one console should left as `off` in `/etc/ttys`. The line
                    111:     ttyE3   "/usr/libexec/getty Pc"         vt220   off secure
                    113: of `/etc/ttys` is used by the X server for this purpose. To use a screen
                    114: different from number 4, a parameter of the form `vt#` must be passed to the X
                    115: server, where `#` is the number of the function key used to activate the
                    116: screen for X.
                    118: For example, `screen 7` could be enabled in `/etc/wscons.conf` and X could be
                    119: started with `vt8`. If you use xdm you must edit `/etc/X11/xdm/Xservers`. For
                    120: example:
                    122:     :0 local /usr/X11R6/bin/X +kb dpms -bpp 16 dpms vt8
                    124: For xdm3d the path is different: `/usr/X11R6/share/xdm3d/Xservers`.
                    126: ##### Getting rid of the message `WSDISPLAYIO_ADDSCREEN: Device busy`
                    128: This error message usually occurs when wsconscfg tries to add a screen which
                    129: already exists. One time this occurs is if you have a `screen 0` line in your
                    130: `/etc/wscons.conf` file, because the kernel always allocates a screen 0 as the
                    131: console device. The error message is harmless in this case, and you can get rid
                    132: of it by deleting (or commenting out) the `screen 0` line.
                    134: #### 50 lines text mode with wscons
                    136: A text mode with 50 lines can be used starting with version 1.4.1 of NetBSD.
                    137: This mode is activated in the `/etc/wscons.conf`. The following line must be
                    138: uncommented:
                    140:     font ibm  -  8  ibm  /usr/share/pcvt/fonts/vt220l.808
                    142: Then the following lines must be modified:
                    144:     #screen 0       80x50   vt100
                    145:     screen  1       80x50   vt100
                    146:     screen  2       80x50   vt100
                    147:     screen  3       80x50   vt100
                    148:     screen  4       80x50   vt100
                    149:     screen  5       80x50   vt100
                    150:     screen  6       80x50   vt100
                    151:     screen  7       80x50   vt100
                    153: This configuration enables eight screens, which can be accessed with the key
                    154: combination `Ctrl-Alt-F#` (where `#` varies from 1 to 8); the corresponding
                    155: devices are `ttyE0` to `ttyE7`. To enable them and get a login prompt,
                    156: `/etc/ttys` must be modified:
                    158:     ttyE0   "/usr/libexec/getty Pc"         vt220   on secure
                    159:     ttyE1   "/usr/libexec/getty Pc"         vt220   on secure
                    160:     ttyE2   "/usr/libexec/getty Pc"         vt220   on secure
                    161:     ttyE3   "/usr/libexec/getty Pc"         vt220   on secure
                    162:     ttyE4   "/usr/libexec/getty Pc"         vt220   on secure
                    163:     ttyE5   "/usr/libexec/getty Pc"         vt220   on secure
                    164:     ttyE6   "/usr/libexec/getty Pc"         vt220   on secure
                    165:     ttyE7   "/usr/libexec/getty Pc"         vt220   on secure
                    167: `screen 0` as system console can be set to another screen type at boot time on
                    168: VGA displays. This is a kernel configuration option. If a non-80x25 setting is
                    169: selected, it must be made sure that a usable font is compiled into the kernel,
                    170: which would be an 8x8 one for 80x50.
                    172: There is a problem with many ATI graphics cards which don't implement the
                    173: standard VGA font switching logics: These need another kernel option to make a
                    174: nonstandard console font work.
                    176: An example set of kernel configuration options might be:
                    178:     options VGA_CONSOLE_SCREENTYPE="\"80x50\""
                    179:     options VGA_CONSOLE_ATI_BROKEN_FONTSEL
                    180:     options FONT_VT220L8x8
                    182: #### Enabling framebuffer console
                    184: On many architectures, there is only one type of screen mode: a graphical
                    185: framebuffer mode. On machines with VGA graphics cards, there is a second mode:
                    186: textmode. This is an optimized mode specially made for displaying text. Hence,
                    187: this is the default console mode for GENERIC kernels on architectures where the
                    188: graphics card is typically a VGA card (i386, amd64).
                    190: However, you can enable a framebuffer on machines with VGA cards that support
                    191: the VESA BIOS extension (VBE).
                    193: Starting in NetBSD 6.0 ,
                    194: [vesafb(4)]( has
                    195: been replaced with
                    196: [genfb(4)]( VESA
                    197: framebuffer mode is configured during
                    198: [boot(8)]( using
                    199: the `vesa` command.
                    201: To enable support for this mode in NetBSD 4.x and 5.x, uncomment the following
                    202: lines in the kernel configuration file:
                    204:     # VESA framebuffer console
                    205:     options     KVM86           # required for vesabios
                    206:     vesabios*   at vesabiosbus?
                    207:     vesafb*     at vesabios?
                    208:     options     VESAFB_WIDTH=640
                    209:     options     VESAFB_HEIGHT=480
                    210:     options     VESAFB_DEPTH=8
                    211:     options     VESAFB_PM       # power management support
                    212:     wsdisplay*  at vesafb? console ?
                    214: Beginning in NetBSD 4.0, if you have a VIA Unichrome-family graphics device, you
                    215: can enable the following instead:
                    217:     # VIA Unichrome framebuffer console
                    218:     unichromefb*    at pci? dev ? function ?
                    219:     wsdisplay*  at unichromefb?
                    221: #### Enabling scrollback on the console
                    223: You can enable scrolling back on wscons consoles by compiling the
                    224: `WSDISPLAY_SCROLLSUPPORT` option into your kernel. Make sure you don't have
                    225: option `VGA_RASTERCONSOLE` enabled at the same time though! See
                    226: [[Compiling the kernel|guide/kernel]] for instructions on building a kernel.
                    228: When you have a kernel with options `WSDISPLAY_SCROLLSUPPORT` running, you can
                    229: scroll up on the console by pressing `LEFT SHIFT` plus `PAGE UP/DOWN`. Please
                    230: note that this may not work on your system console (`ttyE0`)!
                    232: #### wscons and colors
                    234: ##### Changing the color of kernel messages
                    236: It is possible to change the foreground and background color of kernel messages
                    237: by setting the following options in kernel config files:
                    239:     options WS_KERNEL_FG=WSCOL_xxx
                    240:     options WS_KERNEL_BG=WSCOL_xxx
                    242: The `WSCOL_xxx` color constants are defined in
                    243: [`src/sys/dev/wscons/wsdisplayvar.h`](
                    245: Starting from NetBSD 3.0, you can easily customize many aspects of your display
                    246: appearance: the colors used to print normal messages, the colors used to print
                    247: kernel messages and the color used to draw a border around the screen.
                    249: All of these details can be changed either from kernel options or through the
                    250: [wsconsctl(8)](
                    251: utility; the later may be preferable if you don't want to compile your own
                    252: kernel, as the default options in `GENERIC` are suitable to get this tip
                    253: working.
                    255: The following options can be set through
                    256: [wsconsctl(8)](
                    258:  * `border`: The color of the screen border. Its respective kernel option is
                    259:    `WSDISPLAY_BORDER_COLOR`.
                    260: instructions on building a kernel.
                    261:  * `msg.default.attrs`: The attributes used to print normal console messages.
                    262:    Its respective kernel options are `WS_DEFAULT_COLATTR` and
                    263:    `WS_DEFAULT_MONOATTR` (the former is used in color displays, while the later
                    264:    is used in monochrome displays).
                    266:  * ``: The background color used to print normal console messages.
                    267:    Its respective kernel option is `WS_DEFAULT_BG`.
                    269:  * `msg.default.fg`: The foreground color used to print normal console messages.
                    270:    Its respective kernel option is `WS_DEFAULT_FG`.
                    272:  * `msg.kernel.attrs`: The attributes used to print kernel messages and
                    273:    warnings. Its respective kernel options are `WS_KERNEL_COLATTR` and
                    274:    `WS_KERNEL_MONOATTR` (the former is used in color displays, while the later
                    275:    is used in monochrome displays).
                    277:  * ``: The background color used to print kernel messages and
                    278:    warnings. Its respective kernel option is `WS_KERNEL_BG`.
                    280:  * `msg.kernel.fg`: The foreground color used to print kernel messages and
                    281:    warnings. Its respective kernel option is `WS_KERNEL_FG`.
                    283: The values accepted as colors are: black, red, green, brown, blue, magenta, cyan
                    284: and white. The attributes are a comma separated list of one or more flags, which
                    285: can be: reverse, hilit, blink and/or underline.
                    287: For example, to emulate the look of one of those old Amstrad machines:
                    289:     wsconsctl -d -w border=blue msg.default.fg=white msg.default.attrs=hilit
                    291: Or, to make your kernel messages appear red:
                    293:     wsconsctl -d -w msg.kernel.fg=red
                    295: Note that, in older versions of NetBSD, only a subset of this functionality is
                    296: available; more specifically, you can only change the kernel colors by changing
                    297: kernel options, as explained above. Also note that not all drivers support these
                    298: features, so you may not get correct results on all architectures.
                    300: ##### Getting applications to use colors on the console
                    302: NetBSD uses the termcap database to tell applications what the current
                    303: terminal's capabilities are. For example, some terminals don't support colors,
                    304: some don't support underlining (PC VGA terminals don't, for example) etc. The
                    305: `TERM` environment variable tells the termcap library the type of terminal. It
                    306: then refers to its database for the options.
                    308: The default setting for `TERM` can be inspected by typing `echo $TERM` on the
                    309: terminal of interest. Usually this is something like `vt220`. This terminal type
                    310: doesn't support colors. On a typical PC console with 25 lines, you can change
                    311: this value to `wsvt25` instead, to get colors. This is done in the C shell (csh)
                    312: by entering:
                    314:     setenv TERM wsvt25
                    316: In a Bourne-compatible shell (sh, ksh), you can enter:
                    318:     export TERM=wsvt25
                    320: If this does not work for you, you can try the `ansi` terminal type, which
                    321: supports ANSI color codes. However, other functionality may be missing with this
                    322: terminal type. You can have a look at the file `/usr/share/misc/termcap` to see
                    323: if you can find a useful match for your console type.
                    325: #### Loading alternate fonts
                    327: There are several fonts in `/usr/share/wscons/fonts` that can be loaded as
                    328: console fonts. This can be done with the
                    329: [wsfontload(8)](
                    330: command, for example:
                    331: `wsfontload -N ibm -h 8 -e ibm /usr/share/wscons/fonts/vt220l.808`.
                    332: This command loads the IBM-encoded (`-e ibm`) font in the file `vt2201.808`
                    333: which has a height of eight pixels (`-h 8`).  Name it ibm for later reference
                    334: (`-N ibm`).
                    336: To actually display the font on the console, use the command
                    337: `wsconsctl -dw font=ibm`.
                    339: If you want to edit a font, you can use the old pcvt utils that are available in
                    340: the
                    341: [`sysutils/pcvt-utils`](
                    342: package.
                    344: ### wskbd
                    346: #### Keyboard mappings
                    348: wscons also allows setting the keymap to map the keys on various national
                    349: keyboards to the right characters. E.g. to set the keymap for an Italian keymap,
                    350: run:
                    352:     # wsconsctl -k -w encoding=it
                    353:     encoding -> it
                    355: This setting will last until the next reboot. To make it permanent, add a
                    356: `encoding` line to `/etc/wscons.conf`: it will be executed automatically the
                    357: next time you reboot.
                    359:     # cp /etc/wscons.conf /etc/wscons.conf.orig
                    360:     # echo encoding it >>/etc/wscons.conf
                    362: Please be careful and type two `>` characters. If you type only one `>`, you
                    363: will overwrite the file instead of adding a line. But that's why we always make
                    364: backup files before touching critical files!
                    366: A full list of keyboard mappings can be found in
                    367: `/usr/src/sys/dev/wscons/wsksymdef.h`:
                    369:  * `be` - Belgian
                    370:  * `de` - German
                    371:  * `dk` - Danish
                    372:  * `es` - Spanish
                    373:  * `fi` - Finnish
                    374:  * `fr` - French
                    375:  * `gr` - Greek
                    376:  * `hu` - Hungarian
                    377:  * `it` - Italian
                    378:  * `jp` - Japanese
                    379:  * `no` - Norwegian
                    380:  * `pl` - Polish
                    381:  * `pt` - Portuguese
                    382:  * `ru` - Russian
                    383:  * `sf` - Swiss French
                    384:  * `sg` - Swiss German
                    385:  * `sv` - Swedish
                    386:  * `ua` - Ukrainian
                    387:  * `uk` - UK-English
                    388:  * `us` - US-English
                    390: There are also several "variants" that can be used to modify a map:
                    392:  * `declk`
                    393:  * `dvorak`
                    394:  * `iopener`
                    395:  * `lk401`
                    396:  * `metaesc`
                    397:  * `nodead`
                    398:  * `swapctrlcaps`
                    400: `dvorak` uses the Dvorak keyboard layout. `swapctrlcaps` switches the functions
                    401: of the Caps Lock and Left Control keys. `iopener` is for the nonstandard
                    402: keyboard layout on the Netpliance i-opener and makes F1 into Escape and F2
                    403: through F12 into F1 through F11. These can be combined with another map by
                    404: appending a dot and then the variant name, for example, `us.iopener`. Multiple
                    405: variants can be combined, such as `us.dvorak.swapctrlcaps`. Note that not all
                    406: combinations are allowed.
                    408: You can change the compiled in kernel default by adding `options
                    409: PCKBD_LAYOUT=KB_encoding` where `encoding` is an uppercase entry from the list
                    410: above (eg: `PCKBD_LAYOUT=KB_FR`). Variants can be bitwise or'd in (eg:
                    411: `PCKBD_LAYOUT=KB_US|KB_SWAPCTRLCAPS`).
                    413: Configuring the keyboard layout under X is described
                    414: [elsewhere](
                    416: ##### Hacking wscons to add a keymap
                    418: If your favourite keymap is not supported, you can start digging in
                    419: [`src/sys/dev/wscons/wsksymdef.h`](
                    420: and
                    421: [`src/sys/dev/pckbport/wskbdmap_mfii.c`](
                    422: to make your own. Be sure to
                    423: [send-pr]( a
                    424: change-request PR with your work, so others can make use of it!
                    426: You can test your keymap by using `wsconsctl` instead of directly hacking the
                    427: keymaps into the keyboard mapping file. For example, to say keycode 51 without
                    428: any modifiers should map to a comma, with shift it should map to a question
                    429: mark, with alt it should map to a semicolon and with both alt and shift it
                    430: should map to colon, issue the following command:
                    432:     wsconsctl -w "map += keycode 51=comma question semicolon colon"
                    434: #### Changing the keyboard repeat speed
                    436: Keyboard repeat speed can be tuned using the
                    437: [wsconsctl(8)](
                    438: utility. There are two variables of interest: `repeat.del1`, which specifies the
                    439: delay before character repetition starts, and `repeat.deln`, which sets the
                    440: delay between each character repetition (once started).
                    442: Let's see an example, assuming you want to accelerate keyboard speed. You could
                    443: do, from the command line:
                    445:     wsconsctl -w repeat.del1=300
                    446:     wsconsctl -w repeat.deln=40
                    448: Or, if you want this to happen automatically every time you boot up the system,
                    449: you could add the following lines to `/etc/wscons.conf`:
                    451:     setvar repeat.del1=300
                    452:     setvar repeat.deln=40
                    454: ### wsmouse
                    456: #### Serial mouse support
                    458: The wsmouse device (part of wscons) does not directly support serial mice. The
                    459: [moused(8)](
                    460: daemon is provided to read serial mouse data, convert it into wsmouse events and
                    461: inject them in wscons' event queue, so the mouse can be used through the
                    462: abstraction layer provided by wsmouse.
                    464: A typical use can be: `moused -p /dev/tty00`. This will try to determine the
                    465: type of mouse connected to the first serial port and start reading its data. The
                    466: [moused(8)]( man
                    467: page contains more examples.
                    469: #### Cut&paste on the console with wsmoused
                    471: It is possible to use the mouse on the wscons console to mark (cut) text with
                    472: one mouse button, and insert (paste) it again with another button.
                    474: To do this, enable `wsmoused` in `/etc/rc.conf`, and start it:
                    476:     # echo wsmoused=yes >>/etc/rc.conf
                    477:     # sh /etc/rc.d/wsmoused start
                    479: After that you can use the mouse to mark text with the left mouse button, and
                    480: paste it with the right one. To tune the behaviour of
                    481: [wsmoused(8)](
                    482: see its manpage, which also describes the format of the
                    483: [wsmoused.conf(5)](
                    484: config file, an example of which can be found in `/usr/share/examples/wsmoused`.

CVSweb for NetBSD wikisrc <> software: FreeBSD-CVSweb