| blob | 669a0f9f3ace1a23621dec4f4a44da9210460727 |
1 .\" $NetBSD: hil.4,v 1.10 2003/06/27 18:26:36 wiz Exp $
2 .\"
3 .\" Copyright (c) 1990, 1991, 1993
4 .\" The Regents of the University of California. All rights reserved.
5 .\"
6 .\" This code is derived from software contributed to Berkeley by
7 .\" the Systems Programming Group of the University of Utah Computer
8 .\" Science Department.
9 .\"
10 .\" Redistribution and use in source and binary forms, with or without
11 .\" modification, are permitted provided that the following conditions
12 .\" are met:
13 .\" 1. Redistributions of source code must retain the above copyright
14 .\" notice, this list of conditions and the following disclaimer.
15 .\" 2. Redistributions in binary form must reproduce the above copyright
16 .\" notice, this list of conditions and the following disclaimer in the
17 .\" documentation and/or other materials provided with the distribution.
18 .\" 3. Neither the name of the University nor the names of its contributors
19 .\" may be used to endorse or promote products derived from this software
20 .\" without specific prior written permission.
21 .\"
22 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
23 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
24 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
25 .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
26 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
27 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
28 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
29 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
30 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
31 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
32 .\" SUCH DAMAGE.
33 .\"
34 .\" from: @(#)hil.4 8.2 (Berkeley) 11/30/93
35 .\"
36 .Dd November 30, 1993
37 .Dt HIL 4 hp300
38 .Os
39 .Sh NAME
40 .Nm hil
41 .Nd Human Interface Link device driver
42 .Sh SYNOPSIS
43 .Cd "hil* at intio?"
44 .Sh DESCRIPTION
45 The Human Interface Link
46 .Pq Tn HIL
47 is the interface used by the Series
48 300 computers to connect devices such as keyboards, mice, control knobs,
49 and
50 .Tn ID
51 modules to the machine.
52 .Pp
53 Special files
54 .Pa /dev/hil[1-7]
55 refer to physical
56 .Tn HIL
57 devices 1 through 7.
58 .Pa /dev/hil0
59 is an artifact of a never-completed interface and is not currently
60 useful for anything. In the current implementation, only one keyboard
61 can be used for text-mode interaction via the
62 .Xr ite 4
63 interface; other keyboards, if any, are accessible only via their
64 .Pa /dev/hil Ns Em N
65 interfaces, as described here.
66 .Pp
67 The device file that corresponds to a particular
68 .Tn HIL
69 device is determined
70 by the order of the devices on the loop. For instance, if an
71 .Tn ID
72 module
73 is the second physical device on the loop, then
74 .Pa /dev/hil2
75 is the special
76 file that should be used for communication with that module.
77 .Pp
78 Communication with an
79 .Tn HIL
80 device is begun with an
81 .Em open
82 system call. A process may open a device already opened by another
83 process unless the existing process is operating in
84 .Tn HP-UX
85 compatibility mode,
86 in which case it requires exclusive use of the device, or
87 another process has the device open and is using
88 .Tn HP-UX
89 style
90 device access (see
91 .Dv HILIOCHPUX
92 below).
93 .Pp
94 In the current implementation,
95 .Tn HP-UX
96 style access is the only supported access method. This interface uses
97 .Xr read 2
98 calls to receive packets of data representing events. (An interface
99 using a memory area shared between the kernel and the user process was
100 partially implemented, and remnants of it can be found in the include
101 files and the driver, but it does not work and probably will be
102 completely dropped in favor of a console interface providing better
103 cross-port consistency.)
104 .Pp
105 To receive events from a device, a user process uses
106 .Xr open 2
107 to open the device, then uses the
108 .Dv HILIOCHPUX
109 ioctl (see below) to request
110 .Tn HP-UX
111 style access. Then data obtained with
112 .Xr read 2
113 consists of a stream of packets, each of which has a five-byte header
114 consisting of a one-byte length (including the header) and a four-byte
115 timestamp, which is measured in hundredths of a second since some fixed
116 reference point. The timestamp is stored in host-native byte order;
117 copying it into a
118 .Sq long int
119 variable with
120 .Xr memcpy 3
121 or equivalent will give a useful result. Following this header is zero
122 or more bytes, as received from the device. This manual page documents
123 this data only minimally; see PACKET FORMAT below.
124 .\" Need someone who knows to write authoritative doc for device data!
125 .Pp
126 .Xr select 2
127 may be used in the usual way to detect input data.
128 .Pp
129 .Xr ioctl 2
130 is used to control the
131 .Tn HIL
132 device.
133 The ioctl commands (which unfortunately are defined in an include file,
134 .Pa /usr/src/sys/arch/hp300/dev/hilioctl.h ,
135 not normally installed under
136 .Pa /usr/include ) ,
137 are as follows. Many of these are functionally identical to ioctls
138 .Tn HP-UX
139 provides.
140 .Bl -tag -width HILIOCARO
141 .It Dv HILIOCID
142 Identify and Describe
143 .Pp
144 The device will return up to 11 bytes of information describing the
145 type and characteristics of the device.
146 At the very least, 2 bytes of information,
147 the device
148 .Tn ID ,
149 and the Describe Record Header will be returned.
150 Identical to the
151 .Tn HP-UX
152 .Dv HILID
153 ioctl.
154 .It Dv HILIOCSC
155 Report Security Code
156 .Pp
157 Request the security code record from a device. The security code can
158 vary from 1 byte to 15, and is only supported by some
159 .Tn HIL
160 devices.
161 Identical to the
162 .Tn HP-UX
163 .Dv HILSC
164 ioctl.
165 .It Dv HILIOCRN
166 Report Name
167 .Pp
168 An ascii string of up to 15 bytes in length that describes the device
169 is returned.
170 Identical to the
171 .Tn HP-UX
172 .Dv HILRN
173 ioctl.
174 .It Dv HILIOCRS
175 Report Status
176 .Pp
177 An ascii string of up to 15 bytes in length that describes the current
178 status of the device is returned.
179 Identical to the
180 .Tn HP-UX
181 .Dv HILRS
182 ioctl.
183 .It Dv HILIOCED
184 Extended Describe
185 .Pp
186 Additional information of up to 15 bytes is returned describing the device.
187 This ioctl is similar to
188 .Tn HILIOCID ,
189 which must be used first
190 to determine if the device supports extended describe.
191 Identical to the
192 .Tn HP-UX
193 .Dv HILED
194 ioctl.
195 .It Dv HILIOCAROFF
196 Disable Auto Repeat
197 .Pp
198 Turn off auto repeat on the keyboard while it is in cooked mode.
199 Identical to the
200 .Tn HP-UX
201 .Dv HILDKR
202 ioctl.
203 .It Dv HILIOCAR1
204 Enable Auto Repeat
205 .Pp
206 Turn on auto repeat on the keyboard while it is in raw mode.
207 The repeat rate is set to 1/30th of a second.
208 Identical to the
209 .Tn HP-UX
210 .Dv HILER1
211 ioctl.
212 .It Dv HILIOCAR2
213 Enable Auto Repeat
214 .Pp
215 Turn on auto repeat on the keyboard while it is in raw mode.
216 The repeat rate is set to 1/60th of a second.
217 Identical to the
218 .Tn HP-UX
219 .Dv HILER2
220 ioctl.
221 .Pp
222 The following ioctls are specific to this implementation:
223 .It Dv HILIOCBEEP
224 Beep
225 .Pp
226 Generate a keyboard beep as defined by
227 .Ar arg .
228 .Ar arg
229 is a pointer to two bytes of information;
230 the first is the duration of the beep (microseconds),
231 the second is the frequency of the beep (Hertz).
232 .It Dv HILIOCHPUX
233 Use HP-UX Read Interface
234 .Pp
235 Use
236 .Tn HP-UX
237 semantics for gathering data from this device. This call must be used
238 before anything can be read from the descriptor.
239 .El
240 .Sh PACKET FORMAT
241 When reading data from a device, events are received as data packets,
242 with a header as described above. Here we provide (very rudimentary)
243 documentation for the format of the device-dependent data, for at least
244 one type of mouse and keyboard (specifically, the 46060A two-button
245 mechanical mouse and 46021A keyboard); other mice and keyboards may or
246 may not be similar.
247 .Pp
248 The first byte of data is a bitmask. Only two bits have known meaning:
249 .Bl -tag -width 0x123
250 .It Li 0x02
251 The data portion contains mouse motion deltas, two signed 8-bit
252 quantities, X delta first.
253 .It Li 0x40
254 The data portion contains a key or mouse button up/down event, one
255 byte. The low bit is 0 if the event is a
256 .Sq down
257 event, 1 if an
258 .Sq up
259 event. The other seven bits identify the key or button, according to
260 the table below.
261 .El
262 .Pp
263 If both bits are set, the mouse deltas appear before the button byte.
264 .Pp
265 The known identifying values for key/button events are (only the 0xfe
266 bits are listed):
267 .Pp
268 .\" Growl. The .Sm manipulations simply don't work, and I don't know
269 .\" how to get a double-quote or backslash to work. So I name all the
270 .\" special characters...what I want to write is something like,
271 .\" The
272 .\" .Sm off
273 .\" .Li =
274 .\" /
275 .\" .Li +
276 .\" key
277 .\" to get "The =/+ key" with the = and + set .Li style.
278 .Bl -tag -width 0x123 -compact
279 .It 0x04
280 .Sq Extend char
281 (right-hand).
282 .It 0x06
283 .Sq Extend char
284 (left-hand).
285 .It 0x08
286 .Sq Shift
287 (right-hand).
288 .It 0x0a
289 .Sq Shift
290 (left-hand).
291 .It 0x0c
292 .Sq CTRL
293 .It 0x0e
294 .Sq Break
295 /
296 .Sq Reset
297 .It 0x10
298 4, on the numeric keypad.
299 .It 0x12
300 8, on the numeric keypad.
301 .It 0x14
302 5, on the numeric keypad.
303 .It 0x16
304 9, on the numeric keypad.
305 .It 0x18
306 6, on the numeric keypad.
307 .It 0x1a
308 7, on the numeric keypad.
309 .It 0x1c
310 The comma key on the numeric keypad.
311 .It 0x1e
312 .Sq Enter ,
313 on the numeric keypad.
314 .It 0x20
315 1, on the numeric keypad
316 .It 0x22
317 The slash key on the numeric keypad.
318 .It 0x24
319 2, on the numeric keypad.
320 .It 0x26
321 The plus key on the numeric keypad.
322 .It 0x28
323 3, on the numeric keypad.
324 .It 0x2a
325 The asterisk key on the numeric keypad.
326 .It 0x2c
327 0, on the numeric keypad.
328 .It 0x2e
329 The minus key on the numeric keypad.
330 .It 0x30
331 B
332 .It 0x32
333 V
334 .It 0x34
335 C
336 .It 0x36
337 X
338 .It 0x38
339 Z
340 .It 0x3e
341 .Sq ESC
342 /
343 .Sq DEL
344 .It 0x42
345 The second (counting from the left) of the four unmarked keys at the
346 top right.
347 .It 0x46
348 The third (counting from the left) of the four unmarked keys at the top
349 right.
350 .It 0x48
351 The period key on the numeric keypad.
352 .It 0x4a
353 The leftmost of the four unmarked keys at the top right.
354 .It 0x4c
355 The
356 .Sq Tab
357 key on the numeric keypad.
358 .It 0x4e
359 The rightmost of the four unmarked keys at the top right.
360 .It 0x50
361 H
362 .It 0x52
363 G
364 .It 0x54
365 F
366 .It 0x56
367 D
368 .It 0x58
369 S
370 .It 0x5a
371 A
372 .It 0x5e
373 .Sq Caps
374 .It 0x60
375 U
376 .It 0x62
377 Y
378 .It 0x64
379 T
380 .It 0x66
381 R
382 .It 0x68
383 E
384 .It 0x6a
385 W
386 .It 0x6c
387 Q
388 .It 0x6e
389 .Sq Tab
390 .It 0x70
391 The digit-7 / ampersand key.
392 .It 0x72
393 The digit-6 / circumflex key.
394 .It 0x74
395 The digit-5 / percent-sign key.
396 .It 0x76
397 The digit-4 / dollar-sign key.
398 .It 0x78
399 The digit-3 / hash-mark key.
400 .It 0x7a
401 The digit-2 / at-sign key.
402 .It 0x7c
403 The digit-1 / exclamation-point key.
404 .It 0x7e
405 The backquote / tilde key.
406 .It 0x80
407 Left mouse button.
408 .It 0x82
409 Right mouse button.
410 .It 0x90
411 .Sq Menu
412 .It 0x92
413 .Sq F4
414 .It 0x94
415 .Sq F3
416 .It 0x96
417 .Sq F2
418 .It 0x98
419 .Sq F1
420 .It 0x9c
421 .Sq Stop
422 .It 0x9e
423 .Sq Enter
424 /
425 .Sq Print
426 .It 0xa0
427 .Sq System
428 /
429 .Sq User
430 .It 0xa2
431 .Sq F5
432 .It 0xa4
433 .Sq F6
434 .It 0xa6
435 .Sq F7
436 .It 0xa8
437 .Sq F8
438 .It 0xac
439 .Sq Clear line
440 .It 0xae
441 .Sq Clear display
442 .It 0xb0
443 The digit-8 / asterisk key.
444 .It 0xb2
445 The digit-9 / left-parenthesis key.
446 .It 0xb4
447 The digit-0 / right-parenthesis key.
448 .It 0xb6
449 The minus-sign / underscore key.
450 .It 0xb8
451 The equal-sign / plus-sign key.
452 .It 0xba
453 .Sq Back space
454 .It 0xbc
455 .Sq Insert line
456 .It 0xbe
457 .Sq Delete line
458 .It 0xc0
459 I
460 .It 0xc2
461 O
462 .It 0xc4
463 P
464 .It 0xc6
465 The left-bracket / left-brace key.
466 .It 0xc8
467 The right-bracket / right-brace key.
468 .It 0xca
469 The backslash / vertical-bar key.
470 .It 0xcc
471 .Sq Insert char
472 .It 0xce
473 .Sq Delete char
474 .It 0xd0
475 J
476 .It 0xd2
477 K
478 .It 0xd4
479 L
480 .It 0xd6
481 The semicolon / colon key.
482 .It 0xd8
483 The single-quote / double-quote key.
484 .It 0xda
485 .Sq Return
486 .It 0xdc
487 The arrow key pointing up and left.
488 .It 0xde
489 .Sq Prev
490 .It 0xe0
491 M
492 .It 0xe2
493 The period / less-than key.
494 .It 0xe4
495 The comma / greater-than key.
496 .It 0xe6
497 The slash / question-mark key.
498 .It 0xea
499 .Sq Select
500 .It 0xee
501 .Sq Next
502 .It 0xf0
503 N
504 .It 0xf2
505 The spacebar.
506 .It 0xf8
507 The left-pointing arrow key.
508 .It 0xfa
509 The down-pointing arrow key.
510 .It 0xfc
511 The up-pointing arrow key.
512 .It 0xfe
513 The right-pointing arrow key.
514 .El
515 .Sh FILES
516 .Bl -tag -width /dev/hil[1-7] -compact
517 .It Pa /dev/hil[1-7]
518 Individual
519 .Tn HIL
520 loop devices.
521 .El
522 .Sh ERRORS
523 .Bl -tag -width [EINVAL]
524 .It Bq Er ENODEV
525 No such HIL loop device.
526 .It Bq Er ENXIO
527 HIL loop is inoperative.
528 .It Bq Er EBUSY
529 Another HP-UX process has the device open, or another
530 .Bx
531 process has the
532 device open, and is using it in
533 .Tn HP-UX
534 mode.
535 .It Bq Er EINVAL
536 Invalid
537 .Xr ioctl 2
538 specification.
539 .El
540 .Sh BUGS
541 Requiring
542 .Dv HILIOCHPUX
543 to be able to read anything is gross. It is probably not worth fixing,
544 though, because the whole hil/ite mechanism will probably be replaced
545 with a more-or-less port-independent scheme in the foreseeable future.
546 .\" .Sh HISTORY
547 .\" The
548 .\" .Nm
549 .\" interface is
550 .\" .Ud