3: [[!toc levels=3]]
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
66: [[!template id=man name="wsconscfg" section="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
96: The virtual console must also be active in `/etc/ttys`, so that NetBSD runs the
97: [[!template id=man name="getty" section="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
107: When starting up the X server, it will look for a virtual console with no
108: [[!template id=man name="getty" section="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
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: VESA framebuffer mode is configured during
194: [[!template id=man name="boot" section="8"]] using
195: the `vesa` command.
197: #### Enabling scrollback on the console
199: You can enable scrolling back on wscons consoles by compiling the
200: `WSDISPLAY_SCROLLSUPPORT` option into your kernel. Make sure you don't have
201: option `VGA_RASTERCONSOLE` enabled at the same time though! See
202: [[Compiling the kernel|guide/kernel]] for instructions on building a kernel.
204: When you have a kernel with options `WSDISPLAY_SCROLLSUPPORT` running, you can
205: scroll up on the console by pressing `LEFT SHIFT` plus `PAGE UP/DOWN`. Please
206: note that this may not work on your system console (`ttyE0`)!
208: #### wscons and colors
210: ##### Changing the color of kernel messages
212: It is possible to change the foreground and background color of kernel messages
213: by setting the following options in kernel config files:
215: options WS_KERNEL_FG=WSCOL_xxx
216: options WS_KERNEL_BG=WSCOL_xxx
218: The `WSCOL_xxx` color constants are defined in
221: Starting from NetBSD 3.0, you can easily customize many aspects of your display
222: appearance: the colors used to print normal messages, the colors used to print
223: kernel messages and the color used to draw a border around the screen.
225: All of these details can be changed either from kernel options or through the
226: [[!template id=man name="wsconsctl" section="8"]]
227: utility; the later may be preferable if you don't want to compile your own
228: kernel, as the default options in `GENERIC` are suitable to get this tip
231: The following options can be set through
232: [[!template id=man name="wsconsctl" section="8"]]:
234: * `border`: The color of the screen border. Its respective kernel option is
236: instructions on building a kernel.
237: * `msg.default.attrs`: The attributes used to print normal console messages.
238: Its respective kernel options are `WS_DEFAULT_COLATTR` and
239: `WS_DEFAULT_MONOATTR` (the former is used in color displays, while the later
240: is used in monochrome displays).
242: * `msg.default.bg`: The background color used to print normal console messages.
243: Its respective kernel option is `WS_DEFAULT_BG`.
245: * `msg.default.fg`: The foreground color used to print normal console messages.
246: Its respective kernel option is `WS_DEFAULT_FG`.
248: * `msg.kernel.attrs`: The attributes used to print kernel messages and
249: warnings. Its respective kernel options are `WS_KERNEL_COLATTR` and
250: `WS_KERNEL_MONOATTR` (the former is used in color displays, while the later
251: is used in monochrome displays).
253: * `msg.kernel.bg`: The background color used to print kernel messages and
254: warnings. Its respective kernel option is `WS_KERNEL_BG`.
256: * `msg.kernel.fg`: The foreground color used to print kernel messages and
257: warnings. Its respective kernel option is `WS_KERNEL_FG`.
259: The values accepted as colors are: black, red, green, brown, blue, magenta, cyan
260: and white. The attributes are a comma separated list of one or more flags, which
261: can be: reverse, hilit, blink and/or underline.
263: For example, to emulate the look of one of those old Amstrad machines:
265: wsconsctl -d -w border=blue msg.default.bg=blue msg.default.fg=white msg.default.attrs=hilit
267: Or, to make your kernel messages appear red:
269: wsconsctl -d -w msg.kernel.fg=red
271: Note that, in older versions of NetBSD, only a subset of this functionality is
272: available; more specifically, you can only change the kernel colors by changing
273: kernel options, as explained above. Also note that not all drivers support these
274: features, so you may not get correct results on all architectures.
276: ##### Getting applications to use colors on the console
278: NetBSD uses the termcap database to tell applications what the current
279: terminal's capabilities are. For example, some terminals don't support colors,
280: some don't support underlining (PC VGA terminals don't, for example) etc. The
281: `TERM` environment variable tells the termcap library the type of terminal. It
282: then refers to its database for the options.
284: The default setting for `TERM` can be inspected by typing `echo $TERM` on the
285: terminal of interest. Usually this is something like `vt220`. This terminal type
286: doesn't support colors. On a typical PC console with 25 lines, you can change
287: this value to `wsvt25` instead, to get colors. This is done in the C shell (csh)
288: by entering:
290: setenv TERM wsvt25
292: In a Bourne-compatible shell (sh, ksh), you can enter:
294: export TERM=wsvt25
296: If this does not work for you, you can try the `ansi` terminal type, which
297: supports ANSI color codes. However, other functionality may be missing with this
298: terminal type. You can have a look at the file `/usr/share/misc/termcap` to see
299: if you can find a useful match for your console type.
301: #### Loading alternate fonts
303: There are several fonts in `/usr/share/wscons/fonts` that can be loaded as
304: console fonts. This can be done with the
305: [[!template id=man name="wsfontload" section="8"]]
306: command, for example:
307: `wsfontload -N ibm -h 8 -e ibm /usr/share/wscons/fonts/vt220l.808`.
308: This command loads the IBM-encoded (`-e ibm`) font in the file `vt2201.808`
309: which has a height of eight pixels (`-h 8`). Name it ibm for later reference
310: (`-N ibm`).
312: To actually display the font on the console, use the command
313: `wsconsctl -dw font=ibm`.
315: If you want to edit a font, you can use the old pcvt utils that are available in
320: ### wskbd
322: #### Keyboard mappings
324: wscons also allows setting the keymap to map the keys on various national
325: keyboards to the right characters. E.g. to set the keymap for an Italian keymap,
328: # wsconsctl -k -w encoding=it
329: encoding -> it
331: This setting will last until the next reboot. To make it permanent, add a
332: `encoding` line to `/etc/wscons.conf`: it will be executed automatically the
333: next time you reboot.
335: # cp /etc/wscons.conf /etc/wscons.conf.orig
336: # echo encoding it >>/etc/wscons.conf
338: Please be careful and type two `>` characters. If you type only one `>`, you
339: will overwrite the file instead of adding a line. But that's why we always make
340: backup files before touching critical files!
342: A full list of keyboard mappings and variants can be found in
343: [[!template id=man name="wskbd" section="4"]].
345: You can change the compiled in kernel default by adding `options
346: PCKBD_LAYOUT=KB_encoding` where `encoding` is an uppercase entry from the list
347: above (eg: `PCKBD_LAYOUT=KB_FR`). Variants can be bitwise or'd in (eg:
350: Configuring the keyboard layout under X is described
353: ##### Hacking wscons to add a keymap
355: If your favourite keymap is not supported, you can start digging in
359: to make your own. Be sure to
360: [send-pr](http://www.NetBSD.org/support/send-pr.html#submitting) a
361: change-request PR with your work, so others can make use of it!
363: You can test your keymap by using `wsconsctl` instead of directly hacking the
364: keymaps into the keyboard mapping file. For example, to say keycode 51 without
365: any modifiers should map to a comma, with shift it should map to a question
366: mark, with alt it should map to a semicolon and with both alt and shift it
367: should map to colon, issue the following command:
369: wsconsctl -w "map += keycode 51=comma question semicolon colon"
371: #### Changing the keyboard repeat speed
373: Keyboard repeat speed can be tuned using the
374: [[!template id=man name="wsconsctl" section="8"]]
375: utility. There are two variables of interest: `repeat.del1`, which specifies the
376: delay before character repetition starts, and `repeat.deln`, which sets the
377: delay between each character repetition (once started).
379: Let's see an example, assuming you want to accelerate keyboard speed. You could
380: do, from the command line:
382: wsconsctl -w repeat.del1=300
383: wsconsctl -w repeat.deln=40
385: Or, if you want this to happen automatically every time you boot up the system,
386: you could add the following lines to `/etc/wscons.conf`:
388: setvar repeat.del1=300
389: setvar repeat.deln=40
391: ### wsmouse
393: #### Serial mouse support
395: The wsmouse device (part of wscons) does not directly support serial mice. The
396: [[!template id=man name="moused" section="8"]]
397: daemon is provided to read serial mouse data, convert it into wsmouse events and
398: inject them in wscons' event queue, so the mouse can be used through the
399: abstraction layer provided by wsmouse.
401: A typical use can be: `moused -p /dev/tty00`. This will try to determine the
402: type of mouse connected to the first serial port and start reading its data. The
403: [[!template id=man name="moused" section="8"]] man
404: page contains more examples.
406: #### Cut&paste on the console with wsmoused
408: It is possible to use the mouse on the wscons console to mark (cut) text with
409: one mouse button, and insert (paste) it again with another button.
411: To do this, enable `wsmoused` in `/etc/rc.conf`, and start it:
413: # echo wsmoused=yes >>/etc/rc.conf
414: # sh /etc/rc.d/wsmoused start
416: After that you can use the mouse to mark text with the left mouse button, and
417: paste it with the right one. To tune the behaviour of
418: [[!template id=man name="wsmoused" section="8"]]
419: see its manpage, which also describes the format of the
420: [[!template id=man name="wsmoused.conf" section="5"]]
421: config file, an example of which can be found in `/usr/share/examples/wsmoused`.
CVSweb for NetBSD wikisrc <wikimaster@NetBSD.org> software: FreeBSD-CVSweb