Return to keyboardtables CVS log

Up to [MW Coherent from dump] / coherent / f / usr / man / KERNEL

Annotation of coherent/f/usr/man/KERNEL/keyboardtables, revision 1.1

1.1     ! root        1: kkeeyybbooaarrdd ttaabblleess -- Technical Information
        !             2: 
        !             3: 
        !             4: The COHERENT  device-driver nnkkbb  supports industry-standard 83-,  101-, and
        !             5: 102-key AT-protocol keyboards attached as the computer console.
        !             6: 
        !             7: nnkkbb lets you define both the layout of the keyboard and the values returned
        !             8: by function keys.  You can change layout and function-key bindings by using
        !             9: the  special keyboard  mapping programs kept  in directory  /ccoonnff/kkbbdd. This
        !            10: directory contains the  C source code for the mapping  tables, as well as a
        !            11: MMaakkeeffiillee that helps you rebuild the mapping programs.
        !            12: 
        !            13: Before you begin to write or  modify an existing keyboard table, be sure to
        !            14: read throroughly  this article and  the Lexicon article  on nnkkbb. If  you do
        !            15: not, you may foul up the  keyboard so thoroughly that it will not work well
        !            16: enough for you to undo your mistake!
        !            17: 
        !            18: 
        !            19: _O_p_e_r_a_t_i_o_n_a_l _O_v_e_r_v_i_e_w
        !            20: The device driver nnkkbb provides the system's portion of the interface to the
        !            21: console   keyboard.   It   handles  hardware-specific   details,   such  as
        !            22: initializing the keyboard and internal state, handling keyboard interrupts,
        !            23: processing key scan codes, and queueing characters.
        !            24: 
        !            25: The user half of the keyboard interface is provided by a set of stand-alone
        !            26: utilities.   With these,  you can  program the  nnkkbb driver  via specialized
        !            27: iiooccttll() calls.  These utilities differ from each other only in the keyboard
        !            28: binding or mapping tables each uses.  You can re-construct the interface to
        !            29: the  nnkkbb driver  by  modifying a  keyboard-mapping  file and  then using  a
        !            30: support module to link that file to the driver.
        !            31: 
        !            32: The  keyboard-mapping file  is  a C  program that  consists of  initialized
        !            33: tables and  strings.  In  addition, several  header files provide  the scan
        !            34: codes and  other constants required for the key  tables.  This format makes
        !            35: the  file easy  to edit,  and  also lets  you enter  characters in  several
        !            36: different formats.
        !            37: 
        !            38: The  support  module,  in  turn,  performs  several tasks.   These  include
        !            39: scanning the  keyboard-mapping file for errors,  reformatting the table for
        !            40: use by the device driver, and passing the reformatted table to the driver.
        !            41: 
        !            42: _K_e_y _M_a_p_p_i_n_g _F_i_l_e_s
        !            43: By  convention, directory  /ccoonnff/kkbbdd contains  the  keyboard-mapping files,
        !            44: executables, and a MMaakkeeffiillee that  you use to construct the executables from
        !            45: the corresponding source files.
        !            46: 
        !            47: A keyboard-mapping source  file consists primarily of three data structures
        !            48: that you must  modify to support a given keyboard  mapping.  The first, and
        !            49: simplest, of  the structures is  ttbbll_nnaammee. This is a  character string that
        !            50: describes  the keyboard.   For example,  the stock  101-key US  AT keyboard
        !            51: mapping file /ccoonnff/kkbbdd/uuss.cc initializes this string to:
        !            52: 
        !            53:     "U.S. AT keyboard table"
        !            54: 
        !            55: The second  data structure, kkbbttbbll, is an array  of key-mapping entries.  It
        !            56: has one entry (or row) for  each possible key location.  Each entry in this
        !            57: structure consists of 11  fields, which hold, respectively, the key number,
        !            58: nine possible  mapping values, and a mode field.   The following example is
        !            59: for   physical    key   location    3   from   key-mapping    source   file
        !            60: /ccoonnff/kkbbdd/bbeellggiiaann.cc:
        !            61: 
        !            62:     { K_3, 0x82, '2', none, none, 0x82, '2', '~', none, '~', O|T },
        !            63: 
        !            64: Field  1 contains  the _s_c_a_n  _c_o_d_e  _s_e_t _3  code value  for the  desired key.
        !            65: Header file  <ssyyss/kkbbssccaann.hh> contains symbolic  constants of the  form KK__n_n_n
        !            66: that map  the AT  keyboard's _p_h_y_s_i_c_a_l key  number _n_n_n to  the corresponding
        !            67: scan code set 3 value generated by the keyboard.  In the above example, KK_33
        !            68: corresponds to key location three.
        !            69: 
        !            70: Fields 2 through 10 contain the key mappings corresponding to the following
        !            71: shift states, as follows:
        !            72: 
        !            73:     2   base or unshifted
        !            74:     3   SSHHIIFFTT
        !            75:     4   CCOONNTTRROOLL
        !            76:     5   CCOONNTTRROOLL+SSHHIIFFTT
        !            77:     6   AALLTT
        !            78:     7   AALLTT+SSHHIIFFTT
        !            79:     8   AALLTT+CCOONNTTRROOLL
        !            80:     9   AALLTT+CCOONNTTRROOLL+SSHHIIFFTT
        !            81:    10   AALLTT_GGRRAAPPHHIICC
        !            82: 
        !            83: For  ``regular''  keys, the  values  for these  nine  fields are  eight-bit
        !            84: characters; for  ``function'' or ``shift''  keys, they are  special values.
        !            85: The symbolic constant  nnoonnee indicates that you want no  output when the key
        !            86: is pressed in the specified shift state.
        !            87: 
        !            88: In the  case of a  function key, the  value specified is the  number of the
        !            89: desired function  key.  Header  file <ssyyss/kkbb.hh>  defines a set  of symbolic
        !            90: constants of the form ff_n, where _n  is the desired function key number.  You
        !            91: should use these constants; they will improve the readability of your code,
        !            92: and they  will protect your  keyboard mapping source files  from any future
        !            93: changes in the structure of the keyboard driver.
        !            94: 
        !            95: In the case of a ``shift'' key, all nine entries must be identical and must
        !            96: consist  of one  of the  following symbolic  constants: ssccrroollll,  nnuumm, ccaappss,
        !            97: llaalltt, rraalltt,  llsshhiifftt, rrsshhiifftt, llccttrrll,  rrccttrrll, or aallttggrr. These  are defined in
        !            98: the <ssyyss/kkbb.hh> header file.  Note that 83-key XT-layout keyboards only have
        !            99: one ``control''  and ``alt'' key, so not all  shift-key combinations may be
        !           100: possible on your target keyboard.
        !           101: 
        !           102: The  last  (11th) field  in  the  key entry  is  the  ``mode'' field.   The
        !           103: following symbolic constants specify the mode of the current key:
        !           104: 
        !           105: CC    The ccaappss lloocckk key affects this key.
        !           106: 
        !           107: FF    The specified key is a ``function''  or special key.  The value of all
        !           108:      mapping entries must name function keys.  See header file <kkbb.hh> for a
        !           109:      list of predefined function keys.
        !           110: 
        !           111: MM    Make:  use  this  mode  with  keys  that do  not  repeat.   Note  that
        !           112:      accidentally using  this mode with  ``shift'' keys will  stop you from
        !           113:      being able to ``unshift'' upon releasing the key!
        !           114: 
        !           115: MMBB   Make/Break: use this mode with ``shift'' keys.
        !           116: 
        !           117: NN    The nnuumm lloocckk key affects this key.
        !           118: 
        !           119: OO    The specified key is ``regular'' and requires no special processing.
        !           120: 
        !           121: SS    The  specified key  is a  ``shift''  or ``lock''  key.  Note  that all
        !           122:      mapping entries for  a given key must be identical  for a ``shift'' or
        !           123:      ``lock'' key to work correctly.
        !           124: 
        !           125: TT    Typematic: this type is usually associated with a ``regular'' key.
        !           126: 
        !           127: TTMMBB  Typematic/Make/Break.
        !           128: 
        !           129: The above  example specifies a  mode field of  OO|TT, which corresponds  to a
        !           130: ``regular''  key with  Typematic  repeat, and  no special  handling of  the
        !           131: ``lock'' keys.
        !           132: 
        !           133: The  last data  structure,  ffuunnkkeeyy, consists  of an  array of  function-key
        !           134: initializers,  one per  function key.  The  initializers are  simple quoted
        !           135: character strings  delimited by either hexadecimal  value 00xxFFFF, octal value
        !           136: \337777, or symbolic constant DDEELLIIMM. Note  that any other value can be used as
        !           137: part of  a function-key  binding.  Function  keys are numbered  starting at
        !           138: zero.  By convention, function  key 0, when enabled, reboots your computer.
        !           139: For  traditional reasons,  this function  key is usually  bound to  the key
        !           140: sequence <ccttrrll><aalltt><ddeell>.
        !           141: 
        !           142: Function keys are useful not only  in the classic sense of the programmable
        !           143: function keys on the keyboard, but  also as a general purpose mechanism for
        !           144: binding arbitrary length character  sequences to a given key.  For example,
        !           145: physical key  location 16  is usually associated  with the <ttaabb>  and <bbaacckk
        !           146: ttaabb>  on the  AT keyboard;  and /ccoonnff/kkbbdd/uuss.cc sets  the key  mapping table
        !           147: entry for key 16 as follows:
        !           148: 
        !           149:     { K_16, f42, f43, none, none, f42, f43, none, none, none, F|T },
        !           150: 
        !           151: For traditional  reasons, the <bbaacckk  ttaabb> key outputs  the sequence <eesscc>[ZZ
        !           152: whereas the <ttaabb> key simply outputs the horizontal-tab character <ccttrrll-II>.
        !           153: Because at  least one of the  mapping values for this key  is more than one
        !           154: character  long, the  key must  be defined  as a  ``function'' key  and all
        !           155: entries for  the the key must correspond to  function-key numbers.  In this
        !           156: example,  function key  number 42  was chosen for  <ttaabb>, and  function key
        !           157: number 43 was chosen for <bbaacckk  ttaabb>.  The constant nnoonnee indicates that you
        !           158: want no output  when the key is pressed in  the specified shift state.  The
        !           159: corresponding ffuunnkkeeyy  initialization entries for function  keys ff4422 and ff4433
        !           160: are as follows:
        !           161: 
        !           162:     /* 42 */      "\t\377",          /* Tab */
        !           163:     /* 43 */      "\033[Z\377",      /* Back Tab */
        !           164: 
        !           165: We strongly recommend that you comment your function-key bindings.
        !           166: 
        !           167: You  can also  change  function-key bindings  via the  command ffnnkkeeyy.  This
        !           168: command  lets  you  temporarily alter  one  or  more function-key  mappings
        !           169: without changing your key-mapping sources.
        !           170: 
        !           171: _B_u_i_l_d_i_n_g _N_e_w _B_i_n_a_r_i_e_s
        !           172: After  you  have  modified  an  existing  keyboard-mapping table,  use  the
        !           173: following commands to rebuild the corresponding executables:
        !           174: 
        !           175:     cd /conf/kbd
        !           176:     su root
        !           177:     make
        !           178: 
        !           179: If  you  have  created  a   new  keyboard  mapping  table,  you  must  edit
        !           180: /ccoonnff/kkbbdd/MMaakkeeffiillee.  Duplicate an  existing  entry from  the MMaakkeeffiillee,  and
        !           181: change the  duplicated name to match the name  of your new keyboard-mapping
        !           182: table.  After you have finished your editing, build an executable from your
        !           183: source file by simply executing the above series of commands.
        !           184: 
        !           185: To load  your new keyboard  table, simply type  the name of  the executable
        !           186: that corresponds  to your keyboard-mapping file.  For  example, if you just
        !           187: built  executable ffrreenncchh  from  source file  ffrreenncchh.cc,  type the  following
        !           188: command:
        !           189: 
        !           190:     /conf/kbd/french
        !           191: 
        !           192: If the keyboard-support module finds an error, it will print an appropriate
        !           193: message.  If it finds no errors,  it will update the internal tables of the
        !           194: nnkkbb keyboard  driver, reprogram  the keyboard, and  print a message  of the
        !           195: form:
        !           196: 
        !           197:     Loaded French AT keyboard table
        !           198: 
        !           199: _E_x_a_m_p_l_e_s
        !           200: Prior to the release of the 101- and 102-key, enhanced-layout AT keyboards,
        !           201: the <ccttrrll> key was positioned to  the left of `A' key.  Most terminals also
        !           202: locate the <ccttrrll> key there.  The  first example shows how to swap the left
        !           203: <ccttrrll> key  and the <ccaappss-lloocckk>  key on a  101- and 102-key  keyboard.  The
        !           204: <ccaappss-lloocckk> key is physical key 30, whereas the left <ccttrrll> key is physical
        !           205: key 58.  Their respective entries in file /ccoonnff/kkbbdd/uuss.cc source file are as
        !           206: follows:
        !           207: 
        !           208:     { K_30, caps, caps, caps, caps, caps, caps, caps, caps, caps,  S|M },
        !           209:     { K_58, lctrl,lctrl,lctrl,lctrl,lctrl,lctrl,lctrl,lctrl,lctrl, S|MB },
        !           210: 
        !           211: Note that  the <ccaappss-lloocckk> key is  defined with mode MM as  it is a ``lock''
        !           212: key.   The  keyboard  will  interrupt  only  on  key  depressions,  because
        !           213: releasing a  ``lock'' key has  no effect.  The  left <ccttrrll> key  is defined
        !           214: with mode MMBB as it is a ``shift'' key.  The keyboard generates an interrupt
        !           215: on both key  depression and key release, because the  driver must track the
        !           216: state of this key.
        !           217: 
        !           218: To swap  the aforementioned keys, simply change all  occurrences of ccaappss to
        !           219: llccttrrll and  vice-versa, as well  as swapping the mode  fields.  After making
        !           220: the changes, the entries now appear as:
        !           221: 
        !           222:     { K_30, lctrl,lctrl,lctrl,lctrl,lctrl,lctrl,lctrl,lctrl,lctrl, S|MB },
        !           223:     { K_58, caps, caps, caps, caps, caps, caps, caps, caps, caps,  S|M  },
        !           224: 
        !           225: The second example converts a 101-  or 102-key keyboard table to support an
        !           226: XT-style  83-key keyboard  layout.   The following  section summarizes  the
        !           227: ``typical''  differences found  when  comparing the  two keyboard  layouts.
        !           228: Needless  to  say, given  the  extreme variety  in  keyboard designs,  your
        !           229: mileage may vary.
        !           230: 
        !           231:  _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
        !           232:     14          nnoonnee         Various       Keyboard-specific
        !           233:     30          ccaappss          llccttrrll
        !           234:     58         llccttrrll           llaalltt
        !           235:     64         rrccttrrll           ccaappss
        !           236:     65          nnoonnee            FF22         Function Key
        !           237:     66          nnoonnee            FF44         Function Key
        !           238:     67          nnoonnee            FF66         Function Key
        !           239:     68          nnoonnee            FF88         Function Key
        !           240:     69          nnoonnee           FF1100         Function Key
        !           241:     70          nnoonnee            FF11         Function Key
        !           242:     71          nnoonnee            FF33         Function Key
        !           243:     72          nnoonnee            FF55         Function Key
        !           244:     73          nnoonnee            FF77         Function Key
        !           245:     74          nnoonnee            FF99         Function Key
        !           246:     90          nnuumm            EEsscc
        !           247:     95           /             nnuumm
        !           248:     100          *            ssccrroollll
        !           249:     105          -             nnoonnee        <SSyyssRReeqq> not used
        !           250:     106          +              *
        !           251:     107         nnoonnee            -
        !           252:     108       <EEnntteerr>           +
        !           253:     110         eesscc            nnoonnee        Not on XT layout
        !           254:   112-123      FF11-FF1122          nnoonnee        Not on XT layout
        !           255:     124         nnoonnee           nnoonnee        <PPrrttSSccrr> not used
        !           256:     125        ssccrroollll          nnoonnee        Not on XT layout
        !           257:     126         nnoonnee           nnoonnee        <PPaauussee> not used
        !           258: 
        !           259: _S_e_e _A_l_s_o
        !           260: ddeevviiccee ddrriivveerrss, ffnnkkeeyy, kkbb.hh, nnkkbb
        !           261: 
        !           262: _N_o_t_e_s
        !           263: Key 14, if used, varies considerably among keyboard models.
        !           264: 
        !           265: The location of  the key that contains characters `\'  and `|' varies among
        !           266: 101-key US-layout keyboards.
        !           267: 
        !           268: When designing keyboard tables for keyboards that use the AALLTT_GGRRAAPPHHIICC shift
        !           269: key, for  reasons of  backwards compatibility you  should allow the  use of
        !           270: combination shift AALLTT+CCTTRRLL as a synonym for AALLTT_GGRRAAPPHHIICC.

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