iio: proximity: SAR v17 binary filter
[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. 17
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_deassert: Which IQS device controls the deassertion of the SAR
234                          GPIO.  In other words, the SAR GPIO will deassert
235                          according to the gpio_sar_assert_polarity when the
236                          sensor specified in gpio_sar_dev_deassert deasserts.
237 - gpio_sar_dev_assert: Which IQS device controls the assertion of the SAR GPIO.
238                        In other words, the SAR GPIO will assert according to
239                        the gpio_sar_assert_polarity when the sensor specified
240                        in gpio_sar_dev_assert asserts.
241   Note: The SAR GPIO can also be used for debug purposes.  When set to one of
242         the debug options, the SAR GPIO will not be controlled by one of the
243         SAR sensors but instead the debug function.
244         The gpio_sar_dev options are:
245         - SAR_proximity
246         - SAR_touch
247         - SAR_delta
248         - debug_i2c
249         SAR_proximity is the default if no entry is made.
250         Due to this device's I2C "issues", the debug_i2c option will assert the
251         SAR GPIO (according to the gpio_sar_assert_polarity) when an I2C
252         transaction is about to start and deasserts when the I2C transaction
253         finishes.
254 - SAR_<device>_debounce_lo: Each SAR sensor (proximity and touch) in HW binary
255                             mode can be debounced.  To enable this feature, set
256                             this option to a value > 0.  The lo feature will
257                             allow the data state to go low only after the
258                             number of consecutive low reads defined here.
259 - SAR_<device>_debounce_hi: Each SAR sensor (proximity and touch) in HW binary
260                             mode can be debounced.  To enable this feature, set
261                             this option to a value > 0.  The hi feature will
262                             allow the data state to go high only after the
263                             number of consecutive high reads defined here.
264  Note: For the SAR_<device>_debounce_X feature the following devices are:
265        - proximity
266        - touch
267        It is allowed to define only one level.  For example, if only:
268        SAR_proximity_debounce_hi = <5>;
269        is defined, then the SAR_proximity device's data output will only
270        go high after 5 consecutive reads of it being high.  When the
271        SAR_proximity goes low, it is immediately reported as low.  If the lo is
272        defined, then it would only go back to low after the consecutive low
273        reads defined.
274        When the device is enabled with this feature enabled, the data state is
275        assumed low.  In other words, if the device's data state when enabled
276        is low, it will be reported as low.
277        The default value for this is 0 which disables the feature.
278
279 - gpio_sar_suspend_assert: If the device is not configured to operate during
280                            suspend then this determines the SAR GPIO setting
281                            during suspend:
282                            -1 = DISABLE: SAR GPIO remains at current state from
283                                          when device was operational.
284                            0 = !ASSERT: GPIO is not asserted according to
285                                         gpio_sar_assert_polarity.
286                            1 = ASSERT: GPIO is asserted according to
287                                        gpio_sar_assert_polarity.
288 - os_options: If the IQS device is to be controlled by the OS then set this
289               value to 1.  The default is 0.
290   Note: The SAR_proximity and SAR_touch sensors can still be exposed to
291         the OS via the NVS framework's NvspDriver structure.  However, unless
292         os_options is > 0, the OS will be tricked into thinking is has control.
293         In other words, when os_options is 0 (the default), the device will
294         always be enabled.
295 - irq_trigger_edge: Set to 1 if interrupt is to configured as
296                     IRQF_TRIGGER_FALLING.  Otherwise the interrupt will be
297                     configured as IRQF_TRIGGER_LOW.  Using IRQF_TRIGGER_LOW
298                     addresses false triggers while the interrupt is disabled
299                     during the forced communication protocol.
300 - stream_mode: The device triggers an interrupt on every device data cycle.
301   Note: As mentioned above, the IQS devices have an, um, interesting mechanism
302         for communication where there is a small window of time where the
303         device will respond to I2C commands (the reason for I2C transaction
304         stacking).  When stream mode is disabled, the driver uses a combination
305         of disabling/enabling the interrupt, which also doubles in forcing the
306         communication window, and reading the device's status and data via
307         stream and event modes.  The mechanism allows the device to not
308         interrupt the AP unless an event has occured, thereby saving power.
309         However, depending on how the device is configured by the DT commands,
310         it may be desirable to disable this feature and continually stream the
311         data instead.
312         If the IQS has the slider enabled the device will stream automatically
313         during a slider event.  In this case, the disabling/enabling stream
314         mode mechanism above may not be needed and can be disabled by entering
315         the auto value for steam_mode.
316         Possible stream_mode values are:
317         0 = OFF: Event mode will automatically be enabled by the driver and the
318                  above communication mechanism described above used.
319         1 = ON:  Streaming mode is enabled.  No special communication mechanism
320                  is needed since driver gets constantly interrupted with a comm
321                  window.  However, the interrupts may be throttled (disabled
322                  for a period).
323         2 = AUTO: Event mode is enabled but the special communication mechanism
324                   described above is not used.  Instead, it is expected and
325                   required that the device be configured with the slider
326                   enabled to allow for automatic device initiated streaming.
327 - watchdog_timeout_ms: When streaming mode is disabled, a watchdog can
328                        periodically stream the data to confirm the device's
329                        status.
330   Note: The watchdog timer is actually recommended by Azoteq.
331         If this is not defined, the default will be 30 seconds.
332 - deferred_resume_ms: The delay in milliseconds of when to execute the resume.
333                       Due to the time consumed trying to communicate with the
334                       device, suspend and resume can be adversely affected.
335                       This setting allows resume to be deferred for the amount
336                       of time specified; consider the situation where the
337                       system resumes for a very short period and then suspends
338                       again.  If this situation happened within this deferred
339                       resume time, then the whole process of resuming and
340                       suspending again would not require any communication with
341                       the device thereby not affecting the overall system.
342 - i2c_retry: The number of times to try an I2C transaction before bailing.
343 - gpio_rdy_retry: The number of times to try forcing a communication window.
344   Note: When I2C communication is attempted outside the communication window by
345         pulling the gpio_rdy GPIO low (the GPIO also doubles as the interrupt),
346         the i2c_retry and gpio_rdy_retry provide the limits before the driver
347         will consider the communication attempt a failure.
348         The defaults are 10 and 25 respectively.  The sequence of events for a
349         communication attempt are:
350         1. disable gpio_rdy interrupt
351         2. assert gpio_rdy GPIO low
352         3. wait 11ms according to Azotec spec
353         4. release gpio_rdy GPIO
354         5. gpio_rdy_retry--
355         5. wait ~750us according to Azotec spec
356         6. if gpio_rdy not low and gpio_rdy_retry > 0 then step 2.
357         If all is well so far, do I2C transaction(s), but if an I2C failure,
358         then repeat above steps. This is done i2c_retry times before exiting as
359         a failure.
360         BTW, this is all done according to the Azotec spec.
361 - i2c_ss_delay_ns: The I2C bus must be idle for 100us after an I2C transaction
362                    with the IQS device or it will hold the I2C clock low.  This
363                    WAR is already accounted for in the driver but the delay can
364                    be redefined here.
365 There may a situation where intermittent noise on a channel is causing
366 unreliable data.  If this is the case, the delta options below can help
367 determine the proximity state.  This is accomplished by creating virtual delta
368 SW sensors for each channel.  Each SW sensor created will have the name
369 SAR_delta_chX, where X is the channel number and the data acquired is the delta
370 data from the HW pertaining to that channel.  By defining a delta algorithm in
371 the device tree that can use each SW sensor's data, a global SW delta sensor
372 named SAR_delta is used as the final result of the algorithm.  Each algorithm
373 entry in device tree uses the following stucture:
374 struct iqs_delta_tst {
375         int ch;
376         int lt;
377         int gt;
378 };
379 The DT algorithm uses two levels of conditionals.  The first level uses the
380 label SAR_delta_test_X_Y, where X is the entry number and Y is one of the
381 members of the iqs_delta_tst structure.  If all of the first level entrie's
382 conditions result as true, then the second level of conditionals named
383 SAR_delta_test_true_X_Y are executed.  If any of the first level entrie's
384 conditions result in false, then the second level of conditionals named
385 SAR_delta_test_false_X_Y are executed.  The result of the second level of
386 conditionals is the data for the SAR_delta virtual SW sensor.
387 Four entries are allowed for each level of conditionals.  Each entry must not
388 use a negative value.  Each entry must have a valid channel (0 - 3) and at
389 least one of the conditional values.  Here are how the conditionals are used,
390 where d[ch] is the channels SAR_delta_chX delta data which may be a moving
391 average if that feature is enabled (see SAR_delta_average_count below):
392 Entry:
393         SAR_delta_test_0_ch = <0>;
394         SAR_delta_test_0_lt = <50>;
395 Conditional:
396         if (d[0] < 50)
397 Entry:
398         SAR_delta_test_0_ch = <1>;
399         SAR_delta_test_0_gt = <50>;
400 Conditional:
401         if (d[1] > 50)
402 Entry:
403         SAR_delta_test_0_ch = <2>;
404         SAR_delta_test_0_lt = <50>;
405         SAR_delta_test_0_gt = <100>;
406 Conditional:
407         if (d[2] < 50 || d[2] > 100)
408 Entry:
409         SAR_delta_test_0_ch = <3>;
410         SAR_delta_test_0_lt = <100>;
411         SAR_delta_test_0_gt = <50>;
412 Conditional:
413         if (d[3] > 50 && d[3] < 100)
414 Note how ranges can be used depending on whether the lt value is less than or
415 greater than the gt value.
416 The conditionals can be displayed at runtime with the following command in the
417 driver space:
418 #echo 0x6001E > nvs
419 The following are the results from the DT example below:
420 #cat nvs
421 DELTA conditions:
422 SAR_delta_test:
423 if (ch2 < 75)
424 if SAR_delta_test_true:
425 if (ch0 > 5)
426 if (ch2 > 5 && ch2 < 50)
427 if SAR_delta_test_false:
428 if (ch0 > 5)
429 if (ch2 > 75 && ch2 < 90)
430
431 - SAR_delta_channel_mask: The channel mask of the SW delta sensors to create.
432                           A value of 0 disables the feature.  The default is 0.
433 - SAR_delta_average_count: The delta values for each channel can use a moving
434                            average.  This value sets the number of samples to
435                            use for each average calculation.  A value < 2
436                            disables the feature.  The default is 0.
437
438 And finally, an example:
439
440         iqs263@44 {
441                 compatible = "azoteq,iqs2x3";
442                 reg = <0x44>;
443                 vddhi-supply = <&vdd_3v3>;
444                 gpio_rdy = <&gpio TEGRA_GPIO(A, 1) GPIO_ACTIVE_LOW>;
445                 gpio_sar = <&gpio TEGRA_GPIO(V, 5) GPIO_ACTIVE_HIGH>;
446                 gpio_sar_dev = "SAR_touch";
447                 stream_mode = <2>;
448                 os_options = <0>;
449                 263suspend_0 = [01 0D 01 FF];
450                 263suspend_1 = [03 0B 00 0A 0A FF FF FF];
451                 263suspend_2 = [01 09 10 FF];
452                 263suspend_3 = [FF FF];
453                 263suspend_4 = [FF FF];
454                 263suspend_5 = [05 09 80 40 00 00 00 FF FF FF FF FF];
455                 263suspend_6 = [03 0A FF FF FF FF FF FF];
456                 263suspend_7 = [01 0B 0F FF];
457                 263init_0 = [05 09 80 04 10 07 0F FF FF FF FF FF];
458                 263init_1 = [01 0D 07 FF];
459                 263init_2 = [01 01 00 FF];
460                 263init_3 = [05 07 1D 0A 0C 00 11 FF FF FF FF FF];
461                 263init_4 = [04 08 B2 D9 D8 00 FF FF FF FF];
462                 263init_5 = [08 0A 08 03 03 03 0C 00 64 14 FF FF FF FF FF FF FF FF];
463                 263init_6 = [03 0B 00 A5 B4 FF FF FF];
464                 263en_prox_0 = [01 09 10 FF];
465                 263en_prox_1 = [FF FF];
466                 263en_prox_2 = [FF FF];
467                 263en_prox_3 = [FF FF];
468                 263en_prox_4 = [FF FF];
469                 263en_prox_5 = [02 09 00 54 FF FF];
470                 SAR_delta_channel_mask = <0x5>;
471                 SAR_delta_average_count = <10>;
472                 SAR_delta_test_0_ch = <2>;
473                 SAR_delta_test_0_lt = <75>;
474                 SAR_delta_test_true_0_ch = <0>;
475                 SAR_delta_test_true_0_gt = <5>;
476                 SAR_delta_test_true_1_ch = <2>;
477                 SAR_delta_test_true_1_lt = <50>;
478                 SAR_delta_test_true_1_gt = <5>;
479                 SAR_delta_test_false_0_ch = <0>;
480                 SAR_delta_test_false_0_gt = <5>;
481                 SAR_delta_test_false_1_ch = <2>;
482                 SAR_delta_test_false_1_lt = <90>;
483                 SAR_delta_test_false_1_gt = <75>;
484         };