]>
Commit | Line | Data |
---|---|---|
d99b8bad DH |
1 | UHID - User-space I/O driver support for HID subsystem |
2 | ======================================================== | |
3 | ||
76c7c491 DH |
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. | |
d99b8bad | 7 | |
76c7c491 DH |
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. | |
d99b8bad DH |
11 | |
12 | There is an example user-space application in ./samples/uhid/uhid-example.c | |
13 | ||
14 | The UHID API | |
15 | ------------ | |
16 | ||
17 | UHID is accessed through a character misc-device. The minor-number is allocated | |
18 | dynamically so you need to rely on udev (or similar) to create the device node. | |
19 | This is /dev/uhid by default. | |
20 | ||
21 | If a new device is detected by your HID I/O Driver and you want to register this | |
22 | device with the HID subsystem, then you need to open /dev/uhid once for each | |
23 | device you want to register. All further communication is done by read()'ing or | |
24 | write()'ing "struct uhid_event" objects. Non-blocking operations are supported | |
25 | by setting O_NONBLOCK. | |
26 | ||
27 | struct uhid_event { | |
28 | __u32 type; | |
29 | union { | |
76c7c491 DH |
30 | struct uhid_create2_req create2; |
31 | struct uhid_output_req output; | |
32 | struct uhid_input2_req input2; | |
d99b8bad DH |
33 | ... |
34 | } u; | |
35 | }; | |
36 | ||
37 | The "type" field contains the ID of the event. Depending on the ID different | |
38 | payloads are sent. You must not split a single event across multiple read()'s or | |
39 | multiple write()'s. A single event must always be sent as a whole. Furthermore, | |
40 | only a single event can be sent per read() or write(). Pending data is ignored. | |
41 | If you want to handle multiple events in a single syscall, then use vectored | |
42 | I/O with readv()/writev(). | |
76c7c491 DH |
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. | |
d99b8bad | 46 | |
76c7c491 | 47 | The first thing you should do is sending an UHID_CREATE2 event. This will |
d99b8bad DH |
48 | register the device. UHID will respond with an UHID_START event. You can now |
49 | start sending data to and reading data from UHID. However, unless UHID sends the | |
50 | UHID_OPEN event, the internally attached HID Device Driver has no user attached. | |
51 | That is, you might put your device asleep unless you receive the UHID_OPEN | |
52 | event. If you receive the UHID_OPEN event, you should start I/O. If the last | |
53 | user closes the HID device, you will receive an UHID_CLOSE event. This may be | |
54 | followed by an UHID_OPEN event again and so on. There is no need to perform | |
55 | reference-counting in user-space. That is, you will never receive multiple | |
56 | UHID_OPEN events without an UHID_CLOSE event. The HID subsystem performs | |
57 | ref-counting for you. | |
58 | You may decide to ignore UHID_OPEN/UHID_CLOSE, though. I/O is allowed even | |
59 | though the device may have no users. | |
60 | ||
76c7c491 DH |
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). | |
d99b8bad DH |
72 | |
73 | If your device disconnects, you should send an UHID_DESTROY event. This will | |
76c7c491 | 74 | unregister the device. You can now send UHID_CREATE2 again to register a new |
d99b8bad DH |
75 | device. |
76 | If you close() the fd, the device is automatically unregistered and destroyed | |
77 | internally. | |
78 | ||
79 | write() | |
80 | ------- | |
81 | write() allows you to modify the state of the device and feed input data into | |
76c7c491 | 82 | the kernel. The kernel will parse the event immediately and if the event ID is |
d99b8bad DH |
83 | not 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 | |
76c7c491 DH |
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. | |
d99b8bad | 88 | |
76c7c491 | 89 | UHID_CREATE2: |
d99b8bad | 90 | This creates the internal HID device. No I/O is possible until you send this |
76c7c491 | 91 | event to the kernel. The payload is of type struct uhid_create2_req and |
d99b8bad DH |
92 | contains information about your device. You can start I/O now. |
93 | ||
94 | 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. | |
76c7c491 | 98 | You can create a new device by sending UHID_CREATE2 again. There is no need to |
d99b8bad DH |
99 | reopen the character device. |
100 | ||
4522643a | 101 | UHID_INPUT2: |
76c7c491 DH |
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. | |
d99b8bad | 110 | If "err" is 0 then you should fill the buffer of the answer with the results |
76c7c491 DH |
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. | |
d99b8bad DH |
117 | |
118 | read() | |
119 | ------ | |
76c7c491 DH |
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. | |
d99b8bad DH |
122 | |
123 | UHID_START: | |
124 | This is sent when the HID device is started. Consider this as an answer to | |
76c7c491 DH |
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. | |
d99b8bad DH |
139 | |
140 | UHID_STOP: | |
141 | This is sent when the HID device is stopped. Consider this as an answer to | |
142 | UHID_DESTROY. | |
76c7c491 DH |
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. | |
d99b8bad DH |
148 | |
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 | |
76c7c491 | 154 | send UHID_INPUT2 events to the kernel. |
d99b8bad DH |
155 | |
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 | |
76c7c491 DH |
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". | |
d99b8bad DH |
164 | This may be received even though you haven't received UHID_OPEN, yet. |
165 | ||
76c7c491 DH |
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 <dh.herrmann@gmail.com> |