nnkkbb -- Device Driver


The COHERENT  device-driver nnkkbb  supports industry-standard 83-,  101-, and
102-key AT-protocol keyboards attached as the computer console.  Unlike kkbb,
the other COHERENT keyboard driver, nnkkbb  lets you define both the layout of
the keyboard  and the values returned  by function keys.  It  also lets you
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.   See the Lexicon article kkeeyybbooaarrdd ttaabblleess for
details.

_K_e_r_n_e_l _V_a_r_i_a_b_l_e_s
Please  note  that the  COHERENT  286 kernel  references  variables with  a
trailing  underscore character;  for  example, aattppaarrmm_.   The COHERENT  386
kernel, however, does _n_o_t use a trailing underscore; for example, aattppaarrmm.

The following descriptions apply to both COHERENT 286 and COHERENT 386, but
the notation will be in the COHERENT-386 form.

_I_n_t_e_r_n_a_l _S_t_r_u_c_t_u_r_e
The following paragraphs describe the internal structure of the nnkkbb driver.
This information  is of interest  mainly to persons  who wish to  study the
design of device drivers.

nnkkbb understands the following ``shift'' and ``lock'' keys:

     ssccrroollll    Scroll lock
     nnuumm       Keypad NUM lock
     ccaappss      Shift or CAPS lock
     llaalltt      Left ALT key
     rraalltt      Right ALT key
     llsshhiifftt    Left SHIFT key
     rrsshhiifftt    Right SHIFT key
     llccttrrll     Left CTRL key
     rrccttrrll     Right CTRL key
     aallttggrr     ALT Graphic key (non-US keyboards)

nnkkbb records an 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  SSHHIIFFTT, CCTTRRLL, AALLTT,  and AALLTT_GGRR. The llsshhiifftt  and rrsshhiifftt keys
combine  to   form  the  current  SSHHIIFFTT   state  for  non-alphabetic  keys.
Alphabetic keys  generally use the  current state of  the ccaappss lock  key in
addition to  llsshhiifftt and rrsshhiifftt. Numeric keys found  on the keypad generally
use the state of the nnuumm  lock key combined with llsshhiifftt and rrsshhiifftt. The two
``control''  keys, llccttrrll  and rrccttrrll,  form the internal  CCTTRRLL state.   In a
similar manner, the two ``alt'' keys,  llaalltt and rraalltt, form the internal AALLTT
state.  Note that 102-key keyboards generally replace the rraalltt key with the
aallttggrr key,  to allow access  to the alternate graphics  characters found on
some keyboards.

nnkkbb  lets  you  configure or  read  the  internal  mapping  tables via  the
following iiooccttll() requests, as defined in header file <ssggttttyy.hh>:

     TTIIOOCCGGEETTFF  Get function key bindings
     TTIIOOCCSSEETTFF  Set function key bindings
     TTIIOOCCGGEETTKKBBTTGet keyboard table bindings
     TTIIOOCCSSEETTKKBBTTSet keyboard table bindings

Requests TTIIOOCCGGEETTFF  and TTIIOOCCSSEETTFF reference  a data structure  of type FFNNKKEEYY,
which  is a  ttyyppeeddeeff defined  in header  file <ssyyss/kkbb.hh>.  Structure member
kk_ffnnvvaall is a character array  that contains a series of contiguous function
key/value bindings; the end of  the bindings is marked by manifest constant
DDEELLIIMM. You  can use any  value other than  DDEELLIIMM as part  of a function-key
binding.  Structure  member kk_nnffkkeeyyss indicates how  many function keys have
associated entries in kk_ffnnvvaall. Function keys are numbered from zero through
kk_nnffkkeeyyss-1.

_D_i_s_a_b_l_i_n_g <_C_t_r_l><_A_l_t><_D_e_l>
By convention, function-key 0,  when enabled, causes the computer system to
reboot.   This   function  key  is  usually  bound   to  the  key  sequence
<ccttrrll><aalltt><ddeell>, but  you can disable  it by setting the  value of driver-
variable KKBBBBOOOOTT to zero.  To do so, use the following command:

    /conf/patch /coherent KBBOOT=0

Requests  TTIIOOCCGGEETTKKBBTT  and  TTIIOOCCSSEETTKKBBTT  reference  an  array  that  contains
MMAAXX_KKEEYYSS occurrences of data structure KKBBTTBBLL, which is a ttyyppeeddeeff defined in
header file  <ssyyss/kkbb.hh>. Structure member kk_kkeeyy contains  the _s_c_a_n _c_o_d_e _s_e_t
_t_h_r_e_e code value for  the desired key.  Header file <ssyyss/kkbbssccaann.hh> contains
manifest  (symbolic) constants  of the  form KK__n_n_n,  which map  AT keyboard
_p_h_y_s_i_c_a_l  key number  _n_n_n to  the  corresponding scan-code  set-three value
generated by the keyboard.  Note that the nnkkbb driver disables the scan-code
translation  that the  keyboard controller  normally  performs, as  well as
setting the keyboard to scan code set three.

Structure  member  kk_vvaall is  a  nine-element array  that  contains the  key
mappings that correspond to the following index values and shift states:

    00   BBAASSEE
    11   SSHHIIFFTT
    22   CCTTRRLL
    33   CCTTRRLL_SSHHIIFFTT
    44   AALLTT
    55   AALLTT_SSHHIIFFTT
    66   AALLTT_CCTTRRLL
    77   AALLTT_CCTTRRLL_SSHHIIFFTT
    88   AALLTT_GGRR

Structure member kk_ffllaaggss contains  mode information for the given key.  One
field  in kk_ffllaaggss  indicates the  _c_l_a_s_s  of key.   This sub-field  lets you
specify whether a  key is a ``shift'' key (as  defined above), a special or
programmable  ``function''  key,  or  a  ``regular''  key.   The  following
symbolic constants specify the _c_l_a_s_s of key:

SS    The  specified key  is a  ``shift''  or ``lock''  key.  Note  that all
     entries in  array kk_vvaall must be identical for  a ``shift'' or ``lock''
     key to work correctly.

FF    The specified key is a ``function''  or special key.  The value of all
     elements  of array  kk_vvaall  must specify  a function  key number.   See
     header file <kkbb.hh> for a list of predefined function keys.

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

The next  sub-field of kk_ffllaaggss specifies  the _t_y_p_e of key,  as specified in
the AT  keyboard technical reference.   The _t_y_p_e sub-field  specifies under
what  conditions a  given  key will  generate an  interrupt.  The  possible
choices are:

MM    Make: generate an interrupt only upon key ``make'' (i.e., when the key
     is  depressed).  This  mode is  useful for keys  which do  not repeat.
     Note  that  using  this  mode  with  ``shift''  keys  stops  you  from
     unshifting upon release of the key!

T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.

MMBB   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.

TTMMBB  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 last sub-field of kk_ffllaaggss specifies  the _l_o_c_k keys, if any, that affect
the specified key:

CC    The ccaappss  lock key  that affects  this key.  If  the specified  key is
     depressed while  ccaappss lock is active, it is  equivalent to having used
     either of the SHIFT keys with  this key.  When ccaappss lock is in effect,
     use of either  of the SHIFT keys temporarily toggles  the state of the
     ccaappss lock.

NN    The nnuumm lock key affects this  key.  If the specified key is depressed
     while nnuumm  lock is active, it  is equivalent to having  used either of
     the SHIFT  keys in conjunction with the specified  key.  When nnuumm lock
     is in effect, use of either  of the SHIFT keys temporarily toggles the
     state of the nnuumm lock.

_P_r_o_b_l_e_m_s _W_i_t_h _I_n_c_o_m_p_a_t_i_b_l_e _K_e_y_b_o_a_r_d_s
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  nnkkbb  driver  (and  loadable  tables) only  work  with  well-
engineered keyboards,  such as those built by  IBM, Cherry, MicroSwitch, or
Keytronics; when  used with a poorly engineered  ``clone'' keyboard, it may
not work correctly.

The preferred action  is to replace the inferior keyboard  with one made by
one  of the  above-named manufacturers.   If, however, you  wish to  use an
inferior keyboard  with COHERENT, your  best bet is  to re-install COHERENT
and select  the kkbb driver instead  of nnkkbb. kkbb is  not loadable and supports
only the U.S., German, and French keyboard layouts.

If you  do not wish to  replace your keyboard or  re-install COHERENT, then
the following _m_a_y help you cope with your keyboard's problems.

11. If  the shift  or  control keys  seem  to ``stick''  in the  oonn or  ddoowwnn
   postition,  you  can  try   to  fix  the  keyboard  mapping  table  that
   corresponds  to your  country.  For  example, if  you selected  the U.S.
   keyboard mapping table during installation but find that the right shift
   or control key seems to stay down after you press it for the first time,
   edit file  /ccoonnff/kkbbdd/uuss.cc. To fix  the right shift key,  change the line
   that reads:

   {K_57,rshift,rshift,rshift,rshift,rshift,rshift,rshift,rshift,rshift, S|MB },
   to:

   {K_57,none, none, none, none, none, none, none, none, none, O|MB },
   To fix the right control key, change the line that reads

   {K_64, rctrl, rctrl, rctrl, rctrl, rctrl, rctrl, rctrl, rctrl, rctrl, S|MB },
   to:

   {K_64,none, none, none, none, none, none, none, none, none, O|MB },
   This  makes  these keys  inoperative.   This, of  course,  is less  than
   desirable, but it will at least prevent you from accidently forcing your
   keyboard into a shift or control state from which you cannot exit.

   Once you  modified the keyboard  table, rebuild the  keyboard executable
   that corresponds  to the modified  table, as described above  and in the
   Lexicon article  kkeeyybbooaarrdd ttaabblleess. Thereafter, you can  enter the name of
   the  newly  created executable  and it  will load the  modified keyboard
   table into the keyboard driver.  This also happens automatically at boot
   time.

22. If  one or  two  keys are  transposed,  have no  output,  or output  the
   incorrect  value,  you  must  (a)  figure  out  which  key  location  is
   incorrect,  (b) decide  what the  correct  value should  be for  all key
   states, (c)  edit the  file in  directory /ccoonnff/kkbbdd that  corresponds to
   your  selection, (d)  rebuild  the keyboard  table  executable, and  (e)
   reload the keyboard table by invoking the newly created executable.

As noted above, the easiest solution is to replace the keyboard.

_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, kkeeyybbooaarrdd ttaabblleess
_T_e_c_h_n_i_c_a_l  _R_e_f_e_r_e_n_c_e _f_o_r  _t_h_e _I_B_M  _P_e_r_s_o_n_a_l  _C_o_m_p_u_t_e_r _A_T,  IBM Corporation,
1984.
_M_u_l_t_i-_F_u_n_c_t_i_o_n _K_e_y_b_o_a_r_d_s: _L_a_y_o_u_t_s, Cherry Electrical Products Corp.

_N_o_t_e_s
With  release 3.2  of COHERENT,  nnkkbb became  the standard  keyboard driver,
replacing the kkbb driver used  in earlier releases.  Please note that either
nnkkbb or kkbb can be linked  into the COHERENT kernel, like most other COHERENT
device drivers.  Neither driver  is found in directory /ddrrvv; this directory
is reserved for loadable device drivers, such as those for the COM ports or
for  the shared-memory  driver.  The  COHERENT  Device Driver  Kit contains
tools and information to rebuild the COHERENT kernel, which is necessary if
you wish to switch keyboard drivers.

The main difference between nnkkbb and  kkbb is that nnkkbb uses a ``supplemental''
process  to interpret  keystrokes.  This permits  COHERENT users  to switch
among flavors of international  keyboards with a minimum of difficulty.  As
noted above,  the source  code for these  supplemental programs is  kept in
directory  /ccoonnff/kkbbdd.  See  the Lexicon  article  on   kkeeyybbooaarrdd ttaabblleess  for
details  on  how  to modify,  compile,  and  load  one  of these  keyboard-
interpretation programs.

Please note,  finally, that  if you attempt  to use a  keyboard interpreter
with kkbb, it will fail with an error message.
