unixdev.net


Switch to SpeakEasy.net DSL

The Modular Manual Browser

Home Page
Manual: (HP-UX-11.11)
Page:
Section:
Apropos / Subsearch:
optional field



 ps2(7)								      ps2(7)




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

 SYNOPSIS
      #include <&lt&lt&lt;sys/ps2io.h>&gt&gt&gt;

 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



 Hewlett-Packard Company	    - 1 -   HP-UX Release 11i: November 2000






 ps2(7)								      ps2(7)




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





 Hewlett-Packard Company	    - 2 -   HP-UX Release 11i: November 2000






 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 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 <&lt&lt&lt;sys/ps2io.h>&gt&gt&gt;.

    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.



 Hewlett-Packard Company	    - 3 -   HP-UX Release 11i: November 2000






 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 Release 11i: November 2000






 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
      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 Release 11i: November 2000






 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 Release 11i: November 2000






 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
      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 Release 11i: November 2000






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




 Hewlett-Packard Company	    - 8 -   HP-UX Release 11i: November 2000






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





 Hewlett-Packard Company	    - 9 -   HP-UX Release 11i: November 2000






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



 Hewlett-Packard Company	   - 10 -   HP-UX Release 11i: November 2000






 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 Release 11i: November 2000






 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 Release 11i: November 2000






 ps2(7)								      ps2(7)




 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
































 Hewlett-Packard Company	   - 13 -   HP-UX Release 11i: November 2000