.\"	$NetBSD: hil.4,v 1.5 1997/10/19 12:57:00 mrg Exp $
.\"
.\" Copyright (c) 1990, 1991, 1993
.\"	The Regents of the University of California.  All rights reserved.
.\"
.\" This code is derived from software contributed to Berkeley by
.\" the Systems Programming Group of the University of Utah Computer
.\" Science Department.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\" 3. All advertising materials mentioning features or use of this software
.\"    must display the following acknowledgement:
.\"	This product includes software developed by the University of
.\"	California, Berkeley and its contributors.
.\" 4. Neither the name of the University nor the names of its contributors
.\"    may be used to endorse or promote products derived from this software
.\"    without specific prior written permission.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
.\"     from: @(#)hil.4	8.2 (Berkeley) 11/30/93
.\"
.Dd November 30, 1993
.Dt HIL 4 hp300
.Os
.Sh NAME
.Nm hil
.Nd Human Interface Link device driver
.Sh DESCRIPTION
The Human Interface Link
.Pq Tn HIL
is the interface used by the Series
300 computers to connect devices such as keyboards, mice, control knobs,
and
.Tn ID
modules to the machine. 
.Pp
Special files
.Pa /dev/hil[1-7]
refer to physical
.Tn HIL
devices 1 through 7.
.Pa /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
.Xr ite 4
interface; other keyboards, if any, are accessible only via their
.Pa /dev/hil Ns Em N
interfaces, as described here.
.Pp
The device file that corresponds to a particular
.Tn HIL
device is determined
by the order of the devices on the loop. For instance, if an
.Tn ID
module
is the second physical device on the loop, then
.Pa /dev/hil2
is the special
file that should be used for communication with that module.
.Pp
Communication with an
.Tn HIL
device is begun with an
.Em open
system call.  A process may open a device already opened by another
process unless the existing process is operating in
.Tn HP-UX
compatibility mode,
in which case it requires exclusive use of the device, or
another process has the device open and is using
.Tn HP-UX
style
device access (see
.Dv HILIOCHPUX
below).
.Pp
In the current implementation,
.Tn HP-UX
style access is the only supported access method.  This interface uses
.Xr 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.)
.Pp
To receive events from a device, a user process uses
.Xr open 2
to open the device, then uses the
.Dv HILIOCHPUX
ioctl (see below) to request
.Tn HP-UX
style access.  Then data obtained with
.Xr 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
.Sq long int
variable with
.Xr 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.
.\" Need someone who knows to write authoritative doc for device data!
.Pp
.Xr select 2
may be used in the usual way to detect input data.
.Pp
.Xr ioctl 2
is used to control the
.Tn HIL
device.
The ioctl commands (which unfortunately are defined in an include file,
.Pa /usr/src/sys/arch/hp300/dev/hilioctl.h ,
not normally installed under
.Pa /usr/include ) ,
are as follows.  Many of these are functionally identical to ioctls
.Tn HP-UX
provides.
.Bl -tag -width HILIOCARO
.It Dv HILIOCID
Identify and Describe
.Pp
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
.Tn ID ,
and the Describe Record Header will be returned.
Identical to the
.Tn HP-UX
.Dv HILID
ioctl.
.It Dv HILIOCSC
Report Security Code
.Pp
Request the security code record from a device. The security code can
vary from 1 byte to 15, and is only supported by some
.Tn HIL
devices.
Identical to the
.Tn HP-UX
.Dv HILSC
ioctl.
.It Dv HILIOCRN
Report Name
.Pp
An ascii string of up to 15 bytes in length that describes the device
is returned.
Identical to the
.Tn HP-UX
.Dv HILRN
ioctl.
.It Dv HILIOCRS
Report Status
.Pp
An ascii string of up to 15 bytes in length that describes the current
status of the device is returned.
Identical to the
.Tn HP-UX
.Dv HILRS
ioctl.
.It Dv HILIOCED
Extended Describe
.Pp
Additional information of up to 15 bytes is returned describing the device.
This ioctl is similar to
.Tn HILIOCID ,
which must be used first
to determine if the device supports extended describe.
Identical to the
.Tn HP-UX
.Dv HILED
ioctl.
.It Dv HILIOCAROFF
Disable Auto Repeat
.Pp
Turn off auto repeat on the keyboard while it is in cooked mode.
Identical to the
.Tn HP-UX
.Dv HILDKR
ioctl.
.It Dv HILIOCAR1
Enable Auto Repeat
.Pp
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
.Tn HP-UX
.Dv HILER1
ioctl.
.It Dv HILIOCAR2
Enable Auto Repeat
.Pp
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
.Tn HP-UX
.Dv HILER2
ioctl.
.Pp
The following ioctls are specific to this implementation:
.It Dv HILIOCBEEP
Beep
.Pp
Generate a keyboard beep as defined by
.Ar arg .
.Ar 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).
.It Dv HILIOCHPUX
Use HP-UX Read Interface
.Pp
Use
.Tn HP-UX
semantics for gathering data from this device.  This call must be used
before anything can be read from the descriptor.
.El
.Sh "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.
.Pp
The first byte of data is a bitmask.  Only two bits have known meaning:
.Bl -tag -width 0x123
.It Li 0x02
The data portion contains mouse motion deltas, two signed 8-bit
quantities, X delta first.
.It Li 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
.Sq down
event, 1 if an
.Sq up
event.  The other seven bits identify the key or button, according to
the table below.
.El
.Pp
If both bits are set, the mouse deltas appear before the button byte.
.Pp
The known identifying values for key/button events are (only the 0xfe
bits are listed):
.Pp
.\" Growl.  The .Sm manipulations simply don't work, and I don't know
.\" how to get a double-quote or backslash to work.  So I name all the
.\" special characters...what I want to write is something like,
.\"	The
.\"	.Sm off
.\"	.Li =
.\"	/
.\"	.Li +
.\"	key
.\" to get "The =/+ key" with the = and + set .Li style.
.Bl -tag -width 0x123 -compact
.It 0x04
.Sq Extend char
(right-hand).
.It 0x06
.Sq Extend char
(left-hand).
.It 0x08
.Sq Shift
(right-hand).
.It 0x0a
.Sq Shift
(left-hand).
.It 0x0c
.Sq CTRL
.It 0x0e
.Sm off
.Sq Break
/
.Sq Reset
.Sm on
.It 0x10
4, on the numeric keypad.
.It 0x12
8, on the numeric keypad.
.It 0x14
5, on the numeric keypad.
.It 0x16
9, on the numeric keypad.
.It 0x18
6, on the numeric keypad.
.It 0x1a
7, on the numeric keypad.
.It 0x1c
The comma key on the numeric keypad.
.It 0x1e
.Sq Enter ,
on the numeric keypad.
.It 0x20
1, on the numeric keypad
.It 0x22
The slash key on the numeric keypad.
.It 0x24
2, on the numeric keypad.
.It 0x26
The plus key on the numeric keypad.
.It 0x28
3, on the numeric keypad.
.It 0x2a
The asterisk key on the numeric keypad.
.It 0x2c
0, on the numeric keypad.
.It 0x2e
The minus key on the numeric keypad.
.It 0x30
B
.It 0x32
V
.It 0x34
C
.It 0x36
X
.It 0x38
Z
.It 0x3e
.Sm off
.Sq ESC
/
.Sq DEL
.Sm on
.It 0x42
The second (counting from the left) of the four unmarked keys at the
top right.
.It 0x46
The third (counting from the left) of the four unmarked keys at the top
right.
.It 0x48
The period key on the numeric keypad.
.It 0x4a
The leftmost of the four unmarked keys at the top right.
.It 0x4c
The
.Sq Tab
key on the numeric keypad.
.It 0x4e
The rightmost of the four unmarked keys at the top right.
.It 0x50
H
.It 0x52
G
.It 0x54
F
.It 0x56
D
.It 0x58
S
.It 0x5a
A
.It 0x5e
.Sq Caps
.It 0x60
U
.It 0x62
Y
.It 0x64
T
.It 0x66
R
.It 0x68
E
.It 0x6a
W
.It 0x6c
Q
.It 0x6e
.Sq Tab
.It 0x70
The digit-7 / ampersand key.
.It 0x72
The digit-6 / circumflex key.
.It 0x74
The digit-5 / percent-sign key.
.It 0x76
The digit-4 / dollar-sign key.
.It 0x78
The digit-3 / hash-mark key.
.It 0x7a
The digit-2 / at-sign key.
.It 0x7c
The digit-1 / exclamation-point key.
.It 0x7e
The backquote / tilde key.
.It 0x80
Left mouse button.
.It 0x82
Right mouse button.
.It 0x90
.Sq Menu
.It 0x92
.Sq F4
.It 0x94
.Sq F3
.It 0x96
.Sq F2
.It 0x98
.Sq F1
.It 0x9c
.Sq Stop
.It 0x9e
.Sm off
.Sq Enter
/
.Sq Print
.Sm on
.It 0xa0
.Sm off
.Sq System
/
.Sq User
.Sm on
.It 0xa2
.Sq F5
.It 0xa4
.Sq F6
.It 0xa6
.Sq F7
.It 0xa8
.Sq F8
.It 0xac
.Sq Clear line
.It 0xae
.Sq Clear display
.It 0xb0
The digit-8 / asterisk key.
.It 0xb2
The digit-9 / left-parenthesis key.
.It 0xb4
The digit-0 / right-parenthesis key.
.It 0xb6
The minus-sign / underscore key.
.It 0xb8
The equal-sign / plus-sign key.
.It 0xba
.Sq Back space
.It 0xbc
.Sq Insert line
.It 0xbe
.Sq Delete line
.It 0xc0
I
.It 0xc2
O
.It 0xc4
P
.It 0xc6
The left-bracket / left-brace key.
.It 0xc8
The right-bracket / right-brace key.
.It 0xca
The backslash / vertical-bar key.
.It 0xcc
.Sq Insert char
.It 0xce
.Sq Delete char
.It 0xd0
J
.It 0xd2
K
.It 0xd4
L
.It 0xd6
The semicolon / colon key.
.It 0xd8
The single-quote / double-quote key.
.It 0xda
.Sq Return
.It 0xdc
The arrow key pointing up and left.
.It 0xde
.Sq Prev
.It 0xe0
M
.It 0xe2
The period / less-than key.
.It 0xe4
The comma / greater-than key.
.It 0xe6
The slash / question-mark key.
.It 0xea
.Sq Select
.It 0xee
.Sq Next
.It 0xf0
N
.It 0xf2
The spacebar.
.It 0xf8
The left-pointing arrow key.
.It 0xfa
The down-pointing arrow key.
.It 0xfc
The up-pointing arrow key.
.It 0xfe
The right-pointing arrow key.
.El
.Sh FILES
.Bl -tag -width /dev/hil[1-7] -compact
.It Pa /dev/hil[1-7]
Individual
.Tn HIL
loop devices.
.El
.Sh ERRORS
.Bl -tag -width [EINVAL]
.It Bq Er ENODEV
No such HIL loop device.
.It Bq Er ENXIO
HIL loop is inoperative.
.It Bq Er EBUSY
Another HP-UX process has the device open, or another
.Bx
process has the
device open, and is using it in
.Tn HP-UX
mode.
.It Bq Er EINVAL
Invalid
.Xr ioctl
specification.
.El
.Sh BUGS
Requiring
.Dv 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.
.Sh HISTORY
The
.Nm
interface is
.Ud