hil - Human Interface Link device driver
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 /dev/hil[1-7] refer to physical HIL devices 1
through 7.
/dev/hil0 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 /dev/hil2 is
the special
file that should be used for communication with the module.
Communication with an HIL device is begun with an open 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 requires
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 shared-queue
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 mapped 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(2), but each device can only have one interface at any
given time.
Select may be used with either interface to detect when input data are
present. With the read interface, selecting indicates when
there is input
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.
Close 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
<machine/hilioctl.h>) 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 describing
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 ioctl.
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.
HILIOCRN Report Name
An ASCII string of up to 15 bytes in length
that describes
the device is returned. Identical to the HPUX HILRN
ioctl.
HILIOCRS Report Status
An ASCII string of up to 15 bytes in length
that describes
the current status of the device is returned.
Identical to
the HP-UX HILRS ioctl.
HILIOCED Extended Describe
Additional information of up to 15 bytes is
returned describing
the device. This ioctl is similar to
HILIOCID,
which must be used first to determine if the
device supports
extended describe. Identical to the HPUX HILED
ioctl.
HILIOCAROFF Disable Auto Repeat
Turn off auto repeat on the keyboard while it
is in 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 the HP-UX HILER1 ioctl.
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 HP-UX HILER2 ioctl.
The following ioctls are specific to this implementation:
HILIOCBEEP Beep
Generate a keyboard beep as defined by arg.
Arg 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.
HILIOCALLOCQ Allocate Queue
Allocate and map into user space, an HILQ
structure as defined
in <machine/hilioctl.h>. Arg is a
pointer to a
hilqinfo structure (also described in
<machine/hilioctl.h>)
consisting of a qid and an addr. If addr is
non-zero it
specifies where in the address space to map
the queue. If
zero, the system will select a convenient location and fill
in addr. Qid 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-device.
HILIOCFREEQ Free Queue
Release a previously allocated HIL event
queue, unmapping
it from the user's address space. Arg should
point to a
hilqinfo structure which contains the qid of
the queue to
be released. All devices that are currently
mapped to the
queue are unmapped. This ioctl can only be
issued to the
loop pseudo-device.
HILIOCMAPQ Map Device to Queue
Maps this device to a previously allocated HIL
event queue.
Arg is a pointer to an integer containing the
qid of the
queue. Once a device is mapped to a queue,
all event information
generated by the device will be
placed into the
event queue at the tail.
HILIOCUNMAPQ Unmap Device from Queue
Unmap this device from a previously allocated
HIL event
queue. Arg is a pointer to an integer containing the qid
for the queue. Future events from the device
are no longer
placed on the event queue.
HILIOCHPUX Use HP-UX Read Interface
Use HP-UX semantics for gathering data from
this device.
Instead 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 backwards 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.
ioctl(2), intro(4), ite(4)
OpenBSD 3.6 November 30, 1993
[ Back ] |
