Documentation/usb/hiddev.txt

   1 Care and feeding of your Human Interface Devices
   2
   3 INTRODUCTION
   4
   5 In addition to the normal input type HID devices, USB also uses the
   6 human interface device protocols for things that are not really human
   7 interfaces, but have similar sorts of communication needs. The two big
   8 examples for this are power devices (especially uninterruptable power
   9 supplies) and monitor control on higher end monitors.
  10
  11 To support these disparite requirements, the Linux USB system provides
  12 HID events to two seperate interfaces:
  13 * the input subsystem, which converts HID events into normal input
  14 device interfaces (such as keyboard, mouse and joystick) and a
  15 normalised event interface - see Documentation/input/input.txt
  16 * the hiddev interface, which provides fairly raw HID events
  17
  18 The data flow for a HID event produced by a device is something like
  19 the following :
  20
  21  usb.c ---> hid.c  ----> input.c ----> [keyboard/mouse/joystick/event]
  22                     |
  23                     |
  24                     --> hiddev.c ----> POWER / MONITOR CONTROL
  25
  26 In addition, other subsystems (apart from USB) can potentially feed
  27 events into the input subsystem, but these have no effect on the hid
  28 device interface.
  29
  30 USING THE HID DEVICE INTERFACE
  31
  32 The hiddev interface is a char interface using the normal USB major,
  33 with the minor numbers starting at 96 and finishing at 111. Therefore,
  34 you need the following commands:
  35 mknod /dev/usb/hiddev0 c 180 96
  36 mknod /dev/usb/hiddev1 c 180 97
  37 mknod /dev/usb/hiddev2 c 180 98
  38 mknod /dev/usb/hiddev3 c 180 99
  39 mknod /dev/usb/hiddev4 c 180 100
  40 mknod /dev/usb/hiddev5 c 180 101
  41 mknod /dev/usb/hiddev6 c 180 102
  42 mknod /dev/usb/hiddev7 c 180 103
  43 mknod /dev/usb/hiddev8 c 180 104
  44 mknod /dev/usb/hiddev9 c 180 105
  45 mknod /dev/usb/hiddev10 c 180 106
  46 mknod /dev/usb/hiddev11 c 180 107
  47 mknod /dev/usb/hiddev12 c 180 108
  48 mknod /dev/usb/hiddev13 c 180 109
  49 mknod /dev/usb/hiddev14 c 180 110
  50 mknod /dev/usb/hiddev15 c 180 111
  51
  52 So you point your hiddev compliant user-space program at the correct
  53 interface for your device, and it all just works.
  54
  55 Assuming that you have a hiddev compliant user-space program, of
  56 course. If you need to write one, read on.
  57
  58
  59 THE HIDDEV API
  60 This description should be read in conjunction with the HID
  61 specification, freely available from http://www.usb.org, and
  62 conveniently linked of http://www.linux-usb.org.
  63
  64 The hiddev API uses a read() interface, and a set of ioctl() calls.
  65
  66
  67 read():
  68 This is the event interface. When the HID device performs an
  69 interrupt transfer, indicating a change of state, data will be made
  70 available at the associated hiddev device with the content of a struct
  71 hiddev_event:
  72
  73        struct hiddev_event {
  74            unsigned hid;
  75            signed int value;
  76        };
  77
  78 containing the HID usage identifier for the status that changed, and
  79 the value that it was changed to. Note that the structure is defined
  80 within <linux/hiddev.h>, along with some other useful #defines and
  81 structures.
  82
  83
  84 ioctl():
  85 This is the control interface. There are a number of controls:
  86
  87 HIDIOCGVERSION - int (read)
  88 Gets the version code out of the hiddev driver.
  89
  90 HIDIOCAPPLICATION - (none)
  91 This ioctl call returns the HID application usage associated with the
  92 hid device. The third argument to ioctl() specifies which application
  93 index to get. This is useful when the device has more than one
  94 application collection. If the index is invalid (greater or equal to
  95 the number of application collections this device has) the ioctl
  96 returns -1. You can find out beforehand how many application
  97 collections the device has from the num_applications field from the
  98 hiddev_devinfo structure.
  99
 100 HIDIOCGDEVINFO - struct hiddev_devinfo (read)
 101 Gets a hiddev_devinfo structure which describes the device.
 102
 103 HIDIOCGSTRING - struct struct hiddev_string_descriptor (read/write)
 104 Gets a string descriptor from the device. The caller must fill in the
 105 "index" field to indicate which descriptor should be returned.
 106
 107 HIDIOCINITREPORT - (none)
 108 Instructs the kernel to retrieve all input and feature report values
 109 from the device. At this point, all the usage structures will contain
 110 current values for the device, and will maintain it as the device
 111 changes.
 112
 113 HIDIOCGNAME - string (variable length)
 114 Gets the device name
 115
 116 HIDIOCGREPORT - struct hiddev_report_info (write)
 117 Instructs the kernel to get a feature or input report from the device,
 118 in order to selectively update the usage structures (in contrast to
 119 INITREPORT).
 120
 121 HIDIOCSREPORT - struct hiddev_report_info (write)
 122 Instructs the kernel to send a report to the device. This report can
 123 be filled in by the user through HIDIOCSUSAGE calls (below) to fill in
 124 individual usage values in the report beforesending the report in full
 125 to the device.
 126
 127 HIDIOCGREPORTINFO - struct hiddev_report_info (read/write)
 128 Fills in a hiddev_report_info structure for the user. The report is
 129 looked up by type (input, output or feature) and id, so these fields
 130 must be filled in by the user. The ID can be absolute -- the actual
 131 report id as reported by the device -- or relative --
 132 HID_REPORT_ID_FIRST for the first report, and (HID_REPORT_ID_NEXT |
 133 report_id) for the next report after report_id. Without a-priori
 134 information about report ids, the right way to use this ioctl is to
 135 use the relative IDs above to enumerate the valid IDs. The ioctl
 136 returns non-zero when there is no more next ID. The real report ID is
 137 filled into the returned hiddev_report_info structure.
 138
 139 HIDIOCGFIELDINFO - struct hiddev_field_info (read/write)
 140 Returns the field information associated with a report in a
 141 hiddev_field_info structure. The user must fill in report_id and
 142 report_type in this structure, as above. The field_index should also
 143 be filled in, which should be a number from 0 and maxfield-1, as
 144 returned from a previous HIDIOCGREPORTINFO call.
 145
 146 HIDIOCGUCODE - struct hiddev_usage_ref (read/write)
 147 Returns the usage_code in a hiddev_usage_ref structure, given that
 148 given its report type, report id, field index, and index within the
 149 field have already been filled into the structure.
 150
 151 HIDIOCGUSAGE - struct hiddev_usage_ref (read/write)
 152 Returns the value of a usage in a hiddev_usage_ref structure. The
 153 usage to be retrieved can be specified as above, or the user can
 154 choose to fill in the report_type field and specify the report_id as
 155 HID_REPORT_ID_UNKNOWN. In this case, the hiddev_usage_ref will be
 156 filled in with the report and field infomation associated with this
 157 usage if it is found.
 158
 159 HIDIOCSUSAGE - struct hiddev_usage_ref (write)
 160 Sets the value of a usage in an output report.
 161
 162