1ca66dd2de818fd13584ec71693b271a1de9a41e
[linux-3.10.git] / Documentation / devicetree / bindings / iio / iqs253-ps.txt
1 * IQS2x3 proximity sensor
2
3 nvs_ drivers use the NVidia Sensor (NVS) framework.
4 See the nvs.txt documentation for NVS DT capabilities.
5 The nvs_iqs2x3 proximity sensor driver supports the IQS253 and IQS263 devices.
6
7 Required properties:
8 - compatible: Device or generic name.
9               Supported device names:
10               - azoteq,iqs2x3
11               - azoteq,iqs253
12               - azoteq,iqs263
13   Note: If the part is known and is populated, then it can be specified:
14         Example: compatible = "azoteq,iqs263";
15         When specifying a device this way, the driver will assume this specific
16         device is populated during system boot and will not verify its
17         existence.  If, however, the device is unknown or may not be populated,
18         then the label, iqs2x3, (Example: compatible = "azoteq,iqs2x3";),
19         must be used.  This tells the driver to find which device is used.  If
20         the device is not found, the driver will unload itself.  This requires
21         regulators to be setup correctly for the probe function.
22 - reg: i2c address of the device. It is one of 0x44-0x47.
23 - gpio_rdy: GPIO to be used for the I2C handshake with the sensor.
24   Note: the gpio_rdy GPIO will be used as an interrupt also.
25
26 The IQS devices have a very versatile register set.  So much so that the entire
27 register set values can be different among platforms.  Because of this, the way
28 and the values used are defined in the device tree.  The driver will read in
29 the DT block of data for each command into a buffer and parse the byte stream
30 to execute the command.
31 The format for each entry of the command is as follows:
32         u8 LENGTH       // The number of data byte pairs (data[N] / 2).
33         u8 REGISTER     // The register to write to.
34         u8 DATA[N]      // The stream of data bytes.  See below description.
35 The DATA[N] contains N number of register values first and then N number of a
36 mask byte corresponding to the Nth data byte.  For example, if 0x12, 0x34 is to
37 be written to a register, and only bits 4:1 are to be written for the first
38 byte, then the byte stream would be: 0x12, 0x34, 0x1E, 0xFF.  Where 0x1E is the
39 mask for the first byte 0x12, and 0xFF is the mask for the second byte 0x34.
40 The entry for this example if the register is, say, 0x56, would be:
41 02, 56, 12, 34, 1E, FF
42
43 The IQS has a funky register set in that each register has its own register
44 length.  The reason LENGTH is still used is that maybe only the first few bytes
45 of a register are to be written.  For example, a register that is 20 bytes long
46 can get by with defining, say 4 for LENGTH, and only the first 4 bytes will be
47 written.
48
49 The DT labeling mechanism is based on the part number and the command to be
50 accomplished. Currently there are four commands: initialization, enable,
51 disable, and event.  For each label, a "_?" is appended where ? is a decimal
52 number starting at 0.  Note the driver will put the entries in the sequence
53 defined by ? and not by the order defined in the DT.
54 An example for initialization of the IQS263 part in the DT is as follows:
55         263init_0 = [05 09 40 03 00 01 03 FF FF FF FF FF]; // 5 bytes to reg 9
56         263init_1 = [01 0D 09 FF]; // 1 byte written to register 0x0D
57         263init_2 = [01 01 00 FF]; // 1 byte written to register 0x01
58         263init_3 = [05 07 1B 08 08 00 11 FF FF FF FF FF]; // 5 bytes to reg 7
59         263init_4 = [08 0A 08 10 10 02 04 08 14 3F FF FF FF FF FF FF FF FF];
60         263init_5 = [03 0B 00 64 80 FF FF FF]; // 3 bytes written to reg 0x0B
61
62 The IQS parts have two "virtual" sensors: SAR_proximity and SAR_touch.
63 The "virtual" means that the NVS framework will split these two sensors so that
64 the system will see two individual sensors.
65 The SAR_proximity detects objects near the platform whereas the SAR_touch
66 detects actual touches with the platform (assuming it's the screen).
67 Because there are two sensors, there are two enable labels: <part>en_prox and
68 <part>en_touch.
69 Here is a DT example of the enable commands for both sensors:
70         263en_prox_0 = [01 09 10 18];   // 1 byte written to register 0x09
71         263en_prox_1 = [FF 00];         // this is an I2C write with no delay.
72         263en_prox_2 = [01 09 08 18];   // 1 byte written to register 0x09
73         263en_touch_0 = [01 09 10 18];  // 1 byte written to register 0x09
74         263en_touch_1 = [FF 00];        // write flush.  See description below.
75         263en_touch_2 = [01 09 08 18];  // 1 byte written to register 0x09
76 Here are the possible disable command labels:
77         263dis_prox_?
78         263dis_touch_?
79         253dis_prox_?
80         253dis_touch_?
81 The disable commands do not need to write to the registers to put the device to
82 sleep.  When the driver sees that all the sensors are disabled it will handle
83 the global sleep.
84 The event command allows any necessary action whenever the device receives an
85 event:
86         263event_?
87         253event_?
88 If partial ATI is enabled, the driver will automatically handle the reseeding.
89 The suspend command allows any necessary action whenever the driver receives
90 notification of a suspend:
91         263suspend_?
92         253suspend_?
93
94 Due to the IQS device's design for communicating with the device, each entry,
95 which represents an I2C transaction, is actually stacked so that the entire
96 command is executed as a single I2C transaction.  That is, I2C restarts are
97 done instead of I2C stops.  For situations where it is desired to write the
98 transactions thus far and have a delay within the command entries, the LENGTH
99 can be set to FF.  This tells the driver's byte stream parsing engine to
100 execute the I2C transactions thus far and if a millisecond delay is to also be
101 done, then the following byte contains the number of milliseconds to wait,
102 otherwise the following byte's value is 0.
103 The FF does NOT need to be entered at the end of a byte stream command.  The
104 driver's byte stream parsing engine will automatically execute the I2C
105 transactions.
106 It is strongly recommended to not use the flush write within an event command
107 byte stream.
108
109 FYI, internally to the driver, the byte stream terminates when LENGTH is 0.
110 This is handled automatically by the driver's DT parsing, but is an FYI so that
111 0 is never used for LENGTH.
112 The driver's DT parsing engine has error checking and will exit with an error
113 of "ERR: NOMEM @ %s" where %s will be the DT label where things went south.
114 The error can be due to truly out of buffer memory to non-existent register or
115 incorrect register length.  Once the driver has loaded, a debug feature that
116 will dump the parsed byte stream can be done by doing the following at the
117 device's sysfs directory in an adb terminal prompt:
118 #echo 0xXXYYZZ1E > nvs
119 where XX = part device ID (0x29=IQS253, 0x3C=IQS263)
120            If XX is 0, then the part in use will be used.
121       YY = command
122            Possible commands are:
123            1: initialization
124            2: enable
125            3: disable
126            4: event
127            5: suspend
128            6: delta (see delta options far below)
129            If YY is 0, then all the commands will be displayed.
130       ZZ = device
131            Possible devices are:
132            1: SAR_proximiy
133            2: SAR_touch
134            If ZZ is 0, then all the devices will be displayed.
135 Ideally, the 0x1E command would always be used.  However, if not all the data
136 or corruption is displayed due to an undersized buffer (out of the driver's
137 control) then the above formatting allows less data to be shown at once.
138 #cat nvs
139 The results for 0x1001E will be something like:
140         iqs263 initialization:
141         len=5 reg=9 data/mask=40/ff 3/ff 0/ff 1/ff 3/ff
142         len=1 reg=d data/mask=9/ff
143         len=1 reg=1 data/mask=0/ff
144         len=5 reg=7 data/mask=1b/ff 8/ff 8/ff 0/ff 11/ff
145         len=8 reg=a data/mask=8/ff 10/ff 10/ff 2/ff 4/ff 8/ff 14/ff 3f/ff
146         len=3 reg=b data/mask=0/ff 64/ff 80/ff
147 The results for 0x2001E will be something like:
148         iqs263 SAR_proximity enable:
149         len=1 reg=9 data/mask=10/18
150         flush write and mdelay=0
151         len=1 reg=9 data/mask=8/18
152         iqs263 SAR_touch enable:
153         <empty>
154
155 Also, a register dump can be done:
156 #echo 4 > nvs
157 #cat nvs
158 During the tuning process, a debug feature can write a byte to a register:
159 #echo 0xXXYYZZ1D > nvs
160 where XX = the register
161       YY = the register offset
162       ZZ = the byte value
163 Other driver debug commands:
164 #echo 0x??1C > nvs
165 writes ?? to the gpio_sar GPIO.
166 #echo 0x??1B > nvs
167 writes ?? to the gpio_rdy GPIO.
168 #echo 0x1A > nvs
169 switches the gpio_rdy GPIO to input.
170
171 For overall status information:
172 #echo 10 > nvs
173 #cat nvs
174 The results will be something like:
175         IQS driver v. 16
176         ATI redo count=0
177         os_options=0
178         stream_mode=2
179         watchdog_timeout_ms=30000
180         i2c_ss_delay_ns=1000000
181         i2c_retry=10
182         gpio_rdy_retry=25
183         gpio_rdy 1=1
184         gpio_sar 173=0
185         gpio_sar_assert_polarity=0
186         gpio_sar_dev_assert=SAR_proximity
187         gpio_sar_dev_deassert=SAR_proximity
188         gpio_sar_suspend_assert=1
189         deferred_resume_ms=3000
190         resume=0
191         SAR_delta_channel_mask=5
192         SAR_delta_average_count=10
193         irq=2
194         irq_disable=0
195         irq_trigger_edge=0
196         SAR_proximity_binary_hw=1
197         SAR_touch_binary_hw=1
198 When this status is read, the ATI redo count will reset to 0.
199
200 In the case the part populated could be either IQS253 or IQS263, both the 253
201 and 263 commands can be defined in the DT.  The driver will use the one
202 according to the part identified.
203
204 Optional properties:
205 - status: set to "ok" or "okay" for normal operation.  Set to anything else
206           to unload the driver without ever communicating with the device.
207   Note: The "anything else" above is typically "disabled".
208         Since the driver will unload without communicating with the device, the
209         device will be left in its POR state.
210         This device's POR comes up in an operational mode and will draw power.
211         If it is desired to unload the driver leaving the device in a low power
212         sleep state, then use the individual sensor disable mechanism below.
213 - SAR_proximity_disable: Setting this property to <1> will disable the
214                          SAR proximity.
215 - SAR_touch_disable: Setting this property to <1> will disable the
216                            touch sensor.
217   Note: To disable the entire device so that the driver unloads, all sensors
218         must be disabled:
219         SAR_proximity_disable = <1>;
220         SAR_touch_disable = <1>;
221 - vddhi-supply: regulator supply for the chip
222   Note: This is required if the driver is to control the regulator.
223 - gpio_sar: GPIO to be used for sending proximity event for SAR sensor.
224   Note: The gpio_sar define is not required if the following is true:
225         - The device's PO pin is wired to the device requiring the SAR event.
226         - The assert level is high.
227         - The IQS SAR_proximity is configured as a binary value.
228 - gpio_sar_assert_polarity: assert level of the GPIO for the SAR event.
229   Note: gpio_sar_assert_polarity is ONLY for the SAR GPIO and is not needed if
230         the GPIO assert value is low since low is the SAR GPIO assert default.
231         It may still be defined as low (gpio_sar_assert_polarity = <0>;)
232         however.
233 - gpio_sar_dev: Which IQS device controls the SAR GPIO.  In other words, the
234                 SAR GPIO will assert according to the gpio_sar_assert_polarity
235                 when the sensor specified in gpio_sar_dev asserts.
236   Note: The SAR GPIO can also be used for debug purposes.  When set to one of
237         the debug options, the SAR GPIO will not be controlled by one of the
238         SAR sensors but instead the debug function.
239         The gpio_sar_dev options are:
240         - SAR_proximity
241         - SAR_touch
242         - debug_i2c
243         SAR_proximity is the default if no entry is made.
244         Due to this device's I2C "issues", the debug_i2c option will assert the
245         SAR GPIO (according to the gpio_sar_assert_polarity) when an I2C
246         transaction is about to start and deasserts when the I2C transaction
247         finishes.
248 - gpio_sar_suspend_assert: If the device is not configured to operate during
249                            suspend then this determines the SAR GPIO setting
250                            during suspend:
251                            -1 = DISABLE: SAR GPIO remains at current state from
252                                          when device was operational.
253                            0 = !ASSERT: GPIO is not asserted according to
254                                         gpio_sar_assert_polarity.
255                            1 = ASSERT: GPIO is asserted according to
256                                        gpio_sar_assert_polarity.
257 - os_options: If the IQS device is to be controlled by the OS then set this
258               value to 1.  The default is 0.
259   Note: The SAR_proximity and SAR_touch sensors can still be exposed to
260         the OS via the NVS framework's NvspDriver structure.  However, unless
261         os_options is > 0, the OS will be tricked into thinking is has control.
262         In other words, when os_options is 0 (the default), the device will
263         always be enabled.
264 - irq_trigger_edge: Set to 1 if interrupt is to configured as
265                     IRQF_TRIGGER_FALLING.  Otherwise the interrupt will be
266                     configured as IRQF_TRIGGER_LOW.  Using IRQF_TRIGGER_LOW
267                     addresses false triggers while the interrupt is disabled
268                     during the forced communication protocol.
269 - stream_mode: The device triggers an interrupt on every device data cycle.
270   Note: As mentioned above, the IQS devices have an, um, interesting mechanism
271         for communication where there is a small window of time where the
272         device will respond to I2C commands (the reason for I2C transaction
273         stacking).  When stream mode is disabled, the driver uses a combination
274         of disabling/enabling the interrupt, which also doubles in forcing the
275         communication window, and reading the device's status and data via
276         stream and event modes.  The mechanism allows the device to not
277         interrupt the AP unless an event has occured, thereby saving power.
278         However, depending on how the device is configured by the DT commands,
279         it may be desirable to disable this feature and continually stream the
280         data instead.
281         If the IQS has the slider enabled the device will stream automatically
282         during a slider event.  In this case, the disabling/enabling stream
283         mode mechanism above may not be needed and can be disabled by entering
284         the auto value for steam_mode.
285         Possible stream_mode values are:
286         0 = OFF: Event mode will automatically be enabled by the driver and the
287                  above communication mechanism described above used.
288         1 = ON:  Streaming mode is enabled.  No special communication mechanism
289                  is needed since driver gets constantly interrupted with a comm
290                  window.  However, the interrupts may be throttled (disabled
291                  for a period).
292         2 = AUTO: Event mode is enabled but the special communication mechanism
293                   described above is not used.  Instead, it is expected and
294                   required that the device be configured with the slider
295                   enabled to allow for automatic device initiated streaming.
296 - watchdog_timeout_ms: When streaming mode is disabled, a watchdog can
297                        periodically stream the data to confirm the device's
298                        status.
299   Note: The watchdog timer is actually recommended by Azoteq.
300         If this is not defined, the default will be 30 seconds.
301 - deferred_resume_ms: The delay in milliseconds of when to execute the resume.
302                       Due to the time consumed trying to communicate with the
303                       device, suspend and resume can be adversely affected.
304                       This setting allows resume to be deferred for the amount
305                       of time specified; consider the situation where the
306                       system resumes for a very short period and then suspends
307                       again.  If this situation happened within this deferred
308                       resume time, then the whole process of resuming and
309                       suspending again would not require any communication with
310                       the device thereby not affecting the overall system.
311 - i2c_retry: The number of times to try an I2C transaction before bailing.
312 - gpio_rdy_retry: The number of times to try forcing a communication window.
313   Note: When I2C communication is attempted outside the communication window by
314         pulling the gpio_rdy GPIO low (the GPIO also doubles as the interrupt),
315         the i2c_retry and gpio_rdy_retry provide the limits before the driver
316         will consider the communication attempt a failure.
317         The defaults are 10 and 25 respectively.  The sequence of events for a
318         communication attempt are:
319         1. disable gpio_rdy interrupt
320         2. assert gpio_rdy GPIO low
321         3. wait 11ms according to Azotec spec
322         4. release gpio_rdy GPIO
323         5. gpio_rdy_retry--
324         5. wait ~750us according to Azotec spec
325         6. if gpio_rdy not low and gpio_rdy_retry > 0 then step 2.
326         If all is well so far, do I2C transaction(s), but if an I2C failure,
327         then repeat above steps. This is done i2c_retry times before exiting as
328         a failure.
329         BTW, this is all done according to the Azotec spec.
330
331 There may a situation where intermittent noise on a channel is causing
332 unreliable data.  If this is the case, the delta options below can help
333 determine the proximity state.  This is accomplished by creating virtual delta
334 SW sensors for each channel.  Each SW sensor created will have the name
335 SAR_delta_chX, where X is the channel number and the data acquired is the delta
336 data from the HW pertaining to that channel.  By defining a delta algorithm in
337 the device tree that can use each SW sensor's data, a global SW delta sensor
338 named SAR_delta is used as the final result of the algorithm.  Each algorithm
339 entry in device tree uses the following stucture:
340 struct iqs_delta_tst {
341         int ch;
342         int lt;
343         int gt;
344 };
345 The DT algorithm uses two levels of conditionals.  The first level uses the
346 label SAR_delta_test_X_Y, where X is the entry number and Y is one of the
347 members of the iqs_delta_tst structure.  If all of the first level entrie's
348 conditions result as true, then the second level of conditionals named
349 SAR_delta_test_true_X_Y are executed.  If any of the first level entrie's
350 conditions result in false, then the second level of conditionals named
351 SAR_delta_test_false_X_Y are executed.  The result of the second level of
352 conditionals is the data for the SAR_delta virtual SW sensor.
353 Four entries are allowed for each level of conditionals.  Each entry must not
354 use a negative value.  Each entry must have a valid channel (0 - 3) and at
355 least one of the conditional values.  Here are how the conditionals are used,
356 where d[ch] is the channels SAR_delta_chX delta data which may be a moving
357 average if that feature is enabled (see SAR_delta_average_count below):
358 Entry:
359         SAR_delta_test_0_ch = <0>;
360         SAR_delta_test_0_lt = <50>;
361 Conditional:
362         if (d[0] < 50)
363 Entry:
364         SAR_delta_test_0_ch = <1>;
365         SAR_delta_test_0_gt = <50>;
366 Conditional:
367         if (d[1] > 50)
368 Entry:
369         SAR_delta_test_0_ch = <2>;
370         SAR_delta_test_0_lt = <50>;
371         SAR_delta_test_0_gt = <100>;
372 Conditional:
373         if (d[2] < 50 || d[2] > 100)
374 Entry:
375         SAR_delta_test_0_ch = <3>;
376         SAR_delta_test_0_lt = <100>;
377         SAR_delta_test_0_gt = <50>;
378 Conditional:
379         if (d[3] > 50 && d[3] < 100)
380 Note how ranges can be used depending on whether the lt value is less than or
381 greater than the gt value.
382 The conditionals can be displayed at runtime with the following command in the
383 driver space:
384 #echo 0x6001E > nvs
385 The following are the results from the DT example below:
386 #cat nvs
387 DELTA conditions:
388 SAR_delta_test:
389 if (ch2 < 75)
390 if SAR_delta_test_true:
391 if (ch0 > 5)
392 if (ch2 > 5 && ch2 < 50)
393 if SAR_delta_test_false:
394 if (ch0 > 5)
395 if (ch2 > 75 && ch2 < 90)
396
397 - SAR_delta_channel_mask: The channel mask of the SW delta sensors to create.
398                           A value of 0 disables the feature.  The default is 0.
399 - SAR_delta_average_count: The delta values for each channel can use a moving
400                            average.  This value sets the number of samples to
401                            use for each average calculation.  A value < 2
402                            disables the feature.  The default is 0.
403
404 And finally, an example:
405
406         iqs263@44 {
407                 compatible = "azoteq,iqs2x3";
408                 reg = <0x44>;
409                 vddhi-supply = <&vdd_3v3>;
410                 gpio_rdy = <&gpio TEGRA_GPIO(A, 1) GPIO_ACTIVE_LOW>;
411                 gpio_sar = <&gpio TEGRA_GPIO(V, 5) GPIO_ACTIVE_HIGH>;
412                 gpio_sar_dev = "SAR_touch";
413                 stream_mode = <2>;
414                 os_options = <0>;
415                 263suspend_0 = [01 0D 01 FF];
416                 263suspend_1 = [03 0B 00 0A 0A FF FF FF];
417                 263suspend_2 = [01 09 10 FF];
418                 263suspend_3 = [FF FF];
419                 263suspend_4 = [FF FF];
420                 263suspend_5 = [05 09 80 40 00 00 00 FF FF FF FF FF];
421                 263suspend_6 = [03 0A FF FF FF FF FF FF];
422                 263suspend_7 = [01 0B 0F FF];
423                 263init_0 = [05 09 80 04 10 07 0F FF FF FF FF FF];
424                 263init_1 = [01 0D 07 FF];
425                 263init_2 = [01 01 00 FF];
426                 263init_3 = [05 07 1D 0A 0C 00 11 FF FF FF FF FF];
427                 263init_4 = [04 08 B2 D9 D8 00 FF FF FF FF];
428                 263init_5 = [08 0A 08 03 03 03 0C 00 64 14 FF FF FF FF FF FF FF FF];
429                 263init_6 = [03 0B 00 A5 B4 FF FF FF];
430                 263en_prox_0 = [01 09 10 FF];
431                 263en_prox_1 = [FF FF];
432                 263en_prox_2 = [FF FF];
433                 263en_prox_3 = [FF FF];
434                 263en_prox_4 = [FF FF];
435                 263en_prox_5 = [02 09 00 54 FF FF];
436                 SAR_delta_channel_mask = <0x5>;
437                 SAR_delta_average_count = <10>;
438                 SAR_delta_test_0_ch = <2>;
439                 SAR_delta_test_0_lt = <75>;
440                 SAR_delta_test_true_0_ch = <0>;
441                 SAR_delta_test_true_0_gt = <5>;
442                 SAR_delta_test_true_1_ch = <2>;
443                 SAR_delta_test_true_1_lt = <50>;
444                 SAR_delta_test_true_1_gt = <5>;
445                 SAR_delta_test_false_0_ch = <0>;
446                 SAR_delta_test_false_0_gt = <5>;
447                 SAR_delta_test_false_1_ch = <2>;
448                 SAR_delta_test_false_1_lt = <90>;
449                 SAR_delta_test_false_1_gt = <75>;
450         };