About Kernel Documentation Linux Kernel Contact Linux Resources Linux Blog

Documentation / hid / hiddev.txt


Based on kernel version 4.16.1. Page generated on 2018-04-09 11:53 EST.

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.rst
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.
Hide Line Numbers


About Kernel Documentation Linux Kernel Contact Linux Resources Linux Blog