Annotation of wikisrc/guide/cons.mdwn, revision 1.2
1.2 ! jdf 1: **Contents**
! 3: [[!toc levels=3]]
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
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
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
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
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
96: The virtual console must also be active in `/etc/ttys`, so that NetBSD runs the
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
107: When starting up the X server, it will look for a virtual console with no
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
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
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)](http://netbsd.gw.com/cgi-bin/man-cgi?vesafb+4+NetBSD-5.0.1+i386) has
195: been replaced with
196: [genfb(4)](http://netbsd.gw.com/cgi-bin/man-cgi?genfb+4+NetBSD-5.0.1+i386). VESA
197: framebuffer mode is configured during
198: [boot(8)](http://netbsd.gw.com/cgi-bin/man-cgi?boot+8+NetBSD-5.0.1+i386) 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
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
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
255: The following options can be set through
258: * `border`: The color of the screen border. Its respective kernel option is
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: * `msg.default.bg`: 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: * `msg.kernel.bg`: 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.bg=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
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
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,
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
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:
413: Configuring the keyboard layout under X is described
416: ##### Hacking wscons to add a keymap
418: If your favourite keymap is not supported, you can start digging in
422: to make your own. Be sure to
423: [send-pr](http://www.NetBSD.org/support/send-pr.html#submitting) 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
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
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)](http://netbsd.gw.com/cgi-bin/man-cgi?moused+8+NetBSD-5.0.1+i386) 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
482: see its manpage, which also describes the format of the
484: config file, an example of which can be found in `/usr/share/examples/wsmoused`.
CVSweb for NetBSD wikisrc <wikimaster@NetBSD.org> software: FreeBSD-CVSweb