Special files
/dev/hil[1-7]
refer to physical
HIL
devices 1 through 7.
/dev/hil0
is an artifact of a never-completed interface and is not currently
useful for anything. In the current implementation, only one keyboard
can be used for text-mode interaction via the
ite(4)
interface; other keyboards, if any, are accessible only via their
/dev/hil
N
interfaces, as described here.
The device file that corresponds to a particular
HIL
device is determined
by the order of the devices on the loop. For instance, if an
ID
module
is the second physical device on the loop, then
/dev/hil2
is the special
file that should be used for communication with that 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 existing 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).
In the current implementation, HP-UX style access is the only supported access method. This interface uses read(2) calls to receive packets of data representing events. (An interface using a memory area shared between the kernel and the user process was partially implemented, and remnants of it can be found in the include files and the driver, but it does not work and probably will be completely dropped in favor of a console interface providing better cross-port consistency.)
To receive events from a device, a user process uses
open(2)
to open the device, then uses the
HILIOCHPUX
ioctl (see below) to request
HP-UX
style access. Then data obtained with
read(2)
consists of a stream of packets, each of which has a five-byte header
consisting of a one-byte length (including the header) and a four-byte
timestamp, which is measured in hundredths of a second since some fixed
reference point. The timestamp is stored in host-native byte order;
copying it into a
`long int'
variable with
memcpy(3)
or equivalent will give a useful result. Following this header is zero
or more bytes, as received from the device. This manual page documents
this data only minimally; see PACKET FORMAT below.
select(2) may be used in the usual way to detect input data.
ioctl(2)
is used to control the
HIL
device.
The ioctl commands (which unfortunately are defined in an include file,
/usr/src/sys/arch/hp300/dev/hilioctl.h
,
not normally installed under
/usr/include
),
are as follows. Many of these are functionally identical to ioctls
HP-UX
provides.
HILIOCID
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
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
An ascii string of up to 15 bytes in length that describes the device
is returned.
Identical to the
HP-UX
HILRN
ioctl.
HILIOCRS
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
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
Turn off auto repeat on the keyboard while it is in cooked mode.
Identical to the
HP-UX
HILDKR
ioctl.
HILIOCAR1
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
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
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 (Hertz).
HILIOCHPUX
Use HP-UX semantics for gathering data from this device. This call must be used before anything can be read from the descriptor.
The first byte of data is a bitmask. Only two bits have known meaning:
0x02
0x40
If both bits are set, the mouse deltas appear before the button byte.
The known identifying values for key/button events are (only the 0xfe bits are listed):
/dev/hil[1-7]
ENODEV
]
ENXIO
]
EBUSY
]
EINVAL
]
HILIOCHPUX
to be able to read anything is gross. It is probably not worth fixing,
though, because the whole hil/ite mechanism will probably be replaced
with a more-or-less port-independent scheme in the foreseeable future.