About Kernel Documentation Linux Kernel Contact Linux Resources Linux Blog

Documentation / hid / uhid.txt




Custom Search

Based on kernel version 3.15.4. Page generated on 2014-07-07 09:03 EST.

1	      UHID - User-space I/O driver support for HID subsystem
2	     ========================================================
3	
4	The HID subsystem needs two kinds of drivers. In this document we call them:
5	
6	 1. The "HID I/O Driver" is the driver that performs raw data I/O to the
7	    low-level device. Internally, they register an hid_ll_driver structure with
8	    the HID core. They perform device setup, read raw data from the device and
9	    push it into the HID subsystem and they provide a callback so the HID
10	    subsystem can send data to the device.
11	
12	 2. The "HID Device Driver" is the driver that parses HID reports and reacts on
13	    them. There are generic drivers like "generic-usb" and "generic-bluetooth"
14	    which adhere to the HID specification and provide the standardizes features.
15	    But there may be special drivers and quirks for each non-standard device out
16	    there. Internally, they use the hid_driver structure.
17	
18	Historically, the USB stack was the first subsystem to provide an HID I/O
19	Driver. However, other standards like Bluetooth have adopted the HID specs and
20	may provide HID I/O Drivers, too. The UHID driver allows to implement HID I/O
21	Drivers in user-space and feed the data into the kernel HID-subsystem.
22	
23	This allows user-space to operate on the same level as USB-HID, Bluetooth-HID
24	and similar. It does not provide a way to write HID Device Drivers, though. Use
25	hidraw for this purpose.
26	
27	There is an example user-space application in ./samples/uhid/uhid-example.c
28	
29	The UHID API
30	------------
31	
32	UHID is accessed through a character misc-device. The minor-number is allocated
33	dynamically so you need to rely on udev (or similar) to create the device node.
34	This is /dev/uhid by default.
35	
36	If a new device is detected by your HID I/O Driver and you want to register this
37	device with the HID subsystem, then you need to open /dev/uhid once for each
38	device you want to register. All further communication is done by read()'ing or
39	write()'ing "struct uhid_event" objects. Non-blocking operations are supported
40	by setting O_NONBLOCK.
41	
42	struct uhid_event {
43	        __u32 type;
44	        union {
45	                struct uhid_create_req create;
46	                struct uhid_data_req data;
47	                ...
48	        } u;
49	};
50	
51	The "type" field contains the ID of the event. Depending on the ID different
52	payloads are sent. You must not split a single event across multiple read()'s or
53	multiple write()'s. A single event must always be sent as a whole. Furthermore,
54	only a single event can be sent per read() or write(). Pending data is ignored.
55	If you want to handle multiple events in a single syscall, then use vectored
56	I/O with readv()/writev().
57	
58	The first thing you should do is sending an UHID_CREATE event. This will
59	register the device. UHID will respond with an UHID_START event. You can now
60	start sending data to and reading data from UHID. However, unless UHID sends the
61	UHID_OPEN event, the internally attached HID Device Driver has no user attached.
62	That is, you might put your device asleep unless you receive the UHID_OPEN
63	event. If you receive the UHID_OPEN event, you should start I/O. If the last
64	user closes the HID device, you will receive an UHID_CLOSE event. This may be
65	followed by an UHID_OPEN event again and so on. There is no need to perform
66	reference-counting in user-space. That is, you will never receive multiple
67	UHID_OPEN events without an UHID_CLOSE event. The HID subsystem performs
68	ref-counting for you.
69	You may decide to ignore UHID_OPEN/UHID_CLOSE, though. I/O is allowed even
70	though the device may have no users.
71	
72	If you want to send data to the HID subsystem, you send an HID_INPUT event with
73	your raw data payload. If the kernel wants to send data to the device, you will
74	read an UHID_OUTPUT or UHID_OUTPUT_EV event.
75	
76	If your device disconnects, you should send an UHID_DESTROY event. This will
77	unregister the device. You can now send UHID_CREATE again to register a new
78	device.
79	If you close() the fd, the device is automatically unregistered and destroyed
80	internally.
81	
82	write()
83	-------
84	write() allows you to modify the state of the device and feed input data into
85	the kernel. The following types are supported: UHID_CREATE, UHID_DESTROY and
86	UHID_INPUT. The kernel will parse the event immediately and if the event ID is
87	not supported, it will return -EOPNOTSUPP. If the payload is invalid, then
88	-EINVAL is returned, otherwise, the amount of data that was read is returned and
89	the request was handled successfully.
90	
91	  UHID_CREATE:
92	  This creates the internal HID device. No I/O is possible until you send this
93	  event to the kernel. The payload is of type struct uhid_create_req and
94	  contains information about your device. You can start I/O now.
95	
96	  UHID_CREATE2:
97	  Same as UHID_CREATE, but the HID report descriptor data (rd_data) is an array
98	  inside struct uhid_create2_req, instead of a pointer to a separate array.
99	  Enables use from languages that don't support pointers, e.g. Python.
100	
101	  UHID_DESTROY:
102	  This destroys the internal HID device. No further I/O will be accepted. There
103	  may still be pending messages that you can receive with read() but no further
104	  UHID_INPUT events can be sent to the kernel.
105	  You can create a new device by sending UHID_CREATE again. There is no need to
106	  reopen the character device.
107	
108	  UHID_INPUT:
109	  You must send UHID_CREATE before sending input to the kernel! This event
110	  contains a data-payload. This is the raw data that you read from your device.
111	  The kernel will parse the HID reports and react on it.
112	
113	  UHID_INPUT2:
114	  Same as UHID_INPUT, but the data array is the last field of uhid_input2_req.
115	  Enables userspace to write only the required bytes to kernel (ev.type +
116	  ev.u.input2.size + the part of the data array that matters), instead of
117	  the entire struct uhid_input2_req.
118	
119	  UHID_FEATURE_ANSWER:
120	  If you receive a UHID_FEATURE request you must answer with this request. You
121	  must copy the "id" field from the request into the answer. Set the "err" field
122	  to 0 if no error occurred or to EIO if an I/O error occurred.
123	  If "err" is 0 then you should fill the buffer of the answer with the results
124	  of the feature request and set "size" correspondingly.
125	
126	read()
127	------
128	read() will return a queued ouput report. These output reports can be of type
129	UHID_START, UHID_STOP, UHID_OPEN, UHID_CLOSE, UHID_OUTPUT or UHID_OUTPUT_EV. No
130	reaction is required to any of them but you should handle them according to your
131	needs. Only UHID_OUTPUT and UHID_OUTPUT_EV have payloads.
132	
133	  UHID_START:
134	  This is sent when the HID device is started. Consider this as an answer to
135	  UHID_CREATE. This is always the first event that is sent.
136	
137	  UHID_STOP:
138	  This is sent when the HID device is stopped. Consider this as an answer to
139	  UHID_DESTROY.
140	  If the kernel HID device driver closes the device manually (that is, you
141	  didn't send UHID_DESTROY) then you should consider this device closed and send
142	  an UHID_DESTROY event. You may want to reregister your device, though. This is
143	  always the last message that is sent to you unless you reopen the device with
144	  UHID_CREATE.
145	
146	  UHID_OPEN:
147	  This is sent when the HID device is opened. That is, the data that the HID
148	  device provides is read by some other process. You may ignore this event but
149	  it is useful for power-management. As long as you haven't received this event
150	  there is actually no other process that reads your data so there is no need to
151	  send UHID_INPUT events to the kernel.
152	
153	  UHID_CLOSE:
154	  This is sent when there are no more processes which read the HID data. It is
155	  the counterpart of UHID_OPEN and you may as well ignore this event.
156	
157	  UHID_OUTPUT:
158	  This is sent if the HID device driver wants to send raw data to the I/O
159	  device. You should read the payload and forward it to the device. The payload
160	  is of type "struct uhid_data_req".
161	  This may be received even though you haven't received UHID_OPEN, yet.
162	
163	  UHID_OUTPUT_EV (obsolete):
164	  Same as UHID_OUTPUT but this contains a "struct input_event" as payload. This
165	  is called for force-feedback, LED or similar events which are received through
166	  an input device by the HID subsystem. You should convert this into raw reports
167	  and send them to your device similar to events of type UHID_OUTPUT.
168	  This is no longer sent by newer kernels. Instead, HID core converts it into a
169	  raw output report and sends it via UHID_OUTPUT.
170	
171	  UHID_FEATURE:
172	  This event is sent if the kernel driver wants to perform a feature request as
173	  described in the HID specs. The report-type and report-number are available in
174	  the payload.
175	  The kernel serializes feature requests so there will never be two in parallel.
176	  However, if you fail to respond with a UHID_FEATURE_ANSWER in a time-span of 5
177	  seconds, then the requests will be dropped and a new one might be sent.
178	  Therefore, the payload also contains an "id" field that identifies every
179	  request.
180	
181	Document by:
182	  David Herrmann <dh.herrmann@googlemail.com>
Hide Line Numbers
About Kernel Documentation Linux Kernel Contact Linux Resources Linux Blog

Information is copyright its respective author. All material is available from the Linux Kernel Source distributed under a GPL License. This page is provided as a free service by mjmwired.net.