hil(4)
- NetBSD Manual Pages
HIL(4) NetBSD/hp300 Kernel Interfaces Manual HIL(4)
NAME
hil -- Human Interface Link device driver
SYNOPSIS
hil* at intio?
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 is an artifact of a never-completed interface and is not cur-
rently useful for anything. In the current implementation, only one key-
board can be used for text-mode interaction via the ite(4) interface;
other keyboards, if any, are accessible only via their /dev/hilN inter-
faces, 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 con-
sole 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' vari-
able 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 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
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 describ-
ing 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 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
(Hertz).
HILIOCHPUX
Use HP-UX Read Interface
Use HP-UX semantics for gathering data from this device. This
call must be used before anything can be read from the
descriptor.
PACKET FORMAT
When reading data from a device, events are received as data packets,
with a header as described above. Here we provide (very rudimentary)
documentation for the format of the device-dependent data, for at least
one type of mouse and keyboard (specifically, the 46060A two-button
mechanical mouse and 46021A keyboard); other mice and keyboards may or
may not be similar.
The first byte of data is a bitmask. Only two bits have known meaning:
0x02 The data portion contains mouse motion deltas, two signed 8-bit
quantities, X delta first.
0x40 The data portion contains a key or mouse button up/down event, one
byte. The low bit is 0 if the event is a `down' event, 1 if an
`up' event. The other seven bits identify the key or button,
according to the table below.
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):
0x04 `Extend char' (right-hand).
0x06 `Extend char' (left-hand).
0x08 `Shift' (right-hand).
0x0a `Shift' (left-hand).
0x0c `CTRL'
0x0e `Break' / `Reset'
0x10 4, on the numeric keypad.
0x12 8, on the numeric keypad.
0x14 5, on the numeric keypad.
0x16 9, on the numeric keypad.
0x18 6, on the numeric keypad.
0x1a 7, on the numeric keypad.
0x1c The comma key on the numeric keypad.
0x1e `Enter', on the numeric keypad.
0x20 1, on the numeric keypad
0x22 The slash key on the numeric keypad.
0x24 2, on the numeric keypad.
0x26 The plus key on the numeric keypad.
0x28 3, on the numeric keypad.
0x2a The asterisk key on the numeric keypad.
0x2c 0, on the numeric keypad.
0x2e The minus key on the numeric keypad.
0x30 B
0x32 V
0x34 C
0x36 X
0x38 Z
0x3e `ESC' / `DEL'
0x42 The second (counting from the left) of the four unmarked keys at
the top right.
0x46 The third (counting from the left) of the four unmarked keys at
the top right.
0x48 The period key on the numeric keypad.
0x4a The leftmost of the four unmarked keys at the top right.
0x4c The `Tab' key on the numeric keypad.
0x4e The rightmost of the four unmarked keys at the top right.
0x50 H
0x52 G
0x54 F
0x56 D
0x58 S
0x5a A
0x5e `Caps'
0x60 U
0x62 Y
0x64 T
0x66 R
0x68 E
0x6a W
0x6c Q
0x6e `Tab'
0x70 The digit-7 / ampersand key.
0x72 The digit-6 / circumflex key.
0x74 The digit-5 / percent-sign key.
0x76 The digit-4 / dollar-sign key.
0x78 The digit-3 / hash-mark key.
0x7a The digit-2 / at-sign key.
0x7c The digit-1 / exclamation-point key.
0x7e The backquote / tilde key.
0x80 Left mouse button.
0x82 Right mouse button.
0x90 `Menu'
0x92 `F4'
0x94 `F3'
0x96 `F2'
0x98 `F1'
0x9c `Stop'
0x9e `Enter' / `Print'
0xa0 `System' / `User'
0xa2 `F5'
0xa4 `F6'
0xa6 `F7'
0xa8 `F8'
0xac `Clear line'
0xae `Clear display'
0xb0 The digit-8 / asterisk key.
0xb2 The digit-9 / left-parenthesis key.
0xb4 The digit-0 / right-parenthesis key.
0xb6 The minus-sign / underscore key.
0xb8 The equal-sign / plus-sign key.
0xba `Back space'
0xbc `Insert line'
0xbe `Delete line'
0xc0 I
0xc2 O
0xc4 P
0xc6 The left-bracket / left-brace key.
0xc8 The right-bracket / right-brace key.
0xca The backslash / vertical-bar key.
0xcc `Insert char'
0xce `Delete char'
0xd0 J
0xd2 K
0xd4 L
0xd6 The semicolon / colon key.
0xd8 The single-quote / double-quote key.
0xda `Return'
0xdc The arrow key pointing up and left.
0xde `Prev'
0xe0 M
0xe2 The period / less-than key.
0xe4 The comma / greater-than key.
0xe6 The slash / question-mark key.
0xea `Select'
0xee `Next'
0xf0 N
0xf2 The spacebar.
0xf8 The left-pointing arrow key.
0xfa The down-pointing arrow key.
0xfc The up-pointing arrow key.
0xfe The right-pointing arrow key.
FILES
/dev/hil[1-7] Individual HIL loop devices.
ERRORS
[ENODEV] No such HIL loop device.
[ENXIO] HIL loop is inoperative.
[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.
[EINVAL] Invalid ioctl(2) specification.
BUGS
Requiring HILIOCHPUX to be able to read anything is gross. It is proba-
bly 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.
NetBSD 5.2 November 30, 1993 NetBSD 5.2
Powered by man-cgi (2024-03-20).
Maintained for NetBSD
by Kimmo Suominen.
Based on man-cgi by Panagiotis Christias.