*nix Documentation Project
·  Home
 +   man pages
·  Linux HOWTOs
·  FreeBSD Tips
·  *niX Forums

  man pages->OpenBSD man pages -> hp300/hil (4)              



NAME    [Toc]    [Back]

     hil - Human Interface Link device driver

DESCRIPTION    [Toc]    [Back]

     The Human Interface Link (HIL) is the interface used by  the
Series 300
     computers  to  connect devices such as keyboards, mice, control knobs, and
     ID modules to the machine.

     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
     allocation commands described below.  In the current  implementation,
     there  can only be one keyboard and it must be the first device (hil1).

     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
     file  that should be used for communication with the module.

     Communication with an HIL device is begun with an open  system call.  A
     process  may open a device already opened by another process
unless the
     process is operating in HP-UX compatibility  mode  in  which
case it requires
  exclusive  use of the device, or another process has
the device
     open and is using HP-UX style device access (see  HILIOCHPUX

     Input  data  from  a device are obtained in one of two ways.
Processes may
     use an HP-UX style interface in  which  the  read(2)  system
call is used to
     get fixed-size input packets, or they can use a shared-queue
     The shared-queue interface avoids the system  call  overhead
     with  the 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 mapped to
     queues  via an 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 fork(2) and thus, cannot be shared between processes.

     Choosing the type of interface is done on a per device basis
using an
     ioctl(2), but each device can only have one interface at any
given time.

     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 (hil0) indicates when data are present from any
     device on any queue while selecting on an individual  device
     when data are present for that device on any queue.

     Close shuts down the file descriptor associated with the 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
     unmaps all devices and deallocates all queues.

     ioctl(2) is used to control the HIL device.  The ioctl  commands (see
     <machine/hilioctl.h>)  listed  below  are separated into two
groups.  The
     first are those which provide functions identical to  HP-UX.
Refer to
     hil(7) in the 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.

     HILIOCID      Identify and Describe

                   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 HILID ioctl.

     HILIOCSC      Report Security Code

                   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
HILSC ioctl.

     HILIOCRN      Report Name

                   An ASCII string of up to 15  bytes  in  length
that describes
                   the  device is returned.  Identical to the HPUX HILRN

     HILIOCRS      Report Status

                   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 HILRS ioctl.

     HILIOCED      Extended Describe

                   Additional information of up to  15  bytes  is
returned describing
 the device.  This ioctl is similar to
                   which must be used first to determine  if  the
device supports
 extended describe.  Identical to the HPUX HILED

     HILIOCAROFF   Disable Auto Repeat

                   Turn off auto repeat on the keyboard while  it
is in cooked
                   mode.  Identical to the HP-UX HILDKR ioctl.

     HILIOCAR1     Enable Auto Repeat

                   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 HILER1 ioctl.

     HILIOCAR2     Enable Auto Repeat

                   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 HILER2 ioctl.

                   The  following ioctls are specific to this implementation:

     HILIOCBEEP    Beep

                   Generate a keyboard beep as  defined  by  arg.
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.

     HILIOCALLOCQ  Allocate Queue

                   Allocate  and  map  into  user  space, an HILQ
structure as defined
  in  <machine/hilioctl.h>.   Arg  is   a
pointer to a
                   hilqinfo    structure   (also   described   in
                   consisting of a qid and an addr.  If  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  addr.   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.

     HILIOCFREEQ   Free Queue

                   Release   a  previously  allocated  HIL  event
queue, unmapping
                   it from the user's address space.  Arg  should
point to a
                   hilqinfo  structure  which contains the 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.

     HILIOCMAPQ    Map Device to Queue

                   Maps this device to a previously allocated HIL
event queue.
                   Arg  is a pointer to an integer containing the
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.

     HILIOCUNMAPQ  Unmap Device from Queue

                   Unmap this device from a previously  allocated
HIL event
                   queue.   Arg  is  a pointer to an integer containing the qid
                   for the queue.  Future events from the  device
are no longer
                   placed on the event queue.

     HILIOCHPUX    Use HP-UX Read Interface

                   Use  HP-UX  semantics  for gathering data from
this device.
                   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 read(2).  This interface is provided
  for  backwards compatibility.  Refer to
the HP-UX documentation
 for  a  description  of  the  event

FILES    [Toc]    [Back]

     /dev/hil0      HIL loop pseudo device.
     /dev/hil1      HIL keyboard device.
     /dev/hil[2-7]  Individual HIL loop devices.

SEE ALSO    [Toc]    [Back]

     ioctl(2), intro(4), ite(4)

OpenBSD      3.6                        November     30,     1993
[ Back ]
 Similar pages
Name OS Title
uhidev FreeBSD USB Human Interface Device support
uhidev OpenBSD USB Human Interface Device support
ipxlink IRIX Link ipx streams driver to Link Layer
el FreeBSD Ethernet driver for 3Com Etherlink 3C501 device driver
udsbr OpenBSD D-Link DSB-R100 USB radio devices driver
dlfcn NetBSD dynamic link interface
dlclose NetBSD dynamic link interface
dlopen NetBSD dynamic link interface
dlctl OpenBSD dynamic link interface
dlclose OpenBSD dynamic link interface
Copyright © 2004-2005 DeniX Solutions SRL
newsletter delivery service