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

© 2012 by Stephen A. Ness