KBDEMUL(4) —

NAME

kbdemul − default keyboard emulator

DESCRIPTION

The keyboard adapter returns scan codes which the keyboard emulator translates into ASCII characters. This translation is done through table lookup; pf(1) 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 programmable set the user may freely change as desired (see pf).

In addition to generating ASCII characters, the keyboard emulator 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:

KeyNormalShiftCaps LockCtrlAltAction
Print-Screen/FN_PRINTFN_IGNOREFN_PRINTFN_LOGFN_IGNORE FN_SET
SysRq
Scroll-LockFN_SCROLLFN_SWAPFN_SCROLLFN_SWRESETFN_SWITCH FN_CLICK
Pause/BreakFN_DEBUGFN_DEBUGFN_DEBUGFN_IGNOREFN_KILL FN_RESET

Keyboard META Functions

FN_ACTION
(Usually bound to the <Action> key for the IBM RT/PC, and to the Right Ctrl key for the IBM 6152 Academic System.) 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. Not supported for the IBM 6152 Academic System.

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 continue system operation. On systems without the debugger, the screen still displays DEBUG in the status line; but the debugger will not be entered.

The system-attention sequence (<Ctrl>-<Alt>-<Scroll Lock>) can also be used to enter the debugger; use this only if the FN-DEBUG function does not work. On systems without the debugger, the system-attention sequence forces the system to core dump and reboot.

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, and activates the standard translation table. The programmable translation table is re-activated when the FN_NUM_LOCK function is next generated.

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 logging is independent of debugger logging.

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 input focus to be switched to the next available display device (see cons(4)).

FN_SWRESET
(Usually bound to <Ctrl><Scroll-Lock>.) Causes the input focus 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>.) Puts the keyboard into Caps-Lock mode. The keyboard leaves Caps-Lock mode when the FN_CAPS_LOCK function is next generated. Caps-Lock mode selects the “Caps-Lock” set of key values.

FN_CONTROL
(Usually bound to <Ctrl> or to <Caps-Lock>.) 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/caps-lock, control, alt, and action (normal being low and action being high).

Using the shift key when the keyboard is in caps-lock mode generates lower case alphabetic characters, and shifts non-alphabetic characters.

When the keyboard is in num-lock mode, i.e the standard translation table is being used, any keyboard definition will only be added to the programmable translation table; it does not change the standard set.

The keyboard adapter also supports the speaker, which is activated when the ASCII character bel (^G) is sent to the display. For additional speaker control information, see speaker(4).

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 with the pf(1) 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, /dev/console, and have the form:

#include <machinecons/kbd_emul.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_NORMAL0/∗ normal position ∗/
#define KBD_INDEX_SHIFT1/∗ shifted ∗/
#define KBD_INDEX_CAPS2/∗ caps-lock’ed ∗/
#define KBD_INDEX_CONTROL3/∗ control’ed ∗/
#define KBD_INDEX_ALT4/∗ alt’ed ∗/
#define KBD_INDEX_ACTION5/∗ action’ed ∗/
/∗ The following four lines are not supported for the IBM 6152 Academic System ∗/
#define CLICK_OFF0x00
#define CLICK_HARD0x01/∗ hardware click ∗/
#define CLICK_SOFT0x02/∗ software click ∗/
#define CLICK_BOTH0x03/∗ 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 ∗/
#define KBDSSECURE_IOW(k,8,int)/∗ set secure bit and ∗/
/∗ disable keyboard ∗/

The applicable codes are:

KBDCRESETReset the keyboard definitions to the standard definitions. The arg argument is unused.

KBDRSTClear 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.

KBDSSTDReplace the standard definition with the current definition.

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

KBDCGETStore 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_CAPS, 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.

KBDCSETStore 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_CAPS, KBD_INDEX_CONTROL, KBD_INDEX_ALT or KBD_INDEX_ACTION. kbd_length contains the length of the definition text in kbd_text.

KBDGCLICKStore 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. Not supported for the IBM 6152 Academic System.

KBDSCLICKSet 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. Not supported for the IBM 6152 Academic System.

KBDSSECURESet arg as the primary boot device to use on reboot, and disable the keyboard. Definitions for arg may be found in the include file <machine/nvram.h> and have the legal values of NVR_FD0, NVR_FD1, NVR_FD2, NVR_FD3, NVR_HD0, NVR_HD1, NVR_HD2, and NVR_HD3. If arg is zero and the console is secured, KBDSSECURE re-enables the keyboard and resets the boot order to its default. The effects of this ioctl may also be removed by locking and then unlocking the keylock on the front panel. Not supported for the IBM 6152 Academic System.

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

For the IBM RT PC:
/dev/console
/dev/ttyaed
/dev/ttyap16
/dev/ttyap8c
/dev/ttyapa8
/dev/ttyega
/dev/ttymono
/dev/ttympel
/dev/aed
/dev/apa16
/dev/apa8c
/dev/apa8
/dev/ega
/dev/mono
/dev/mpel

For the IBM 6152 Academic System:
/dev/tty8514
/dev/ttyvga
/dev/vga
/dev/ibm8514

DIAGNOSTICS

None.

PRPQs 5799-WZQ/5799-PFF: IBM/4.3 — Dec 1987

Museum

Related Articles