HPUX ps2[7]
ps2(7) Series 700 Only ps2(7)
NAME
ps2, ps2kbd, ps2mouse - PS/2 Keyboard/Mouse device driver
SYNOPSIS
#include <sys/ps2io.h>
DESCRIPTION
The ps2 driver allows the use of IBM Personal System/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 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 the termio(7) manpage.
The ps2 driver provides a low-level programming interface to PS/2
keyboards and mice. To access these devices in a hardware independent
- 1 - Formatted: August 11, 1996
ps2(7) Series 700 Only ps2(7)
way, use the X Windows programming environment.
System Calls
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 non-existant 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 or O_NONBLOCK can be set to enable
non-blocking 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)).
- 2 - Formatted: August 11, 1996
ps2(7) Series 700 Only 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 mouse-specific
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 parameter.
The request codes that follow are defined in <sys/ps2io.h>.
ioctl requests common to both the keyboard and the mouse:
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.
- 3 - Formatted: August 11, 1996
ps2(7) Series 700 Only 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 will return 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
bytes to indicate a successful reset ( arg[0]=0xAA
- 4 - Formatted: August 11, 1996
ps2(7) Series 700 Only ps2(7)
and arg[1]=0x00 ). The keyboard returns only one
byte ( arg[0]=0xAA ).
Keyboard specific ioctl requests:
PS2_SCANCODE Set 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 delay are set via
the PS2_RATEDELAY ioctl request.
- 5 - Formatted: August 11, 1996
ps2(7) Series 700 Only ps2(7)
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
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.
- 6 - Formatted: August 11, 1996
ps2(7) Series 700 Only ps2(7)
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:
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.
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.
- 7 - Formatted: August 11, 1996
ps2(7) Series 700 Only ps2(7)
PS2_REPORT 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 bitmap 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.
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.
- 8 - Formatted: August 11, 1996
ps2(7) Series 700 Only ps2(7)
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 bitmap 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:
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
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 non-
linear 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
- 9 - Formatted: August 11, 1996
ps2(7) Series 700 Only ps2(7)
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
[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(2), read(2), or ioctl(2)
system call.
[EINVAL] An invalid parameter was detected by ioctl(2).
[ENXIO] No device is present at the specified address.
[EIO] A hardware or software error occurred while executing
an ioctl(2) system call.
[ENODEV] write(2) is not implemented for PS/2 devices.
EXAMPLES
Assume that fildes is a valid file descriptor for a ps2 port connected
to a keyboard. The first example will blink the keyboard indicators,
set scancode set 3 operation, and then loop 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 on0);
sleep( 1);
kbdbuf[0] = NONE_LED; /* all off */
if( ioctl( fildes, PS2_INDICATORS, &kbdbuf) < 0){
- 10 - Formatted: August 11, 1996
ps2(7) Series 700 Only ps2(7)
perror("ioctl PS2_INDICATORS failed");
exit( 1);
}
printf("Indicators off0);
/* 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 %d0,
(unsigned int) kbdbuf[0]);
/* now, loop forever while printing keycodes */
while( 1){
read( fildes, &inchar, 1);
printf("Keycode: %x0, (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.
#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 failed0);
exit(1);
}
printf("Mouse disabled0);
/* Put mouse in stream mode */
if( ioctl( fildes, PS2_STREAMMODE) < 0){
perror("ioctl PS2_STREAMMODE failed0);
exit(1);
}
printf("Mouse in stream mode0);
- 11 - Formatted: August 11, 1996
ps2(7) Series 700 Only ps2(7)
/* set samplerate */
ioctl_buf[0] = SAMPLE_80;
if( ioctl( fildes, PS2_SAMPLERATE, ioctl_buf) < 0){
perror("ioctl PS2_SAMPLERATE failed0);
exit(1);
}
printf("Mouse sample rate set to SAMPLE_800);
/* Enable mouse */
if( ioctl( fildes, PS2_ENABLE) < 0){
perror("ioctl PS2_ENABLE failed0);
exit(1);
}
printf("Mouse enabled.0);
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 %d0, buf[0], buf[1], buf[2]);
}
AUTHOR
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
/usr/include/sys/ps2io.h
/dev/ps2_[0-15]
/dev/ps2_*.[0-15]
/dev/ps2mouse
/dev/ps2kbd
SEE ALSO
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
- 12 - Formatted: August 11, 1996