Jump to content United States-English
HP.com Home Products and Services Support and Drivers Solutions How to Buy
» Contact HP
More options
HP.com home
HP-UX Reference > H

hil(7)

HP-UX 11i Version 3: February 2007
» 

Technical documentation

» Feedback
Content starts here

 » Table of Contents

 » Index

NAME

hil — HP-HIL device driver

SYNOPSIS

#include <sys/hilioctl.h>

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.

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 nonblocking 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 repacked 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:

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

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 the WARNINGS section.

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.

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

AUTHOR

hil was developed by HP.

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.

Printable version
Privacy statement Using this site means you accept its terms Feedback to webmaster
© 1983-2007 Hewlett-Packard Development Company, L.P.