     THE STRUCTURE OF THE KEYB CONTROL BLOCK (KeybCB)
     ================================================

  ===========================================================================

   Format of the Keyb Control Block (KeybCB specification)

   Copyright (C) 2003 by Aitor SANTAMARIA_MERINO
   aitorsm@inicia.es

   Version  : 1.50
   Last edit: 2004-03-15 (ASM)
     (thanks to suggestions from Axel Frinke)

  ===========================================================================

   DISCLAIMER:

   THIS MATERIAL IS PROVIDED "AS IS"! USE AT YOUR OWN RISK! NO WARRANTIES,
   NEITHER EXPRESSED NOR IMPLIED! I cannot be held responsible for any
   problems caused by use or misuse of the software and/or information!


The Keyb Control Block (KeybCB) is a data structure that represents a binary
image of the possibilities of a physical keyboard, with descriptions of all
the possible admissible behaviours under changes of modes and codepages, and
many more information that a keyboard manager could handle.

Physical keyboard:
   Each possible variation of an enhanced AT (MFII) keyboard, where by
   variation it is understood the labels physically printed in the keys.

Scancode (breakcode, makecode)
   Each key pressing produces at least one or more scancodes, that is, a byte
   code that can be read from the keyboard controller. The sequence of
   scancodes is used to univocally determine the key that has been pressed.
   There are two types of scancodes, breakcodes and makecodes. A makecode is
   produced when a key is pressed, and a breakcode is produced when the key is
   released. The breakcode and makecode produced by the same key have the lower
   order 7 bits equal, whereas the makecode has the bit 7 clear, and the
   breakcode has this bit set to 1. Thus, makecodes range 1-127, whereas
   breakcodes range 129-255.
   Most keys produce a single scancode (break or make) upon a key pressing or
   releasing. However, some keys (added in MFII keyboards, respect to the old
   PC style keyboards) send the scancode E0h (224) before the proper breakcode
   or makecode. These keys will be called E0-prefixed.
   Finally, some few keys behave oddly. Exemply gratia, pressing and releasing
   the PAUSE key produces the scancode E1h (225) before a key combination that
   simulates the pressing of Control+NumLock.

Character:
   Pressing a single key may have several effects, being the most usual the
   production of a (character,scancode) pair that is stored in a character
   buffer, that may be queried by upper layer applications. We shall use the
   term character to denote a byte that identifies a character in the
   current codepage table.
   
Command:
   A key may produce a character. For the contrary, pressing a key may as well
   trigger other special effects, such as invoking OS calls, which will be
   called COMMANDS.

Mode:
   A family of assignments of scancodes to 1-byte characters or commands of a
   same physical keyboard, so that a change in mode causes that a single key 
   may be producing two different character patterns in the screen.
   For example, the existence of a Cyrillic and Latin mode on Russian layouts.

Codepage awareness:
   A keyboard driver is a codepage aware device, because upon a change of the
   display device codepage, the codes for the same character pattern may
   change.

Submapping:
   Each of the possibly assignment tables (lookup tables) of scancodes to
   1-byte characters. Different submappings exist because of the existence of
   Modes, and because of the codepage awareness of a keyboard driver. Each
   submapping has an associated codepage number, but it does not need to be
   unique, and two different submappings may well have the same codepage ID,
   for example if they belong to two different modes.
   A submapping is often given as a table, where blank entries mean that the
   submapping does not define a character or command (see below), that we shall
   express as 'not found'.
   This table may usually only cover changes respect to other existing mapping.

Planes:
   For each submapping, the behaviour of a key may be multiplexed by using
   different PLANES, so that the number of characters that may be produced is
   far larger than the number of keys. Planes are differentiated of each other
   depending of the status of activity of certain other modifier keys, which
   status is tracked by the driver and/or BIOS. Typical keys of this type are
   SHIFT or CapsLock.

General and particular submappings:
   There will be a division between one GENERAL SUBMAPPING, and the rest, a
   list or PARTICULAR SUBMAPPINGS, of which only one of them will be active at
   a time. 
   A new scancode/plane triggered by the keyboard controller is checked against
   the active particular submapping first. If the scancode/plane is NOT found,
   then it is checked against the general submapping.
   If it is neither found there, then the keyboard driver functioning may
   prescribe how to deal with that.
   Note that in submapping tables, a particular submapping assignation of a
   scancode/plane pair OVERRIDES the assignation of the general table.

Diacritic sequence:
   To enlarge the number of characters that can be produced even more, some of
   them (often diacritics) may be produced as the result of the pressing of two
   different keys. The first key is said to trigger the start of an accented
   sequence command, and it is often called a Dead Key, because it produces not
   visible character.

string:
   Some drivers may offer the ability to produce a whole array of
   (character,scancode) pairs, instead of a single one. Such array will be
   called a string.



============================================================================
TABLE 1: The KeybCB
============================================================================
This table describes the structure of a KeybCB, as may be referenced
by some keyboard drivers present in memory.

Ofs  Size      Description
---  --------- ------------------------------------------------------------

     ---Header---
000  BYTE      Number of submappings (n+1) described in the block
               General submapping is counted, and is usually numbered as 0.
001  BYTE      Number of additional planes (m) that are globally defined for
               the whole keyb control block. The total number of planes is
               m+2 (there are two implicit ones, see TABLE 3)
               The maximum number of planes is 10 (that is, m=8)
002  BYTE      Character to be used as decimal separator character by
               the driver when using this layout.
               0 when the default character (usually .) should be used.
003  BYTE      Current particular submapping in use (1 to n)
004  WORD      MCB-ID of the KeybCB, only if the KeybCB resides in a MCB
               that must be deallocated if the KeybCB will no longer be
               used.
006  DWORD     PTR=> Next KeybCB
               KeybCBs may be organized in a linked list, if the keyboard
               driver supports more than one.
               Set to 00:00 if there are no more KeybCBs.
010  WORD      ID Word of the current KeybCB (see ofs 012)
012  8 BYTES   0-padded string of the name with which the KeybCB has been
               loaded. It is usually a two-letter identifier, such as UK,
               GR or SP.
               KeybCBs are usually loaded as single "keyboard layouts"
               identified by a short string and an identifier word in case
               there are several models appliable to the same string ID.
               (for the identifier word, see ofs 010)

     ---Submappings---
020  n+1 QWORDS Each QWORD describes a submapping (see TABLE 2)
                The general submappings comes first, the others are the
                particular submappings.

     ---Planes---
020 + (n+1)*8
     m   QWORDS Each QWORD describes an additional plane (see TABLE 3)

     ---Data---
020 + (n+1)*8 + m*8
                Data blocks start here
============================================================================

  NOTE:  The number of total planes used in the KeybCB is m+2.
         There are two implicitely defined planes, the NO-KEY and the
         SHIFT only plane, the rest of the planes are defined by the
         additional plane descriptors after the submappings

  NOTE:  As seen above, after a 20-byte header there comes the descriptors of
         the submappings and planes of the KeybCB, each of which takes 8 bytes.
         The first two bytes identify the number of submappings and planes.

  NOTE:  The end of the file is formed by data blocks of unspecified size and
         offset. The offsets to these data blocks are referenced inside the
         submapping structure.
         There are three types of blocks:
         - TABLE  type blocks
         - DIACRITIC type blocks
         - STRING type blocks
         Their structures are described in the tables 4-6 below.


============================================================================
TABLE 2: Structure of a submapping
============================================================================
A submapping is a 4 word structure defining a submapping.

Ofs  Size   Description
---  ----- --------------------------------------------------------------
000  WORD  CODEPAGE.
           This is the codepage for which the submapping is prepared.
           0 if it is valid for ANY codepage.
           This value is recommended to be 0 for the general submapping.
002  WORD  TABLE OFFSET.
           Offset to the TABLE type block of the submapping.
           This block defines the assignation of scancode/plane to
           character.
           0 if this table does not define any assignment.
004  WORD  DIACRITIC OFFSET.
           Offset to the DIACRITIC type block of the submapping.
           This block defines how the accent sequences should be handled for
           this submapping.
           0 if this submapping does NOT define accented sequences.
006  WORD  STRING OFFSET.
           Offset to the STRING type block of the submapping.
           This block defines the strings to be printed in this
           submapping.
           0 if this submapping does NOT define STRINGs.
============================================================================

  NOTE:  As explained above, scancode/plane pairs are first checked against
         the PARTICULAR submapping table, and if not found, are looked up in
         the GENERAL submapping table.
         For DIACRITICs and STRINGs, only the PARTICULAR submapping data
         blocks are used. If they do not exist, then the offsets of the
         GENERAL submapping are respectively used.

  NOTE:  The order prescribed of the file is used by the driver to determine
         the submapping to which it should change when the driver receives
         a codepage change call.
         The first submapping which fullfills the requirements becomes active,
         where it fullfills the requirements when the submapping codepage
         matches the codepage sought, or when the submapping codepage is 0.         

============================================================================
TABLE 3: Plane descriptor
============================================================================
A plane descriptor is a 4 word structure defining a plane.

The status keys define two WORD-size maks:
- the STANDARD MASK, which is the set of flags defined by the standard
  status defining keys (SHIFT, CONTROL, etc)
  Its format is described in table 7
- the USER DEFINED MASK, in case the keyboard driver allows the user to
  define new status defining keys. Up to a word of keys can be defined

The table describes the conditions that these masks must meet to identify
a plane.

Ofs  Size   Description
---  ----- --------------------------------------------------------------
000  WORD   REQUIRED STANDARD FLAGS.
            Standard keys include mask
002  WORD   FORBIDDEN STANDARD FLAGS.
            Standard keys exclude mask
004  WORD   REQUIRED USER-DEFINED FLAGS.
            User-defined keys include mask
006  WORD   FORBIDDEN USER-DEFINED FLAGS.
            User-defined keys exclude mask

============================================================================

  NOTE:  The order in which the planes appear is important, because the planes
         must be tested in that order. The first plane which conditions are
         met is considered the plane to be used.

  NOTE:  The first two planes are in all cases implicitely defined to be

         PLANE 1: INCLUDE:  -     EXCLUDE: Shift, Ctrl, Alt, UserKeys
         PLANE 2: INCLUDE: Shift  EXCLUDE: Ctrl, Alt, UserKeys

         If any of the remaining planes uses the CapsLock (resp. NumLock,
         ScrollLock) at all, then CapsLock (resp. NumLock, ScrollLock) must
         be excluded too.


============================================================================
TABLE 4: TABLE TYPE BLOCK
============================================================================
A TABLE type block describes how a scancode/plane maps to a character or a
command.
It is formed by a bunch of contiguous variable-length smaller data items,
each of which is identified by the scancode (leading the structure). After
the last data item, a byte 0 is set to indicate the end of the block.
The table is searched by scancode. The scancode of each item is checked.
The item itself contains the length of the item, and the data for the
different planes.

Ofs        Size   Description
---------  ----- --------------------------------------------------------------
000        BYTE    SCANCODE. Scancode which is defined by this item.

001        BYTE    FLAGS
                      0..2: Length l-1 of DATA subsctructure (0..15)
                      3   : Reserved
                      4   : LOCK: kill any effect of this scancode (key)
                      5   : This key is affected by NumLock. If Numlock is
                            pressed, planes 0 and 1 are exchanged
                      6   : This key is affected by CapsLock. If Capslock is
                            pressed, planes 0 and 1 are exchanged
                      7   : S-flag or granularity: specifies that data are
                            (scancode,char) pairs instead of characters only

002        BYTE   COMMAND BIT FIELD.
                  BitK is set if the K-th DATA corresponds to a command number
                          clear if the k-th DATA corresponds to a character

003   l BYTES or WORDS    k-th BYTE/WORD is the DATA for the k-th PLANE.
                          They are words when the S-flag is set, bytes
                          otherwise.
                          In this case, the high word is a remapped scancode
                          number, and the low word is the character/command
                          byte. When the S-flag is off, ONLY the
                          character/command byte is specified.
                          The character/command number is either a command
                          number or a character, depending on the COMMAND bit
                          field.

Command meanings are driver dependent.

For a correctly defined KeybCB one must have that if flags 5 or 6 on the
flags BYTE are used, then l>1

<NEW> From version 1.6 (KL file version 1.1), it is required that these
data items are ordered ascending by the scancode (BYTE OFS 000).

============================================================================


============================================================================
TABLE 5: DIACRITIC TYPE BLOCK
============================================================================
A DIACRITIC type block describes how to deal with accented sequences.
It is formed by a bunch of contiguous variable-length smaller data items,
and the position of each item represents the accented sequence which is
triggered (the first item is for the first "START ACCENTED SEQUENCE" command,
and so on). 
There should never be less items than the maximum START ACCENTED SEQUENCE
command used in the current submapping. Beware on the commands called from
the general submapping tables too.
Each item self-contains its length, so that the list can be walked.
The item data contains an array of pairs of characters (see below)
The structure ends in a 0, used to mark that there are no more items.
The maximum number of items is limited by the commands that have been
reserved to start accented sequences sequences. Check the number of start
accented sequence commands for your particular driver.


Ofs   Size     Description
----  ------- --------------------------------------------------------------
000   BYTE     Diacritic individal character
               This is displayed when the driver fails to find an
               appropriate character to be combinated with
001   BYTE     Size t of the array of pairs
002   t [BYTE1,BYTE2] pairs. The structure means:
               BYTE1: The character to be combinated. When a diacritic
                      sequence status is pending, the next character must be
                      one of these, or the driver may vomit the combination
                      individual character (ofs 000) and the new character
                      that was not found in the array
               BYTE2: For the contrary, if the character was found, the
                      corresponding BYTE2 is produced.

For example: a possible diacritic item for the umlaut character in German
language would be formed by the individual UMLAUT symbol, the number 6
of pairs, and the six pairs of aouAOU with their respective diacritics
============================================================================



============================================================================
TABLE 6: STRING TYPE BLOCK
============================================================================
A STRING type block describes how to deal with STRINGs.
It is formed by a bunch of contiguous variable-length smaller data items,
and the position of each item represents the STRING which must be output
(the first item is for the first STRING, and so on).
There should never be less items than the maximum STRING command used
in the current submapping. Beware on the commands called from the general
submapping tables too.
Each item self-contains its length, so that the list can be walked.
The item data contains an array of pairs of characters (see below)
The structure ends in a 0, used to mark that there are no more items.
The maximum number of items is limited by the commands that have been
reserved to STRINGS. Check the number of STRINGS for your particular driver.

Ofs   Size     Description
----  ------- --------------------------------------------------------------
000   BYTE     Size t of the array of pairs
001   t [character,scancode] pairs.

============================================================================


============================================================================
TABLE 7: STANDARD STATUS MASK
============================================================================
This word defines standard status bits.

bit   value  Description
----  ------ --------------------------------------------------------
  0   0001h  Right Shift
  1   0002h  Left  Shift
  2   0004h  (Either) Control
  3   0008h  (Either) Alt
  4   0010h  Scroll Lock active
  5   0020h  Num Lock active
  6   0040h  Caps Lock active
  8   0100h  Left Control
  9   0200h  Left Alt
 10   0400h  Right Control
 11   0800h  Right Alt (AltGr)
 12   1000h  E0 prefixed key
 13   4000h  (Either) Shift

============================================================================


