kkeeyybbooaarrdd ttaabblleess -- Technical Information


The COHERENT  device-driver nnkkbb  supports industry-standard 83-,  101-, and
102-key AT-protocol keyboards attached as the computer console.

nnkkbb lets you define both the layout of the keyboard and the values returned
by function keys.  You can change layout and function-key bindings by using
the  special keyboard  mapping programs kept  in directory  /ccoonnff/kkbbdd. This
directory contains the  C source code for the mapping  tables, as well as a
MMaakkeeffiillee that helps you rebuild the mapping programs.

Before you begin to write or  modify an existing keyboard table, be sure to
read throroughly  this article and  the Lexicon article  on nnkkbb. If  you do
not, you may foul up the  keyboard so thoroughly that it will not work well
enough for you to undo your mistake!


_O_p_e_r_a_t_i_o_n_a_l _O_v_e_r_v_i_e_w
The device driver nnkkbb provides the system's portion of the interface to the
console   keyboard.   It   handles  hardware-specific   details,   such  as
initializing the keyboard and internal state, handling keyboard interrupts,
processing key scan codes, and queueing characters.

The user half of the keyboard interface is provided by a set of stand-alone
utilities.   With these,  you can  program the  nnkkbb driver  via specialized
iiooccttll() calls.  These utilities differ from each other only in the keyboard
binding or mapping tables each uses.  You can re-construct the interface to
the  nnkkbb driver  by  modifying a  keyboard-mapping  file and  then using  a
support module to link that file to the driver.

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.

_K_e_y _M_a_p_p_i_n_g _F_i_l_e_s
By  convention, directory  /ccoonnff/kkbbdd contains  the  keyboard-mapping files,
executables, and a MMaakkeeffiillee that  you use to construct the executables from
the corresponding source files.

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  ttbbll_nnaammee. This is a  character string that
describes  the keyboard.   For example,  the stock  101-key US  AT keyboard
mapping file /ccoonnff/kkbbdd/uuss.cc initializes this string to:

    "U.S. AT keyboard table"

The second  data structure, kkbbttbbll, 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
/ccoonnff/kkbbdd/bbeellggiiaann.cc:

    { K_3, 0x82, '2', none, none, 0x82, '2', '~', none, '~', O|T },

Field  1 contains  the _s_c_a_n  _c_o_d_e  _s_e_t _3  code value  for the  desired key.
Header file  <ssyyss/kkbbssccaann.hh> contains symbolic  constants of the  form KK__n_n_n
that map  the AT  keyboard's _p_h_y_s_i_c_a_l key  number _n_n_n to  the corresponding
scan code set 3 value generated by the keyboard.  In the above example, KK_3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   SSHHIIFFTT
    4   CCOONNTTRROOLL
    5   CCOONNTTRROOLL+SSHHIIFFTT
    6   AALLTT
    7   AALLTT+SSHHIIFFTT
    8   AALLTT+CCOONNTTRROOLL
    9   AALLTT+CCOONNTTRROOLL+SSHHIIFFTT
   10   AALLTT_GGRRAAPPHHIICC

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  nnoonnee 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 <ssyyss/kkbb.hh>  defines a set  of symbolic
constants of the form ff_n, where _n  is the desired function key number.  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: ssccrroollll,  nnuumm, ccaappss,
llaalltt, rraalltt,  llsshhiifftt, rrsshhiifftt, llccttrrll,  rrccttrrll, or aallttggrr. These  are defined in
the <ssyyss/kkbb.hh> header file.  Note that 83-key XT-layout keyboards only have
one ``control''  and ``alt'' key, so not all  shift-key combinations 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:

CC    The ccaappss lloocckk key affects this key.

FF    The specified key is a ``function''  or special key.  The value of all
     mapping entries must name function keys.  See header file <kkbb.hh> for a
     list of predefined function keys.

MM    Make:  use  this  mode  with  keys  that do  not  repeat.   Note  that
     accidentally using  this mode with  ``shift'' keys will  stop you from
     being able to ``unshift'' upon releasing the key!

MMBB   Make/Break: use this mode with ``shift'' keys.

NN    The nnuumm lloocckk key affects this key.

OO    The specified key is ``regular'' and requires no special processing.

SS    The  specified key  is a  ``shift''  or ``lock''  key.  Note  that all
     mapping entries for  a given key must be identical  for a ``shift'' or
     ``lock'' key to work correctly.

TT    Typematic: this type is usually associated with a ``regular'' key.

TTMMBB  Typematic/Make/Break.

The above  example specifies a  mode field of  OO|TT, which corresponds  to a
``regular''  key with  Typematic  repeat, and  no special  handling of  the
``lock'' keys.

The  last data  structure,  ffuunnkkeeyy, consists  of an  array of  function-key
initializers,  one per  function key.  The  initializers are  simple quoted
character strings  delimited by either hexadecimal  value 00xxFFFF, octal value
\337777, or symbolic constant DDEELLIIMM. Note  that any other value can be used as
part of  a function-key  binding.  Function  keys are numbered  starting at
zero.  By convention, function  key 0, when enabled, reboots your computer.
For  traditional reasons,  this function  key is usually  bound to  the key
sequence <ccttrrll><aalltt><ddeell>.

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 <ttaabb>  and <bbaacckk
ttaabb>  on the  AT keyboard;  and /ccoonnff/kkbbdd/uuss.c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 <bbaacckk  ttaabb> key outputs  the sequence <eesscc>[ZZ
whereas the <ttaabb> key simply outputs the horizontal-tab character <ccttrrll-I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  <ttaabb>, and  function key
number 43 was chosen for <bbaacckk  ttaabb>.  The constant nnoonnee indicates that you
want no output  when the key is pressed in  the specified shift state.  The
corresponding ffuunnkkeeyy  initialization entries for function  keys ff4422 and ff4433
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 ffnnkkeeyy.  This
command  lets  you  temporarily alter  one  or  more function-key  mappings
without changing your key-mapping sources.

_B_u_i_l_d_i_n_g _N_e_w _B_i_n_a_r_i_e_s
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
/ccoonnff/kkbbdd/MMaakkeeffiillee.  Duplicate an  existing  entry from  the MMaakkeeffiillee,  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 ffrreenncchh  from  source file  ffrreenncchh.c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
nnkkbb keyboard  driver, reprogram  the keyboard, and  print a message  of the
form:

    Loaded French AT keyboard table

_E_x_a_m_p_l_e_s
Prior to the release of the 101- and 102-key, enhanced-layout AT keyboards,
the <ccttrrll> key was positioned to  the left of `A' key.  Most terminals also
locate the <ccttrrll> key there.  The  first example shows how to swap the left
<ccttrrll> key  and the <ccaappss-lloocckk>  key on a  101- and 102-key  keyboard.  The
<ccaappss-lloocckk> key is physical key 30, whereas the left <ccttrrll> key is physical
key 58.  Their respective entries in file /ccoonnff/kkbbdd/uuss.c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 <ccaappss-lloocckk> key is  defined with mode M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 <ccttrrll> key  is defined
with mode MMBB 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 ccaappss to
llccttrrll 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.

 _L_o_c_a_t_i_o_n  _1_0_1/_1_0_2 _V_a_l_u_e   _8_3-_k_e_y _V_a_l_u_e    _C_o_m_m_e_n_t_s
    14          nnoonnee         Various       Keyboard-specific
    30          ccaappss          llccttrrll
    58         llccttrrll           llaalltt
    64         rrccttrrll           ccaappss
    65          nnoonnee            FF22         Function Key
    66          nnoonnee            FF44         Function Key
    67          nnoonnee            FF66         Function Key
    68          nnoonnee            FF88         Function Key
    69          nnoonnee           FF1100         Function Key
    70          nnoonnee            FF11         Function Key
    71          nnoonnee            FF33         Function Key
    72          nnoonnee            FF55         Function Key
    73          nnoonnee            FF77         Function Key
    74          nnoonnee            FF99         Function Key
    90          nnuumm            EEsscc
    95           /             nnuumm
    100          *            ssccrroollll
    105          -             nnoonnee        <SSyyssRReeqq> not used
    106          +              *
    107         nnoonnee            -
    108       <EEnntteerr>           +
    110         eesscc            nnoonnee        Not on XT layout
  112-123      FF11-FF1122          nnoonnee        Not on XT layout
    124         nnoonnee           nnoonnee        <PPrrttSSccrr> not used
    125        ssccrroollll          nnoonnee        Not on XT layout
    126         nnoonnee           nnoonnee        <PPaauussee> not used

_S_e_e _A_l_s_o
ddeevviiccee ddrriivveerrss, ffnnkkeeyy, kkbb.hh, nnkkbb

_N_o_t_e_s
Key 14, if used, varies considerably among keyboard models.

The location of  the key that contains characters `\'  and `|' varies among
101-key US-layout keyboards.

When designing keyboard tables for keyboards that use the AALLTT_GGRRAAPPHHIICC shift
key, for  reasons of  backwards compatibility you  should allow the  use of
combination shift AALLTT+CCTTRRLL as a synonym for AALLTT_GGRRAAPPHHIICC.
