]>
Commit | Line | Data |
---|---|---|
cca47861 MCC |
1 | ====================================================== |
2 | UHID - User-space I/O driver support for HID subsystem | |
3 | ====================================================== | |
d99b8bad | 4 | |
76c7c491 DH |
5 | UHID allows user-space to implement HID transport drivers. Please see |
6 | hid-transport.txt for an introduction into HID transport drivers. This document | |
7 | relies heavily on the definitions declared there. | |
d99b8bad | 8 | |
76c7c491 DH |
9 | With UHID, a user-space transport driver can create kernel hid-devices for each |
10 | device connected to the user-space controlled bus. The UHID API defines the I/O | |
11 | events provided from the kernel to user-space and vice versa. | |
d99b8bad DH |
12 | |
13 | There is an example user-space application in ./samples/uhid/uhid-example.c | |
14 | ||
15 | The UHID API | |
16 | ------------ | |
17 | ||
18 | UHID is accessed through a character misc-device. The minor-number is allocated | |
19 | dynamically so you need to rely on udev (or similar) to create the device node. | |
20 | This is /dev/uhid by default. | |
21 | ||
22 | If a new device is detected by your HID I/O Driver and you want to register this | |
23 | device with the HID subsystem, then you need to open /dev/uhid once for each | |
24 | device you want to register. All further communication is done by read()'ing or | |
25 | write()'ing "struct uhid_event" objects. Non-blocking operations are supported | |
cca47861 | 26 | by setting O_NONBLOCK:: |
d99b8bad | 27 | |
cca47861 | 28 | struct uhid_event { |
d99b8bad DH |
29 | __u32 type; |
30 | union { | |
76c7c491 DH |
31 | struct uhid_create2_req create2; |
32 | struct uhid_output_req output; | |
33 | struct uhid_input2_req input2; | |
d99b8bad DH |
34 | ... |
35 | } u; | |
cca47861 | 36 | }; |
d99b8bad DH |
37 | |
38 | The "type" field contains the ID of the event. Depending on the ID different | |
39 | payloads are sent. You must not split a single event across multiple read()'s or | |
40 | multiple write()'s. A single event must always be sent as a whole. Furthermore, | |
41 | only a single event can be sent per read() or write(). Pending data is ignored. | |
42 | If you want to handle multiple events in a single syscall, then use vectored | |
43 | I/O with readv()/writev(). | |
76c7c491 DH |
44 | The "type" field defines the payload. For each type, there is a |
45 | payload-structure available in the union "u" (except for empty payloads). This | |
46 | payload contains management and/or device data. | |
d99b8bad | 47 | |
76c7c491 | 48 | The first thing you should do is sending an UHID_CREATE2 event. This will |
d99b8bad DH |
49 | register the device. UHID will respond with an UHID_START event. You can now |
50 | start sending data to and reading data from UHID. However, unless UHID sends the | |
51 | UHID_OPEN event, the internally attached HID Device Driver has no user attached. | |
52 | That is, you might put your device asleep unless you receive the UHID_OPEN | |
53 | event. If you receive the UHID_OPEN event, you should start I/O. If the last | |
54 | user closes the HID device, you will receive an UHID_CLOSE event. This may be | |
55 | followed by an UHID_OPEN event again and so on. There is no need to perform | |
56 | reference-counting in user-space. That is, you will never receive multiple | |
57 | UHID_OPEN events without an UHID_CLOSE event. The HID subsystem performs | |
58 | ref-counting for you. | |
59 | You may decide to ignore UHID_OPEN/UHID_CLOSE, though. I/O is allowed even | |
60 | though the device may have no users. | |
61 | ||
76c7c491 DH |
62 | If you want to send data on the interrupt channel to the HID subsystem, you send |
63 | an HID_INPUT2 event with your raw data payload. If the kernel wants to send data | |
64 | on the interrupt channel to the device, you will read an UHID_OUTPUT event. | |
65 | Data requests on the control channel are currently limited to GET_REPORT and | |
66 | SET_REPORT (no other data reports on the control channel are defined so far). | |
67 | Those requests are always synchronous. That means, the kernel sends | |
68 | UHID_GET_REPORT and UHID_SET_REPORT events and requires you to forward them to | |
69 | the device on the control channel. Once the device responds, you must forward | |
70 | the response via UHID_GET_REPORT_REPLY and UHID_SET_REPORT_REPLY to the kernel. | |
71 | The kernel blocks internal driver-execution during such round-trips (times out | |
72 | after a hard-coded period). | |
d99b8bad DH |
73 | |
74 | If your device disconnects, you should send an UHID_DESTROY event. This will | |
76c7c491 | 75 | unregister the device. You can now send UHID_CREATE2 again to register a new |
d99b8bad DH |
76 | device. |
77 | If you close() the fd, the device is automatically unregistered and destroyed | |
78 | internally. | |
79 | ||
80 | write() | |
81 | ------- | |
82 | write() allows you to modify the state of the device and feed input data into | |
76c7c491 | 83 | the kernel. The kernel will parse the event immediately and if the event ID is |
d99b8bad DH |
84 | not supported, it will return -EOPNOTSUPP. If the payload is invalid, then |
85 | -EINVAL is returned, otherwise, the amount of data that was read is returned and | |
76c7c491 DH |
86 | the request was handled successfully. O_NONBLOCK does not affect write() as |
87 | writes are always handled immediately in a non-blocking fashion. Future requests | |
88 | might make use of O_NONBLOCK, though. | |
d99b8bad | 89 | |
cca47861 | 90 | UHID_CREATE2: |
d99b8bad | 91 | This creates the internal HID device. No I/O is possible until you send this |
76c7c491 | 92 | event to the kernel. The payload is of type struct uhid_create2_req and |
d99b8bad DH |
93 | contains information about your device. You can start I/O now. |
94 | ||
cca47861 | 95 | UHID_DESTROY: |
d99b8bad DH |
96 | This destroys the internal HID device. No further I/O will be accepted. There |
97 | may still be pending messages that you can receive with read() but no further | |
98 | UHID_INPUT events can be sent to the kernel. | |
76c7c491 | 99 | You can create a new device by sending UHID_CREATE2 again. There is no need to |
d99b8bad DH |
100 | reopen the character device. |
101 | ||
cca47861 | 102 | UHID_INPUT2: |
76c7c491 DH |
103 | You must send UHID_CREATE2 before sending input to the kernel! This event |
104 | contains a data-payload. This is the raw data that you read from your device | |
105 | on the interrupt channel. The kernel will parse the HID reports. | |
106 | ||
cca47861 | 107 | UHID_GET_REPORT_REPLY: |
76c7c491 DH |
108 | If you receive a UHID_GET_REPORT request you must answer with this request. |
109 | You must copy the "id" field from the request into the answer. Set the "err" | |
110 | field to 0 if no error occurred or to EIO if an I/O error occurred. | |
d99b8bad | 111 | If "err" is 0 then you should fill the buffer of the answer with the results |
76c7c491 DH |
112 | of the GET_REPORT request and set "size" correspondingly. |
113 | ||
cca47861 | 114 | UHID_SET_REPORT_REPLY: |
76c7c491 DH |
115 | This is the SET_REPORT equivalent of UHID_GET_REPORT_REPLY. Unlike GET_REPORT, |
116 | SET_REPORT never returns a data buffer, therefore, it's sufficient to set the | |
117 | "id" and "err" fields correctly. | |
d99b8bad DH |
118 | |
119 | read() | |
120 | ------ | |
76c7c491 DH |
121 | read() will return a queued output report. No reaction is required to any of |
122 | them but you should handle them according to your needs. | |
d99b8bad | 123 | |
cca47861 | 124 | UHID_START: |
d99b8bad | 125 | This is sent when the HID device is started. Consider this as an answer to |
76c7c491 DH |
126 | UHID_CREATE2. This is always the first event that is sent. Note that this |
127 | event might not be available immediately after write(UHID_CREATE2) returns. | |
128 | Device drivers might required delayed setups. | |
129 | This event contains a payload of type uhid_start_req. The "dev_flags" field | |
130 | describes special behaviors of a device. The following flags are defined: | |
cca47861 MCC |
131 | |
132 | - UHID_DEV_NUMBERED_FEATURE_REPORTS | |
133 | - UHID_DEV_NUMBERED_OUTPUT_REPORTS | |
134 | - UHID_DEV_NUMBERED_INPUT_REPORTS | |
135 | ||
76c7c491 DH |
136 | Each of these flags defines whether a given report-type uses numbered |
137 | reports. If numbered reports are used for a type, all messages from | |
138 | the kernel already have the report-number as prefix. Otherwise, no | |
139 | prefix is added by the kernel. | |
140 | For messages sent by user-space to the kernel, you must adjust the | |
141 | prefixes according to these flags. | |
d99b8bad | 142 | |
cca47861 | 143 | UHID_STOP: |
d99b8bad DH |
144 | This is sent when the HID device is stopped. Consider this as an answer to |
145 | UHID_DESTROY. | |
cca47861 | 146 | |
76c7c491 DH |
147 | If you didn't destroy your device via UHID_DESTROY, but the kernel sends an |
148 | UHID_STOP event, this should usually be ignored. It means that the kernel | |
149 | reloaded/changed the device driver loaded on your HID device (or some other | |
150 | maintenance actions happened). | |
cca47861 | 151 | |
76c7c491 | 152 | You can usually ignored any UHID_STOP events safely. |
d99b8bad | 153 | |
cca47861 | 154 | UHID_OPEN: |
d99b8bad DH |
155 | This is sent when the HID device is opened. That is, the data that the HID |
156 | device provides is read by some other process. You may ignore this event but | |
157 | it is useful for power-management. As long as you haven't received this event | |
158 | there is actually no other process that reads your data so there is no need to | |
76c7c491 | 159 | send UHID_INPUT2 events to the kernel. |
d99b8bad | 160 | |
cca47861 | 161 | UHID_CLOSE: |
d99b8bad DH |
162 | This is sent when there are no more processes which read the HID data. It is |
163 | the counterpart of UHID_OPEN and you may as well ignore this event. | |
164 | ||
cca47861 | 165 | UHID_OUTPUT: |
d99b8bad | 166 | This is sent if the HID device driver wants to send raw data to the I/O |
76c7c491 | 167 | device on the interrupt channel. You should read the payload and forward it to |
46b14eef | 168 | the device. The payload is of type "struct uhid_output_req". |
d99b8bad DH |
169 | This may be received even though you haven't received UHID_OPEN, yet. |
170 | ||
cca47861 | 171 | UHID_GET_REPORT: |
76c7c491 DH |
172 | This event is sent if the kernel driver wants to perform a GET_REPORT request |
173 | on the control channeld as described in the HID specs. The report-type and | |
174 | report-number are available in the payload. | |
175 | The kernel serializes GET_REPORT requests so there will never be two in | |
176 | parallel. However, if you fail to respond with a UHID_GET_REPORT_REPLY, the | |
177 | request might silently time out. | |
178 | Once you read a GET_REPORT request, you shall forward it to the hid device and | |
179 | remember the "id" field in the payload. Once your hid device responds to the | |
180 | GET_REPORT (or if it fails), you must send a UHID_GET_REPORT_REPLY to the | |
181 | kernel with the exact same "id" as in the request. If the request already | |
182 | timed out, the kernel will ignore the response silently. The "id" field is | |
183 | never re-used, so conflicts cannot happen. | |
184 | ||
cca47861 | 185 | UHID_SET_REPORT: |
76c7c491 DH |
186 | This is the SET_REPORT equivalent of UHID_GET_REPORT. On receipt, you shall |
187 | send a SET_REPORT request to your hid device. Once it replies, you must tell | |
188 | the kernel about it via UHID_SET_REPORT_REPLY. | |
189 | The same restrictions as for UHID_GET_REPORT apply. | |
190 | ||
191 | ---------------------------------------------------- | |
cca47861 | 192 | |
76c7c491 | 193 | Written 2012, David Herrmann <dh.herrmann@gmail.com> |