Return to keyboardtables CVS log

Up to [MW Coherent from dump] / coherent / a / usr / man / COHERENT

coherent

keyboard tables       Technical Information       keyboard tables




How to write a keyboard table


The  COHERENT device-driver  nnkkbb supports  industry-standard 83-,
101-, and 102-key  AT-protocol keyboards attached as the computer
console.

nnkkbb  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 /ccoonnff/kkbbdd. This directory contains the
C source code for the mapping  tables, as well as a MMaakkeeffiillee 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 nnkkbb. 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 nnkkbb 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  nnkkbb
driver  via specialized  iiooccttll() 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 nnkkbb 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  /ccoonnff/kkbbdd contains the keyboard-mapping
files, executables, and a  MMaakkeeffiillee 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 ttbbll_nnaammee.
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
/ccoonnff/kkbbdd/uuss.cc initializes this string to:


        "U.S. AT keyboard table"


The  second data  structure, kkbbttbbll,  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 /ccoonnff/kkbbdd/bbeellggiiaann.cc:


        { 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 <ssyyss/kkbbssccaann.hh> contains  symbolic constants of
the form KK__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, KK_33 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   SSHHIIFFTT
         4   CCOONNTTRROOLL
         5   CCOONNTTRROOLL+SSHHIIFFTT
         6   AALLTT
         7   AALLTT+SSHHIIFFTT
         8   AALLTT+CCOONNTTRROOLL
         9   AALLTT+CCOONNTTRROOLL+SSHHIIFFTT
        10   AALLTT_GGRRAAPPHHIICC


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 nnoonnee 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 <ssyyss/kkbb.hh>  defines a
set of symbolic constants of the form ff_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: ssccrroollll, nnuumm,  ccaappss, llaalltt, rraalltt, llsshhiifftt, rrsshhiifftt, llccttrrll,
rrccttrrll, or aallttggrr. These are defined in the <ssyyss/kkbb.hh> 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:

CC    The ccaappss lock key affects this key.

FF    The  specified key  is a ``function''  or special  key.  The
     value of  all mapping entries must  name function keys.  See
     header file <kkbb.hh> for a list of predefined function keys.

MM    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!

MMBB   Make/Break: use this mode with ``shift'' keys.

NN    The nnuumm lock key affects this key.

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

SS    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.

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

TTMMBB  Typematic/Make/Break.

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

The  last  data  structure,  ffuunnkkeeyy,  consists  of  an  array  of
function-key   initializers,   one   per   function   key.    The
initializers  are simple  quoted character  strings  delimited by
either  hexadecimal value  00xxFFFF,  octal value  \337777, or  symbolic
constant DDEELLIIMM. 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 <ccttrrll><aalltt><ddeell>.

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 <ttaabb> and  <bbaacckk ttaabb> on
the  AT  keyboard.   For  example,  /ccoonnff/kkbbdd/uuss.cc 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 <bbaacckk ttaabb> key outputs the sequence
<eesscc>[ZZ whereas  the <ttaabb> key simply  outputs the horizontal-tab
character <ccttrrll-II>.   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 <ttaabb>, and  function key
number 43 was chosen for <bbaacckk ttaabb>.  The constant nnoonnee indicates
that you want no output when  the key is pressed in the specified
shift state.  The corresponding ffuunnkkeeyy initialization entries for
function keys ff4422 and ff4433 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 ffnnkkeeyy.
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
/ccoonnff/kkbbdd/MMaakkeeffiillee.   Duplicate  an   existing  entry   from  the
MMaakkeeffiillee, 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  ffrreenncchh from  source file
ffrreenncchh.cc, 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  nnkkbb  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 <ccttrrll> key was  positioned to the left of `A' key.
Most  terminals also  locate  the <ccttrrll>  key  there.  The  first
example shows how to swap the left <ccttrrll> key and the <ccaappss-lloocckk>
key  on a  101-  and 102-key  keyboard.  The  <ccaappss-lloocckk> key  is
physical key 30, whereas the  left <ccttrrll> key is physical key 58.
Their respective  entries in file /ccoonnff/kkbbdd/uuss.cc  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  <ccaappss-lloocckk> key is defined with mode  MM as it is a
``lock''  key.    The  keyboard   will  interrupt  only   on  key
depressions, because releasing a ``lock'' key has no effect.  The
left <ccttrrll> key is defined with mode MMBB 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
ccaappss  to  llccttrrll 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          nnoonnee         _v_a_r_i_o_u_s       Keyboard specific
         30          ccaappss          llccttrrll
         58         llccttrrll          llaalltt
         64         rrccttrrll          ccaappss
         65          nnoonnee            ff22         Function Key
         66          nnoonnee            ff44         Function Key
         67          nnoonnee            ff66         Function Key
         68          nnoonnee            ff88         Function Key
         69          nnoonnee           ff1100         Function Key
         70          nnoonnee            ff11         Function Key
         71          nnoonnee            ff33         Function Key
         72          nnoonnee            ff55         Function Key
         73          nnoonnee            ff77         Function Key
         74          nnoonnee            ff99         Function Key
         90          nnuumm            eesscc
         95          `/'            nnuumm
         100         `*'          ssccrroollll
         105         `-'            nnoonnee        <SSyyssRReeqq> not used
         106         `+'            '*'
         107         nnoonnee           '-'
         108       <eenntteerr>          '+'
         110         eesscc            nnoonnee        Not on XT layout
       112-123      FF11-FF1122          nnoonnee        Not on XT layout
         124         nnoonnee           nnoonnee        <PPrrttSSccrr> not used
         125        ssccrroollll          nnoonnee        Not on XT layout
         126         nnoonnee           nnoonnee        <PPaauussee> not used


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

ddeevviiccee ddrriivveerrss, ffnnkkeeyy, nnkkbb

***** 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
AALLTT_GGRRAAPPHHIICC shift key, for reasons of backwards compatibility you
should allow  the use of combination shift  AALLTT+CCTTRRLL as a synonym
for AALLTT_GGRRAAPPHHIICC.












COHERENT Lexicon                                           Page 6

This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.