HIL

Section: Devices and Network Interfaces (4)
Updated: hp300
Index Return to Main Contents

BSD mandoc
 

NAME

hil - Human Interface Link device driver  

DESCRIPTION

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, 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 Aq Pa hpdev/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 HP-UX 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 HP-UX HILED ioctl.

HILIOCAROFF
Disable Auto Repeat

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 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 Aq Pa hpdev/hilioctl.h . Arg is a pointer to a hilqinfo structure (also described in Aq Pa hpdev/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.

 

FILES

/dev/hil0
HIL loop pseudo device.
/dev/hil1
HIL keyboard device.
/dev/hil[2-7]
Individual HIL loop devices.

 

ERRORS

Bq Er ENODEV
no such HIL loop device.
Bq Er ENXIO
HIL loop is inoperative.
Bq Er EBUSY
Another HP-UX process has the device open, or another BSD process has the device open, and is using it in HP-UX mode.
Bq Er EINVAL
Invalid ioctl specification.
Bq Er EMFILE
No more shared queues available.

 

HISTORY

The interface Ud
 

Index

NAME
DESCRIPTION
FILES
ERRORS
HISTORY

This document was created by man2html, using the manual pages.
Time: 06:48:20 GMT, May 19, 2025