0001 ======================================================
0002 UHID - User-space I/O driver support for HID subsystem
0003 ======================================================
0004
0005 UHID allows user-space to implement HID transport drivers. Please see
0006 hid-transport.rst for an introduction into HID transport drivers. This document
0007 relies heavily on the definitions declared there.
0008
0009 With UHID, a user-space transport driver can create kernel hid-devices for each
0010 device connected to the user-space controlled bus. The UHID API defines the I/O
0011 events provided from the kernel to user-space and vice versa.
0012
0013 There is an example user-space application in ./samples/uhid/uhid-example.c
0014
0015 The UHID API
0016 ------------
0017
0018 UHID is accessed through a character misc-device. The minor number is allocated
0019 dynamically so you need to rely on udev (or similar) to create the device node.
0020 This is /dev/uhid by default.
0021
0022 If a new device is detected by your HID I/O Driver and you want to register this
0023 device with the HID subsystem, then you need to open /dev/uhid once for each
0024 device you want to register. All further communication is done by read()'ing or
0025 write()'ing "struct uhid_event" objects. Non-blocking operations are supported
0026 by setting O_NONBLOCK::
0027
0028 struct uhid_event {
0029 __u32 type;
0030 union {
0031 struct uhid_create2_req create2;
0032 struct uhid_output_req output;
0033 struct uhid_input2_req input2;
0034 ...
0035 } u;
0036 };
0037
0038 The "type" field contains the ID of the event. Depending on the ID different
0039 payloads are sent. You must not split a single event across multiple read()'s or
0040 multiple write()'s. A single event must always be sent as a whole. Furthermore,
0041 only a single event can be sent per read() or write(). Pending data is ignored.
0042 If you want to handle multiple events in a single syscall, then use vectored
0043 I/O with readv()/writev().
0044 The "type" field defines the payload. For each type, there is a
0045 payload-structure available in the union "u" (except for empty payloads). This
0046 payload contains management and/or device data.
0047
0048 The first thing you should do is send a UHID_CREATE2 event. This will
0049 register the device. UHID will respond with a UHID_START event. You can now
0050 start sending data to and reading data from UHID. However, unless UHID sends the
0051 UHID_OPEN event, the internally attached HID Device Driver has no user attached.
0052 That is, you might put your device asleep unless you receive the UHID_OPEN
0053 event. If you receive the UHID_OPEN event, you should start I/O. If the last
0054 user closes the HID device, you will receive a UHID_CLOSE event. This may be
0055 followed by a UHID_OPEN event again and so on. There is no need to perform
0056 reference-counting in user-space. That is, you will never receive multiple
0057 UHID_OPEN events without a UHID_CLOSE event. The HID subsystem performs
0058 ref-counting for you.
0059 You may decide to ignore UHID_OPEN/UHID_CLOSE, though. I/O is allowed even
0060 though the device may have no users.
0061
0062 If you want to send data on the interrupt channel to the HID subsystem, you send
0063 a HID_INPUT2 event with your raw data payload. If the kernel wants to send data
0064 on the interrupt channel to the device, you will read a UHID_OUTPUT event.
0065 Data requests on the control channel are currently limited to GET_REPORT and
0066 SET_REPORT (no other data reports on the control channel are defined so far).
0067 Those requests are always synchronous. That means, the kernel sends
0068 UHID_GET_REPORT and UHID_SET_REPORT events and requires you to forward them to
0069 the device on the control channel. Once the device responds, you must forward
0070 the response via UHID_GET_REPORT_REPLY and UHID_SET_REPORT_REPLY to the kernel.
0071 The kernel blocks internal driver-execution during such round-trips (times out
0072 after a hard-coded period).
0073
0074 If your device disconnects, you should send a UHID_DESTROY event. This will
0075 unregister the device. You can now send UHID_CREATE2 again to register a new
0076 device.
0077 If you close() the fd, the device is automatically unregistered and destroyed
0078 internally.
0079
0080 write()
0081 -------
0082 write() allows you to modify the state of the device and feed input data into
0083 the kernel. The kernel will parse the event immediately and if the event ID is
0084 not supported, it will return -EOPNOTSUPP. If the payload is invalid, then
0085 -EINVAL is returned, otherwise, the amount of data that was read is returned and
0086 the request was handled successfully. O_NONBLOCK does not affect write() as
0087 writes are always handled immediately in a non-blocking fashion. Future requests
0088 might make use of O_NONBLOCK, though.
0089
0090 UHID_CREATE2:
0091 This creates the internal HID device. No I/O is possible until you send this
0092 event to the kernel. The payload is of type struct uhid_create2_req and
0093 contains information about your device. You can start I/O now.
0094
0095 UHID_DESTROY:
0096 This destroys the internal HID device. No further I/O will be accepted. There
0097 may still be pending messages that you can receive with read() but no further
0098 UHID_INPUT events can be sent to the kernel.
0099 You can create a new device by sending UHID_CREATE2 again. There is no need to
0100 reopen the character device.
0101
0102 UHID_INPUT2:
0103 You must send UHID_CREATE2 before sending input to the kernel! This event
0104 contains a data-payload. This is the raw data that you read from your device
0105 on the interrupt channel. The kernel will parse the HID reports.
0106
0107 UHID_GET_REPORT_REPLY:
0108 If you receive a UHID_GET_REPORT request you must answer with this request.
0109 You must copy the "id" field from the request into the answer. Set the "err"
0110 field to 0 if no error occurred or to EIO if an I/O error occurred.
0111 If "err" is 0 then you should fill the buffer of the answer with the results
0112 of the GET_REPORT request and set "size" correspondingly.
0113
0114 UHID_SET_REPORT_REPLY:
0115 This is the SET_REPORT equivalent of UHID_GET_REPORT_REPLY. Unlike GET_REPORT,
0116 SET_REPORT never returns a data buffer, therefore, it's sufficient to set the
0117 "id" and "err" fields correctly.
0118
0119 read()
0120 ------
0121 read() will return a queued output report. No reaction is required to any of
0122 them but you should handle them according to your needs.
0123
0124 UHID_START:
0125 This is sent when the HID device is started. Consider this as an answer to
0126 UHID_CREATE2. This is always the first event that is sent. Note that this
0127 event might not be available immediately after write(UHID_CREATE2) returns.
0128 Device drivers might require delayed setups.
0129 This event contains a payload of type uhid_start_req. The "dev_flags" field
0130 describes special behaviors of a device. The following flags are defined:
0131
0132 - UHID_DEV_NUMBERED_FEATURE_REPORTS
0133 - UHID_DEV_NUMBERED_OUTPUT_REPORTS
0134 - UHID_DEV_NUMBERED_INPUT_REPORTS
0135
0136 Each of these flags defines whether a given report-type uses numbered
0137 reports. If numbered reports are used for a type, all messages from
0138 the kernel already have the report-number as prefix. Otherwise, no
0139 prefix is added by the kernel.
0140 For messages sent by user-space to the kernel, you must adjust the
0141 prefixes according to these flags.
0142
0143 UHID_STOP:
0144 This is sent when the HID device is stopped. Consider this as an answer to
0145 UHID_DESTROY.
0146
0147 If you didn't destroy your device via UHID_DESTROY, but the kernel sends an
0148 UHID_STOP event, this should usually be ignored. It means that the kernel
0149 reloaded/changed the device driver loaded on your HID device (or some other
0150 maintenance actions happened).
0151
0152 You can usually ignore any UHID_STOP events safely.
0153
0154 UHID_OPEN:
0155 This is sent when the HID device is opened. That is, the data that the HID
0156 device provides is read by some other process. You may ignore this event but
0157 it is useful for power-management. As long as you haven't received this event
0158 there is actually no other process that reads your data so there is no need to
0159 send UHID_INPUT2 events to the kernel.
0160
0161 UHID_CLOSE:
0162 This is sent when there are no more processes which read the HID data. It is
0163 the counterpart of UHID_OPEN and you may as well ignore this event.
0164
0165 UHID_OUTPUT:
0166 This is sent if the HID device driver wants to send raw data to the I/O
0167 device on the interrupt channel. You should read the payload and forward it to
0168 the device. The payload is of type "struct uhid_output_req".
0169 This may be received even though you haven't received UHID_OPEN yet.
0170
0171 UHID_GET_REPORT:
0172 This event is sent if the kernel driver wants to perform a GET_REPORT request
0173 on the control channel as described in the HID specs. The report-type and
0174 report-number are available in the payload.
0175 The kernel serializes GET_REPORT requests so there will never be two in
0176 parallel. However, if you fail to respond with a UHID_GET_REPORT_REPLY, the
0177 request might silently time out.
0178 Once you read a GET_REPORT request, you shall forward it to the HID device and
0179 remember the "id" field in the payload. Once your HID device responds to the
0180 GET_REPORT (or if it fails), you must send a UHID_GET_REPORT_REPLY to the
0181 kernel with the exact same "id" as in the request. If the request already
0182 timed out, the kernel will ignore the response silently. The "id" field is
0183 never re-used, so conflicts cannot happen.
0184
0185 UHID_SET_REPORT:
0186 This is the SET_REPORT equivalent of UHID_GET_REPORT. On receipt, you shall
0187 send a SET_REPORT request to your HID device. Once it replies, you must tell
0188 the kernel about it via UHID_SET_REPORT_REPLY.
0189 The same restrictions as for UHID_GET_REPORT apply.
0190
0191 ----------------------------------------------------
0192
0193 Written 2012, David Herrmann <dh.herrmann@gmail.com>
