File:  [NetBSD Developer Wiki] / wikisrc / guide / cons.mdwn
Revision 1.4: download - view: text, annotated - select for diffs
Sat Oct 3 09:03:40 2020 UTC (3 months, 3 weeks ago) by nia
Branches: MAIN
CVS tags: HEAD
remove outdated information

    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: VESA framebuffer mode is configured during
  194: [[!template id=man name="boot" section="8"]] using
  195: the `vesa` command.
  196: 
  197: #### Enabling scrollback on the console
  198: 
  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.
  203: 
  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`)!
  207: 
  208: #### wscons and colors
  209: 
  210: ##### Changing the color of kernel messages
  211: 
  212: It is possible to change the foreground and background color of kernel messages
  213: by setting the following options in kernel config files:
  214: 
  215:     options WS_KERNEL_FG=WSCOL_xxx
  216:     options WS_KERNEL_BG=WSCOL_xxx
  217: 
  218: The `WSCOL_xxx` color constants are defined in
  219: [`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).
  220: 
  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.
  224: 
  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
  229: working.
  230: 
  231: The following options can be set through
  232: [[!template id=man name="wsconsctl" section="8"]]:
  233: 
  234:  * `border`: The color of the screen border. Its respective kernel option is
  235:    `WSDISPLAY_BORDER_COLOR`.
  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).
  241: 
  242:  * `msg.default.bg`: The background color used to print normal console messages.
  243:    Its respective kernel option is `WS_DEFAULT_BG`.
  244: 
  245:  * `msg.default.fg`: The foreground color used to print normal console messages.
  246:    Its respective kernel option is `WS_DEFAULT_FG`.
  247: 
  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).
  252: 
  253:  * `msg.kernel.bg`: The background color used to print kernel messages and
  254:    warnings. Its respective kernel option is `WS_KERNEL_BG`.
  255: 
  256:  * `msg.kernel.fg`: The foreground color used to print kernel messages and
  257:    warnings. Its respective kernel option is `WS_KERNEL_FG`.
  258: 
  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.
  262: 
  263: For example, to emulate the look of one of those old Amstrad machines:
  264: 
  265:     wsconsctl -d -w border=blue msg.default.bg=blue msg.default.fg=white msg.default.attrs=hilit
  266: 
  267: Or, to make your kernel messages appear red:
  268: 
  269:     wsconsctl -d -w msg.kernel.fg=red
  270: 
  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.
  275: 
  276: ##### Getting applications to use colors on the console
  277: 
  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.
  283: 
  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:
  289: 
  290:     setenv TERM wsvt25
  291: 
  292: In a Bourne-compatible shell (sh, ksh), you can enter:
  293: 
  294:     export TERM=wsvt25
  295: 
  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.
  300: 
  301: #### Loading alternate fonts
  302: 
  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`).
  311: 
  312: To actually display the font on the console, use the command
  313: `wsconsctl -dw font=ibm`.
  314: 
  315: If you want to edit a font, you can use the old pcvt utils that are available in
  316: the
  317: [`sysutils/pcvt-utils`](http://ftp.NetBSD.org/pub/pkgsrc/current/pkgsrc/sysutils/pcvt-utils/README.html)
  318: package.
  319: 
  320: ### wskbd
  321: 
  322: #### Keyboard mappings
  323: 
  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,
  326: run:
  327: 
  328:     # wsconsctl -k -w encoding=it
  329:     encoding -> it
  330: 
  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.
  334: 
  335:     # cp /etc/wscons.conf /etc/wscons.conf.orig
  336:     # echo encoding it >>/etc/wscons.conf
  337: 
  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!
  341: 
  342: A full list of keyboard mappings and variants can be found in
  343: [[!template id=man name="wskbd" section="4"]].
  344: 
  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:
  348: `PCKBD_LAYOUT=KB_US|KB_SWAPCTRLCAPS`).
  349: 
  350: Configuring the keyboard layout under X is described
  351: [elsewhere](http://www.NetBSD.org/docs/x/#x-keyboard-maps).
  352: 
  353: ##### Hacking wscons to add a keymap
  354: 
  355: If your favourite keymap is not supported, you can start digging in
  356: [`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)
  357: and
  358: [`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)
  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!
  362: 
  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:
  368: 
  369:     wsconsctl -w "map += keycode 51=comma question semicolon colon"
  370: 
  371: #### Changing the keyboard repeat speed
  372: 
  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).
  378: 
  379: Let's see an example, assuming you want to accelerate keyboard speed. You could
  380: do, from the command line:
  381: 
  382:     wsconsctl -w repeat.del1=300
  383:     wsconsctl -w repeat.deln=40
  384: 
  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`:
  387: 
  388:     setvar repeat.del1=300
  389:     setvar repeat.deln=40
  390: 
  391: ### wsmouse
  392: 
  393: #### Serial mouse support
  394: 
  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.
  400: 
  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.
  405: 
  406: #### Cut&paste on the console with wsmoused
  407: 
  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.
  410: 
  411: To do this, enable `wsmoused` in `/etc/rc.conf`, and start it:
  412: 
  413:     # echo wsmoused=yes >>/etc/rc.conf
  414:     # sh /etc/rc.d/wsmoused start
  415: 
  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`.
  422: 

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