COHERENT manpages
This page displays the COHERENT manpage for vtnkb [Configurable keyboard driver, virtual consoles].
List of available manpages
Index
vtnkb -- Device Driver Configurable keyboard driver, virtual consoles The device driver vtnkb drives the keyboard on your system's console -- that is, the keyboard that is plugged directly into your computer. Unlike the related driver vtkb, vtnkb uses a loadable translation table to interpret keystrokes. This permits you to use any number of national keyboard mappings on your COHERENT system without changing the kernel in any way. You can select among any number of configuration programs stored in directory /conf/kbd, or you can create your own keymapping table to suit your preferences. To change the layout and function-key bindings, run one of the keyboard- mapping programs kept in directory /conf/kbd. This directory contains the C source code for the mapping tables, as well as a Makefile that helps you rebuild the mapping programs. This rest of this article describes the structure of the driver vtnkb, and describes how you can write or modify a keyboard-mapping program. Internal Structure of the Driver vtnkb understands the following ``shift'' and ``lock'' keys: scroll Scroll lock num Keypad <num> lock caps <shift> or <caps> lock lalt Left <alt> key ralt Right <alt> key lshift Left <shift> key rshift Right <shift> key lctrl Left <ctrl> key rctrl Right <ctrl> key altgr <alt graphic> key (non-U.S. keyboards) vtnkb records the internal shift state, as defined by the current positions of the shift and lock keys. The shift state is a logical combination of internal states SHIFT, CTRL, ALT, and ALT_GR. The <lshift> and <rshift> keys combine to form the current SHIFT state for non- alphabetic keys. Alphabetic keys generally use the current state of the <caps-lock> key plus the left and right <shift> keys. Numeric keys on the keypad generally use the state of the <num lock> key plus the left and right <shift> keys. The left and right <ctrl> keys form the internal CTRL state. Likewise, the left and right <alt> keys form the internal ALT state. Note that 102-key keyboards generally replace the right <alt> key with the <altgr> (alt graphics) key, to allow access to the alternate graphics characters found on some keyboards. vtnkb lets you configure or read the internal mapping tables via the following requests to ioctl(), as defined in header file <sgtty.h>: TIOCGETF Get function key bindings TIOCSETF Set function key bindings TIOCGETKBTGet keyboard table bindings TIOCSETKBTSet keyboard table bindings Requests TIOCGETF and TIOCSETF reference a data structure of type FNKEY, which is defined in header file <sys/kb.h>. Structure member k_fnval is a character array that contains a series of contiguous function key/value bindings; the end of the bindings is marked by manifest constant DELIM. You can use any value other than DELIM as part of a function-key binding. Structure member k_nfkeys indicates how many function keys have associated entries in k_fnval. Function keys are numbered from zero through k_nfkeys-1. How To Write a Keyboard Table The main difference between the keyboard drivers vtnkb and vtkb is that vtnkb uses a ``supplemental'' process to interpret keystrokes. You can re- construct the interface to the vtnkb driver by modifying a keyboard-mapping file and then using a support module to link that file to the driver. As noted above, directory /conf/kbd contains the source code for a series of such supplemental programs. These programs differ from each other only in the keyboard binding or mapping tables each uses; by selecting one such program and linking it into vtnkb, you can switch easily from the standard keyboard layout used in the U.S. to any of a number of layouts used in other countries. /conf/kbd also contains compiled executables, and a Makefile that you use to construct the executables from the corresponding source files. The keyboard-mapping file is a C program that consists of initialized tables and strings. In addition, several header files provide the scan codes and other constants required for the key tables. This format makes the file easy to edit, and also lets you enter characters in several different formats. The support module, in turn, performs several tasks. These include scanning the keyboard-mapping file for errors, reformatting the table for use by the device driver, and passing the reformatted table to the driver. A keyboard-mapping source file consists primarily of three data structures that you must modify to support a given keyboard mapping. The first, and simplest, of the structures is tbl_name. This is a character string that describes the keyboard. For example, the stock 101-key U.S. AT keyboard mapping file /conf/kbd/us.c initializes this string to: "U.S. AT keyboard table" The second data structure, kbtbl, is an array of key-mapping entries. It has one entry (or row) for each possible key location. Each entry in this structure consists of 11 fields, which hold, respectively, the key number, nine possible mapping values, and a mode field. The following example is for physical key location 3 from key-mapping source file /conf/kbd/belgian.c: { K_3, 0x82, '2', none, none, 0x82, '2', '~', none, '~', O|T }, Field 1 contains the scan code set 3 code value for the desired key. Header file <sys/kbscan.h> contains manifest constants of the form K_nnn that map the AT keyboard's physical key number nnn to the corresponding scan code set 3 value generated by the keyboard. In the above example, K_3 corresponds to key location three. Fields 2 through 10 contain the key mappings corresponding to the following shift states, as follows: 2 base or unshifted 3 SHIFT 4 CONTROL 5 CONTROL+SHIFT 6 ALT 7 ALT+SHIFT 8 ALT+CONTROL 9 ALT+CONTROL+SHIFT 10 ALT_GRAPHIC For ``regular'' keys, the values for these nine fields are eight-bit characters; for ``function'' or ``shift'' keys, they are special values. The symbolic constant none indicates that you want no output when the key is pressed in the specified shift state. In the case of a function key, the value specified is the number of the desired function key. Header file <sys/kb.h> defines a set of symbolic constants of the form fn, where n is the number of the desired function key. You should use these constants; they will improve the readability of your code, and they will protect your keyboard mapping source files from any future changes in the structure of the keyboard driver. In the case of a ``shift'' key, all nine entries must be identical and must consist of one of the following symbolic constants: scroll, num, caps, lalt, ralt, lshift, rshift, lctrl, rctrl, or altgr. These are defined in the header file <sys/kb.h>. Note that 83-key XT-layout keyboards only have one ``control'' and ``alt'' key, so not every shift-key combination may be possible on your target keyboard. The last (11th) field in the key entry is the ``mode'' field. The following symbolic constants specify the mode of the current key: S The specified key is a ``shift'' or ``lock'' key. Note that all entries in array k_val must be identical for a ``shift'' or ``lock'' key to work correctly. F The specified key is a ``function'' or special key. The value of all elements of array k_val must specify a function key number. O The specified key is ``regular'' and requires no special processing. C The <caps-lock> key affects this key. M Make: generate an interrupt only upon key ``make'' (i.e., when the key is depressed). This mode is useful for keys that do not repeat. Note that using this mode with a ``shift'' key stops you from unshifting upon release of the key! T Typematic: generate an interrupt when the key is depressed, and generate subsequent key-depression interrupts while the key is depressed. The rate at which interrupts are generated is specified by the typematic rate of the keyboard. This type is usually associated with a ``regular'' key. MB Make/Break: generate an interrupt when the key is depressed and when it is released. No additional interrupts are generated no matter how long the key is depressed. This mode is used for ``shift'' keys. TMB Typematic/Make/Break: generate an interrupt when the key is first depressed; generate subsequent key depression interrupts while the key remains depressed; and generate an interrupt when the key is released. The above example specifies a mode field of O|T, which corresponds to a ``regular'' key with typematic repeat, and no special handling of the ``lock'' keys. The last data structure, funkey, consists of an array of function-key initializers, one per function key. The initializers are simple, quoted character strings delimited by either hexadecimal value 0xFF, octal value \377, or symbolic constant DELIM. Note that any other value can be used as part of a function-key binding. Function keys are numbered starting at zero. Function keys are useful not only in the classic sense of the programmable function keys on the keyboard, but also as a general purpose mechanism for binding arbitrary length character sequences to a given key. For example, physical key location 16 is usually associated with the <tab> and <back tab> on the AT keyboard; and /conf/kbd/us.c sets the key mapping table entry for key 16 as follows: { K_16, f42, f43, none, none, f42, f43, none, none, none, F|T }, For traditional reasons, the <back tab> key outputs the sequence <esc>[Z whereas the <tab> key simply outputs the horizontal-tab character <ctrl-I>. Because at least one of the mapping values for this key is more than one character long, the key must be defined as a ``function'' key and all entries for the the key must correspond to function-key numbers. In this example, function key number 42 was chosen for <tab>, and function key number 43 was chosen for <back tab>. The constant none indicates that you want no output when the key is pressed in the specified shift state. The corresponding funkey initialization entries for function keys f42 and f43 are as follows: /* 42 */ "\t\377", /* Tab */ /* 43 */ "\033[Z\377", /* Back Tab */ We strongly recommend that you comment your function-key bindings. You can also change function-key bindings via the command fnkey. This command lets you temporarily alter one or more function-key mappings without changing your key-mapping sources. Examples Prior to the release of the 101- and 102-key, enhanced-layout AT keyboards, the <ctrl> key was positioned to the left of `A' key. Most terminals also locate the <ctrl> key there. The first example shows how to swap the left <ctrl> key and the <caps-lock> key on a 101- and 102-key keyboard. The <caps-lock> key is physical key 30, whereas the left <ctrl> key is physical key 58. Their respective entries in file /conf/kbd/us.c source file are as follows: { K_30, caps, caps, caps, caps, caps, caps, caps, caps, caps, S|M }, { K_58, lctrl,lctrl,lctrl,lctrl,lctrl,lctrl,lctrl,lctrl,lctrl, S|MB }, Note that the <caps-lock> key is defined with mode M as it is a ``lock'' key. The keyboard will interrupt only on key depressions, because releasing a ``lock'' key has no effect. The left <ctrl> key is defined with mode MB as it is a ``shift'' key. The keyboard generates an interrupt on both key depression and key release, because the driver must track the state of this key. To swap the aforementioned keys, simply change all occurrences of caps to lctrl and vice-versa, as well as swapping the mode fields. After making the changes, the entries now appear as: { K_30, lctrl,lctrl,lctrl,lctrl,lctrl,lctrl,lctrl,lctrl,lctrl, S|MB }, { K_58, caps, caps, caps, caps, caps, caps, caps, caps, caps, S|M }, The second example converts a 101- or 102-key keyboard table to support an XT-style 83-key keyboard layout. The following section summarizes the ``typical'' differences found when comparing the two keyboard layouts. Needless to say, given the extreme variety in keyboard designs, your mileage may vary: Location 101/102 Value 83-key Value Comments 14 none Various Keyboard-specific 30 caps lctrl 58 lctrl lalt 64 rctrl caps 65 none F2 Function Key 66 none F4 Function Key 67 none F6 Function Key 68 none F8 Function Key 69 none F10 Function Key 70 none F1 Function Key 71 none F3 Function Key 72 none F5 Function Key 73 none F7 Function Key 74 none F9 Function Key 90 num Esc 95 / num 100 * scroll 105 - none <SysReq> not used 106 + * 107 none - 108 <Enter> + 110 esc none Not on XT layout 112-123 F1-F12 none Not on XT layout 124 none none <PrtScr> not used 125 scroll none Not on XT layout 126 none none <Pause> not used Building New Binaries After you have modified an existing keyboard-mapping table, use the following commands to rebuild the corresponding executables: cd /conf/kbd su root make If you have created a new keyboard mapping table, you must edit /conf/kbd/Makefile. Duplicate an existing entry from the Makefile, and change the duplicated name to match the name of your new keyboard-mapping table. After you have finished your editing, build an executable from your source file by simply executing the above series of commands. To load your new keyboard table, simply type the name of the executable that corresponds to your keyboard-mapping file. For example, if you just built executable french from source file french.c, type the following command: /conf/kbd/french If the keyboard-support module finds an error, it will print an appropriate message. If it finds no errors, it will update the internal tables of the vtnkb keyboard driver, reprogram the keyboard, and print a message of the form: Loaded French AT keyboard table To ensure that the keyboard-support module is loaded automatically when you boot your COHERENT system, edit file drvld.all to name the module you wish to use. For example, to ensure that the French keyboard table is loaded automatically when you boot your system, insert the following command into /etc/drvld.all: /conf/kbd/french Disabling <Ctrl><Alt><Del> By convention, function-key 0, when enabled, causes the computer system to reboot. This function key is usually bound to the key sequence <ctrl><alt><del>, but you can disable it by setting the value of driver-variable KBBOOT to zero. The installation script for configuring your console asks you if you want to turn off this feature; and if so, it sets KBBOOT to the correct value. Problems With Incompatible Keyboards If you are experiencing problems with respect to key mappings, and you installed one of the loadable keyboard mapping tables from the keyboard selection menu, you may have an incompatible keyboard. Please note that the COHERENT vtnkb driver (and loadable tables) only work with well- engineered keyboards, such as those built by IBM, Cherry, MicroSwitch, or Keytronics; it may not work correctly with a poorly engineered ``clone'' keyboard. The preferred action is to replace your keyboard with one made by one of the above-named manufacturers. If, however, you wish to use a ``clone'' keyboard with COHERENT, your best bet is to re-install COHERENT and select the vtkb driver instead of vtnkb. vtkb is not loadable and supports only the U.S., German, and French keyboard layouts. For details on how to replace vtnkb with vtkb, see the Lexicon entry for keyboard. See Also device drivers, keyboard, vtkb