Update (rewrite significant fraction of, actually) this to at least
approximately match current reality. Also give some description of HP-UX-style event format, with a table of key/button codes discovered by experimentation with my keyboard/mouse. (Ain't great, but better than what was there, which was zilcho.)
This commit is contained in:
mouse
parent
4256cf1898
commit
03c91976bf
@ -34,7 +34,7 @@
|
||||
.\" SUCH DAMAGE.
|
||||
.\"
|
||||
.\" from: @(#)hil.4 5.2 (Berkeley) 3/27/91
|
||||
.\" $Id: hil.4,v 1.2 1993/08/01 07:56:30 mycroft Exp $
|
||||
.\" $Id: hil.4,v 1.3 1997/04/06 15:09:48 mouse Exp $
|
||||
.\"
|
||||
.Dd March 27, 1991
|
||||
.Dt HIL 4 hp300
|
||||
@ -57,32 +57,33 @@ refer to physical
|
||||
.Tn HIL
|
||||
devices 1 through 7.
|
||||
.Pa /dev/hil0
|
||||
refers to the ``loop'' pseudo-device and is used for the queue
|
||||
allocation commands described below.
|
||||
In the current implementation,
|
||||
there can only be one keyboard and it must be the first device
|
||||
.Pq Li hil1 .
|
||||
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 the
|
||||
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 the module.
|
||||
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 process is operating in
|
||||
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
|
||||
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
|
||||
@ -91,81 +92,52 @@ device access (see
|
||||
.Dv HILIOCHPUX
|
||||
below).
|
||||
.Pp
|
||||
Input data from a device are obtained in one of two ways.
|
||||
Processes may use an
|
||||
In the current implementation,
|
||||
.Tn HP-UX
|
||||
style interface in which the
|
||||
style access is the only supported access method. This interface uses
|
||||
.Xr read 2
|
||||
system call is used to get fixed-size input packets,
|
||||
or they can use a
|
||||
.Em shared-queue
|
||||
interface.
|
||||
The shared-queue interface avoids the system call overhead associated with
|
||||
the
|
||||
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
|
||||
read interface by sharing a region of memory between the system
|
||||
and a user process.
|
||||
This region consists of a circular list of 255 event packets,
|
||||
and a header containing the size of the queue, and its head and tail indices.
|
||||
The system deposits event data at the tail of the queue,
|
||||
a process extracts it from the head.
|
||||
Extracting an event is done by copying it from the queue and then updating
|
||||
the head appropriately (i.e. head = (head + 1) % qsize).
|
||||
It is up to the process to ensure that packets are removed from the
|
||||
queue quickly enough to prevent the queue from filling.
|
||||
The system, when it determines that the queue is full,
|
||||
will ignore future packets from the device.
|
||||
Devices are
|
||||
.Em mapped
|
||||
to queues via an
|
||||
.Xr ioctl 2.
|
||||
More than one device can be mapped to a single queue and one device can
|
||||
be mapped to several queues.
|
||||
Queues are implicitly unmapped by a
|
||||
.Xr fork 2
|
||||
and thus,
|
||||
cannot be shared between processes.
|
||||
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
|
||||
Choosing the type of interface is done on a per device basis using
|
||||
an
|
||||
.Xr ioctl ,
|
||||
but each device can only have one interface at any given time.
|
||||
.Xr select 2
|
||||
may be used in the usual way to detect input data.
|
||||
.Pp
|
||||
.Em Select
|
||||
may be used with either interface to detect when input data are present.
|
||||
With the read interface, selecting indicates when there is input for a
|
||||
given device.
|
||||
With the shared-queue interface, selecting on the loop pseudo-device
|
||||
.Pq Li hil0
|
||||
indicates when data are present from any device on any queue
|
||||
while selecting on an individual device indicates when data are present
|
||||
for that device on any queue.
|
||||
.Pp
|
||||
.Em Close
|
||||
shuts down the file descriptor associated with the
|
||||
.Tn HIL
|
||||
device.
|
||||
The last close (system-wide) of any device removes that device
|
||||
from all queues it was mapped to while the last close of the loop
|
||||
pseudo-device unmaps all devices and deallocates all queues.
|
||||
.Pp
|
||||
.Xr Ioctl 2
|
||||
.Xr ioctl 2
|
||||
is used to control the
|
||||
.Tn HIL
|
||||
device.
|
||||
The ioctl commands (see
|
||||
.Aq Pa hpdev/hilioctl.h )
|
||||
listed below are separated into two groups.
|
||||
The first are those which provide functions identical to
|
||||
.Tn HP-UX .
|
||||
Refer to
|
||||
.Xr hil 7
|
||||
in the
|
||||
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
|
||||
documentation for more
|
||||
complete descriptions of these ioctls.
|
||||
The second set of ioctls are specific to this implementation and are
|
||||
primarily related to the shared-queue interface.
|
||||
provides.
|
||||
.Bl -tag -width HILIOCARO
|
||||
.It Dv HILIOCID
|
||||
Identify and Describe
|
||||
@ -254,101 +226,304 @@ Beep
|
||||
.Pp
|
||||
Generate a keyboard beep as defined by
|
||||
.Ar arg .
|
||||
.Ar Arg
|
||||
is a pointer to two bytes of information,
|
||||
.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.
|
||||
.It Dv HILIOCALLOCQ
|
||||
Allocate Queue
|
||||
.Pp
|
||||
Allocate and map into user space,
|
||||
an
|
||||
.Tn HILQ
|
||||
structure as defined in
|
||||
.Aq Pa hpdev/hilioctl.h .
|
||||
.Ar Arg
|
||||
is a pointer to a
|
||||
.Ar hilqinfo
|
||||
structure (also described in
|
||||
.Aq Pa hpdev/hilioctl.h )
|
||||
consisting of a
|
||||
.Pa qid
|
||||
and an
|
||||
.Pa addr .
|
||||
If
|
||||
.Pa addr
|
||||
is non-zero it specifies where in the address space to map the queue.
|
||||
If zero, the system will select a convenient location and fill in
|
||||
.Pa addr .
|
||||
.Pa Qid
|
||||
is filled in by the system and
|
||||
is a small integer used to uniquely identify this queue.
|
||||
This ioctl can only be issued to the loop pseudo-device.
|
||||
.It Dv HILIOCFREEQ
|
||||
Free Queue
|
||||
.Pp
|
||||
Release a previously allocated
|
||||
.Tn HIL
|
||||
event queue,
|
||||
unmapping it from the user's address space.
|
||||
.Ar Arg
|
||||
should point to a
|
||||
.Ar hilqinfo
|
||||
structure which contains the
|
||||
.Ar qid
|
||||
of the queue to be released.
|
||||
All devices that are currently mapped to the queue are unmapped.
|
||||
This ioctl can only be issued to the loop pseudo-device.
|
||||
.It Dv HILIOCMAPQ
|
||||
Map Device to Queue
|
||||
.Pp
|
||||
Maps this device to a previously allocated
|
||||
.Tn HIL
|
||||
event queue.
|
||||
.Ar Arg
|
||||
is a pointer to an integer containing the
|
||||
.Ar qid
|
||||
of the queue.
|
||||
Once a device is mapped to a queue,
|
||||
all event information generated by the device will be placed
|
||||
into the event queue at the tail.
|
||||
.It Dv HILIOCUNMAPQ
|
||||
Unmap Device from Queue
|
||||
.Pp
|
||||
Unmap this device from a previously allocated
|
||||
.Tn HIL
|
||||
event queue.
|
||||
.Ar Arg
|
||||
is a pointer to an integer containing the
|
||||
.Ar qid
|
||||
for the queue.
|
||||
Future events from the device are no longer placed on the event queue.
|
||||
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.
|
||||
Instead of placing input events for the device on a queue,
|
||||
they are placed, in
|
||||
.Tn HP-UX
|
||||
format, into a buffer from which they
|
||||
can be obtained via
|
||||
.Xr read 2 .
|
||||
This interface is provided for backwards compatibility.
|
||||
Refer to the
|
||||
.Tn HP-UX
|
||||
documentation for a description of the event packet.
|
||||
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[2-7] -compact
|
||||
.It Pa /dev/hil0
|
||||
.Tn HIL
|
||||
loop pseudo device.
|
||||
.It Pa /dev/hil1
|
||||
.Tn HIL
|
||||
keyboard device.
|
||||
.It Pa /dev/hil[2-7]
|
||||
.Bl -tag -width /dev/hil[1-7] -compact
|
||||
.It Pa /dev/hil[1-7]
|
||||
Individual
|
||||
.Tn HIL
|
||||
loop devices.
|
||||
@ -356,7 +531,7 @@ loop devices.
|
||||
.Sh ERRORS
|
||||
.Bl -tag -width [EINVAL]
|
||||
.It Bq Er ENODEV
|
||||
no such HIL loop device.
|
||||
No such HIL loop device.
|
||||
.It Bq Er ENXIO
|
||||
HIL loop is inoperative.
|
||||
.It Bq Er EBUSY
|
||||
@ -370,11 +545,15 @@ mode.
|
||||
Invalid
|
||||
.Xr ioctl
|
||||
specification.
|
||||
.It Bq Er EMFILE
|
||||
No more shared queues available.
|
||||
.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
|
||||
interface is
|
||||
.Ud
|
||||
|
||||
Loading…
Reference in New Issue
Block a user