ps2(7)ps2(7)NAME
ps2, ps2kbd, ps2mouse - PS/2 keyboard/mouse device driver and files
SYNOPSISDESCRIPTION
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 fol‐
lowing 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 num‐
ber. For example, the device file is used to access port two on inter‐
face 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 charac‐
ters 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 suc‐
ceed.
Upon a successful open, any previously queued input from the device is
discarded. Keystrokes are routed to the ITE by default. While a key‐
board 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 conditions
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-spe‐
cific 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 informa‐
tion. 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 key‐
board 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 charac‐
ter 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 when‐
ever 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 interval, 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 charac‐
ter buffer addressed by arg. Four discrete resolutions are sup‐
ported:
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
converted 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\n");
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\n");
/* 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\n",
(unsigned int) kbdbuf[0]);
/* now, loop forever while printing keycodes */
while( 1){
read( fildes, &inchar, 1);
printf("Keycode: %x\n", (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\n");
exit(1);
}
printf("Mouse disabled\n");
/* Put mouse in stream mode */
if (ioctl( fildes, PS2_STREAMMODE) < 0){
perror("ioctl PS2_STREAMMODE failed\n");
exit(1);
}
printf("Mouse in stream mode\n");
/* set samplerate */
ioctl_buf[0] = SAMPLE_80;
if (ioctl( fildes, PS2_SAMPLERATE, ioctl_buf) < 0){
perror("ioctl PS2_SAMPLERATE failed\n");
exit(1);
}
printf("Mouse sample rate set to SAMPLE_80\n");
/* Enable mouse */
if (ioctl( fildes, PS2_ENABLE) < 0){
perror("ioctl PS2_ENABLE failed\n");
exit(1);
}
printf("Mouse enabled.\n");
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\n", 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.
FILESSEE ALSOclose(2), errno(2), fcntl(2), ioctl(2), open(2), read(2), select(2),
signal(5), termio(7).
ps2(7)