HP HIL driver suite

Driver code Copyright (c) 2001-2004 Brian S. Julin <bri@abrij.org>.

This documentation file is hereby placed in the public domain.


Introduction:

HP HIL (Human Interface Loop) is a somewhat ancient ancestor the
modern USB standard.  The HP HIL bus is a seven-device daisy-chain
running at a raw bit-rate of 8MHz.  It is most commonly used for
keyboards and mice, but supports a much wider range of input and
output peripherals.

HIL is only found on two architectures currently supported by Linux:
HP PA-RISC and one particular model of m68k server.  On both of these
system types, a small i8042 microprocessor called the SDC (System
Device Controller) is used as a front-end to the MLC, which is the
chipset at the heart of host-side HIL.  In order to see HIL device
support options when configuring the kernel, you should first turn on
SDC support (module "hp_sdc").  The SDC also provides a couple of 
extra functions which are not covered in this document, since they 
do not relate to HIL.


Two core drivers:

After turning on SDC support you must choose between two different
drivers.  The first driver, "hilape", is a simple driver analogous to
the USB "HIDBP" driver.  It is has several limitations and a couple of
quirks, but it is smaller, uses less resources, and is signifigantly
less complicated than the alternative.  This is the recommended driver
if all you have are normal keyboards and mice, and you do not 
plug/unplug them while the machine is running.

Limitations and quirks of the "hilape" driver:

     1) Communication is one-way.  There is no support for output devices.
     2) Keyboard LEDS are not supported.
     3) Keyboard auto-repeat settings cannot be changed per-keyboard.
     4) On startup, phantom keyboards are enumerated at all device addresses.
     5) There is no device tracking, disconnected devices are forgotten.
     6) Mice have to be moved a bit (with no buttons pressed) to be seen.
     7) Any buttons pressed on a mouse embedded in a keyboard before 
        the mouse is moved may cause keyboard keystroke events.
     8) Absolute positioning devices like joysticks or tablets may not work.
     9) 3-button mice may have to have all three buttons tickled before 
        the second and third buttons map correctly.
     10) Device serial numbers, keyboard languages, and various other
         pieces of information will not be available in sysfs.
     11) Raw serio access for userspace drivers is not available.

Some of the above may be removed in future versions of the driver.

These limitations result from allowing the SDC firmware to control the
HIL, which makes sending commands to the HIL bus a clumsy affair best
avoided.  The other driver consists of two parts -- hp_sdc_mlc, which
bypasses the SDC firmware as much as is possible to expose the MLC
interface to the host, and hil_mlc, which is a full driver for the
MLC.  (Although all known MLCs use an SDC, that was no reason to
cripple the driver.  Enterprising hardware hobbyists will find the MLC
driver is suitably modularized that support for driving HIL slave
devices from a hacked serial or parallel port would be relatively easy
to add.)

The full HIL MLC driver is currently in various stages of development
and disrepair, and as such is only available from the parisc port's
CVS archive.


Keyboard Driver:

A keyboard driver "hil_kbd" is provided and works in about the same
manner as a USB keyboard.  Some work is needed to complete the mapping
of special keys and SAK.  This driver will not yet work on the truly
ancient HIL keyboards that only report key-down events.

If the keyboard detects that it has an embedded mouse or joystick, it
will create a new linux-input device for it and pass positioning and
button data along to any driver that claims the device.

Barcode readers will also be (unconditionally, at this time) attached
to the keyboard driver.


Pointer driver:

A pointer driver "hil_ptr" is provided to handle mice and tablets,
which should behave basically as USB devices do.


Joystick driver:

... has not been written yet.  It will handle paddleboxes and joysticks, 
which should behave basically as USB devices do.


Raw serio driver:

... is not written yet, but will probably be supported when the 
full MLC driver is next syncronized with the mainstream kernel source.

A direct connection to the raw HIL protocol can be reached through the
serio devices provided by the core driver, as long as the serio has
not been siezed by one of the above drivers.  Userspace drivers can be
written using the linux/hil.h header file.  HPUX raw device emulation
is not supported yet, and won't be unless/until there is more demand
for running old HPUX legacy application binaries.


Devices not covered:

ID keys and audio input devices are not yet supported, but will probably
be supported when the full MLC driver is next syncronized with the 
mainstream kernel source.

Most output devices are also not yet fully supported because the author 
does not have access to any.  Donations of anything capable of 
host-to-hil transfers and/or "prompt" functions, even something as 
simple as a keyboard with LEDs, would aid in development.


Development issues/status:

The full MLC driver, and sysfs support for keyboard and mouse drivers, 
is waiting on the finalization of the migration of the serio and 
linux-input system to the new driver-model.  No further development 
is expected to take place until then, since refitting it to the 
current system, which is likely to change soon, would be a waste of 
effort.