November 30, 1993 HIL 4 hp300

### 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 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`
  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 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 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.