hil(7)hil(7)NAMEhil - HP-HIL device driver
SYNOPSISDESCRIPTION
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. 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 follow‐
ing format:
where n represents a single digit that specifies the physical HP-HIL
device address, which ranges from 1 to 7. For example, 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:
where m represents the instance number, and n represents the physical
HP-HIL device address. For example, would be used to access the second
device on the link which has an instance number of zero. Likewise,
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 sys‐
tem calls to can be interrupted by caught signals (see signal(5)).
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 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:
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 instead of blocking.
write(2) is not supported by
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:
The following request codes are defined in
HILID Identify and Describe
This request returns the Identify and Describe Record in
the 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 key‐
board 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 imme‐
diately 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 sup‐
port 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
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 reg‐
ister address in the 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 con‐
taining 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 regis‐
ter. 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 indi‐
cates 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 con‐
tain 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 appli‐
cation 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" fea‐
ture 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" fea‐
ture 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 WARN‐
INGS, 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 is reconfiguring the link during power-
failure recovery.
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
was developed by the Hewlett-Packard Company.
FILESSEE ALSOclose(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
hil(7)