← Back to branch summary

~ubuntu-branches/ubuntu/precise/linux-lowlatency/precise

« back to all changes in this revision

Viewing changes to Documentation/hid/hiddev.txt

  • Committer: Package Import Robot
  • Author(s): Alessio Igor Bogani
  • Date: 2011-10-26 11:13:05 UTC
  • Revision ID: package-import@ubuntu.com-20111026111305-tz023xykf0i6eosh
Tags: upstream-3.2.0
Import upstream version 3.2.0

Show diffs side-by-side

added added

removed removed

Lines of Context:
Documentation/hid/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 disparate requirements, the Linux USB system provides
 
12
HID events to two separate 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-core.c  ----> hid-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
HID devices exchange data with the host computer using data
 
67
bundles called "reports".  Each report is divided into "fields",
 
68
each of which can have one or more "usages".  In the hid-core,
 
69
each one of these usages has a single signed 32 bit value.
 
70
 
 
71
read():
 
72
This is the event interface.  When the HID device's state changes,
 
73
it performs an interrupt transfer containing a report which contains
 
74
the changed value.  The hid-core.c module parses the report, and
 
75
returns to hiddev.c the individual usages that have changed within
 
76
the report.  In its basic mode, the hiddev will make these individual
 
77
usage changes available to the reader using a struct hiddev_event:
 
78
 
 
79
       struct hiddev_event {
 
80
           unsigned hid;
 
81
           signed int value;
 
82
       };
 
83
 
 
84
containing the HID usage identifier for the status that changed, and
 
85
the value that it was changed to. Note that the structure is defined
 
86
within <linux/hiddev.h>, along with some other useful #defines and
 
87
structures.  The HID usage identifier is a composite of the HID usage
 
88
page shifted to the 16 high order bits ORed with the usage code.  The
 
89
behavior of the read() function can be modified using the HIDIOCSFLAG
 
90
ioctl() described below.
 
91
 
 
92
 
 
93
ioctl(): 
 
94
This is the control interface. There are a number of controls: 
 
95
 
 
96
HIDIOCGVERSION - int (read)
 
97
Gets the version code out of the hiddev driver.
 
98
 
 
99
HIDIOCAPPLICATION - (none)
 
100
This ioctl call returns the HID application usage associated with the
 
101
hid device. The third argument to ioctl() specifies which application
 
102
index to get. This is useful when the device has more than one
 
103
application collection. If the index is invalid (greater or equal to
 
104
the number of application collections this device has) the ioctl
 
105
returns -1. You can find out beforehand how many application
 
106
collections the device has from the num_applications field from the
 
107
hiddev_devinfo structure. 
 
108
 
 
109
HIDIOCGCOLLECTIONINFO - struct hiddev_collection_info (read/write)
 
110
This returns a superset of the information above, providing not only
 
111
application collections, but all the collections the device has.  It
 
112
also returns the level the collection lives in the hierarchy.
 
113
The user passes in a hiddev_collection_info struct with the index 
 
114
field set to the index that should be returned.  The ioctl fills in 
 
115
the other fields.  If the index is larger than the last collection 
 
116
index, the ioctl returns -1 and sets errno to -EINVAL.
 
117
 
 
118
HIDIOCGDEVINFO - struct hiddev_devinfo (read)
 
119
Gets a hiddev_devinfo structure which describes the device.
 
120
 
 
121
HIDIOCGSTRING - struct hiddev_string_descriptor (read/write)
 
122
Gets a string descriptor from the device. The caller must fill in the
 
123
"index" field to indicate which descriptor should be returned.
 
124
 
 
125
HIDIOCINITREPORT - (none)
 
126
Instructs the kernel to retrieve all input and feature report values
 
127
from the device. At this point, all the usage structures will contain
 
128
current values for the device, and will maintain it as the device
 
129
changes.  Note that the use of this ioctl is unnecessary in general,
 
130
since later kernels automatically initialize the reports from the
 
131
device at attach time.
 
132
 
 
133
HIDIOCGNAME - string (variable length)
 
134
Gets the device name
 
135
 
 
136
HIDIOCGREPORT - struct hiddev_report_info (write)
 
137
Instructs the kernel to get a feature or input report from the device,
 
138
in order to selectively update the usage structures (in contrast to
 
139
INITREPORT).
 
140
 
 
141
HIDIOCSREPORT - struct hiddev_report_info (write)
 
142
Instructs the kernel to send a report to the device. This report can
 
143
be filled in by the user through HIDIOCSUSAGE calls (below) to fill in
 
144
individual usage values in the report before sending the report in full
 
145
to the device. 
 
146
 
 
147
HIDIOCGREPORTINFO - struct hiddev_report_info (read/write)
 
148
Fills in a hiddev_report_info structure for the user. The report is
 
149
looked up by type (input, output or feature) and id, so these fields
 
150
must be filled in by the user. The ID can be absolute -- the actual
 
151
report id as reported by the device -- or relative --
 
152
HID_REPORT_ID_FIRST for the first report, and (HID_REPORT_ID_NEXT |
 
153
report_id) for the next report after report_id. Without a-priori
 
154
information about report ids, the right way to use this ioctl is to
 
155
use the relative IDs above to enumerate the valid IDs. The ioctl
 
156
returns non-zero when there is no more next ID. The real report ID is
 
157
filled into the returned hiddev_report_info structure. 
 
158
 
 
159
HIDIOCGFIELDINFO - struct hiddev_field_info (read/write)
 
160
Returns the field information associated with a report in a
 
161
hiddev_field_info structure. The user must fill in report_id and
 
162
report_type in this structure, as above. The field_index should also
 
163
be filled in, which should be a number from 0 and maxfield-1, as
 
164
returned from a previous HIDIOCGREPORTINFO call. 
 
165
 
 
166
HIDIOCGUCODE - struct hiddev_usage_ref (read/write)
 
167
Returns the usage_code in a hiddev_usage_ref structure, given that
 
168
given its report type, report id, field index, and index within the
 
169
field have already been filled into the structure.
 
170
 
 
171
HIDIOCGUSAGE - struct hiddev_usage_ref (read/write)
 
172
Returns the value of a usage in a hiddev_usage_ref structure. The
 
173
usage to be retrieved can be specified as above, or the user can
 
174
choose to fill in the report_type field and specify the report_id as
 
175
HID_REPORT_ID_UNKNOWN. In this case, the hiddev_usage_ref will be
 
176
filled in with the report and field information associated with this
 
177
usage if it is found. 
 
178
 
 
179
HIDIOCSUSAGE - struct hiddev_usage_ref (write)
 
180
Sets the value of a usage in an output report.  The user fills in
 
181
the hiddev_usage_ref structure as above, but additionally fills in
 
182
the value field.
 
183
 
 
184
HIDIOGCOLLECTIONINDEX - struct hiddev_usage_ref (write)
 
185
Returns the collection index associated with this usage.  This
 
186
indicates where in the collection hierarchy this usage sits.
 
187
 
 
188
HIDIOCGFLAG - int (read)
 
189
HIDIOCSFLAG - int (write)
 
190
These operations respectively inspect and replace the mode flags
 
191
that influence the read() call above.  The flags are as follows:
 
192
 
 
193
    HIDDEV_FLAG_UREF - read() calls will now return 
 
194
        struct hiddev_usage_ref instead of struct hiddev_event.
 
195
        This is a larger structure, but in situations where the
 
196
        device has more than one usage in its reports with the
 
197
        same usage code, this mode serves to resolve such
 
198
        ambiguity.
 
199
 
 
200
    HIDDEV_FLAG_REPORT - This flag can only be used in conjunction
 
201
        with HIDDEV_FLAG_UREF.  With this flag set, when the device
 
202
        sends a report, a struct hiddev_usage_ref will be returned
 
203
        to read() filled in with the report_type and report_id, but 
 
204
        with field_index set to FIELD_INDEX_NONE.  This serves as
 
205
        additional notification when the device has sent a report.