HIL(4) BSD Programmer's Manual (HP300 Architecture) HIL(4)
h
\bhi
\bil
\bl - Human Interface Link device driver
D
\bDE
\bES
\bSC
\bCR
\bRI
\bIP
\bPT
\bTI
\bIO
\bON
\bN
The Human Interface Link (HIL) is the interface used by the Series 300
computers to connect devices such as keyboards, mice, control knobs, and
ID modules to the machine.
Special files _
\b/_
\bd_
\be_
\bv_
\b/_
\bh_
\bi_
\bl_
\b[_
\b1_
\b-_
\b7_
\b] refer to physical HIL devices 1 through 7.
_
\b/_
\bd_
\be_
\bv_
\b/_
\bh_
\bi_
\bl_
\b0 refers to the ``loop'' pseudo-device and is used for the queue
allocation commands described below. In the current implementation,
there can only be one keyboard and it must be the first device (hil1).
The device file that corresponds to a particular HIL device is determined
by the order of the devices on the loop. For instance, if the ID module
is the second physical device on the loop, then _
\b/_
\bd_
\be_
\bv_
\b/_
\bh_
\bi_
\bl_
\b2 is the special
file that should be used for communication with the module.
Communication with an HIL device is begun with an _
\bo_
\bp_
\be_
\bn system call. A
process may open a device already opened by another process unless the
process is operating in HP-UX compatibility mode in which case it re-
quires exclusive use of the device, or another process has the device
open and is using HP-UX style device access (see HILIOCHPUX below).
Input data from a device are obtained in one of two ways. Processes may
use an HP-UX style interface in which the read(2) system call is used to
get fixed-size input packets, or they can use a _
\bs_
\bh_
\ba_
\br_
\be_
\bd_
\b-_
\bq_
\bu_
\be_
\bu_
\be interface.
The shared-queue interface avoids the system call overhead associated
with the HP-UX read interface by sharing a region of memory between the
system and a user process. This region consists of a circular list of
255 event packets, and a header containing the size of the queue, and its
head and tail indices. The system deposits event data at the tail of the
queue, a process extracts it from the head. Extracting an event is done
by copying it from the queue and then updating the head appropriately
(i.e. head = (head + 1) % qsize). It is up to the process to ensure that
packets are removed from the queue quickly enough to prevent the queue
from filling. The system, when it determines that the queue is full,
will ignore future packets from the device. Devices are _
\bm_
\ba_
\bp_
\bp_
\be_
\bd to queues
via an ioctl(2.) More than one device can be mapped to a single queue
and one device can be mapped to several queues. Queues are implicitly
unmapped by a fork(2) and thus, cannot be shared between processes.
Choosing the type of interface is done on a per device basis using an
ioctl, but each device can only have one interface at any given time.
_
\bS_
\be_
\bl_
\be_
\bc_
\bt may be used with either interface to detect when input data are
present. With the read interface, selecting indicates when there is in-
put for a given device. With the shared-queue interface, selecting on
the loop pseudo-device (hil0) indicates when data are present from any
device on any queue while selecting on an individual device indicates
when data are present for that device on any queue.
_
\bC_
\bl_
\bo_
\bs_
\be shuts down the file descriptor associated with the HIL device. The
last close (system-wide) of any device removes that device from all
queues it was mapped to while the last close of the loop pseudo-device
unmaps all devices and deallocates all queues.
Ioctl(2) is used to control the HIL device. The ioctl commands (see
<_
\bh_
\bp_
\bd_
\be_
\bv_
\b/_
\bh_
\bi_
\bl_
\bi_
\bo_
\bc_
\bt_
\bl_
\b._
\bh>) listed below are separated into two groups. The
first are those which provide functions identical to HP-UX. Refer to
hil(7) in the HP-UX documentation for more complete descriptions of these
ioctls. The second set of ioctls are specific to this implementation and
are primarily related to the shared-queue interface.
HILIOCID Identify and Describe
The device will return up to 11 bytes of information describ-
ing the type and characteristics of the device. At the very
least, 2 bytes of information, the device ID, and the Describe
Record Header will be returned. Identical to the HP-UX HILID
HILIOCSC Report Security Code
Request the security code record from a device. The security
code can vary from 1 byte to 15, and is only supported by some
HIL devices. Identical to the HP-UX HILSC ioctl.
An ascii string of up to 15 bytes in length that describes the
device is returned. Identical to the HP-UX HILRN ioctl.
An ascii string of up to 15 bytes in length that describes the
current status of the device is returned. Identical to the
HILIOCED Extended Describe
Additional information of up to 15 bytes is returned describ-
ing the device. This ioctl is similar to HILIOCID, which must
be used first to determine if the device supports extended de-
scribe. Identical to the HP-UX HILED ioctl.
Turn off auto repeat on the keyboard while it is cooked mode.
Identical to the HP-UX HILDKR ioctl.
HILIOCAR1 Enable Auto Repeat
Turn on auto repeat on the keyboard while it is in raw mode.
The repeat rate is set to 1/30th of a second. Identical to
HILIOCAR2 Enable Auto Repeat
Turn on auto repeat on the keyboard while it is in raw mode.
The repeat rate is set to 1/60th of a second. Identical to
The following ioctls are specific to this implementation:
Generate a keyboard beep as defined by _
\ba_
\br_
\bg. _
\bA_
\br_
\bg is a pointer
to two bytes of information, the first is the duration of the
beep (microseconds), the second is the frequency of the beep.
Allocate and map into user space, an HILQ structure as defined
in <_
\bh_
\bp_
\bd_
\be_
\bv_
\b/_
\bh_
\bi_
\bl_
\bi_
\bo_
\bc_
\bt_
\bl_
\b._
\bh>. _
\bA_
\br_
\bg is a pointer to a _
\bh_
\bi_
\bl_
\bq_
\bi_
\bn_
\bf_
\bo struc-
ture (also described in <_
\bh_
\bp_
\bd_
\be_
\bv_
\b/_
\bh_
\bi_
\bl_
\bi_
\bo_
\bc_
\bt_
\bl_
\b._
\bh>) consisting of a
_
\bq_
\bi_
\bd and an _
\ba_
\bd_
\bd_
\br. If _
\ba_
\bd_
\bd_
\br is non-zero it specifies where in the
address space to map the queue. If zero, the system will se-
lect a convenient location and fill in _
\ba_
\bd_
\bd_
\br. _
\bQ_
\bi_
\bd is filled in
by the system and is a small integer used to uniquely identify
this queue. This ioctl can only be issued to the loop pseudo-
Release a previously allocated HIL event queue, unmapping it
from the user's address space. _
\bA_
\br_
\bg should point to a _
\bh_
\bi_
\bl_
\bq_
\bi_
\bn_
\bf_
\bo
structure which contains the _
\bq_
\bi_
\bd of the queue to be released.
All devices that are currently mapped to the queue are un-
mapped. This ioctl can only be issued to the loop pseudo-
Maps this device to a previously allocated HIL event queue.
_
\bA_
\br_
\bg is a pointer to an integer containing the _
\bq_
\bi_
\bd of the
queue. Once a device is mapped to a queue, all event informa-
tion generated by the device will be placed into the event
Unmap this device from a previously allocated HIL event queue.
_
\bA_
\br_
\bg is a pointer to an integer containing the _
\bq_
\bi_
\bd for the
queue. Future events from the device are no longer placed on
Use HP-UX semantics for gathering data from this device. In-
stead of placing input events for the device on a queue, they
are placed, in HP-UX format, into a buffer from which they can
be obtained via read(2). This interface is provided for back-
wards compatibility. Refer to the HP-UX documentation for a
description of the event packet.
/dev/hil0 HIL loop pseudo device.
/dev/hil1 HIL keyboard device.
/dev/hil[2-7] Individual HIL loop devices.
[ENODEV] no such HIL loop device.
[ENXIO] HIL loop is inoperative.
[EBUSY] Another HP-UX process has the device open, or another BSD pro-
cess has the device open, and is using it in HP-UX mode.
[EINVAL] Invalid ioctl specification.
[EMFILE] No more shared queues available.
projects / unix-history / blob