blob: c8656dd029a910251bc9f6ffec70781d3a093f90 [file] [log] [blame]
David Herrmannd99b8ba2012-06-10 15:16:26 +02001 UHID - User-space I/O driver support for HID subsystem
2 ========================================================
3
David Herrmann76c7c492014-07-29 17:14:26 +02004UHID allows user-space to implement HID transport drivers. Please see
5hid-transport.txt for an introduction into HID transport drivers. This document
6relies heavily on the definitions declared there.
David Herrmannd99b8ba2012-06-10 15:16:26 +02007
David Herrmann76c7c492014-07-29 17:14:26 +02008With UHID, a user-space transport driver can create kernel hid-devices for each
9device connected to the user-space controlled bus. The UHID API defines the I/O
10events provided from the kernel to user-space and vice versa.
David Herrmannd99b8ba2012-06-10 15:16:26 +020011
12There is an example user-space application in ./samples/uhid/uhid-example.c
13
14The UHID API
15------------
16
17UHID is accessed through a character misc-device. The minor-number is allocated
18dynamically so you need to rely on udev (or similar) to create the device node.
19This is /dev/uhid by default.
20
21If a new device is detected by your HID I/O Driver and you want to register this
22device with the HID subsystem, then you need to open /dev/uhid once for each
23device you want to register. All further communication is done by read()'ing or
24write()'ing "struct uhid_event" objects. Non-blocking operations are supported
25by setting O_NONBLOCK.
26
27struct uhid_event {
28 __u32 type;
29 union {
David Herrmann76c7c492014-07-29 17:14:26 +020030 struct uhid_create2_req create2;
31 struct uhid_output_req output;
32 struct uhid_input2_req input2;
David Herrmannd99b8ba2012-06-10 15:16:26 +020033 ...
34 } u;
35};
36
37The "type" field contains the ID of the event. Depending on the ID different
38payloads are sent. You must not split a single event across multiple read()'s or
39multiple write()'s. A single event must always be sent as a whole. Furthermore,
40only a single event can be sent per read() or write(). Pending data is ignored.
41If you want to handle multiple events in a single syscall, then use vectored
42I/O with readv()/writev().
David Herrmann76c7c492014-07-29 17:14:26 +020043The "type" field defines the payload. For each type, there is a
44payload-structure available in the union "u" (except for empty payloads). This
45payload contains management and/or device data.
David Herrmannd99b8ba2012-06-10 15:16:26 +020046
David Herrmann76c7c492014-07-29 17:14:26 +020047The first thing you should do is sending an UHID_CREATE2 event. This will
David Herrmannd99b8ba2012-06-10 15:16:26 +020048register the device. UHID will respond with an UHID_START event. You can now
49start sending data to and reading data from UHID. However, unless UHID sends the
50UHID_OPEN event, the internally attached HID Device Driver has no user attached.
51That is, you might put your device asleep unless you receive the UHID_OPEN
52event. If you receive the UHID_OPEN event, you should start I/O. If the last
53user closes the HID device, you will receive an UHID_CLOSE event. This may be
54followed by an UHID_OPEN event again and so on. There is no need to perform
55reference-counting in user-space. That is, you will never receive multiple
56UHID_OPEN events without an UHID_CLOSE event. The HID subsystem performs
57ref-counting for you.
58You may decide to ignore UHID_OPEN/UHID_CLOSE, though. I/O is allowed even
59though the device may have no users.
60
David Herrmann76c7c492014-07-29 17:14:26 +020061If you want to send data on the interrupt channel to the HID subsystem, you send
62an HID_INPUT2 event with your raw data payload. If the kernel wants to send data
63on the interrupt channel to the device, you will read an UHID_OUTPUT event.
64Data requests on the control channel are currently limited to GET_REPORT and
65SET_REPORT (no other data reports on the control channel are defined so far).
66Those requests are always synchronous. That means, the kernel sends
67UHID_GET_REPORT and UHID_SET_REPORT events and requires you to forward them to
68the device on the control channel. Once the device responds, you must forward
69the response via UHID_GET_REPORT_REPLY and UHID_SET_REPORT_REPLY to the kernel.
70The kernel blocks internal driver-execution during such round-trips (times out
71after a hard-coded period).
David Herrmannd99b8ba2012-06-10 15:16:26 +020072
73If your device disconnects, you should send an UHID_DESTROY event. This will
David Herrmann76c7c492014-07-29 17:14:26 +020074unregister the device. You can now send UHID_CREATE2 again to register a new
David Herrmannd99b8ba2012-06-10 15:16:26 +020075device.
76If you close() the fd, the device is automatically unregistered and destroyed
77internally.
78
79write()
80-------
81write() allows you to modify the state of the device and feed input data into
David Herrmann76c7c492014-07-29 17:14:26 +020082the kernel. The kernel will parse the event immediately and if the event ID is
David Herrmannd99b8ba2012-06-10 15:16:26 +020083not supported, it will return -EOPNOTSUPP. If the payload is invalid, then
84-EINVAL is returned, otherwise, the amount of data that was read is returned and
David Herrmann76c7c492014-07-29 17:14:26 +020085the request was handled successfully. O_NONBLOCK does not affect write() as
86writes are always handled immediately in a non-blocking fashion. Future requests
87might make use of O_NONBLOCK, though.
David Herrmannd99b8ba2012-06-10 15:16:26 +020088
Petri Gynther45226432014-03-24 13:50:01 -070089 UHID_CREATE2:
David Herrmann76c7c492014-07-29 17:14:26 +020090 This creates the internal HID device. No I/O is possible until you send this
91 event to the kernel. The payload is of type struct uhid_create2_req and
92 contains information about your device. You can start I/O now.
Petri Gynther45226432014-03-24 13:50:01 -070093
David Herrmannd99b8ba2012-06-10 15:16:26 +020094 UHID_DESTROY:
95 This destroys the internal HID device. No further I/O will be accepted. There
96 may still be pending messages that you can receive with read() but no further
97 UHID_INPUT events can be sent to the kernel.
David Herrmann76c7c492014-07-29 17:14:26 +020098 You can create a new device by sending UHID_CREATE2 again. There is no need to
David Herrmannd99b8ba2012-06-10 15:16:26 +020099 reopen the character device.
100
Petri Gynther45226432014-03-24 13:50:01 -0700101 UHID_INPUT2:
David Herrmann76c7c492014-07-29 17:14:26 +0200102 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.
Petri Gynther45226432014-03-24 13:50:01 -0700105
David Herrmann76c7c492014-07-29 17:14:26 +0200106 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.
David Herrmannd99b8ba2012-06-10 15:16:26 +0200110 If "err" is 0 then you should fill the buffer of the answer with the results
David Herrmann76c7c492014-07-29 17:14:26 +0200111 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.
David Herrmannd99b8ba2012-06-10 15:16:26 +0200117
118read()
119------
David Herrmann76c7c492014-07-29 17:14:26 +0200120read() will return a queued output report. No reaction is required to any of
121them but you should handle them according to your needs.
David Herrmannd99b8ba2012-06-10 15:16:26 +0200122
123 UHID_START:
124 This is sent when the HID device is started. Consider this as an answer to
David Herrmann76c7c492014-07-29 17:14:26 +0200125 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.
David Herrmannd99b8ba2012-06-10 15:16:26 +0200139
140 UHID_STOP:
141 This is sent when the HID device is stopped. Consider this as an answer to
142 UHID_DESTROY.
David Herrmann76c7c492014-07-29 17:14:26 +0200143 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.
David Herrmannd99b8ba2012-06-10 15:16:26 +0200148
149 UHID_OPEN:
150 This is sent when the HID device is opened. That is, the data that the HID
151 device provides is read by some other process. You may ignore this event but
152 it is useful for power-management. As long as you haven't received this event
153 there is actually no other process that reads your data so there is no need to
David Herrmann76c7c492014-07-29 17:14:26 +0200154 send UHID_INPUT2 events to the kernel.
David Herrmannd99b8ba2012-06-10 15:16:26 +0200155
156 UHID_CLOSE:
157 This is sent when there are no more processes which read the HID data. It is
158 the counterpart of UHID_OPEN and you may as well ignore this event.
159
160 UHID_OUTPUT:
161 This is sent if the HID device driver wants to send raw data to the I/O
David Herrmann76c7c492014-07-29 17:14:26 +0200162 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".
David Herrmannd99b8ba2012-06-10 15:16:26 +0200164 This may be received even though you haven't received UHID_OPEN, yet.
165
David Herrmann76c7c492014-07-29 17:14:26 +0200166 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.
David Herrmannd99b8ba2012-06-10 15:16:26 +0200179
David Herrmann76c7c492014-07-29 17:14:26 +0200180 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.
David Herrmannd99b8ba2012-06-10 15:16:26 +0200185
David Herrmann76c7c492014-07-29 17:14:26 +0200186----------------------------------------------------
187Written 2012, David Herrmann <dh.herrmann@gmail.com>