

keyboard tables       Technical Information       keyboard tables




How to write a keyboard table


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!

***** Operational  Overview ***** 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.

***** Key Mapping Files *****

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


COHERENT Lexicon                                           Page 1




keyboard tables       Technical Information       keyboard tables



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.




COHERENT Lexicon                                           Page 2




keyboard tables       Technical Information       keyboard tables



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 lock 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 lock 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  classical sense of the
programmable function keys on the keyboard, but also as a general
purpose   mechanism  for   binding  arbitrary   length  character


COHERENT Lexicon                                           Page 3




keyboard tables       Technical Information       keyboard tables



sequences  to a  given key.  For  example, physical  key location
sixteen is  usually associated with  the <ttaabb> and  <bbaacckk ttaabb> on
the  AT  keyboard.   For  example,  /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.

***** 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
/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:


COHERENT Lexicon                                           Page 4




keyboard tables       Technical Information       keyboard tables





/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


***** Examples *****

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.






COHERENT Lexicon                                           Page 5




keyboard tables       Technical Information       keyboard tables



      _P_h_y_s_i_c_a_l     _1_0_1/_1_0_2        _8_3-_k_e_y
      _L_o_c_a_t_i_o_n      _V_a_l_u_e          _V_a_l_u_e        _C_o_m_m_e_n_t_s
         14          nnoonnee         _v_a_r_i_o_u_s       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


***** See Also *****

ddeevviiccee ddrriivveerrss, ffnnkkeeyy, nnkkbb

***** Notes *****

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.












COHERENT Lexicon                                           Page 6


