561 lines
12 KiB
Groff
561 lines
12 KiB
Groff
.\" $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
|