KEYBOARD(4)

NAME
keyboard - keyboard interface

DESCRIPTION

The keyboard adapter returns scan codes that the keyboard driver translates into ASCII characters. This translation is done through table lookup; pf(i) allows users to change the translation tables so as to redefine the ASCII characters generated by particular keystrokes.

There are two sets of translation tables: a standard set not normally changed (see keyboard_codes(5)),, and a working set the user may freely change as desired (see pf(i)).

In addition to generating ASCII characters, the keyboard interface can invoke special functions (swapping of key definitions, etc.; see below). Most of these special functions are bound to the three keys labeled <Print-Screen/SysRq>, <Scroll-Lock>, and <Pause/Break>. The normal use of these keys, together with the four shift or meta-keys, give a total of 15 possible meta functions that can be invoked:
Key		Normal        Shift		Ctrl	    	  Alt		 Action
Print-Screen/	FN_PRINT    FN_IGNORE	FN_LOG          FN_IGNORE	  FN_SET
   SysRq
Scroll-Lock	FN_SCROLL  FN_SWAP	FN_SWRESET    FN_SWITCH	  FN_CLICK
Pause/Break	FN_DEBUG   FN_DEBUG	FN_IGNORE      FN_KILL	  FN_RESET

Keyboard META Functions

FN_ACTION
    (Usually bound to the <Action> key.) Puts the keyboard into action mode. Action mode selects the ``action'' set of key values.

FN_ALT
    (Usually bound to <Alt>.) Puts the keyboard into alt mode. Alt mode selects the ``alt'' set of key values.

FN_BREAK
    Not usually specified by the user; it is invoked when a ``make-break'' key is released by the user and should only be bound to that single hardware code.

FN_CLICK
    (Usually bound to <Action><Scroll/Lock>.) Causes a different ``key click'' mode to be selected. There are four such modes: no click, hardware click, software click, and both hardware and software click.

FN_DEBUG
    (Usually bound to the <Pause/Break> key.) Invokes the debugger (see debug(8)). Once in console-debugger mode, a ``go'' command can be used to restart the system. On systems without the debugger, the screen still displays DEBUG in the status line; but the debugger will not be entered.
    A system-attention sequence (<Ctrl>-<Alt>-<SysRq>) can also be used to enter the debugger; use this only if the FN-DEBUG function does not work.

FN_IGNORE
    (Usually bound to keys that neither generate characters nor activate meta-functions.) Causes that key to be ignored.

FN_KILL
    (Usually bound to <Alt><Pause/Break>.) Causes a HANGUP signal (see signal(2)) to be sent to the processes currently in the console terminal process group. It also marks the console terminal as closed. This is sufficient to stop most programs that do not catch or ignore the HANGUP signal. This is analogous to hanging up a dialup line to drop the connection. If the function is invoked again while the console terminal is marked as closed, it generates a KILL signal to all processes in the current process group.

FN_NUM_LOCK
    (Usually bound to <Num-Lock>.) Puts the keyboard into num-lock mode.

FN_PRINT
    (Usually bound to <Print-Screen>.) Causes the current console screen image to be sent to the line printer.

FN_LOG
    (Usually bound to <Ctrl>-<Print-Screen>.) Turns hardcopy logging of the screen on and off. Kernel/user hardcopy is independent of debugger hardcopy.

FN_RESET
    (Usually bound to <Action><Pause-Break>.) Causes the keyboard definitions to be reset to their standard values. This is also automatically done when the console terminal is closed, in order to ensure that the next user to log in receives a normal keyboard.

FN_SWAP
    (Usually bound to <Shift><Scroll-Lock>.) Exchanges the bindings of the next two keys typed. This is particularly useful for swapping the definitions of the <Caps-Lock> key and the <Ctrl> key.

FN_SHIFT
    (Usually bound to the keys labeled <Shift> on either side of the keyboard.) Puts the keyboard into shifted mode.

FN_SWITCH
    (Usually bound to <Alt><Scroll-Lock>.) Causes the console output to be switched to the next available display device (see console(4)).

FN_SWRESET
    (Usually bound to <Ctrl><Scroll-Lock>.) Causes the console output to be switched to the next available display device, and the display to be re-initialized. If necessary, this involves loading microcode; in all cases, the display is cleared and the cursor moved to the top left corner.

FN_SCROLL
    (Usually bound to <Scroll-Lock>.) Causes normal output to the console display to be locked out by generating the current XOFF character (see tty(4)). Output stops, and the Scroll-Lock light on the keyboard comes on. When the Scroll-Lock light is on, pressing the <Scroll Lock> key again generates the current XON character, which causes output to resume and the Scroll Lock to go off. Note that if the console is in RAW mode, the <Scroll Lock> key only generates XOFF characters.

FN_SET
    (Usually bound to <Action><Print-Screen>.) Sets a new value into the keyboard translation table that determines the ASCII characters generated for particular scan codes (see below).

FN_BEEP
    (Not usually bound to a key.) Sounds the bell (a beep) when invoked.

FN_CAPS_LOCK
    (Usually bound to <Caps-Lock> or to <Ctrl>.) Causes the keyboard to go into Caps-Lock mode. The keyboard leaves Caps-Lock mode when the FN_CAPS_LOCK function is next generated or when the next FN_SHIFT is generated. This behavior is similar to that of many typewriters. Caps-Lock mode selects the ``Shift'' set of key values.

FN_CONTROL
    (Usually bound to <Ctrl> or to <Caps-Lock>fR.) Causes the keyboard to go into Control mode. Control mode selects the ``control'' set of key values.

NOTES

When the keyboard has more than one mode in effect, the key value selected is that of the highest priority mode. The mode priority ordering is: normal, shift, control, alt, and action (normal being low and action being high).

The keyboard adapter also supports the speaker, which is activated when the ASCII character bel (^G) is sent to the display.

It is possible to change the association of keyboard functions and the ASCII strings generated by the keyboard driver in two ways: from the keyboard and from within a program. It is convenient to have a set of definitions (or bindings) done every time a user logs on the system; this is best done via the pf(i) utility invoked from one's .login file during login. If this utility is unavailable, or the user wishes to redefine a key temporarily, it may be done from the keyboard. The keyboard procedure is:

1.  Invoke the FN_SET function (normally bound to <Action><Print-Screen>). This causes KEY? to be displayed in the status line.

2.  Enter the keystroke for the key to be set (this includes using the appropriate shift (or meta) key such as <Shift>, <Alt>, <Ctrl>, or <Action>). The status line will show DEF when the keystroke has been accepted.

3.  Enter the definition. It echoes on the status line as it is accepted. Note that control keys are displayed as ^, followed by the appropriate letter.

4.  Enter the keystroke for the key being set (as for step 2). This completes the definition.

If during definition you decide to cancel the definition being entered, re-invoke the FN_SET function.

A few ioctl(2) calls apply to the keyboard device, and have the form:
    #include <machinecons/keyboard.h>
    struct kbdarg {
    	char kbd_scan;			/* scan code */
    	char kbd_index;			/* the position to change */
    	char kbd_length;		/* the length following */
    	char kbd_text[KBD_STRING_LENGTH];	/* the text */
    	char kbd_end;			/* a nullend flag just in case */
    };
    ioctl(files, code, arg)
    int *arg;
    or:
    struct kbdarg *arg;
    #define KBD_INDEX_NORMAL	0	/* normal position */
    #define KBD_INDEX_SHIFT	1	/* shifted */
    #define KBD_INDEX_CONTROL	2	/* control'ed */
    #define KBD_INDEX_ALT		3	/* alt'ed */
    #define KBD_INDEX_ACTION	4	/* action'ed */
    #define CLICK_OFF	0x00
    #define CLICK_HARD	0x01		/* hardware click */
    #define CLICK_SOFT	0x02		/* software click */
    #define CLICK_BOTH	0x03		/* both */

    #define KBDCGET		_IOWR(k,0,struct kbdarg)  /* get current def'n */
    #define KBDCSET		_IOW(k,1,struct kbdarg)	/* set new definition */
    #define KBDCRESET	_IO(k,2)	/* reset keyboard to standard */
    #define KBDCRST		_IO(k,3)		/* reset (clear) string table */
    #define KBDCSSTD		_IO(k,4)	/* set standard table */
    #define KBDSGET		_IOR(k,5,int)	/* get available string space */
    #define KBDGCLICK	_IOR(k,6,int)	/*  get click */
    #define KBDSCLICK	_IOW(k,7,int)	/*  set click */
The applicable codes are:

KBDCRESET
    Reset the keyboard definitions to the standard definitions. The arg argument is unused.

KBDRST
    Clear the string definitions. This makes space available for a new set of strings to be defined. It causes any key with a definition of more than two bytes to be set to the FN_IGNORE function.

KBDSSTD
    Replace the standard definition with the current definition.

KBDSGET
    Store the number of bytes available for string definitions in the int pointed to by arg.

KBDCGET
    Store the current definition for scancode kbd_scan at index kbd_index in the struct kbdarg pointed to by arg. The keyboard index is one of KBD_INDEX_NORMAL, KBD_INDEX_SHIFT, KBD_INDEX_CONTROL, KBD_INDEX_ALT or KBD_INDEX_ACTION. On the ioctl, the kbd_length contains the maximum length to return; upon return it contains the actual length stored in the keyboard. The definition is returned into kbd_text.

KBDCSET
    Store a new definition for scancode kbd_scan at index kbd_index in the keyboard from struct kbdarg pointed to by arg. The keyboard index is one of KBD_INDEX_NORMAL, KBD_INDEX_SHIFT, KBD_INDEX_CONTROL, KBD_INDEX_ALT or KBD_INDEX_ACTION. kbd_length contains the length of the definition text in kbd_text.

KBDGCLICK
    Store the current keyboard click status into the int pointed to by arg. The value is one of CLICK_OFF, CLICK_HARD, CLICK_SOFT or CLICK_BOTH.

KBDSCLICK
    Set the current keyboard click status from the int pointed to by arg. The value must be one of CLICK_OFF, CLICK_HARD, CLICK_SOFT or CLICK_BOTH.

ERRORS
The following errors can be returned by the driver:

[EINVAL]
    The kbd_scan or kbd_index is invalid.

[E2BIG]
    The string being defined exceeds the available space.

[EPERM]
    The caller is not the super-user (for the KBDSSTD ioctl).

FILES
/dev/console

SEE ALSO
cons(4), ibm5151(4), ibmaed(4), tty(4), reboot(8), debug(i), pf(i)

DIAGNOSTICS
None.

BUGS

The console screen print function works only for the monochrome display and the IBM Academic Information Systems experimental display.

The only user output to the speaker is a beep (bel). It should be possible to control the speaker's frequency and duration parameters.

Caps-Lock mode should be enhanced. Using the shift key when in Caps-Lock mode should generate lower case letters; also, Caps-Lock should not shift non-alphabetic characters.

Num-Lock mode does not do anything; the numeric pad generates numbers regardless of mode.