File:  [NetBSD Developer Wiki] / wikisrc / guide / cons.mdwn
Revision 1.3: download - view: text, annotated - select for diffs
Fri Jun 19 19:18:31 2015 UTC (5 years ago) by plunky
Branches: MAIN
CVS tags: HEAD
replace direct links to manpages on netbsd.gw.com with templates

    1: **Contents**
    2: 
    3: [[!toc levels=3]]
    4: 
    5: # Console drivers
    6: 
    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.
   11: 
   12: ## wscons
   13: 
   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.
   19: 
   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.
   24: 
   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.
   32: 
   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.
   37: 
   38: ### wsdisplay
   39: 
   40: This section will explain how to configure display and screen-related options.
   41: 
   42: #### Virtual consoles
   43: 
   44: The number of pre-allocated virtual console is controlled by the following
   45: option:
   46: 
   47:     options     WSDISPLAY_DEFAULTSCREENS=4
   48: 
   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:
   53: 
   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
   63: 
   64: The `rc.wscons` script transforms each of the non commented lines in a call to
   65: the
   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:
   72: 
   73:     screen 3       -       vt100
   74: 
   75: becomes a call to:
   76: 
   77:     wsconscfg -e vt100 3
   78: 
   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:
   83: 
   84:     wsconscfg: WSDISPLAYIO_ADDSCREEN: Device busy
   85: 
   86: The solution is to comment out the offending lines in `/etc/wscons.conf`.
   87: 
   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.
   91: 
   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.
   95: 
   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:
   99: 
  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:     ...
  106: 
  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
  110: 
  111:     ttyE3   "/usr/libexec/getty Pc"         vt220   off secure
  112: 
  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.
  117: 
  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:
  121: 
  122:     :0 local /usr/X11R6/bin/X +kb dpms -bpp 16 dpms vt8
  123: 
  124: For xdm3d the path is different: `/usr/X11R6/share/xdm3d/Xservers`.
  125: 
  126: ##### Getting rid of the message `WSDISPLAYIO_ADDSCREEN: Device busy`
  127: 
  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.
  133: 
  134: #### 50 lines text mode with wscons
  135: 
  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:
  139: 
  140:     font ibm  -  8  ibm  /usr/share/pcvt/fonts/vt220l.808
  141: 
  142: Then the following lines must be modified:
  143: 
  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
  152: 
  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:
  157: 
  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
  166: 
  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.
  171: 
  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.
  175: 
  176: An example set of kernel configuration options might be:
  177: 
  178:     options VGA_CONSOLE_SCREENTYPE="\"80x50\""
  179:     options VGA_CONSOLE_ATI_BROKEN_FONTSEL
  180:     options FONT_VT220L8x8
  181: 
  182: #### Enabling framebuffer console
  183: 
  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).
  189: 
  190: However, you can enable a framebuffer on machines with VGA cards that support
  191: the VESA BIOS extension (VBE).
  192: 
  193: Starting in NetBSD 6.0 ,
  194: [[!template id=man name="vesafb" section="4"]] has
  195: been replaced with
  196: [[!template id=man name="genfb" section="4"]]. VESA
  197: framebuffer mode is configured during
  198: [[!template id=man name="boot" section="8"]] using
  199: the `vesa` command.
  200: 
  201: To enable support for this mode in NetBSD 4.x and 5.x, uncomment the following
  202: lines in the kernel configuration file:
  203: 
  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 ?
  213: 
  214: Beginning in NetBSD 4.0, if you have a VIA Unichrome-family graphics device, you
  215: can enable the following instead:
  216: 
  217:     # VIA Unichrome framebuffer console
  218:     unichromefb*    at pci? dev ? function ?
  219:     wsdisplay*  at unichromefb?
  220: 
  221: #### Enabling scrollback on the console
  222: 
  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.
  227: 
  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`)!
  231: 
  232: #### wscons and colors
  233: 
  234: ##### Changing the color of kernel messages
  235: 
  236: It is possible to change the foreground and background color of kernel messages
  237: by setting the following options in kernel config files:
  238: 
  239:     options WS_KERNEL_FG=WSCOL_xxx
  240:     options WS_KERNEL_BG=WSCOL_xxx
  241: 
  242: The `WSCOL_xxx` color constants are defined in
  243: [`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).
  244: 
  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.
  248: 
  249: All of these details can be changed either from kernel options or through the
  250: [[!template id=man name="wsconsctl" section="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.
  254: 
  255: The following options can be set through
  256: [[!template id=man name="wsconsctl" section="8"]]:
  257: 
  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).
  265: 
  266:  * `msg.default.bg`: The background color used to print normal console messages.
  267:    Its respective kernel option is `WS_DEFAULT_BG`.
  268: 
  269:  * `msg.default.fg`: The foreground color used to print normal console messages.
  270:    Its respective kernel option is `WS_DEFAULT_FG`.
  271: 
  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).
  276: 
  277:  * `msg.kernel.bg`: The background color used to print kernel messages and
  278:    warnings. Its respective kernel option is `WS_KERNEL_BG`.
  279: 
  280:  * `msg.kernel.fg`: The foreground color used to print kernel messages and
  281:    warnings. Its respective kernel option is `WS_KERNEL_FG`.
  282: 
  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.
  286: 
  287: For example, to emulate the look of one of those old Amstrad machines:
  288: 
  289:     wsconsctl -d -w border=blue msg.default.bg=blue msg.default.fg=white msg.default.attrs=hilit
  290: 
  291: Or, to make your kernel messages appear red:
  292: 
  293:     wsconsctl -d -w msg.kernel.fg=red
  294: 
  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.
  299: 
  300: ##### Getting applications to use colors on the console
  301: 
  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.
  307: 
  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:
  313: 
  314:     setenv TERM wsvt25
  315: 
  316: In a Bourne-compatible shell (sh, ksh), you can enter:
  317: 
  318:     export TERM=wsvt25
  319: 
  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.
  324: 
  325: #### Loading alternate fonts
  326: 
  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: [[!template id=man name="wsfontload" section="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`).
  335: 
  336: To actually display the font on the console, use the command
  337: `wsconsctl -dw font=ibm`.
  338: 
  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`](http://ftp.NetBSD.org/pub/pkgsrc/current/pkgsrc/sysutils/pcvt-utils/README.html)
  342: package.
  343: 
  344: ### wskbd
  345: 
  346: #### Keyboard mappings
  347: 
  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:
  351: 
  352:     # wsconsctl -k -w encoding=it
  353:     encoding -> it
  354: 
  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.
  358: 
  359:     # cp /etc/wscons.conf /etc/wscons.conf.orig
  360:     # echo encoding it >>/etc/wscons.conf
  361: 
  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!
  365: 
  366: A full list of keyboard mappings can be found in
  367: `/usr/src/sys/dev/wscons/wsksymdef.h`:
  368: 
  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
  389: 
  390: There are also several "variants" that can be used to modify a map:
  391: 
  392:  * `declk`
  393:  * `dvorak`
  394:  * `iopener`
  395:  * `lk401`
  396:  * `metaesc`
  397:  * `nodead`
  398:  * `swapctrlcaps`
  399: 
  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.
  407: 
  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`).
  412: 
  413: Configuring the keyboard layout under X is described
  414: [elsewhere](http://www.NetBSD.org/docs/x/#x-keyboard-maps).
  415: 
  416: ##### Hacking wscons to add a keymap
  417: 
  418: If your favourite keymap is not supported, you can start digging in
  419: [`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)
  420: and
  421: [`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)
  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!
  425: 
  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:
  431: 
  432:     wsconsctl -w "map += keycode 51=comma question semicolon colon"
  433: 
  434: #### Changing the keyboard repeat speed
  435: 
  436: Keyboard repeat speed can be tuned using the
  437: [[!template id=man name="wsconsctl" section="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).
  441: 
  442: Let's see an example, assuming you want to accelerate keyboard speed. You could
  443: do, from the command line:
  444: 
  445:     wsconsctl -w repeat.del1=300
  446:     wsconsctl -w repeat.deln=40
  447: 
  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`:
  450: 
  451:     setvar repeat.del1=300
  452:     setvar repeat.deln=40
  453: 
  454: ### wsmouse
  455: 
  456: #### Serial mouse support
  457: 
  458: The wsmouse device (part of wscons) does not directly support serial mice. The
  459: [[!template id=man name="moused" section="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.
  463: 
  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: [[!template id=man name="moused" section="8"]] man
  467: page contains more examples.
  468: 
  469: #### Cut&paste on the console with wsmoused
  470: 
  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.
  473: 
  474: To do this, enable `wsmoused` in `/etc/rc.conf`, and start it:
  475: 
  476:     # echo wsmoused=yes >>/etc/rc.conf
  477:     # sh /etc/rc.d/wsmoused start
  478: 
  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: [[!template id=man name="wsmoused" section="8"]]
  482: see its manpage, which also describes the format of the
  483: [[!template id=man name="wsmoused.conf" section="5"]]
  484: config file, an example of which can be found in `/usr/share/examples/wsmoused`.
  485: 

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