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:
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:
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 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.
Printable version
