About Kernel Documentation Linux Kernel Contact Linux Resources Linux Blog

Documentation / hid / uhid.txt


Based on kernel version 4.16.1. Page generated on 2018-04-09 11:53 EST.

1	      UHID - User-space I/O driver support for HID subsystem
2	     ========================================================
3	
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.
7	
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.
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 {
30	                struct uhid_create2_req create2;
31	                struct uhid_output_req output;
32	                struct uhid_input2_req input2;
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().
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.
46	
47	The first thing you should do is sending an UHID_CREATE2 event. This will
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	
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).
72	
73	If your device disconnects, you should send an UHID_DESTROY event. This will
74	unregister the device. You can now send UHID_CREATE2 again to register a new
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
82	the kernel. The kernel will parse the event immediately and if the event ID is
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
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.
88	
89	  UHID_CREATE2:
90	  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.
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.
98	  You can create a new device by sending UHID_CREATE2 again. There is no need to
99	  reopen the character device.
100	
101	  UHID_INPUT2:
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.
110	  If "err" is 0 then you should fill the buffer of the answer with the results
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.
117	
118	read()
119	------
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.
122	
123	  UHID_START:
124	  This is sent when the HID device is started. Consider this as an answer to
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.
139	
140	  UHID_STOP:
141	  This is sent when the HID device is stopped. Consider this as an answer to
142	  UHID_DESTROY.
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.
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
154	  send UHID_INPUT2 events to the kernel.
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
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".
164	  This may be received even though you haven't received UHID_OPEN, yet.
165	
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>
Hide Line Numbers


About Kernel Documentation Linux Kernel Contact Linux Resources Linux Blog