About Kernel Documentation Linux Kernel Contact Linux Resources Linux Blog

Documentation / hid / hid-sensor.txt




Custom Search

Based on kernel version 4.1. Page generated on 2015-06-28 12:12 EST.

1	
2	HID Sensors Framework
3	======================
4	HID sensor framework provides necessary interfaces to implement sensor drivers,
5	which are connected to a sensor hub. The sensor hub is a HID device and it provides
6	a report descriptor conforming to HID 1.12 sensor usage tables.
7	
8	Description from the HID 1.12 "HID Sensor Usages" specification:
9	"Standardization of HID usages for sensors would allow (but not require) sensor
10	hardware vendors to provide a consistent Plug And Play interface at the USB boundary,
11	thereby enabling some operating systems to incorporate common device drivers that
12	could be reused between vendors, alleviating any need for the vendors to provide
13	the drivers themselves."
14	
15	This specification describes many usage IDs, which describe the type of sensor
16	and also the individual data fields. Each sensor can have variable number of
17	data fields. The length and order is specified in the report descriptor. For
18	example a part of report descriptor can look like:
19	
20	   INPUT(1)[INPUT]
21	 ..
22	    Field(2)
23	      Physical(0020.0073)
24	      Usage(1)
25	        0020.045f
26	      Logical Minimum(-32767)
27	      Logical Maximum(32767)
28	      Report Size(8)
29	      Report Count(1)
30	      Report Offset(16)
31	      Flags(Variable Absolute)
32	..
33	..
34	
35	The report is indicating "sensor page (0x20)" contains an accelerometer-3D (0x73).
36	This accelerometer-3D has some fields. Here for example field 2 is motion intensity
37	(0x045f) with a logical minimum value of -32767 and logical maximum of 32767. The
38	order of fields and length of each field is important as the input event raw
39	data will use this format.
40	
41	
42	Implementation
43	=================
44	
45	This specification defines many different types of sensors with different sets of
46	data fields. It is difficult to have a common input event to user space applications,
47	for different sensors. For example an accelerometer can send X,Y and Z data, whereas
48	an ambient light sensor can send illumination data.
49	So the implementation has two parts:
50	- Core hid driver
51	- Individual sensor processing part (sensor drivers)
52	
53	Core driver
54	-----------
55	The core driver registers (hid-sensor-hub) registers as a HID driver. It parses
56	report descriptors and identifies all the sensors present. It adds an MFD device
57	with name HID-SENSOR-xxxx (where xxxx is usage id from the specification).
58	For example
59	HID-SENSOR-200073 is registered for an Accelerometer 3D driver.
60	So if any driver with this name is inserted, then the probe routine for that
61	function will be called. So an accelerometer processing driver can register
62	with this name and will be probed if there is an accelerometer-3D detected.
63	
64	The core driver provides a set of APIs which can be used by the processing
65	drivers to register and get events for that usage id. Also it provides parsing
66	functions, which get and set each input/feature/output report.
67	
68	Individual sensor processing part (sensor drivers)
69	-----------
70	The processing driver will use an interface provided by the core driver to parse
71	the report and get the indexes of the fields and also can get events. This driver
72	can use IIO interface to use the standard ABI defined for a type of sensor.
73	
74	
75	Core driver Interface
76	=====================
77	
78	Callback structure:
79	Each processing driver can use this structure to set some callbacks.
80		int (*suspend)(..): Callback when HID suspend is received
81		int (*resume)(..): Callback when HID resume is received
82		int (*capture_sample)(..): Capture a sample for one of its data fields
83		int (*send_event)(..): One complete event is received which can have
84	                               multiple data fields.
85	
86	Registration functions:
87	int sensor_hub_register_callback(struct hid_sensor_hub_device *hsdev,
88				u32 usage_id,
89				struct hid_sensor_hub_callbacks *usage_callback):
90	
91	Registers callbacks for an usage id. The callback functions are not allowed
92	to sleep.
93	
94	
95	int sensor_hub_remove_callback(struct hid_sensor_hub_device *hsdev,
96				u32 usage_id):
97	
98	Removes callbacks for an usage id.
99	
100	
101	Parsing function:
102	int sensor_hub_input_get_attribute_info(struct hid_sensor_hub_device *hsdev,
103				u8 type,
104				u32 usage_id, u32 attr_usage_id,
105				struct hid_sensor_hub_attribute_info *info);
106	
107	A processing driver can look for some field of interest and check if it exists
108	in a report descriptor. If it exists it will store necessary information
109	so that fields can be set or get individually.
110	These indexes avoid searching every time and getting field index to get or set.
111	
112	
113	Set Feature report
114	int sensor_hub_set_feature(struct hid_sensor_hub_device *hsdev, u32 report_id,
115				u32 field_index, s32 value);
116	
117	This interface is used to set a value for a field in feature report. For example
118	if there is a field report_interval, which is parsed by a call to
119	sensor_hub_input_get_attribute_info before, then it can directly set that individual
120	field.
121	
122	
123	int sensor_hub_get_feature(struct hid_sensor_hub_device *hsdev, u32 report_id,
124				u32 field_index, s32 *value);
125	
126	This interface is used to get a value for a field in input report. For example
127	if there is a field report_interval, which is parsed by a call to
128	sensor_hub_input_get_attribute_info before, then it can directly get that individual
129	field value.
130	
131	
132	int sensor_hub_input_attr_get_raw_value(struct hid_sensor_hub_device *hsdev,
133				u32 usage_id,
134				u32 attr_usage_id, u32 report_id);
135	
136	This is used to get a particular field value through input reports. For example
137	accelerometer wants to poll X axis value, then it can call this function with
138	the usage id of X axis. HID sensors can provide events, so this is not necessary
139	to poll for any field. If there is some new sample, the core driver will call
140	registered callback function to process the sample.
141	
142	
143	----------
144	
145	HID Custom and generic Sensors
146	
147	HID Sensor specification defines two special sensor usage types. Since they
148	don't represent a standard sensor, it is not possible to define using Linux IIO
149	type interfaces.
150	The purpose of these sensors is to extend the functionality or provide a
151	way to obfuscate the data being communicated by a sensor. Without knowing the
152	mapping between the data and its encapsulated form, it is difficult for
153	an application/driver to determine what data is being communicated by the sensor.
154	This allows some differentiating use cases, where vendor can provide applications.
155	Some common use cases are debug other sensors or to provide some events like
156	keyboard attached/detached or lid open/close.
157	
158	To allow application to utilize these sensors, here they are exported uses sysfs
159	attribute groups, attributes and misc device interface.
160	
161	An example of this representation on sysfs:
162	/sys/devices/pci0000:00/INT33C2:00/i2c-0/i2c-INT33D1:00/0018:8086:09FA.0001/HID-SENSOR-2000e1.6.auto$ tree -R
163	.
164	????????? enable_sensor
165	????????? feature-0-200316
166	??????? ????????? feature-0-200316-maximum
167	??????? ????????? feature-0-200316-minimum
168	??????? ????????? feature-0-200316-name
169	??????? ????????? feature-0-200316-size
170	??????? ????????? feature-0-200316-unit-expo
171	??????? ????????? feature-0-200316-units
172	??????? ????????? feature-0-200316-value
173	????????? feature-1-200201
174	??????? ????????? feature-1-200201-maximum
175	??????? ????????? feature-1-200201-minimum
176	??????? ????????? feature-1-200201-name
177	??????? ????????? feature-1-200201-size
178	??????? ????????? feature-1-200201-unit-expo
179	??????? ????????? feature-1-200201-units
180	??????? ????????? feature-1-200201-value
181	????????? input-0-200201
182	??????? ????????? input-0-200201-maximum
183	??????? ????????? input-0-200201-minimum
184	??????? ????????? input-0-200201-name
185	??????? ????????? input-0-200201-size
186	??????? ????????? input-0-200201-unit-expo
187	??????? ????????? input-0-200201-units
188	??????? ????????? input-0-200201-value
189	????????? input-1-200202
190	??????? ????????? input-1-200202-maximum
191	??????? ????????? input-1-200202-minimum
192	??????? ????????? input-1-200202-name
193	??????? ????????? input-1-200202-size
194	??????? ????????? input-1-200202-unit-expo
195	??????? ????????? input-1-200202-units
196	??????? ????????? input-1-200202-value
197	
198	Here there is a custom sensors with four fields, two feature and two inputs.
199	Each field is represented by a set of attributes. All fields except the "value"
200	are read only. The value field is a RW field.
201	Example
202	/sys/bus/platform/devices/HID-SENSOR-2000e1.6.auto/feature-0-200316$ grep -r . *
203	feature-0-200316-maximum:6
204	feature-0-200316-minimum:0
205	feature-0-200316-name:property-reporting-state
206	feature-0-200316-size:1
207	feature-0-200316-unit-expo:0
208	feature-0-200316-units:25
209	feature-0-200316-value:1
210	
211	How to enable such sensor?
212	By default sensor can be power gated. To enable sysfs attribute "enable" can be
213	used.
214	$ echo 1 > enable_sensor
215	
216	Once enabled and powered on, sensor can report value using HID reports.
217	These reports are pushed using misc device interface in a FIFO order.
218	/dev$ tree | grep HID-SENSOR-2000e1.6.auto
219	??????? ????????? 10:53 -> ../HID-SENSOR-2000e1.6.auto
220	????????? HID-SENSOR-2000e1.6.auto
221	
222	Each reports can be of variable length preceded by a header. This header
223	consist of a 32 bit usage id, 64 bit time stamp and 32 bit length field of raw
224	data.
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.