11 UHID - User-space I/O driver support for HID subsystem
22 ========================================================
33
4- The HID subsystem needs two kinds of drivers. In this document we call them:
4+ UHID allows user-space to implement HID transport drivers. Please see
5+ hid-transport.txt for an introduction into HID transport drivers. This document
6+ relies heavily on the definitions declared there.
57
6- 1. The "HID I/O Driver" is the driver that performs raw data I/O to the
7- low-level device. Internally, they register an hid_ll_driver structure with
8- the HID core. They perform device setup, read raw data from the device and
9- push it into the HID subsystem and they provide a callback so the HID
10- subsystem can send data to the device.
11-
12- 2. The "HID Device Driver" is the driver that parses HID reports and reacts on
13- them. There are generic drivers like "generic-usb" and "generic-bluetooth"
14- which adhere to the HID specification and provide the standardizes features.
15- But there may be special drivers and quirks for each non-standard device out
16- there. Internally, they use the hid_driver structure.
17-
18- Historically, the USB stack was the first subsystem to provide an HID I/O
19- Driver. However, other standards like Bluetooth have adopted the HID specs and
20- may provide HID I/O Drivers, too. The UHID driver allows to implement HID I/O
21- Drivers in user-space and feed the data into the kernel HID-subsystem.
22-
23- This allows user-space to operate on the same level as USB-HID, Bluetooth-HID
24- and similar. It does not provide a way to write HID Device Drivers, though. Use
25- hidraw for this purpose.
8+ With UHID, a user-space transport driver can create kernel hid-devices for each
9+ device connected to the user-space controlled bus. The UHID API defines the I/O
10+ events provided from the kernel to user-space and vice versa.
2611
2712There is an example user-space application in ./samples/uhid/uhid-example.c
2813
@@ -42,8 +27,9 @@ by setting O_NONBLOCK.
4227struct uhid_event {
4328 __u32 type;
4429 union {
45- struct uhid_create_req create;
46- struct uhid_data_req data;
30+ struct uhid_create2_req create2;
31+ struct uhid_output_req output;
32+ struct uhid_input2_req input2;
4733 ...
4834 } u;
4935};
@@ -54,8 +40,11 @@ multiple write()'s. A single event must always be sent as a whole. Furthermore,
5440only a single event can be sent per read() or write(). Pending data is ignored.
5541If you want to handle multiple events in a single syscall, then use vectored
5642I/O with readv()/writev().
43+ The "type" field defines the payload. For each type, there is a
44+ payload-structure available in the union "u" (except for empty payloads). This
45+ payload contains management and/or device data.
5746
58- The first thing you should do is sending an UHID_CREATE event. This will
47+ The first thing you should do is sending an UHID_CREATE2 event. This will
5948register the device. UHID will respond with an UHID_START event. You can now
6049start sending data to and reading data from UHID. However, unless UHID sends the
6150UHID_OPEN event, the internally attached HID Device Driver has no user attached.
@@ -69,114 +58,130 @@ ref-counting for you.
6958You may decide to ignore UHID_OPEN/UHID_CLOSE, though. I/O is allowed even
7059though the device may have no users.
7160
72- If you want to send data to the HID subsystem, you send an HID_INPUT event with
73- your raw data payload. If the kernel wants to send data to the device, you will
74- read an UHID_OUTPUT or UHID_OUTPUT_EV event.
61+ If you want to send data on the interrupt channel to the HID subsystem, you send
62+ an HID_INPUT2 event with your raw data payload. If the kernel wants to send data
63+ on the interrupt channel to the device, you will read an UHID_OUTPUT event.
64+ Data requests on the control channel are currently limited to GET_REPORT and
65+ SET_REPORT (no other data reports on the control channel are defined so far).
66+ Those requests are always synchronous. That means, the kernel sends
67+ UHID_GET_REPORT and UHID_SET_REPORT events and requires you to forward them to
68+ the device on the control channel. Once the device responds, you must forward
69+ the response via UHID_GET_REPORT_REPLY and UHID_SET_REPORT_REPLY to the kernel.
70+ The kernel blocks internal driver-execution during such round-trips (times out
71+ after a hard-coded period).
7572
7673If your device disconnects, you should send an UHID_DESTROY event. This will
77- unregister the device. You can now send UHID_CREATE again to register a new
74+ unregister the device. You can now send UHID_CREATE2 again to register a new
7875device.
7976If you close() the fd, the device is automatically unregistered and destroyed
8077internally.
8178
8279write()
8380-------
8481write() allows you to modify the state of the device and feed input data into
85- the kernel. The following types are supported: UHID_CREATE, UHID_DESTROY and
86- UHID_INPUT. The kernel will parse the event immediately and if the event ID is
82+ the kernel. The kernel will parse the event immediately and if the event ID is
8783not supported, it will return -EOPNOTSUPP. If the payload is invalid, then
8884-EINVAL is returned, otherwise, the amount of data that was read is returned and
89- the request was handled successfully.
85+ the request was handled successfully. O_NONBLOCK does not affect write() as
86+ writes are always handled immediately in a non-blocking fashion. Future requests
87+ might make use of O_NONBLOCK, though.
9088
91- UHID_CREATE :
89+ UHID_CREATE2 :
9290 This creates the internal HID device. No I/O is possible until you send this
93- event to the kernel. The payload is of type struct uhid_create_req and
91+ event to the kernel. The payload is of type struct uhid_create2_req and
9492 contains information about your device. You can start I/O now.
9593
96- UHID_CREATE2:
97- Same as UHID_CREATE, but the HID report descriptor data (rd_data) is an array
98- inside struct uhid_create2_req, instead of a pointer to a separate array.
99- Enables use from languages that don't support pointers, e.g. Python.
100-
10194 UHID_DESTROY:
10295 This destroys the internal HID device. No further I/O will be accepted. There
10396 may still be pending messages that you can receive with read() but no further
10497 UHID_INPUT events can be sent to the kernel.
105- You can create a new device by sending UHID_CREATE again. There is no need to
98+ You can create a new device by sending UHID_CREATE2 again. There is no need to
10699 reopen the character device.
107100
108- UHID_INPUT:
109- You must send UHID_CREATE before sending input to the kernel! This event
110- contains a data-payload. This is the raw data that you read from your device.
111- The kernel will parse the HID reports and react on it.
112-
113101 UHID_INPUT2:
114- Same as UHID_INPUT, but the data array is the last field of uhid_input2_req.
115- Enables userspace to write only the required bytes to kernel (ev.type +
116- ev.u.input2.size + the part of the data array that matters), instead of
117- the entire struct uhid_input2_req.
118-
119- UHID_FEATURE_ANSWER:
120- If you receive a UHID_FEATURE request you must answer with this request. You
121- must copy the "id" field from the request into the answer. Set the "err" field
122- to 0 if no error occurred or to EIO if an I/O error occurred.
102+ You must send UHID_CREATE2 before sending input to the kernel! This event
103+ contains a data-payload. This is the raw data that you read from your device
104+ on the interrupt channel. The kernel will parse the HID reports.
105+
106+ UHID_GET_REPORT_REPLY:
107+ If you receive a UHID_GET_REPORT request you must answer with this request.
108+ You must copy the "id" field from the request into the answer. Set the "err"
109+ field to 0 if no error occurred or to EIO if an I/O error occurred.
123110 If "err" is 0 then you should fill the buffer of the answer with the results
124- of the feature request and set "size" correspondingly.
111+ of the GET_REPORT request and set "size" correspondingly.
112+
113+ UHID_SET_REPORT_REPLY:
114+ This is the SET_REPORT equivalent of UHID_GET_REPORT_REPLY. Unlike GET_REPORT,
115+ SET_REPORT never returns a data buffer, therefore, it's sufficient to set the
116+ "id" and "err" fields correctly.
125117
126118read()
127119------
128- read() will return a queued output report. These output reports can be of type
129- UHID_START, UHID_STOP, UHID_OPEN, UHID_CLOSE, UHID_OUTPUT or UHID_OUTPUT_EV. No
130- reaction is required to any of them but you should handle them according to your
131- needs. Only UHID_OUTPUT and UHID_OUTPUT_EV have payloads.
120+ read() will return a queued output report. No reaction is required to any of
121+ them but you should handle them according to your needs.
132122
133123 UHID_START:
134124 This is sent when the HID device is started. Consider this as an answer to
135- UHID_CREATE. This is always the first event that is sent.
125+ UHID_CREATE2. This is always the first event that is sent. Note that this
126+ event might not be available immediately after write(UHID_CREATE2) returns.
127+ Device drivers might required delayed setups.
128+ This event contains a payload of type uhid_start_req. The "dev_flags" field
129+ describes special behaviors of a device. The following flags are defined:
130+ UHID_DEV_NUMBERED_FEATURE_REPORTS:
131+ UHID_DEV_NUMBERED_OUTPUT_REPORTS:
132+ UHID_DEV_NUMBERED_INPUT_REPORTS:
133+ Each of these flags defines whether a given report-type uses numbered
134+ reports. If numbered reports are used for a type, all messages from
135+ the kernel already have the report-number as prefix. Otherwise, no
136+ prefix is added by the kernel.
137+ For messages sent by user-space to the kernel, you must adjust the
138+ prefixes according to these flags.
136139
137140 UHID_STOP:
138141 This is sent when the HID device is stopped. Consider this as an answer to
139142 UHID_DESTROY.
140- If the kernel HID device driver closes the device manually (that is, you
141- didn't send UHID_DESTROY) then you should consider this device closed and send
142- an UHID_DESTROY event. You may want to reregister your device, though. This is
143- always the last message that is sent to you unless you reopen the device with
144- UHID_CREATE .
143+ If you didn't destroy your device via UHID_DESTROY, but the kernel sends an
144+ UHID_STOP event, this should usually be ignored. It means that the kernel
145+ reloaded/changed the device driver loaded on your HID device (or some other
146+ maintenance actions happened).
147+ You can usually ignored any UHID_STOP events safely .
145148
146149 UHID_OPEN:
147150 This is sent when the HID device is opened. That is, the data that the HID
148151 device provides is read by some other process. You may ignore this event but
149152 it is useful for power-management. As long as you haven't received this event
150153 there is actually no other process that reads your data so there is no need to
151- send UHID_INPUT events to the kernel.
154+ send UHID_INPUT2 events to the kernel.
152155
153156 UHID_CLOSE:
154157 This is sent when there are no more processes which read the HID data. It is
155158 the counterpart of UHID_OPEN and you may as well ignore this event.
156159
157160 UHID_OUTPUT:
158161 This is sent if the HID device driver wants to send raw data to the I/O
159- device. You should read the payload and forward it to the device. The payload
160- is of type "struct uhid_data_req".
162+ device on the interrupt channel . You should read the payload and forward it to
163+ the device. The payload is of type "struct uhid_data_req".
161164 This may be received even though you haven't received UHID_OPEN, yet.
162165
163- UHID_OUTPUT_EV (obsolete):
164- Same as UHID_OUTPUT but this contains a "struct input_event" as payload. This
165- is called for force-feedback, LED or similar events which are received through
166- an input device by the HID subsystem. You should convert this into raw reports
167- and send them to your device similar to events of type UHID_OUTPUT.
168- This is no longer sent by newer kernels. Instead, HID core converts it into a
169- raw output report and sends it via UHID_OUTPUT.
170-
171- UHID_FEATURE:
172- This event is sent if the kernel driver wants to perform a feature request as
173- described in the HID specs. The report-type and report-number are available in
174- the payload.
175- The kernel serializes feature requests so there will never be two in parallel.
176- However, if you fail to respond with a UHID_FEATURE_ANSWER in a time-span of 5
177- seconds, then the requests will be dropped and a new one might be sent.
178- Therefore, the payload also contains an "id" field that identifies every
179- request.
180-
181- Document by:
182- David Herrmann <
[email protected] >
166+ UHID_GET_REPORT:
167+ This event is sent if the kernel driver wants to perform a GET_REPORT request
168+ on the control channeld as described in the HID specs. The report-type and
169+ report-number are available in the payload.
170+ The kernel serializes GET_REPORT requests so there will never be two in
171+ parallel. However, if you fail to respond with a UHID_GET_REPORT_REPLY, the
172+ request might silently time out.
173+ Once you read a GET_REPORT request, you shall forward it to the hid device and
174+ remember the "id" field in the payload. Once your hid device responds to the
175+ GET_REPORT (or if it fails), you must send a UHID_GET_REPORT_REPLY to the
176+ kernel with the exact same "id" as in the request. If the request already
177+ timed out, the kernel will ignore the response silently. The "id" field is
178+ never re-used, so conflicts cannot happen.
179+
180+ UHID_SET_REPORT:
181+ This is the SET_REPORT equivalent of UHID_GET_REPORT. On receipt, you shall
182+ send a SET_REPORT request to your hid device. Once it replies, you must tell
183+ the kernel about it via UHID_SET_REPORT_REPLY.
184+ The same restrictions as for UHID_GET_REPORT apply.
185+
186+ ----------------------------------------------------
187+ Written 2012, David Herrmann <
[email protected] >
0 commit comments