KB(4M)

NAME
kb - Sun keyboard STREAMS module

CONFIG
pseudo-device kbnumber

SYNOPSIS
#include <sys/types.h>
#include <sys/stream.h>
#include <sys/stropts.h>
#include <sundev/vuid_event.h>
#include <sundev/kbio.h>
#include <sundev/kbd.h>

ioctl(fd, I_PUSH, "kb");

DESCRIPTION

The kb STREAMS module processes byte streams generated by Sun keyboards attached to a CPU serial or parallel port. Definitions for altering keyboard translation, and reading events from the keyboard, are in <sundev/kbio.h> and <sundev/kbd.h>. number specifies the maximum number of keyboards supported by the system.

kb recognizes which keys have been typed using a set of tables for each known type of keyboard. Each translation table is an array of 128 16-bit words (unsigned shorts). If an entry in the table is less than 0x100, it is treated as an ISO 8859/1 character. Higher values indicate special characters that invoke more complicated actions.

  Keyboard Translation Mode

The keyboard can be in one of the following translation modes:

    TR_NONE
        Keyboard translation is turned off and up/down key codes are reported.

    TR_ASCII
        ISO 8859/1 codes are reported.

    TR_EVENT
        firm_events are reported (see

    TR_UNTRANS_EVENT
        firm_events containing unencoded keystation codes are reported for all input events within the window system.

  Keyboard Translation-Table Entries

All instances of the kb module share seven translation tables used to convert raw keystation codes to event values. The tables are:

    Unshifted
        Used when a key is depressed and no shifts are in effect.

    Shifted
        Used when a key is depressed and a Shift key is being held down.

    Caps Lock
        Used when a key is depressed and Caps Lock is in effect.

    Alt Graph
        Used when a key is depressed and the Alt Graph key is being held down.

    Num Lock
        Used when a key is depressed and Num Lock is in effect.

    Controlled
        Used when a key is depressed and the Control key is being held down (regardless of whether a Shift key or the Alt Graph is being held down, or whether Caps Lock or Num Lock is in effect).

    Key Up
        Used when a key is released.

Each key on the keyboard has a “key station” code which is a number from 0 to 127. This number is used as an index into the translation table that is currently in effect. If the corresponding entry in that translation table is a value from 0 to 255, this value is treated as an ISO 8859/1 character, and that character is the result of the translation.

If the entry is a value above 255, it is a “special” entry. Special entry values are classified according to the value of the high-order bits. The high-order value for each class is defined as a constant, as shown in the list below. The value of the low-order bits, when added to this constant, distinguishes between keys within each class:

SHIFTKEYS 0x100
    A shift key. The value of the particular shift key is added to determine which shift mask to apply:

    CAPSLOCK 0
        “Caps Lock” key.

    SHIFTLOCK 1
        “Shift Lock” key.

    LEFTSHIFT 2
        Left-hand “Shift” key.

    RIGHTSHIFT 3
        Right-hand “Shift” key.

    LEFTCTRL 4
        Left-hand (or only) “Control” key.

    RIGHTCTRL 5
        Right-hand “Control” key.

    ALTGRAPH 9
        “Alt Graph” key.

    ALT 10
        “Alternate” key on the Sun-3 keyboard, or “Alt” key on the Sun-4 keyboard.

    NUMLOCK 11
        “Num Lock” key.

BUCKYBITS 0x200
    Used to toggle mode-key-up/down status without altering the value of an accompanying ISO 8859/1 character. The actual bit-position value, minus 7, is added.

    METABIT 0
        The “Meta” key was pressed along with the key. This is the only user-accessible bucky bit. It is ORed in as the 0x80 bit; since this bit is a legitimate bit in a character, the only way to distinguish between, for example, 0xA0 as META+0x20 and 0xA0 as an 8-bit character is to watch for “META key up” and “META key down” events and keep track of whether the META key was down.

    SYSTEMBIT 1
        The “System” key was pressed. This is a place holder to indicate which key is the system-abort key.

FUNNY 0x300
    Performs various functions depending on the value of the low 4 bits:

    NOP 0x300
        Does nothing.

    OOPS 0x301
        Exists, but is undefined.

    HOLE 0x302
        There is no key in this position on the keyboard, and the position-code should not be used.

    NOSCROLL 0x303
        Alternately sends CTRL-S and CTRL-Q characters.

    CTRLS 0x304
        Sends CTRL-S character and toggles NOSCROLL key.

    CTRLQ 0x305
        Sends CTRL-Q character and toggles NOSCROLL key.

    RESET 0x306
        Keyboard reset.

    ERROR 0x307
        The keyboard driver detected an internal error.

    IDLE 0x308
        The keyboard is idle (no keys down).

    COMPOSE 0x309
        This key is the COMPOSE key; the next two keys should comprise a two-character “COMPOSE key” sequence.

    NONL 0x30A
        Used only in the Num Lock table; indicates that this key is not affected by the Num Lock state, so that the translation table to use to translate this key should be the one that would have been used had Num Lock not been in effect.

    0x30B — 0x30F
        Reserved for nonparameterized functions.

FA_CLASS 0x400
    This key is a “floating accent” or “dead” key. When this key is pressed, the next key generates an event for an accented character; for example, “floating accent grave” followed by the “a” key generates an event with the ISO 8859/1 code for the “a with grave accent” character. The low-order bits indicate which accent; the codes for the individual “floating accents” are as follows:

    FA_UMLAUT 0x400
        umlaut

    FA_CFLEX 0x401
        circumflex

    FA_TILDE 0x402
        tilde

    FA_CEDILLA 0x403
        cedilla

    FA_ACUTE 0x404
        acute accent

    FA_GRAVE 0x405
        grave accent

STRING 0x500
    The low-order bits index a table of strings. When a key with a STRING entry is depressed, the characters in the null-terminated string for that key are sent, character by character. The maximum length is defined as:

        KTAB_STRLEN 10

    Individual string numbers are defined as:

        HOMEARROW
            0x00
        UPARROW
            0x01
        DOWNARROW
            0x02
        LEFTARROW
            0x03
        RIGHTARROW
            0x04

    String numbers 0x05 — 0x0F are available for custom entries.

FUNCKEYS 0x600
    Function keys. The next-to-lowest 4 bits indicate the group of function keys:

        LEFTFUNC 0x600
        RIGHTFUNC 0x610
        TOPFUNC 0x620
        BOTTOMFUNC 0x630

The low 4 bits indicate the function key number within the group:

    LF(n)
        (LEFTFUNC+(n)-1)
    RF(n)
        (RIGHTFUNC+(n)-1)
    TF(n)
        (TOPFUNC+(n)-1)
    BF(n)
        (BOTTOMFUNC+(n)-1)

There are 64 keys reserved for function keys. The actual positions may not be on left/right/top/bottom of the keyboard, although they usually are.

PADKEYS 0x700
    This key is a “numeric keypad key.” These entries should appear only in the Num Lock translation table; when Num Lock is in effect, these events will be generated by pressing keys on the right-hand keypad. The low-order bits indicate which key; the codes for the individual keys are as follows:

    PADEQUAL 0x700
        “=” key

    PADSLASH 0x701
        “/” key

    PADSTAR 0x702
        “*” key

    PADMINUS 0x703
        “-” key

    PADSEP 0x704
        “,” key

    PAD7 0x705
        “7” key

    PAD8 0x706
        “8” key

    PAD9 0x707
        “9” key

    PADPLUS 0x708
        “+” key

    PAD4 0x709
        “4” key

    PAD5 0x70A
        “5” key

    PAD6 0x70B
        “6” key

    PAD1 0x70C
        “1” key

    PAD2 0x70D
        “2” key

    PAD3 0x70E
        “3” key

    PAD0 0x70F
        “0” key

    PADDOT 0x710
        “.” key

    PADENTER 0x711
        “Enter” key

In TR_ASCII mode, when a function key is pressed, the following escape sequence is sent:
    ESC[0....9z
where ESC is a single escape character and “0...9” indicates the decimal representation of the function-key value. For example, function key R1 sends the sequence:
    ESC[208z
because the decimal value of RF(1) is 208. In TR_EVENT mode, if there is a VUID event code for the function key in question, an event with that event code is generated; otherwise, individual events for the characters of the escape sequence are generated.

  Keyboard Compatibility Mode

kb is in “compatibility mode” when it starts up. In this mode, when the keyboard is in the TR_EVENT translation mode, ISO 8859/1 characters from the “upper half” of the character set (that is, characters with the 8th bit set) are presented as events with codes in the ISO_FIRST range (as defined in <sundev/vuid_event.h>). The event code is ISO_FIRST plus the character value. This is for backwards compatibility with older versions of the keyboard driver. If compatibility mode is turned off, ISO 8859/1 characters are presented as events with codes equal to the character code.

IOCTLS

The following ioctl() requests set and retrieve the current translation mode of a keyboard:

KIOCTRANS
    The argument is a pointer to an int. The translation mode is set to the value in the int pointed to by the argument.

KIOCGTRANS
    The argument is a pointer to an int. The current translation mode is stored in the int pointed to by the argument.

ioctl() requests for changing and retrieving entries from the keyboard translation table use the kiockeymap structure:

    struct	kiockeymap {
    	int	kio_tablemask;	/* Translation table (one of: 0, CAPSMASK,
    				   SHIFTMASK, CTRLMASK, UPMASK,
    				   ALTGRAPHMASK, NUMLOCKMASK) */
    #define KIOCABORT1	-1	/* Special “mask”: abort1 keystation */
    #define KIOCABORT2	-2	/* Special “mask”: abort2 keystation */
    	u_char	kio_station;	/* Physical keyboard key station (0-127) */
    	u_short	kio_entry;	/* Translation table station's entry */
    	char	kio_string[10];	/* Value for STRING entries (null terminated) */
    };

KIOCSKEY
    The argument is a pointer to a kiockeymap structure. The translation table entry referred to by the values in that structure is changed.

    kio_tablemask specifies which of the five translation tables contains the entry to be modified:

        UPMASK 0x0080
            “Key Up” translation table.

        NUMLOCKMASK 0x0800
            “Num Lock” translation table.

        CTRLMASK 0x0030
            “Controlled” translation table.

        ALTGRAPHMASK 0x0200
            “Alt Graph” translation table.

        SHIFTMASK 0x000E
            “Shifted” translation table.

        CAPSMASK 0x0001
            “Caps Lock” translation table.

        (No shift keys pressed or locked)
            “Unshifted” translation table.

    kio_station specifies the keystation code for the entry to be modified. The value of kio_entry is stored in the entry in question. If kio_entry is between STRING and STRING+15, the string contained in kio_string is copied to the appropriate string table entry. This call may return EINVAL if there are invalid arguments.

    There are a couple special values of kio_tablemask that affect the two step “break to the PROM monitor” sequence. The usual sequence is SETUP-a or L1-a. If kio_tablemask is KIOCABORT1 then the value of kio_station is set to be the first keystation in the sequence. If kio_tablemask is KIOCABORT2 then the value of kio_station is set to be the second keystation in the sequence.

KIOCGKEY
    The argument is a pointer to a kiockeymap structure. The current value of the keyboard translation table entry specified by kio_tablemask and kio_station is stored in the structure pointed to by the argument. This call may return EINVAL if there are invalid arguments.

KIOCTYPE
    The argument is a pointer to an int. A code indicating the type of the keyboard is stored in the int pointed to by the argument:
        KB_KLUNK
            Micro Switch 103SD32-2
        KB_VT100
            Keytronics VT100 compatible
        KB_SUN2
            Sun-2 keyboard
        KB_SUN3
            Sun-3 keyboard
        KB_SUN4
            Sun-4 keyboard
        KB_ASCII
            ASCII terminal masquerading as keyboard

    -1 is stored in the int pointed to by the argument if the keyboard type is unknown.

KIOCLAYOUT
    The argument is a pointer to an int. On a Sun-4 keyboard, the layout code specified by the keyboard's DIP switches is stored in the int pointed to by the argument.

KIOCCMD
    The argument is a pointer to an int. The command specified by the value of the int pointed to by the argument is sent to the keyboard. The commands that can be sent are:

    Commands to the Sun-2, Sun-3, and Sun-4 keyboard:
        KBD_CMD_RESET
            Reset keyboard as if power-up.
        KBD_CMD_BELL
            Turn on the bell.
        KBD_CMD_NOBELL
            Turn off the bell

    Commands to the Sun-3 and Sun-4 keyboard:
        KBD_CMD_CLICK
            Turn on the click annunciator.
        KBD_CMD_NOCLICK
            Turn off the click annunciator.

    Inappropriate commands for particular keyboard types are ignored. Since there is no reliable way to get the state of the bell or click (because we cannot query the keyboard, and also because a process could do writes to the appropriate serial driver — thus going around this ioctl( request) we do not provide an equivalent ioctl( to query its state.

KIOCSLED
    The argument is a pointer to an char. On the Sun-4 keyboard, the LEDs are set to the value specified in that char. The values for the four LEDs are:
        LED_CAPS_LOCK
            “Caps Lock” light.
        LED_COMPOSE
            “Compose” light.
        LED_SCROLL_LOCK
            “Scroll Lock” light.
        LED_NUM_LOCK
            “Num Lock” light.

KIOCGLED
    The argument is a pointer to a char. The current state of the LEDs is stored in the char pointed to by the argument.

KIOCSCOMPAT
    The argument is a pointer to an int. “Compatibility mode” is turned on if the int has a value of 1, and is turned off if the int has a value of 0.

KIOCGCOMPAT
    The argument is a pointer to an int. The current state of “compatibility mode” is stored in the int pointed to by the argument.

KIOCGDIRECT
    These ioctl() requests are supported for compatibility with the system keyboard device /dev/kbd. KIOCSDIRECT has no effect, and KIOCGDIRECT always returns 1.

SEE ALSO
click(1), loadkeys(1), kbd(4S), termio(4), win(4S), keytables(5)

(describes firm_event format)