Eric Lee / smarc-ti-linux-kernel | Embedian Git Server

Commit 1a978c50c6cff743c3516ffa6d2ce44382e7b70b

Authored by Alan Ott 2011-03-20 08:29:45 +0800

Committed by Jiri Kosina 2011-03-22 18:43:51 +0800

HID: Move hiddev.txt to the new Documentation/hid directory

With the new Documentation/hid directory, it makes sense to have
hiddev.txt here as well.

Signed-off-by: Alan Ott <alan@signal11.us>
Signed-off-by: Jiri Kosina <jkosina@suse.cz>

Showing 2 changed files with 205 additions and 205 deletions Side-by-side Diff

Documentation/hid/hiddev.txt
Documentation/usb/hiddev.txt

Documentation/hid/hiddev.txt

Diff comments View file @ 1a978c5

	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.

Documentation/usb/hiddev.txt

View file @ 1a978c5

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.