ps2(7) ps2(7)
NAME [Toc] [Back]
ps2, ps2kbd, ps2mouse - PS/2 keyboard/mouse device driver and files
SYNOPSIS [Toc] [Back]
#include <sys/ps2io.h>
DESCRIPTION [Toc] [Back]
The ps2 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:
/dev/ps2_n
where n represents the interface port number, ranging from 0 to 15.
For example, the device file /dev/ps2_1 is used to access port one.
On systems with more than one interface, PS/2 device file names use
the following format:
/dev/ps2_m.n
where m represents the interface number, and n represents the port
number. For example, the device file /dev/ps2_1.2 is used to access
port two on interface one.
At boot time, the ps2 driver scans all interface ports from port zero
to the maximum number of ports implemented and attempts to identify
attached PS/2 devices. The /dev/ps2mouse device file accesses the
first mouse detected by ps2. The /dev/ps2kbd device file accesses the
first keyboard detected by ps2.
PS/2 devices are classified as "slow" devices. This means that system
calls to ps2 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 read() system call (see read(2)). In prompt mode, an ioctl()
request polls the mouse, returning a three-byte report packet in a
buffer whose address is passed as an argument to the ioctl() call.
PS/2 keyboards return keycodes that represent key-press and keyrelease
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 ps2 driver provides a low-level programming interface to PS/2
keyboards and mice. To access these devices in a hardware independent
Hewlett-Packard Company - 1 - HP-UX 11i Version 2: August 2003
ps2(7) ps2(7)
way, use the X Window programming environment.
System Calls [Toc] [Back]
The open() system call gives exclusive access to the specified PS/2
device (see open(2)). If a port is open, all open() calls made on
that port will fail with errno set to [EBUSY] (see errno(2)).
If an open is attempted on a nonexistent port, the open() call fails
with errno set to [ENXIO].
If no keyboard is detected at system boot and an open() is attempted
on /dev/ps2kbd, or if no mouse is detected at system boot and an
open() is attempted on /dev/ps2mouse, the open() call fails with errno
set to [ENXIO].
Attempts to open an existing ps2 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
keyboard input.
The file status flags O_NDELAY and O_NONBLOCK can be set to enable
nonblocking reads (see open(2)).
read() 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 read() 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 read() call completes
successfully, having read all available data and returning the number
of bytes actually read.
If both file status flags O_NDELAY and O_NONBLOCK are clear and no
data is available, the read() call blocks until data becomes available
or a signal is received.
If the file status flag O_NDELAY is set and no data is available, the
read() call returns zero instead of blocking.
If the file status flag O_NONBLOCK is set and no data is available,
the read() call returns -1 with errno set to [EAGAIN] (see errno(2)).
Hewlett-Packard Company - 2 - HP-UX 11i Version 2: August 2003
ps2(7) ps2(7)
The write() system call is not supported by ps2.
The select() system call can be used to determine if data is currently
available to be read from a ps2 port. Using select() for write or for
exception conditions always returns a false indication in the file
descriptor bit masks (see select(2)).
The ioctl() system call is used to perform special operations on PS/2
mouse and keyboard devices (see ioctl(2)). The set of ps2 driver
ioctl() requests are divided into three groups: general requests to
both mouse and keyboard, keyboard-specific requests, and mousespecific
requests. Mouse-specific requests used on keyboards, and
keyboard-specific requests used on mice, fail, returning -1 with errno
set to [EINVAL].
Any ioctl() request (except PS2_PORTSTAT) used on a port not connected
to a PS/2 device will time out, returning -1 with errno set to [EIO].
All ioctl() system calls use the following syntax:
int ioctl(int fildes, int request, char *arg);
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 <sys/ps2io.h>.
General ioctl() Requests for Both Keyboard and Mouse [Toc] [Back]
PS2_PORTSTAT 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:
PS2_NONE No device is detected.
PS2_MOUSE Mouse is detected.
PS2_KEYBD Keyboard is detected.
PS2_UNKNOWN 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
/usr/include/sys/ps2io.h:
INTERFACE_HAS_ITE If set, the interface
containing this port is
used by the Internal
Terminal Emulator (ITE)
for keyboard input.
Hewlett-Packard Company - 3 - HP-UX 11i Version 2: August 2003
ps2(7) ps2(7)
PORT_HAS_FIRST_KEYBD If set, this port is
connected to the first
keyboard detected by the
driver.
PORT_HAS_FIRST_MOUSE 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.
PS2_DISABLE 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.
PS2_ENABLE Enable a PS/2 device
Transmissions from the device are enabled. This
request does not use arg.
PS2_IDENT 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 (arg[0]=0xAB and
arg[1]=0x83). The mouse returns one byte
(arg[0]=0x00).
PS2_SETDEFAULT Set the device to its default (power-up) state.
The device is returned to its default internal
state. This request does not use arg.
PS2_RESET 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
Hewlett-Packard Company - 4 - HP-UX 11i Version 2: August 2003
ps2(7) ps2(7)
bytes to indicate a successful reset (arg[0]=0xAA
and arg[1]=0x00). The keyboard returns one byte
(arg[0]=0xAA).
Keyboard-Specific ioctl() Requests [Toc] [Back]
PS2_SCANCODE 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:
SCANCODE_1 Selects scancode set 1.
SCANCODE_2 Selects scancode set 2.
SCANCODE_3 Selects scancode set 3.
GET_SCANCODE Returns the scancode used.
When GET_SCANCODE 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.
PS2_ALL_TMAT 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 PS2_RATEDELAY ioctl()
request.
PS2_ALL_MK 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.
PS2_ALL_MKBRK 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.
PS2_ALL_TMAT_MKBRK 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
Hewlett-Packard Company - 5 - HP-UX 11i Version 2: August 2003
ps2(7) ps2(7)
delay are set via the PS2_RATEDELAY ioctl()
request.
PS2_KEY_TMAT 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 PS2_RATEDELAY ioctl()
request. Because keyboards might be left in a
disabled state after this request, the PS2_ENABLE
request should be performed after PS2_KEY_TMAT.
PS2_KEY_MAKE 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 PS2_ENABLE request should be
performed after PS2_KEY_MAKE.
PS2_KEY_MKBRK 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 PS2_ENABLE request should be
performed after PS2_KEY_MKBRK.
PS2_INDICATORS 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:
NONE_LED No indicators active
CAPS_LED Caps Lock indicator active
Hewlett-Packard Company - 6 - HP-UX 11i Version 2: August 2003
ps2(7) ps2(7)
NUM_LED Num Lock indicator active
SCROLL_LED Scroll Lock indicator active
PS2_RATEDELAY 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:
delay = (1+X) * 250 (+|- 20%)
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:
period = (8+Y) * (2^Z) * 0.00417 (+|- 20%)
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 [Toc] [Back]
PS2_SAMPLERATE 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:
SAMPLE_10 10 reports/second maximum
SAMPLE_20 20 reports/second maximum
SAMPLE_40 40 reports/second maximum
SAMPLE_60 60 reports/second maximum
SAMPLE_80 80 reports/second maximum
SAMPLE_100 100 reports/second maximum
SAMPLE_200 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.
Hewlett-Packard Company - 7 - HP-UX 11i Version 2: August 2003
ps2(7) ps2(7)
PS2_PROMPTMODE 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 PS2_REPORT
ioctl() request. The arg parameter is not used.
PS2_REPORT Obtain a prompt mode mouse report.
This request polls the mouse, obtaining a threebyte
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 PS2_2TO1_SCALING ioctl() request does not
apply to reports obtained with the PS2_REPORT
ioctl() request. PS2_2TO1_SCALING affects only
reports sent in stream mode.
PS2_STREAMMODE 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 PS2_SAMPLERATE
ioctl() 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.
Hewlett-Packard Company - 8 - HP-UX 11i Version 2: August 2003
ps2(7) ps2(7)
The stream-mode reports are obtained via the
read() system call (see read(2)). The format of
the report is identical to reports returned by the
PS2_REPORT ioctl() request described above.
When in stream mode, the PS2_DISABLE request must
be sent prior to any other ioctl() requests.
The arg parameter is not used.
PS2_STATUS Obtain mouse status.
This request polls the mouse, obtaining a threebyte
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
PS2_RESOLUTION 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
RES_1 1 count/mm 1 count/mm
RES_2 2 count/mm 3 count/mm
RES_3 4 count/mm 6 count/mm
RES_4 8 count/mm 12 count/mm
Hewlett-Packard Company - 9 - HP-UX 11i Version 2: August 2003
ps2(7) ps2(7)
PS2_2TO1_SCALING 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 PS2_REPORT ioctl() request.
The arg parameter is not used.
PS2_1TO1_SCALING 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 [Toc] [Back]
If a system call fails, as noted above in the DESCRIPTION section
errno 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 open(), read(), or ioctl()
system call.
[EINVAL] An invalid parameter was detected by ioctl().
[EIO] A hardware or software error occurred while executing
an ioctl() system call.
[ENODEV] write() is not implemented for PS/2 devices.
[ENXIO] No device is present at the specified address.
EXAMPLES [Toc] [Back]
Assume that fildes is a valid file descriptor for a ps2 port connected
to a keyboard. The first example blinks the keyboard indicators,
Hewlett-Packard Company - 10 - HP-UX 11i Version 2: August 2003
ps2(7) ps2(7)
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 ps2 port connected to a mouse.
Hewlett-Packard Company - 11 - HP-UX 11i Version 2: August 2003
ps2(7) ps2(7)
#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]);
}
Hewlett-Packard Company - 12 - HP-UX 11i Version 2: August 2003
ps2(7) ps2(7)
AUTHOR [Toc] [Back]
ps2 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 [Toc] [Back]
/usr/include/sys/ps2io.h
/dev/ps2_[0-15]
/dev/ps2_*.[0-15]
/dev/ps2mouse
/dev/ps2kbd
SEE ALSO [Toc] [Back]
close(2), errno(2), fcntl(2), ioctl(2), open(2), read(2), select(2),
signal(5), termio(7).
SoftPC User's Guide
SoftPC Installation Guide
Sun System Administrators Guide for the HP700/RX
Hewlett-Packard Company - 13 - HP-UX 11i Version 2: August 2003 [ Back ] |
