unixdev.net


Switch to SpeakEasy.net DSL

The Modular Manual Browser

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



 hil(7)								      hil(7)




 NAME
      hil - HP-HIL device driver

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

 DESCRIPTION
      HP-HIL, the Hewlett-Packard Human Interface Link, is the Hewlett-
      Packard standard for interfacing a personal computer, terminal, or
      workstation to its input devices.	 hil supports devices such as
      keyboards, mice, control knobs, ID modules, button boxes, digitizers,
      quadrature devices, bar code readers, and touchscreens.

      On systems with a single link, HP-HIL device file names use the
      following format:

	   /dev/hiln

      where n represents a single digit that specifies the physical HP-HIL
      device address, which ranges from 1 to 7.	 For example, /dev/hil3 is
      used to access the third HP-HIL device.

      On systems with more than one link, HP-HIL device file names use the
      following format:

	   /dev/hil_m.n

      where m represents the instance number, and n represents the physical
      HP-HIL device address.  For example, /dev/hil_0.2 would be used to
      access the second device on the link which has an instance number of
      zero.  Likewise, /dev/hil_12.7 references the seventh device on the
      link with instance number twelve.

      Note that HP-HIL device addresses are determined only by the order in
      which devices are attached to the link.  The first device attached to
      the link becomes device one, the second device attached becomes device
      two, etc.

      HP-HIL devices are classified as "slow" devices.	This means that
      system calls to hil can be interrupted by caught signals (see
      signal(5)).

      hil can only read HP-HIL keyboards in raw keycode mode.  Raw keycode
      mode means that all keyboard input is read unfiltered.  HP-HIL
      keyboards return keycodes that represent key press and key release
      events.

      Use hilkbd(7) to read mapped keycodes from HP-HIL keyboards.  Use the
      Internal Terminal Emulator (ITE) described in termio(7) to read ASCII
      characters from HP-HIL keyboards.




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






 hil(7)								      hil(7)




    System Calls
      open(2) gives exclusive access to the specified HP-HIL device.  Any
      previously queued input from the device is discarded.  If the device
      is a keyboard, it is opened in raw keycode mode.	A side effect of
      opening a keyboard in raw keycode mode is that the ITE (see termio(7))
      and mapped keyboard driver (see hilkbd(7)) lose input from that
      keyboard until it is closed.  Only device implemented auto-repeat
      functionality is available while in raw keycode mode (see HILER1 and
      HILER2).

      The file status flag, O_NDELAY, can be set to enable non-blocking
      reads (see open(2)).

      close(2) returns an HP-HIL keyboard to mapped keycode mode, making its
      input available to the ITE or mapped keyboard driver (see hilkbd(7)).

      read(2) returns data from the specified HP-HIL device, in time-stamped
      packets:

	   unsigned char packet_length;
	   unsigned char time_stamp[4];
	   unsigned char poll_record_header;
	   unsigned char data[ packet_length - 6 ];

      packet_length specifies the number of bytes in the packet including
      itself, and can range from six to twenty bytes.  time_stamp, when re-
      packed into an integer, specifies the time, in tens of milliseconds,
      that the system has been running since the last system boot.  The most
      significant byte of the time stamp is time_stamp[0].
      poll_record_header indicates the type and quantity of information to
      follow, and reports simple device status information.  The number of
      data bytes is device dependent.  Refer to the text listed in SEE ALSO
      for descriptions of the poll_record_header and device-specific data.

      Usually two system calls are required to read each data packet, the
      first system call reads the data packet length; the second system call
      reads the actual data packet.  Some devices always return the same
      amount of data in each packet, in which case the count and the packet
      can both be read in the same system call.

      If the file status flag, O_NDELAY, is set and no data is available,
      read(2) returns 0 instead of blocking.

      write(2) is not supported by hil.

      select(2) can be used to poll for available input from HP-HIL devices.
      select(2) for write or for exception conditions always returns a false
      indication in the file descriptor bit masks.

      ioctl(2) is used to perform special operations on HP-HIL devices.
      ioctl(2) system calls all have the form:



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






 hil(7)								      hil(7)




	   int ioctl(int fildes, int request, char *arg);

      The following request codes are defined in <sys/hilioctl.h>:

      HILID	     Identify and Describe

		     This request returns the Identify and Describe Record
		     in the char variable to which arg points, as supplied
		     by the specified HP-HIL device.  The Identify and
		     Describe Record is used to determine the type and
		     characteristics of each device connected to the link.
		     The Identify and Describe Record can vary in length
		     from 2 to 11 bytes.  The record contains at least:

			  +    A Device ID byte, and

			  +    A Describe Record Header byte.

		     The Device ID byte is used to identify the general
		     class of a device, and its nationality in the case of a
		     keyboard or keypad.  The Describe Record Header byte
		     describes the position report capabilities of the
		     device.  The Describe Record Header byte also indicates
		     if an I/O Descriptor byte follows at the end of the
		     Describe Record.  It also indicates support of the
		     Extended Describe and the Report Security Code
		     requests.	If the device is capable of reporting any
		     coordinates, the Describe Record contains the device
		     resolution immediately after the Describe Record Header
		     byte.  If the device reports absolute coordinates, the
		     maximum count for each axis is specified after the
		     device resolution.	 The I/O Descriptor byte indicates
		     how many buttons the device has.  The I/O Descriptor
		     byte also indicates device proximity detection
		     capabilities and specifies Prompt/Acknowledge
		     functions.	 All HP-HIL devices support the Identify and
		     Describe request.

      HILPST	     Perform Self Test

		     This request causes the addressed device to perform its
		     self test, and returns the one-byte test result in the
		     char variable to which arg points.	 A test result of
		     zero indicates a successful test, non-zero results
		     indicate device-specific failures.	 All HP-HIL devices
		     support the Self Test request.

      HILRR	     Read Register

		     The Read Register request expects an HP-HIL device
		     register address in the char variable to which arg



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






 hil(7)								      hil(7)




		     points, and returns the one-byte contents of that
		     register in *arg.	The Extended Describe Record
		     indicates whether a device supports the Read Register
		     request.

      HILWR	     Write Register

		     The Write Register request expects *arg to contain a
		     record containing one or more packets of data, each
		     containing the HP-HIL device register address and one
		     or more data bytes to be written to that register.
		     There are two types of Register Writes.  Type 1 can be
		     used to write a single byte to each individual device
		     register.	Type 2 can be used to write several bytes to
		     one register.  The Extended Describe Record indicates
		     if a device supports either or both types of register
		     write requests.

      HILRN	     Report Name

		     The Report Name request returns the device description
		     string in the character array to which arg points.	 The
		     string may be up to fifteen characters long.  The
		     Extended Describe Record indicates support of the
		     Report Name request.

      HILRS	     Report Status

		     The Report Status request returns the device-specific
		     status information string in the character array to
		     which arg points.	The string can be up to fifteen
		     bytes long.  The Extended Describe record indicates
		     support of the Report Status request.

      HILED	     Extended Describe

		     The Extended Describe request returns the Extended
		     Describe Record in the character array to which arg
		     points.  The Extended Describe Record may contain up to
		     fifteen bytes of additional device information.  The
		     first byte is the Extended Describe Header, which
		     indicates whether a device supports the Report Status,
		     Report Name, Read Register, or Write Register requests.
		     If the device implements the Read Register request, the
		     maximum readable register is specified.  If the device
		     supports the Write Register request, the Extended
		     Describe Record specifies whether the device implements
		     either or both of the two types of register writes and
		     the maximum writeable register.  If the device supports
		     Type 2 register writes, the maximum write buffer size
		     is specified.  The Extended Describe Record can also



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






 hil(7)								      hil(7)




		     contain the localization (language) code for a device.
		     Support of the Extended Describe request is indicated
		     in the Describe Record Header byte.

      HILSC	     Report Security Code

		     The Report Security Code request returns the Security
		     Code Record in the character array to which arg points.
		     The Security Code Record can be between one and fifteen
		     bytes of data that uniquely identifies that particular
		     device.  Applications can use this request to implement
		     a hardware "key" that restricts each copy of the
		     application to a single machine or user.  An
		     application can read the Security Code Record from an
		     HP-HIL ID Module and then verify that the application
		     is running on a specific machine or that the
		     application is being used by a legitimate user.
		     Devices indicate support of the Report Security Code
		     request in the Describe Record Header.

      HILER1	     Enable Auto Repeat Rate = 1/30 Second

		     This request is used to enable the "repeating keys"
		     feature implemented by the firmware of some HP-HIL
		     keyboard and keypad devices.  It also sets the cursor
		     key repeat rate to 1/30 sec.  This request does not use
		     arg.

      HILER2	     Enable Auto Repeat Rate = 1/60 Second

		     This request is used to enable the "repeating keys"
		     feature implemented in the firmware of some HP-HIL
		     keyboard and keypad devices.  It also sets the cursor
		     key repeat rate to 1/60 sec.  This request does not use
		     arg.

      HILDKR	     Disable Keyswitch Auto Repeat

		     This request turns off the "repeating keys" feature
		     implemented in the firmware of some HP-HIL keyboard and
		     keypad devices.  This request does not use arg.

      HILP1..HILP7   Prompt 1 through Prompt 7

		     These seven requests are supported by some HP-HIL
		     devices to give an audio or visual response to the
		     user, perhaps indicating that the system is ready for
		     some type of input.  A device specifies acceptance of
		     these requests in the I/O Descriptor Byte in the
		     Describe Record.  These requests do not use arg.




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






 hil(7)								      hil(7)




      HILP	     Prompt (General Purpose)

		     This request is intended as a general purpose stimulus
		     to the user.  Devices accepting this request indicate
		     so in the I/O Descriptor Byte in the Describe Record.
		     This request does not use arg.

      HILA1..HILA7   Acknowledge 1 through Acknowledge 7

		     These seven requests are intended to provide an audio
		     or visual response to the user, generally to
		     acknowledge a user's input.  The I/O Descriptor Byte in
		     the Describe Record indicates whether an HP-HIL device
		     implements this request.  These requests do not use
		     arg.

      HILA	     Acknowledge (General Purpose)

		     The Acknowledge request is intended to provide an audio
		     or visual response to the user.  Devices accepting this
		     request indicate so in the I/O Descriptor Byte in the
		     Describe Record.  This request does not use arg.

 ERRORS
      [EBUSY]	     The specified HP-HIL 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; see
		     WARNINGS, below.

      [EIO]	     A hardware or software error occurred while executing
		     an ioctl(2) system call.

      [ENODEV]	     write(2) is not implemented for HP-HIL devices.

 WARNINGS
      An ENXIO error is returned by open(2) and ioctl(2) if any attempt is
      made to access a device while hil is reconfiguring the link during
      power-failure recovery.

      hil cannot detect whether or not a device executed an ioctl(2)
      request.





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






 hil(7)								      hil(7)




      HP-HIL devices have no status bit available to indicate whether they
      support the HILER1, HILER2, or HILDKR requests.

 AUTHOR
      hil was developed by the Hewlett-Packard Company.

 FILES
      /dev/hil[1-7]
      /dev/hil_*.[1-7]

 SEE ALSO
      close(2), errno(2), fcntl(2), ioctl(2), open(2), read(2), select(2),
      signal(5), hilkbd(7), termio(7).

      For detailed information about HP-HIL hardware and software in
      general, see the HP-HIL Technical Reference Manual.






































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