Diff for /wikisrc/guide/cons.mdwn between versions 1.5 and 1.6

version 1.5, 2021/04/07 07:35:41 version 1.6, 2021/04/12 13:15:02
Line 1 Line 1
 **Contents**  This page was moved to:
   [The NetBSD Guide - Console drivers](//www.NetBSD.org/docs/guide/en/chap-cons.html)
 [[!toc levels=3]]  
   
 # 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  
 [[!template id=man name="wsconscfg" section="8"]]  
 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  
 [[!template id=man name="getty" section="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  
 [[!template id=man name="getty" section="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 `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).  
   
 VESA framebuffer mode is configured during  
 [[!template id=man name="boot" section="8"]] using  
 the `vesa` command.  
   
 #### 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  
 [[!template id=man name="wsconsctl" section="8"]]  
 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  
 [[!template id=man name="wsconsctl" section="8"]]:  
   
  * `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  
 [[!template id=man name="wsfontload" section="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`](http://ftp.NetBSD.org/pub/pkgsrc/current/pkgsrc/sysutils/pcvt-utils/)  
 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 and variants can be found in  
 [[!template id=man name="wskbd" section="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 (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  
 [[!template id=man name="wsconsctl" section="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  
   
 ### wsmouse  
   
 #### Serial mouse support  
   
 The wsmouse device (part of wscons) does not directly support serial mice. The  
 [[!template id=man name="moused" section="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  
 [[!template id=man name="moused" section="8"]] 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  
 [[!template id=man name="wsmoused" section="8"]]  
 see its manpage, which also describes the format of the  
 [[!template id=man name="wsmoused.conf" section="5"]]  
 config file, an example of which can be found in `/usr/share/examples/wsmoused`.  
   

Removed from v.1.5  
changed lines
  Added in v.1.6


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