ps2(7) Miscellaneous Information Manual ps2(7)
NAME
ps2, ps2kbd, ps2mouse - PS/2 keyboard/mouse device driver and files
SYNOPSIS
DESCRIPTION
The driver allows the use of IBM Personal System/2 (PS/2) compatible keyboards and mouse devices on Hewlett-Packard workstations equipped
with PS/2 interface hardware.
On systems with a single interface, PS/2 device file names use the following format:
where n represents the interface port number, ranging from 0 to 15. For example, the device file is used to access port one.
On systems with more than one interface, PS/2 device file names use the following format:
where m represents the interface number, and n represents the port number. For example, the device file is used to access port two on
interface one.
At boot time, the driver scans all interface ports from port zero to the maximum number of ports implemented and attempts to identify
attached PS/2 devices. The device file accesses the first mouse detected by The device file accesses the first keyboard detected by
PS/2 devices are classified as "slow" devices. This means that system calls to can be interrupted by caught signals (see signal(5)).
The mouse may be placed in one of two output modes. In stream mode, the mouse generates a three-byte report packet in response to mouse
movement and/or button presses. These reports can be obtained with the system call (see read(2)). In prompt mode, an request polls the
mouse, returning a three-byte report packet in a buffer whose address is passed as an argument to the call.
PS/2 keyboards return keycodes that represent key-press and key-release events. Use the Internal Terminal Emulator (ITE) to read ASCII
characters from PS/2 keyboards. The ASCII terminal interface used by the ITE is described in termio(7).
The driver provides a low-level programming interface to PS/2 keyboards and mice. To access these devices in a hardware independent way,
use the X Window programming environment.
System Calls
The system call gives exclusive access to the specified PS/2 device (see open(2)). If a port is open, all calls made on that port will
fail with set to [EBUSY] (see errno(2)).
If an open is attempted on a nonexistent port, the call fails with set to [ENXIO].
If no keyboard is detected at system boot and an is attempted on or if no mouse is detected at system boot and an is attempted on the call
fails with set to [ENXIO].
Attempts to open an existing port with no device connected will succeed.
Upon a successful open, any previously queued input from the device is discarded. Keystrokes are routed to the ITE by default. While a
keyboard is open, ITE does not receive keystrokes from that keyboard; until the keyboard device is closed, it has exclusive access to key-
board input.
The file status flags and can be set to enable nonblocking reads (see open(2)).
returns bytes from a PS/2 device. HP-UX maintains a 512-byte buffer for each port. When this buffer is full, additional bytes received
from the device are discarded.
If enough buffered data is available to satisfy the entire number of bytes requested, the call completes successfully, having read all of
the data requested and returning the number of bytes read.
If there is not enough buffered data available to satisfy the entire request, but at least one byte is available, the call completes suc-
cessfully, having read all available data and returning the number of bytes actually read.
If both file status flags and are clear and no data is available, the call blocks until data becomes available or a signal is received.
If the file status flag is set and no data is available, the call returns zero instead of blocking.
If the file status flag is set and no data is available, the call returns with set to [EAGAIN] (see errno(2)).
The system call is not supported by
The system call can be used to determine if data is currently available to be read from a port. Using for write or for exception condi-
tions always returns a false indication in the file descriptor bit masks (see select(2)).
The system call is used to perform special operations on PS/2 mouse and keyboard devices (see ioctl(2)). The set of driver requests are
divided into three groups: general requests to both mouse and keyboard, keyboard-specific requests, and mouse-specific requests. Mouse-
specific requests used on keyboards, and keyboard-specific requests used on mice, fail, returning with set to [EINVAL].
Any request (except used on a port not connected to a PS/2 device will time out, returning with set to [EIO].
All system calls use the following syntax:
All requests that require parameters or return data use a 4-byte unsigned character buffer addressed by the arg argument.
The request codes that follow are defined in
General ioctl() Requests for Both Keyboard and Mouse
Return driver status information.
Two bytes of data are returned in the character buffer addressed by arg.
Byte 0, which indicates the type of connected device, can have four possible values: No device is detected.
Mouse is detected.
Keyboard is detected.
Unknown device is detected.
Byte 1 contains bit flags for various pieces of driver information. The following bit masks for this byte are defined in the file
If set, the interface containing this port is used by the Internal Terminal Emulator (ITE) for keyboard input.
If set, this port is connected to the first keyboard detected by the driver.
If set, this port is connected to the first mouse detected by the driver.
All other bits are currently unused, and are cleared to zero.
Disable a PS/2 device.
Further output from the device is prevented by the device itself. This request does not use arg. Certain devices perform actions
in addition to disabling themselves.
The keyboard resets its internal state to the default state, stops scanning the keys, and waits for further commands.
The mouse stops transmission of reports, and then disables itself.
Enable a PS/2 device
Transmissions from the device are enabled. This request does not use arg.
Identify a PS/2 device.
A value identifying the type of device is returned in the 4-byte buffer addressed by arg. The keyboard returns two bytes and The
mouse returns one byte
Set the device to its default (power-up) state.
The device is returned to its default internal state. This request does not use arg.
Reset a PS/2 device.
The device is told to execute its internal reset routine and execute its power-up test. The result of the power-up test is returned
in the 4-byte buffer addressed by arg. The mouse returns two bytes to indicate a successful reset and The keyboard returns one byte
Keyboard-Specific ioctl() Requests
Select the keyboard scancode set
The scancode set to be used by the keyboard is passed as the first byte of the buffer addressed by arg. The following are valid
values for this byte: Selects scancode set 1.
Selects scancode set 2.
Selects scancode set 3.
Returns the scancode used.
When is specified, the scancode used by the keyboard is returned as the first byte of the character buffer addressed by arg. Some
keyboards do not support all scancode sets.
Set all keys to typematic behavior.
This request can be made when the keyboard is using any scancode set; however, it affects only the operation of scancode set 3. The
arg parameter is not used. The typematic rate and delay are set via the request.
Set all keys to make-only behavior.
This request can be made when the keyboard is using any scancode set; however, it affects only the operation of scancode set 3. The
arg parameter is not used.
Set all keys to make/break behavior.
This request can be made when the keyboard is using any scancode set; however, it affects only the operation of scancode set 3. The
arg parameter is not used.
Set all keys to typematic make/break behavior.
This request can be made when the keyboard is using any scancode set; however, it affects only the operation of scancode set 3. The
arg parameter is not used. The typematic rate and delay are set via the request.
Set typematic behavior for an individual key.
The key code from scancode set 3 for the individual key is passed as the first byte in the character buffer addressed by arg. This
request can be made when the keyboard is using any scancode set; however, it affects only the operation of scancode set 3. The
typematic rate and delay are set via the request. Because keyboards might be left in a disabled state after this request, the
request should be performed after
Set make-only behavior for an individual key.
The key code from scancode set 3 for the individual key is passed as the first byte in the character buffer addressed by arg. This
request can be made when the keyboard is using any scancode set; however, it affects only the operation of scancode set 3. Because
keyboards might be left in a disabled state after this request, the request should be performed after
Set make/break for an individual key.
The key code from scancode set 3 for the individual key is passed as the first byte in the character buffer addressed by arg.
Make/break behavior will be set for this key. This request can be made when the keyboard is using any scancode set; however, it
affects only the operation of scancode set 3. Because keyboards might be left in a disabled state after this request, the request
should be performed after
Set the state of keyboard indicators,
Num Lock, Caps Lock, and Scroll Lock, according to the value passed in the first byte of the character buffer addressed by arg.
The indicators are bit-mapped as follows:
No indicators active
Caps Lock indicator active
Num Lock indicator active
Scroll Lock indicator active
Set the rate and delay for all typematic keys
by specifying the value passed as the first byte in the character buffer addressed by arg.
Bits zero through four give the rate. Bits five and six give the delay. Bit seven (the most significant bit) is unused and should
be set to zero. The delay in milliseconds is determined by the following equation, where X is the numeric value of bits five
through six:
The period (interval from one output key code to the next) in seconds is determined by the following equation, where Y is the
numeric value of bits zero through two, and Z is the numeric value of bits three through four:
The typematic rate (expressed in make codes per second) is one for each period using the above equation. The default typematic rate
is 10.9 characters per second. The default delay is 500 milliseconds.
Mouse-Specific ioctl() Requests
Set the mouse sampling rate used in stream mode by specifying the value passed as the first byte in the character buffer addressed by arg.
Seven specific rates are supported:
10 reports/second maximum
20 reports/second maximum
40 reports/second maximum
60 reports/second maximum
80 reports/second maximum
100 reports/second maximum
200 reports/second maximum
The default rate is 100 reports/second maximum. This request updates the mouse sampling rate only in stream mode. If the mouse is
in prompt mode, this request is ignored.
Put mouse into prompt mode.
In prompt mode, the mouse updates its internal values due to movement or button presses, but issues reports only in response to the
request. The arg parameter is not used.
Obtain a prompt mode mouse report.
This request polls the mouse, obtaining a three-byte report returned in the character buffer addressed by the arg parameter. The
report has the following format:
Byte 1 A bit map of buttons, signs, and overflows
Bit 0 Left button (1=depressed)
Bit 1 Right button (1=depressed)
Bit 2 Center button (1=depressed)
Bit 3 Always 1
Bit 4 X data sign (1=negative)
Bit 5 Y data sign (1=negative)
Bit 6 X data overflow (1=overflow)
Bit 7 Y data overflow (1=overflow)
Byte 2 X-coordinate data byte
Byte 3 Y-coordinate data byte
The X and Y coordinate values are expressed in two's complement. The scaling behavior specified via the request does not apply to
reports obtained with the request. affects only reports sent in stream mode.
Put mouse into stream mode.
When in stream mode, the mouse sends a three-byte report whenever the mouse is moved, or a button is pressed or released since the
last report. The maximum report rate is set with the request. If a button is both pressed and then released within a sample inter-
val, it will be reported as pressed at the end of that interval.
The stream-mode reports are obtained via the system call (see read(2)). The format of the report is identical to reports returned
by the request described above.
When in stream mode, the request must be sent prior to any other requests.
The arg parameter is not used.
Obtain mouse status.
This request polls the mouse, obtaining a three-byte report returned in the character buffer addressed by the arg parameter.
The status report has the following format:
Byte 1 A bit map of buttons and mouse internal state
Bit 0 Right button (1=depressed)
Bit 1 Center button (1=depressed)
Bit 2 Left button (1=depressed)
Bit 3 Always 0
Bit 4 If 0, scaling 1:1; if 1, scaling 2:1
Bit 5 If 0, disabled; if 1, enabled
Bit 6 If 0, stream mode; if 1, prompt mode
Bit 7 Always 0
Byte 2 Current resolution setting
Byte 3 Current sampling rate
Set mouse resolution for X and Y coordinate values
by specifying the value passed as the first byte in the character buffer addressed by arg. Four discrete resolutions are supported:
Resolution 200 DPI 320 DPI
1 count/mm 1 count/mm
2 count/mm 3 count/mm
4 count/mm 6 count/mm
8 count/mm 12 count/mm
Set mouse scaling at 2 to 1.
The X and Y coordinate values returned in stream-mode reports are doubled, except for absolute values less than six, which are con-
verted to new values in a nonlinear fashion. The conversion is detailed in this table:
Mouse Internal Value Converted Value
0 0
+|- 1 +|- 1
+|- 2 +|- 1
+|- 3 +|- 3
+|- 4 +|- 6
+|- 5 +|- 9
All other n 2 * n
This conversion does not apply to reports obtained via the request.
The arg parameter is not used.
Set mouse scaling at 1 to 1.
The X and Y values returned in mouse reports are not scaled. This request does not use the arg parameter.
ERRORS
If a system call fails, as noted above in the DESCRIPTION section is set to one of the following values:
[EBUSY] The specified PS/2 device is already opened.
[EFAULT] A bad address was detected while attempting to use an argument to a system call.
[EINTR] A signal interrupted an or system call.
[EINVAL] An invalid parameter was detected by
[EIO] A hardware or software error occurred while executing an system call.
[ENODEV] is not implemented for PS/2 devices.
[ENXIO] No device is present at the specified address.
EXAMPLES
Assume that fildes is a valid file descriptor for a port connected to a keyboard. The first example blinks the keyboard indicators,
selects scancode set 3, and loops forever while printing keycodes.
#include <sys/ps2io.h>
unsigned char kbdbuf[4]; /* buffer for ioctl operations */
unsigned char inchar; /* keycode read */
/* flash the LED indicators */
kbdbuf[0] = CAPS_LED | SCROLL_LED | NUM_LED; /* all on */
if( ioctl( fildes, PS2_INDICATORS, &kbdbuf) < 0){
perror("ioctl PS2_INDICATORS failed");
exit(1);
}
printf("Indicators on
");
sleep(1);
kbdbuf[0] = NONE_LED; /* all off */
if( ioctl( fildes, PS2_INDICATORS, &kbdbuf) < 0){
perror("ioctl PS2_INDICATORS failed");
exit(1);
}
printf("Indicators off
");
/* use scancode set 3 */
kbdbuf[0] = SCANCODE_3;
if( ioctl( fildes, PS2_SCANCODE, &kbdbuf) < 0){
perror("ioctl PS2_SCANCODE failed");
exit(1);
}
/* identify our scancode set */
kbdbuf[0] = GET_SCANCODE;
if( ioctl( fildes, PS2_SCANCODE, &kbdbuf) < 0){
perror("ioctl PS2_SCANCODE failed");
exit(1);
}
printf("Keyboard reports it is using scancode set %d
",
(unsigned int) kbdbuf[0]);
/* now, loop forever while printing keycodes */
while( 1){
read( fildes, &inchar, 1);
printf("Keycode: %x
", (unsigned int)inchar);
}
The following example puts the mouse in stream mode, sets the report limit to 80 per second, enables the mouse, and then loops forever
printing mouse reports. Assume that fildes is a valid file descriptor for a port connected to a mouse.
#include <sys/ps2io.h>
unsigned char buf[3]; /* mouse report buffer */
unsigned char ioctl_buf[4]; /* mouse ioctl buffer */
/* first, disable the mouse */
if (ioctl( fildes, PS2_DISABLE) < 0){
perror("ioctl PS2_DISABLE failed
");
exit(1);
}
printf("Mouse disabled
");
/* Put mouse in stream mode */
if (ioctl( fildes, PS2_STREAMMODE) < 0){
perror("ioctl PS2_STREAMMODE failed
");
exit(1);
}
printf("Mouse in stream mode
");
/* set samplerate */
ioctl_buf[0] = SAMPLE_80;
if (ioctl( fildes, PS2_SAMPLERATE, ioctl_buf) < 0){
perror("ioctl PS2_SAMPLERATE failed
");
exit(1);
}
printf("Mouse sample rate set to SAMPLE_80
");
/* Enable mouse */
if (ioctl( fildes, PS2_ENABLE) < 0){
perror("ioctl PS2_ENABLE failed
");
exit(1);
}
printf("Mouse enabled.
");
for (;;) {
if (read(fildes, &buf[0], 1) != 1){
perror("Read of report byte 1 failed");
return 1;
}
if (read(fildes, &buf[1], 1) != 1){
perror("Read of report byte 2 failed");
return 1;
}
if (read(fildes, &buf[3], 1) != 1){
perror("Read of report byte 3 failed");
return 1;
}
printf("mouse: 0x%02x, %d %d
", buf[0], buf[1], buf[2]);
}
AUTHOR
was developed by the Hewlett-Packard Company.
PS/2 and Personal System/2 are registered trademarks of International Business Machines, Incorporated, in the U.S. and other countries.
FILES
SEE ALSO
close(2), errno(2), fcntl(2), ioctl(2), open(2), read(2), select(2), signal(5), termio(7).
ps2(7)