![[BACK]](/cvsweb/icons/back.gif){kind=icon}
Return to hil.4 CVS log ![[TXT]](/cvsweb/icons/text.gif){kind=icon}
![[DIR]](/cvsweb/icons/dir.gif){kind=icon}
Up to [CSRG BSD Unix] / 43BSDReno / share / man / man4 / man4.hp300|
Return to hil.4 CVS log | Up to [CSRG BSD Unix] / 43BSDReno / share / man / man4 / man4.hp300 |
1.1 root 1: .\" Copyright (c) 1990 The Regents of the University of California.
2: .\" All rights reserved.
3: .\"
4: .\" This code is derived from software contributed to Berkeley by
5: .\" the Systems Programming Group of the University of Utah Computer
6: .\" Science Department.
7: .\"
8: .\" Redistribution and use in source and binary forms are permitted provided
9: .\" that: (1) source distributions retain this entire copyright notice and
10: .\" comment, and (2) distributions including binaries display the following
11: .\" acknowledgement: ``This product includes software developed by the
12: .\" University of California, Berkeley and its contributors'' in the
13: .\" documentation or other materials provided with the distribution and in
14: .\" all advertising materials mentioning features or use of this software.
15: .\" Neither the name of the University nor the names of its contributors may
16: .\" be used to endorse or promote products derived from this software without
17: .\" specific prior written permission.
18: .\" THIS SOFTWARE IS PROVIDED ``AS IS'' AND WITHOUT ANY EXPRESS OR IMPLIED
19: .\" WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF
20: .\" MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.
21: .\"
22: .\" @(#)hil.4 5.1 (Berkeley) 6/29/90
23: .\"
24: .TH HIL 4 "June 29, 1990"
25: .UC 7
26: .SH NAME
27: hil \- Human Interface Link device driver
28: .SH DESCRIPTION
29: The Human Interface Link (HIL) is the interface used by the Series
30: 300 computers to connect devices such as keyboards, mice, control knobs,
31: and ID modules to the machine.
32: .PP
33: Special files /dev/hil[1-7] refer to physical HIL devices 1 through 7.
34: /dev/hil0 refers to the ``loop'' pseudo-device and is used for the queue
35: allocation commands described below.
36: In the current implementation,
37: there can only be one keyboard and it must be the first device (hil1).
38: .PP
39: The device file that corresponds to a particular HIL device is determined
40: by the order of the devices on the loop. For instance, if the ID module
41: is the second physical device on the loop, then /dev/hil2 is the special
42: file that should be used for communication with the module.
43: .PP
44: Communication with an HIL device is begun with an
45: .I open
46: system call.
47: A process may open a device already opened by another process unless
48: the process is operating in HP-UX compatibility mode
49: in which case it requires exclusive use of the device, or
50: another process has the device open and is using HP-UX style
51: device access (see
52: .SM HILIOCHPUX
53: below).
54: .PP
55: Input data from a device are obtained in one of two ways.
56: Processes may use an HP-UX style interface in which the \fIread\fP(2)
57: system call is used to get fixed-size input packets,
58: or they can use a
59: .I "shared-queue"
60: interface.
61: The shared-queue interface avoids the system call overhead associated with
62: the HP-UX read interface by sharing a region of memory between the system
63: and a user process.
64: This region consists of a circular list of 255 event packets,
65: and a header containing the size of the queue, and its head and tail indices.
66: The system deposits event data at the tail of the queue,
67: a process extracts it from the head.
68: Extracting an event is done by copying it from the queue and then updating
69: the head appropriately (i.e. head = (head + 1) % qsize).
70: It is up to the process to ensure that packets are removed from the
71: queue quickly enough to prevent the queue from filling.
72: The system, when it determines that the queue is full,
73: will ignore future packets from the device.
74: Devices are \fImapped\fP to queues via an ioctl.
75: More than one device can be mapped to a single queue and one device can
76: be mapped to several queues.
77: Queues are implicitly unmapped by a \fIfork\fP(2) and thus,
78: cannot be shared between processes.
79: .PP
80: Choosing the type of interface is done on a per device basis using
81: an ioctl, but each device can only have one interface at any given time.
82: .PP
83: .I Select
84: may be used with either interface to detect when input data are present.
85: With the read interface, selecting indicates when there is input for a
86: given device.
87: With the shared-queue interface, selecting on the loop pseudo-device (hil0)
88: indicates when data are present from any device on any queue
89: while selecting on an individual device indicates when data are present
90: for that device on any queue.
91: .PP
92: .I Close
93: shuts down the file descriptor associated with the HIL device.
94: The last close (system-wide) of any device removes that device
95: from all queues it was mapped to while the last close of the loop
96: pseudo-device unmaps all devices and deallocates all queues.
97: .PP
98: .IR Ioctl (2)
99: is used to control the HIL device.
100: The ioctl commands (see <hpdev/hilioctl.h>)
101: listed below are separated into two groups.
102: The first are those which provide functions identical to HP-UX.
103: Refer to \fIhil\fP(7) in the HP-UX documentation for more
104: complete descriptions of these ioctls.
105: The second set of ioctls are specific to this implementation and are
106: primarily related to the shared-queue interface.
107: .TP 10
108: HILIOCID
109: Identify and Describe
110: .sp
111: The device will return up to 11 bytes of information describing the
112: type and characteristics of the device.
113: At the very least, 2 bytes of information,
114: the device ID, and the Describe Record Header will be returned.
115: Identical to the HP-UX
116: .SM HILID
117: ioctl.
118: .TP
119: HILIOCSC
120: Report Security Code
121: .sp
122: Request the security code record from a device. The security code can
123: vary from 1 byte to 15, and is only supported by some HIL devices.
124: Identical to the HP-UX
125: .SM HILSC
126: ioctl.
127: .TP
128: HILIOCRN
129: Report Name
130: .sp
131: An ascii string of up to 15 bytes in length that describes the device
132: is returned.
133: Identical to the HP-UX
134: .SM HILRN
135: ioctl.
136: .TP
137: HILIOCRS
138: Report Status
139: .sp
140: An ascii string of up to 15 bytes in length that describes the current
141: status of the device is returned.
142: Identical to the HP-UX
143: .SM HILRS
144: ioctl.
145: .TP
146: HILIOCED
147: Extended Describe
148: .sp
149: Additional information of up to 15 bytes is returned describing the device.
150: This ioctl is similar to HILIOCID, which must be used first
151: to determine if the device supports extended describe.
152: Identical to the HP-UX
153: .SM HILED
154: ioctl.
155: .TP
156: HILIOCAROFF
157: Disable Auto Repeat
158: .sp
159: Turn off auto repeat on the keyboard while it is cooked mode.
160: Identical to the HP-UX
161: .SM HILDKR
162: ioctl.
163: .TP
164: HILIOCAR1
165: Enable Auto Repeat
166: .sp
167: Turn on auto repeat on the keyboard while it is in raw mode.
168: The repeat rate is set to 1/30th of a second.
169: Identical to the HP-UX
170: .SM HILER1
171: ioctl.
172: .TP
173: HILIOCAR2
174: Enable Auto Repeat
175: .sp
176: Turn on auto repeat on the keyboard while it is in raw mode.
177: The repeat rate is set to 1/60th of a second.
178: Identical to the HP-UX
179: .SM HILER2
180: ioctl.
181: .PP
182: The following ioctls are specific to this implementation:
183: .TP 13
184: HILIOCBEEP
185: Beep
186: .sp
187: Generate a keyboard beep as defined by
188: .IR arg .
189: .I Arg
190: is a pointer to two bytes of information,
191: the first is the duration of the beep (microseconds),
192: the second is the frequency of the beep.
193: .TP 13
194: HILIOCALLOCQ
195: Allocate Queue
196: .sp
197: Allocate and map into user space,
198: an HILQ structure as defined in <hpdev/hilioctl.h>.
199: .I Arg
200: is a pointer to a
201: .I hilqinfo
202: structure (also described in <hpdev/hilioctl.h>)
203: consisting of a
204: .I qid
205: and an
206: .I addr .
207: If
208: .I addr
209: is non-zero it specifies where in the address space to map the queue.
210: If zero, the system will select a convenient location and fill in
211: .IR addr .
212: .I Qid
213: is filled in by the system and
214: is a small integer used to uniquely identify this queue.
215: This ioctl can only be issued to the loop pseudo-device.
216: .TP 14
217: HILIOCFREEQ
218: Free Queue
219: .sp
220: Release a previously allocated HIL event queue,
221: unmapping it from the user's address space.
222: .I Arg
223: should point to a
224: .I hilqinfo
225: structure which contains the
226: .I qid
227: of the queue to be released.
228: All devices that are currently mapped to the queue are unmapped.
229: This ioctl can only be issued to the loop pseudo-device.
230: .TP 14
231: HILIOCMAPQ
232: Map Device to Queue
233: .sp
234: Maps this device to a previously allocated HIL event queue.
235: .I Arg
236: is a pointer to an integer containing the
237: .I qid
238: of the queue.
239: Once a device is mapped to a queue,
240: all event information generated by the device will be placed
241: into the event queue at the tail.
242: .TP 14
243: HILIOCUNMAPQ
244: Unmap Device from Queue
245: .sp
246: Unmap this device from a previously allocated HIL event queue.
247: .I Arg
248: is a pointer to an integer containing the
249: .I qid
250: for the queue.
251: Future events from the device are no longer placed on the event queue.
252: .TP 14
253: HILIOCHPUX
254: Use HP-UX Read Interface
255: .sp
256: Use HP-UX semantics for gathering data from this device.
257: Instead of placing input events for the device on a queue,
258: they are placed, in HP-UX format, into a buffer from which they
259: can be obtained via \fIread\fP(2).
260: This interface is provided for backwards compatibility.
261: Refer to the HP-UX documentation for a description of the event packet.
262: .SH ERRORS
263: .TP 15
264: [ENODEV]
265: no such HIL loop device.
266: .TP 15
267: [ENXIO]
268: HIL loop is inoperative.
269: .TP 15
270: [EBUSY]
271: Another HP-UX process has the device open, or another BSD process has the
272: device open, and is using it in HP-UX mode.
273: .TP 15
274: [EINVAL]
275: Invalid ioctl specification.
276: .TP 15
277: [EMFILE]
278: No more shared queues available.
279: .SH FILES
280: .ta \w'/dev/hil[1-7] 'u
281: /dev/hil0 HIL loop pseudo device.
282: .br
283: /dev/hil1 HIL keyboard device.
284: .br
285: /dev/hil[2-7] Individual HIL loop devices.
This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.