ps2(7)

NAME

ps2, ps2kbd, ps2mouse — PS/2 keyboard/mouse device driver and files

SYNOPSIS

#include <sys/ps2io.h>

DESCRIPTION

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 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 ps2 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 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)).

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 argument.

The request codes that follow are defined in <sys/ps2io.h>.

General ioctl() Requests for Both Keyboard and 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.
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 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

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.

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.

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.

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 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.

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 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

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

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

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

Assume that fildes is a valid file descriptor for a ps2 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 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 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

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