All Rights Reserved Copyright (c) 2004, Sun Microsystems, Inc. All Rights Reserved
The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License.
You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License.
When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
#include <sys/types.h>
#include <sys/stream.h>
#include <sys/stropts.h>
#include <sys/vuid_event.h>
#include <sys/kbio.h>
#include <sys/kbd.h>
ioctl(fd, I_PUSH, "kb");
The kb STREAMS module processes byte streams generated by a keyboard attached to a CPU serial port. Definitions for altering keyboard translation and reading events from the keyboard are contained in <sys/kbio.h> and <sys/kbd.h>.
The kb STREAMS module utilizes a set of keyboard tables to recognize which keys have been typed. Each translation table is an array of 128 16-bit words (unsigned shorts). If a table entry is less than 0x100, the entry is treated as an ISO 8859/1 character. Higher values indicate special characters that invoke more complicated actions.
The keyboard can be in one of the following translation modes: TR_NONE
TR_ASCIIISO 8859/1 codes are reported.
firm_events are reported.
firm_events containing unencoded keystation codes are reported for all input events within the window system.
All instances of the kb module share seven translation tables that convert raw keystation codes to event values. The tables are: Unshifted
Used when a key is depressed and no shifts are in effect.
Used when a key is depressed and a Shift key is held down.
Used when a key is depressed and Caps Lock is in effect.
Used when a key is depressed and the Alt Graph key is held down.
Used when a key is depressed and Num Lock is in effect.
Used when a key is depressed and the Control key is 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).
Used when a key is released.
Each key on the keyboard has a key station code that represents a number from 0 to 127. The number is used as an index into the translation table that is currently in effect. If the corresponding entry in the translation table is a value from 0 to 255, the value is treated as an ISO 8859/1 character, and the character is the result of the translation.
If the entry in the translation table is higher than 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 below. When added to the constant, the value of the low-order bits distinguish 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.
"Shift Lock" key.
Left-hand Shift key.
Right-hand Shift key.
Left-hand (or only) Control key.
Right-hand Control key.
Alt Graph key.
Alternate or Alt key.
Num Lock key.
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.
The System key was pressed. This is a place holder to indicate which key is the system-abort key.
Performs various functions depending on the value of the low 4 bits: NOP 0x300
Does nothing.
Exists, but is undefined.
There is no key in this position on the keyboard, and the position-code should not be used.
Keyboard reset.
The keyboard driver detected an internal error.
The keyboard is idle (no keys down).
The COMPOSE key; the next two keys should comprise a two-character COMPOSE key sequence.
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.
Reserved for non-parameterized functions.
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
circumflex
tilde
cedilla
acute accent
grave accent
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
0x00
0x01
0x02
0x03
0x04
There are 64 keys reserved for function keys. The actual positions are usually on the left/right/top/bottom of the keyboard. The next-to-lowest 4 bits indicate the group of function keys: LEFTFUNC
0x600
0x610
0x610
0x630
(LEFTFUNC+(n)-1)
(RIGHTFUNC+(n)-1)
(TOPFUNC+(n)-1)
(BOTTOMFUNC+(n)-1)
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: PADEQUAL 0x700
"=" key
"/" key
"*" key
"-" key
"," key
"7" key
"8" key
"9" key
"+" key
"4" key
"5" key
"6" key
"1" key
"2" key
"3" key
"0" key
"." key
"Enter" key
When a function key is pressed in TR_ASCII mode, 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.
When started, the kb STREAMS module is in the compatibility 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 eighth bit set) , are presented as events with codes in the ISO_FIRST range (as defined in <<sys/vuid_event.h>>). For backwards compatibility with older versions of the keyboard driver, the event code is ISO_FIRST plus the character value. When compatibility mode is turned off, ISO 8859/1 characters are presented as events with codes equal to the character code.
The following ioctl() requests set and retrieve the current translation mode of a keyboard: KIOCTRANS
Pointer to an int. The translation mode is set to the value in the int pointed to by the argument.
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 */
uchar_t kio_station; /* Physical keyboard key station (0-127) */
ushort_t kio_entry; /* Translation table station's entry */
char kio_string[10]; /* Value for STRING entries-null terminated */
};
KIOCSKEY
Pointer to a kiockeymap structure. The translation table entry referred to by the values in that structure is changed. The kio_tablemask request specifies which of the following translation tables contains the entry to be modified: UPMASK 0x0080
"Key Up" translation table.
"Num Lock" translation table.
"Controlled" translation table.
"Alt Graph" translation table.
"Shifted" translation table.
"Caps Lock" translation table.
"Unshifted" translation table.
The kio_station request 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.
Special values of kio_tablemask can affect the two step "break to the PROM monitor" sequence. The usual sequence is L1-a or Stop-. 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. An attempt to change the "break to the PROM monitor" sequence without having superuser permission results in an EPERM error. 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.
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_SUN3
Sun Type 3 keyboard
Sun Type 4 or 5 keyboard, or non-USB Sun Type 6 keyboard
USB standard HID keyboard, including Sun Type 6 USB keyboards
ASCII terminal masquerading as keyboard
Type 101 PC keyboard
Stored in the int pointed to by the argument if the keyboard type is unknown. In case of error, -1 is stored in the int pointed to by the argument.
The argument is a pointer to an int. On a Sun Type 4 keyboard, the layout code specified by the keyboard's DIP switches is stored in the int pointed to by the argument.
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 Type 3 and Sun Type 4 keyboards: KBD_CMD_RESET
Reset keyboard as if power-up.
Turn on the bell.
Turn off the bell.
Turn on the click annunciator.
Turn off the click annunciator.
Set keyboard LEDs.
Request that keyboard indicate layout.
Inappropriate commands for particular keyboard types are ignored. Since there is no reliable way to get the state of the bell or click (because the keyboard cannot be queried and a process could do writes to the appropriate serial driver \(em circumventing this ioctl() request) an equivalent ioctl() to query its state is not provided. KIOCSLED
The argument is a pointer to an char. On the Sun Type 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.
"Compose" light.
"Scroll Lock" light.
"Num Lock" light.
"Kana" light.
Pointer to a char. The current state of the LEDs is stored in the char pointed to by the argument.
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.
Pointer to an int. The current state of "compatibility mode" is stored in the int pointed to by the argument.
The following ioctl() request allows the default effect of the keyboard abort sequence to be changed. KIOCSKABORTEN
Pointer to an int. The keyboard abort sequence effect (typically L1-A or Stop-A on the keyboard on SPARC systems, F1-A on x86 systems, and BREAK on the serial console device) is enabled if the int has a value of KIOCABORTENABLE(1). If the value is KIOCABORTDISABLE(0) , the keyboard abort sequence effect is disabled. If the value is KIOCABORTALTERNATE(2), the Alternate Break sequence is in effect and is defined by the serial console drivers zs(7D)se(7D) and asy(7D). Any other value of the parameter for this ioctl() is treated as enable. The Alternate Break sequence is applicable to the serial console devices only. Due to a risk of incorrect sequence interpretation, SLIP and certain other binary protocols should not be run over the serial console port when Alternate Break sequence is in effect. Although PPP is a binary protocol, it is able to avoid these sequences using the ACCM feature in RFC 1662. For Solaris PPP 4.0, you do this by adding the following line to the /etc/ppp/options file (or other configuration files used for the connection; see pppd(1M) for details):
asyncmap 0x00002000SLIP has no comparable capability, and must not be used if the Alternate Break sequence is in use. This ioctl() will be active and retain state even if there is no physical keyboard in the system. The default effect (enable) causes the operating system to suspend and enter the kernel debugger (if present) or the system prom (on most systems with OpenBoot proms). The default effect is enabled on most systems, but may be different on server systems with key switches in the 'secure' position. On these systems, the effect is always disabled when the key switch is in the 'secure' position. This ioctl()returns EPERM if the caller is not the superuser.
These ioctl() requests are supported for compatibility with the system keyboard device /dev/kbd. KIOCSDIRECT
Has no effect.
Always returns 1.
The following ioctl() requests are used to set and get the keyboard autorepeat delay and rate. KIOCSRPTDELAY
This argument is a pointer to an int, which is the kb autorepeat delay, unit in millisecond.
This argument is a pointer to an int. The current auto repeat delay setting is stored in the integer pointed by the argument, unit in millisecond.
This argument is a pointer to an int, which is the kb autorepeat rate, unit in millisecond.
This argument is a pointer to an int. The current auto repeat rate setting is stored in the integer pointed by the argument, unit in millisecond.
See attributes(5) for descriptions of the following attributes:
| ATTRIBUTE TYPE ATTRIBUTE VALUE |
| Interface Stability Stable |
kbd(1), loadkeys(1), kadb(1M), pppd(1M), keytables(4), attributes(5), zs(7D), se(7D), asy(7D), virtualkm(7D), termio(7I), usbkbm(7M)
Many keyboards released after Sun Type 4 keyboard also report themselves as Sun Type 4 keyboards.