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