Hiddev driver

Non-input HID device driver

I've written a "non-input HID" driver that sits alongside the mouse/keyboard/joystick/etc driver for handling devices that don't create regular type/code events. It provides a means for browsing the HID report tables from user code as well as querying the table values. This effort is done on top of the linux-usb project as well as the input drivers project. To test out the code, I've written a user-mode program similar to "powerd" that monitors the status of a UPS device. I've also included code for traversing the report descriptors of a HID device. The following files are available:

hiddev-2.4.3-ac7.diff: Latest patch against the kernel (note, for "virgin" 2.4.3, use the patch below.
hiddev-2.4.2.diff: Patch to Linux 2.4.2 (also works on 2.4.3) which adds the hiddev driver code. This code should also apply fairly cleanly against older 2.4 kernels and 2.2.18, since much of the code is shared.
ups.c: Application that monitors and examines a HID power-class device.

Kernels 2.4.5 and later

The reason that I haven't published later versions of the patch is that it's been picked up in Alan Cox's patches to the Linux kernel (the "ac" patches). While this is not "stable" in the classic sense, I've found them quite usable and reliable. The version of the patch available in the "ac" releases is later than my patches, and reflects the efforts of the HID maintainer (Vojtech Pavlik) in assimilating the hiddev work into his greater effort. I expect a later version of the "mainline" kernel to pick up this code at some point.

Installation

To enable this addition:

Apply the patch above to a 2.4.2 kernel. If you want to be safe, or if you run into issues, use a clean kernel source tree.

    cd /usr/src
    mv linux linux.old
    tar zxvf /tmp/linux-2.4.2.tar.gz
    mv linux linux-2.4.2
    ln  -s linux-2.4.2 linux
    cd linux
    patch -p1 /tmp/hiddev-2.4.2.diff

Configure your kernel to enable "CONFIG_USB_HIDDEV".
If you configured USB as a module before in your kernel, technically all you need to do now is rebuild your modules (make modules; make modules_install) and reload the "hid" module (modprobe -r hid; modprobe hid). If this isn't true or you want to be safe, you can build a new kernel, install the binaries, perform the required lilo/bootloader magic to setup the kernel, and reboot.

Create the hiddev devices (if you don't use devfs) using the formula "mknod /dev/usb/hid/hiddevN c 180 96+N" for values of N between 0 and 16:

    mkdir -p /dev/usb/hid
    mknod /dev/usb/hid/hiddev0 c 180 96
    mknod /dev/usb/hid/hiddev1 c 180 97
    mknod /dev/usb/hid/hiddev2 c 180 98
    mknod /dev/usb/hid/hiddev3 c 180 99
    ...
    mknod /dev/usb/hid/hiddev15 c 180 111

Compile ups.c (the link to the source code is above) by just doing "make ups".

The Hiddev interface

The hiddev driver provides its functionality by providing a special device (mknod /dev/usb/hid/hiddevN c 180 96+N) which ioctl() and read() can be called on to provide the following functionality:

read(): This is the event interface. When the HID device performs an interrupt transfer, indicating a change of state, data will be made available at the associated hiddev device with the content of a struct hiddev_event:
```
struct hiddev_event {
    unsigned hid;
    signed int value;
};
```
containing the HID usage identifier for the status that changed, and the value that it was changed to.

ioctl(): This is the control interface. There are a number of controls:

HIDIOCGVERSION	int (read)	Gets the version code out of the hiddev driver.
HIDIOCAPPLICATION	(none)	This ioctl call returns the HID application usage associated with the hid device. The third argument to ioctl() specifies which application index to get. This is useful when the device has more than one application collection. If the index is invalid (greater or equal to the number of application collections this device has) the ioctl returns -1. You can find out beforehand how many application collections the device has from the num_applications field from the hiddev_devinfo structure.
HIDIOCGDEVINFO	struct hiddev_devinfo (read)	Gets a hiddev_devinfo structure which describes the device.
HIDIOCGSTRING	struct struct hiddev_string_descriptor (read/write)	Gets a string descriptor from the device. The caller must fill in the "index" field to indicate which descriptor should be returned.
HIDIOCINITREPORT		Instructs the kernel to retrieve all input and feature report values from the device. At this point, all the usage structures will contain current values for the device, and will maintain it as the device changes.
HIDIOCGNAME	string (variable length)	Gets the device name
HIDIOCGREPORT	struct hiddev_report_info (write)	Instructs the kernel to get a feature or input report from the device, in order to selectively update the usage structures (in contrast to INITREPORT).
HIDIOCSREPORT	struct hiddev_report_info (write)	Instructs the kernel to send a report to the device. This report can be filled in by the user through HIDIOCSUSAGE calls (below) to fill in individual usage values in the report before sending the report in full to the device.
HIDIOCGREPORTINFO	struct hiddev_report_info (read/write)	Fills in a hiddev_report_info structure for the user. The report is looked up by type (input, output or feature) and id, so these fields must be filled in by the user. The ID can be absolute -- the actual report id as reported by the device -- or relative -- HID_REPORT_ID_FIRST for the first report, and (HID_REPORT_ID_NEXT \| report_id) for the next report after report_id. Without a-priori information about report ids, the right way to use this ioctl is to use the relative IDs above to enumerate the valid IDs. The ioctl returns non-zero when there is no more next ID. The real report ID is filled into the returned hiddev_report_info structure.
HIDIOCGFIELDINFO	struct hiddev_field_info (read/write)	Returns the field information associated with a report in a hiddev_field_info structure. The user must fill in report_id and report_type in this structure, as above. The field_index should also be filled in, which should be a number from 0 and maxfield-1, as returned from a previous HIDIOCGREPORTINFO call.
HIDIOCGUCODE	struct hiddev_usage_ref (read/write)	Returns the usage_code in a hiddev_usage_ref structure, given that given its report type, report id, field index, and index within the field have already been filled into the structure.
HIDIOCGUSAGE	struct hiddev_usage_ref (read/write)	Returns the value of a usage in a hiddev_usage_ref structure. The usage to be retrieved can be specified as above, or the user can choose to fill in the report_type field and specify the report_id as HID_REPORT_ID_UNKNOWN. In this case, the hiddev_usage_ref will be filled in with the report and field infomation associated with this usage if it is found.
HIDIOCSUSAGE	struct hiddev_usage_ref (write)	Sets the value of a usage in an output report.

ChangeLog

2/24/2001: Minor cleanup to probe routine, extracting a "hid_init_hiddev" routine, and moving more code into hid_init_input. Now there are no more nasty CONFIG_USB_HIDDEV ifdefs in hid.c. Also, hiddev and input can be used simultaneously if this interface has application collections for both types (an indirect benefit thanks to Tom's suggestion below).
2/24/2001: Implemented a suggestion from Tom Clark to transition "application" field to an array, so devices that have more than one application collection can be found from the hiddev code. The hiddev code gains HIDIOCAPPLICATION as a result.
2/24/2001: Implemented a suggestion from David Brownell to provide bus and device information in the devinfo structure. Also threw in the interface number as well.
2/24/2001: Diffs are now made against 2.4.2, not that it matters much with the usb/hid code.
2/20/2001: Fixed bug in ioctl() where finfo.field_index was improperly used.
2/13/2001: Cosmetic changes: Re-indented code and switched diff style to "-urN".
2/12/2001: ChangeLog added to web page
2/12/2001: Removed hiddev startup printk in hid.c, which used the input minor number instead of the hiddev minor. We now depend to the hiddev code to print its own startup message.
2/12/2001: hid->name was formatted using the input.idvendor instead of hid->dev->descriptor.idVendor, and the equivalents for idProduct as well.
2/12/2001: Return -EIO to callers (including those waiting in read()) for devices that have disconnected.
2/12/2001: Revised ups.c to cast the output of sizeof() to an int, because otherwise "-1 < sizeof(foo)" evaluates as 0.
2/9/2001: Fixed bug in devfs_register() reported by Philipp Matthias Hahn and Jason Richey.

Send comments to: hiddev@wetlogic.net