BSD 4_4 release

[unix-history] / usr / src / share / man / man4 / man4.hp300 / hil.4

diff --git a/usr/src/share/man/man4/man4.hp300/hil.4 b/usr/src/share/man/man4/man4.hp300/hil.4
index 5e356e4..83833fe 100644 (file)
--- a/usr/src/share/man/man4/man4.hp300/hil.4
+++ b/usr/src/share/man/man4/man4.hp300/hil.4
@@ -1,65 +1,108 @@
-.\" Copyright (c) 1990 The Regents of the University of California.
-.\" All rights reserved.
+.\" 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.
 .\"
 .\"
 .\" 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 are permitted provided
-.\" that: (1) source distributions retain this entire copyright notice and
-.\" comment, and (2) distributions including binaries display the following
-.\" acknowledgement:  ``This product includes software developed by the
-.\" University of California, Berkeley and its contributors'' in the
-.\" documentation or other materials provided with the distribution and in
-.\" all advertising materials mentioning features or use of this software.
-.\" 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 ``AS IS'' AND WITHOUT ANY EXPRESS OR IMPLIED
-.\" WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF
-.\" MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.
+.\" 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.

 .\"
 .\"

-.\"    @(#)hil.4       5.1 (Berkeley) 6/29/90
+.\" 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.

 .\"
 .\"

-.TH HIL 4 "June 29, 1990"
-.UC 7
-.SH NAME
-hil \- Human Interface Link device driver
-.SH DESCRIPTION
-The Human Interface Link (HIL) is the interface used by the Series
+.\"     @(#)hil.4      8.1 (Berkeley) 6/9/93
+.\"
+.Dd June 9, 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,
 300 computers to connect devices such as keyboards, mice, control knobs,

-and ID modules to the machine. 
-.PP
-Special files /dev/hil[1-7] refer to physical HIL devices 1 through 7.
-/dev/hil0 refers to the ``loop'' pseudo-device and is used for the queue
+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
+refers to the ``loop'' pseudo-device and is used for the queue

 allocation commands described below.
 In the current implementation,
 allocation commands described below.
 In the current implementation,

-there can only be one keyboard and it must be the first device (hil1).
-.PP
-The device file that corresponds to a particular HIL device is determined
-by the order of the devices on the loop. For instance, if the ID module
-is the second physical device on the loop, then /dev/hil2 is the special
+there can only be one keyboard and it must be the first device
+.Pq Li hil1 .
+.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
+.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 the module.

-.PP
-Communication with an HIL device is begun with an
-.I open
+.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
 system call.
 A process may open a device already opened by another process unless

-the process is operating in HP-UX compatibility mode
+the process is operating in
+.Tn HP-UX
+compatibility mode

 in which case it requires exclusive use of the device, or
 in which case it requires exclusive use of the device, or

-another process has the device open and is using HP-UX style
+another process has the device open and is using
+.Tn HP-UX
+style

 device access (see
 device access (see

-.SM HILIOCHPUX
+.Dv HILIOCHPUX

 below).
 below).

-.PP
+.Pp

 Input data from a device are obtained in one of two ways.
 Input data from a device are obtained in one of two ways.

-Processes may use an HP-UX style interface in which the \fIread\fP(2)
+Processes may use an
+.Tn HP-UX
+style interface in which the
+.Xr read 2

 system call is used to get fixed-size input packets,
 or they can use a
 system call is used to get fixed-size input packets,
 or they can use a

-.I "shared-queue"
+.Em shared-queue

 interface.
 The shared-queue interface avoids the system call overhead associated with
 interface.
 The shared-queue interface avoids the system call overhead associated with

-the HP-UX read interface by sharing a region of memory between the system
+the
+.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.
 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.


@@ -71,215 +114,261 @@ 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.
 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 \fImapped\fP to queues via an ioctl.
+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.
 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 \fIfork\fP(2) and thus,
+Queues are implicitly unmapped by a
+.Xr fork 2
+and thus,

 cannot be shared between processes.
 cannot be shared between processes.

-.PP
+.Pp

 Choosing the type of interface is done on a per device basis using
 Choosing the type of interface is done on a per device basis using

-an ioctl, but each device can only have one interface at any given time.
-.PP
-.I Select
+an
+.Xr ioctl ,
+but each device can only have one interface at any given time.
+.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.
 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 (hil0)
+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.
 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
-.I Close
-shuts down the file descriptor associated with the HIL device.
+.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.
 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
-.IR Ioctl (2)
-is used to control the HIL device.
-The ioctl commands (see <hpdev/hilioctl.h>)
+.Pp
+.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.
 listed below are separated into two groups.

-The first are those which provide functions identical to HP-UX.
-Refer to \fIhil\fP(7) in the HP-UX documentation for more
+The first are those which provide functions identical to
+.Tn HP-UX .
+Refer to
+.Xr hil 7
+in the
+.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.
 complete descriptions of these ioctls.
 The second set of ioctls are specific to this implementation and are
 primarily related to the shared-queue interface.

-.TP 10
-HILIOCID
+.Bl -tag -width HILIOCARO
+.It Dv HILIOCID

 Identify and Describe
 Identify and Describe

-.sp
+.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 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 ID, and the Describe Record Header will be returned.
-Identical to the HP-UX
-.SM HILID
+the device
+.Tn ID ,
+and the Describe Record Header will be returned.
+Identical to the
+.Tn HP-UX
+.Dv HILID

 ioctl.
 ioctl.

-.TP
-HILIOCSC
+.It Dv HILIOCSC

 Report Security Code
 Report Security Code

-.sp
+.Pp

 Request the security code record from a device. The security code can
 Request the security code record from a device. The security code can

-vary from 1 byte to 15, and is only supported by some HIL devices.
-Identical to the HP-UX
-.SM HILSC
+vary from 1 byte to 15, and is only supported by some
+.Tn HIL
+devices.
+Identical to the
+.Tn HP-UX
+.Dv HILSC

 ioctl.
 ioctl.

-.TP
-HILIOCRN
+.It Dv HILIOCRN

 Report Name
 Report Name

-.sp
+.Pp

 An ascii string of up to 15 bytes in length that describes the device
 is returned.
 An ascii string of up to 15 bytes in length that describes the device
 is returned.

-Identical to the HP-UX
-.SM HILRN
+Identical to the
+.Tn HP-UX
+.Dv HILRN

 ioctl.
 ioctl.

-.TP
-HILIOCRS
+.It Dv HILIOCRS

 Report Status
 Report Status

-.sp
+.Pp

 An ascii string of up to 15 bytes in length that describes the current
 status of the device is returned.
 An ascii string of up to 15 bytes in length that describes the current
 status of the device is returned.

-Identical to the HP-UX
-.SM HILRS
+Identical to the
+.Tn HP-UX
+.Dv HILRS

 ioctl.
 ioctl.

-.TP
-HILIOCED
+.It Dv HILIOCED

 Extended Describe
 Extended Describe

-.sp
+.Pp

 Additional information of up to 15 bytes is returned describing the device.
 Additional information of up to 15 bytes is returned describing the device.

-This ioctl is similar to HILIOCID, which must be used first
+This ioctl is similar to
+.Tn HILIOCID ,
+which must be used first

 to determine if the device supports extended describe.
 to determine if the device supports extended describe.

-Identical to the HP-UX
-.SM HILED
+Identical to the
+.Tn HP-UX
+.Dv HILED

 ioctl.
 ioctl.

-.TP
-HILIOCAROFF
+.It Dv HILIOCAROFF

 Disable Auto Repeat
 Disable Auto Repeat

-.sp
+.Pp

 Turn off auto repeat on the keyboard while it is cooked mode.
 Turn off auto repeat on the keyboard while it is cooked mode.

-Identical to the HP-UX
-.SM HILDKR
+Identical to the
+.Tn HP-UX
+.Dv HILDKR

 ioctl.
 ioctl.

-.TP
-HILIOCAR1
+.It Dv HILIOCAR1

 Enable Auto Repeat
 Enable Auto Repeat

-.sp
+.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.
 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 HP-UX
-.SM HILER1
+Identical to the
+.Tn HP-UX
+.Dv HILER1

 ioctl.
 ioctl.

-.TP
-HILIOCAR2
+.It Dv HILIOCAR2

 Enable Auto Repeat
 Enable Auto Repeat

-.sp
+.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.
 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 HP-UX
-.SM HILER2
+Identical to the
+.Tn HP-UX
+.Dv HILER2

 ioctl.
 ioctl.

-.PP
+.Pp

 The following ioctls are specific to this implementation:
 The following ioctls are specific to this implementation:

-.TP 13
-HILIOCBEEP
+.It Dv HILIOCBEEP

 Beep
 Beep

-.sp
+.Pp

 Generate a keyboard beep as defined by
 Generate a keyboard beep as defined by

-.IR arg .
-.I Arg
+.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.
 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.

-.TP 13
-HILIOCALLOCQ
+.It Dv HILIOCALLOCQ

 Allocate Queue
 Allocate Queue

-.sp
+.Pp

 Allocate and map into user space,
 Allocate and map into user space,

-an HILQ structure as defined in <hpdev/hilioctl.h>.
-.I Arg
+an
+.Tn HILQ
+structure as defined in
+.Aq Pa hpdev/hilioctl.h .
+.Ar Arg

 is a pointer to a
 is a pointer to a

-.I hilqinfo
-structure (also described in <hpdev/hilioctl.h>)
+.Ar hilqinfo
+structure (also described in
+.Aq Pa hpdev/hilioctl.h )

 consisting of a
 consisting of a

-.I qid
+.Pa qid

 and an
 and an

-.I addr .
+.Pa addr .

 If
 If

-.I addr
+.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
 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

-.IR addr .
-.I Qid
+.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.
 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.

-.TP 14
-HILIOCFREEQ
+.It Dv HILIOCFREEQ

 Free Queue
 Free Queue

-.sp
-Release a previously allocated HIL event queue,
+.Pp
+Release a previously allocated
+.Tn HIL
+event queue,

 unmapping it from the user's address space.
 unmapping it from the user's address space.

-.I Arg
+.Ar Arg

 should point to a
 should point to a

-.I hilqinfo
+.Ar hilqinfo

 structure which contains the
 structure which contains the

-.I qid
+.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.
 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.

-.TP 14
-HILIOCMAPQ
+.It Dv HILIOCMAPQ

 Map Device to Queue
 Map Device to Queue

-.sp
-Maps this device to a previously allocated HIL event queue.
-.I Arg
+.Pp
+Maps this device to a previously allocated
+.Tn HIL
+event queue.
+.Ar Arg

 is a pointer to an integer containing the
 is a pointer to an integer containing the

-.I qid
+.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.
 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.

-.TP 14
-HILIOCUNMAPQ
+.It Dv HILIOCUNMAPQ

 Unmap Device from Queue
 Unmap Device from Queue

-.sp
-Unmap this device from a previously allocated HIL event queue.
-.I Arg
+.Pp
+Unmap this device from a previously allocated
+.Tn HIL
+event queue.
+.Ar Arg

 is a pointer to an integer containing the
 is a pointer to an integer containing the

-.I qid
+.Ar qid

 for the queue.
 Future events from the device are no longer placed on the event queue.
 for the queue.
 Future events from the device are no longer placed on the event queue.

-.TP 14
-HILIOCHPUX
+.It Dv HILIOCHPUX

 Use HP-UX Read Interface
 Use HP-UX Read Interface

-.sp
-Use HP-UX semantics for gathering data from this device.
+.Pp
+Use
+.Tn HP-UX
+semantics for gathering data from this device.

 Instead of placing input events for the device on a queue,
 Instead of placing input events for the device on a queue,

-they are placed, in HP-UX format, into a buffer from which they
-can be obtained via \fIread\fP(2).
+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.
 This interface is provided for backwards compatibility.

-Refer to the HP-UX documentation for a description of the event packet.
-.SH ERRORS
-.TP 15
-[ENODEV]
+Refer to the
+.Tn HP-UX
+documentation for a description of the event packet.
+.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]
+Individual
+.Tn HIL
+loop devices.
+.El
+.Sh ERRORS
+.Bl -tag -width [EINVAL]
+.It Bq Er ENODEV

 no such HIL loop device.
 no such HIL loop device.

-.TP 15
-[ENXIO]
+.It Bq Er ENXIO

 HIL loop is inoperative.
 HIL loop is inoperative.

-.TP 15
-[EBUSY]
-Another HP-UX process has the device open, or another BSD process has the
-device open, and is using it in HP-UX mode.
-.TP 15
-[EINVAL]
-Invalid ioctl specification.
-.TP 15
-[EMFILE]
+.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.
+.It Bq Er EMFILE

 No more shared queues available.
 No more shared queues available.

-.SH FILES
-.ta \w'/dev/hil[1-7]  'u
-/dev/hil0      HIL loop pseudo device.
-.br
-/dev/hil1      HIL keyboard device.
-.br
-/dev/hil[2-7]  Individual HIL loop devices.
+.El