arm64: dts: add IQS263 SAR driver data.
Erik Lilliebjerg [Tue, 5 May 2015 10:56:58 +0000 (03:56 -0700)]
- The IQS263 SAR NVS driver is now data driven from the device tree.
  Register values for initialization and enable are from the device tree.

bug 1614729

Change-Id: I525acd1f6b9ec802237696a16b020e9b0264500a
Signed-off-by: Erik Lilliebjerg <elilliebjerg@nvidia.com>
Reviewed-on: http://git-master/r/739119
(cherry picked from commit 15cb4036d7f1f588b565c6e4cb2301d54d044cf8)
Reviewed-on: http://git-master/r/739040
Reviewed-by: Automatic_Commit_Validation_User
Reviewed-by: Robert Collins <rcollins@nvidia.com>

Documentation/devicetree/bindings/iio/iqs253-ps.txt
arch/arm64/boot/dts/tegra210-platforms/tegra210-hawkeye-sensor-p2290-1100-a00.dtsi

index 02e49b1..43e4537 100644 (file)
@@ -1,9 +1,125 @@
-* IQS253 proximity sensor
+* IQS2x3 proximity sensor
+
+The nvs_iqs2x3 proximity sensor driver supports the IQS253 and IQS263 devices.
+These two parts are not register compatible and therefore should be specified
+in the device tree.  Example: iqs263@44.  By specifying a device this way, the
+driver will assume this specific device is populated during system boot and
+will not verify its existence.
+If, however, the device is unknown or may not be populated, then the label,
+iqs2x3, (e.g. iqs2x3@44), must be used.  This tells the driver to find which
+device is used.  If the device is not found, the driver will unload itself.
+This also requires that regulators be setup correctly for the probe function.
 
 Required properties:
 - compatible: must be "azoteq,iqs2x3"
 - reg: i2c address of the device. It is one of 0x44-0x47.
-- gpio_rdy: gpio to be used for i2c handshake with the sensor.
+- gpio_rdy: gpio to be used for the I2C handshake with the sensor.
+
+The IQS devices have a very versatile register set.  So much so that the entire
+register set values can be different among platforms.  Because of this, the way
+and the values used are defined in the device tree.  The driver will read in
+the DT block of data for each command into a buffer and parse the byte stream
+to execute the command.
+The format for each entry of the command is as follows:
+       u8 LENGTH       // The number of data byte pairs (data[N] / 2).
+       u8 REGISTER     // The register to write to.
+       u8 DATA[N]      // The stream of data bytes.  See below description.
+The DATA[N] contains N number of register values first and then N number of a
+mask byte corresponding to the Nth data byte.  For example, if 0x12, 0x34 is to
+be written to a register, and only bits 4:1 are to be written for the first
+byte, then the byte stream would be: 0x12, 0x34, 0x1E, 0xFF.  Where 0x1E is the
+mask for the first byte 0x12, and 0xFF is the mask for the second byte 0x34.
+The entry for this example if the register is, say, 0x56, would be:
+02, 56, 12, 34, 1E, FF
+
+Note that the IQS has a funky register set in that each register has its own
+register length.  The reason LENGTH is still used is that maybe only the first
+few bytes of a register are to be written.  For example, a register that is 20
+bytes long can get by with defining, say 4 for LENGTH, and only the first 4
+bytes will be written.
+
+The DT labeling mechanism is based on the part number and the command to be
+accomplished. Currently there are only two commands: initialization and enable.
+For each label, a "_?" is appended where ? is a decimal number starting at 0.
+Note that driver will put the entries in the sequence defined by ? and not by
+the order defined in the DT.
+An example for initialization of the IQS263 part in the DT is as follows:
+       263init_0 = [05 09 40 03 00 01 03 FF FF FF FF FF]; // 5 bytes to reg 9
+       263init_1 = [01 0D 09 FF]; // 1 byte written to register 0x0D
+       263init_2 = [01 01 00 FF]; // 1 byte written to register 0x01
+       263init_3 = [05 07 1B 08 08 00 11 FF FF FF FF FF]; // 5 bytes to reg 7
+       263init_4 = [08 0A 08 10 10 02 04 08 14 3F FF FF FF FF FF FF FF FF];
+       263init_5 = [03 0B 00 64 80 FF FF FF]; // 3 bytes written to reg 0x0B
+
+The IQS parts have two "virtual" sensors: SAR_proximity and touch_proximity.
+The "virtual" means that the NVS framework will split these two sensors so that
+the system will see two individual sensors.
+The SAR_proximity detects objects near the platform whereas the touch_proximity
+detects actual touches with the platform (assuming it's the screen).
+Because there are two sensors, there are two enable labels: <part>en_prox and
+<part>en_touch.
+Here is a DT example of the enable commands for both sensors:
+       263en_prox_0 = [01 09 10 18];   // 1 byte written to register 0x09
+       263en_prox_1 = [FF 00];         // this is an I2C write with no delay.
+       263en_prox_2 = [01 09 08 18];   // 1 byte written to register 0x09
+       263en_touch_0 = [01 09 10 18];  // 1 byte written to register 0x09
+       263en_touch_1 = [FF 00];        // write flush.  See description below.
+       263en_touch_2 = [01 09 08 18];  // 1 byte written to register 0x09
+
+Due to the IQS device's design for communicating with the device, each entry,
+which represents an I2C transaction, is actually stacked so that the entire
+command is executed as a single I2C transaction.  That is, I2C restarts are
+done instead of I2C stops.  For situations where it is desired to write the
+transactions thus far and have a delay within the command entries, the LENGTH
+can be set to FF.  This tells the driver's byte stream parsing engine to
+execute the I2C transactions thus far and if a millisecond delay is to also be
+done, then the following byte contains the number of milliseconds to wait,
+otherwise the following byte's value is 0.
+
+FYI, internally to the driver, the byte stream terminates when LENGTH is 0.
+This is handled automatically by the driver's DT parsing, but is an FYI so that
+0 is never used for LENGTH.  Also note that the driver's DT parsing engine has
+error checking and will exit with an error of "ERR: NOMEM @ %s" where %s will
+be the DT label where things went south.  The error can be due to truly out of
+buffer memory to non-existent register or incorrect register length.
+Once the driver has loaded, a debug feature that will dump the parsed byte
+stream can be done by doing the following at the device's sysfs directory in an
+adb terminal prompt:
+$echo 10 > nvs
+$cat nvs
+The results will be something like:
+       IQS driver v. 4
+       os_options=0
+       stream_mode=0
+       watchdog_timeout_ms=30000
+       i2c_retry=10
+       gpio_rdy_retry=25
+       gpio_rdy 1=1
+       gpio_sar 173=1
+       irq=2
+       irq_disable=0
+       SAR_proximity_binary_hw=1
+       touch_proximity_binary_hw=1
+       IQS263 initialization:
+       len=5 reg=9 data/mask=40/ff 3/ff 0/ff 1/ff 3/ff
+       len=1 reg=d data/mask=9/ff
+       len=1 reg=1 data/mask=0/ff
+       len=5 reg=7 data/mask=1b/ff 8/ff 8/ff 0/ff 11/ff
+       len=8 reg=a data/mask=8/ff 10/ff 10/ff 2/ff 4/ff 8/ff 14/ff 3f/ff
+       len=3 reg=b data/mask=0/ff 64/ff 80/ff
+       IQS263 proximity enable:
+       len=1 reg=9 data/mask=10/18
+       flush write and mdelay=0
+       len=1 reg=9 data/mask=8/18
+       IQS263 touch enable:
+       len=1 reg=9 data/mask=10/18
+       flush write and mdelay=0
+       len=1 reg=9 data/mask=8/18
+       IQS253 initialization:
+
+Note that in the case the part populated could be either IQS253 or IQS263, both
+the 253 and 263 commands can be defined in the DT.  The driver will use the one
+according to the part identified.
 
 Optional properties:
 - SAR_proximity_disable: Setting this property to <1> will disable the
@@ -14,13 +130,79 @@ Optional properties:
         must be disabled:
        SAR_proximity_disable = <1>;
        touch_proximity_disable = <1>;
-- gpio_sar: gpio to be used for sending proximity event to SAR sensor.
+- gpio_sar: gpio to be used for sending proximity event for SAR sensor.
+  Note: The gpio_sar define is not required if the following is true:
+       - The device's PO pin is wired to the device requiring the SAR event.
+       - The assert level is high.
+       - The IQS SAR_proximity is configured as a binary value.
+- sar_assert_polarity: assert level of the GPIO for the SAR proximity event.
+  Note: sar_assert_polarity is ONLY for the SAR GPIO and is not needed if the
+       GPIO assert value is low since low is the SAR GPIO assert default.  It
+       may still be defined as low (sar_assert_polarity = <0>;) however.
+- os_options: If the IQS device is to be controlled by the OS then set this
+             value to 1.  The default is 0.
+  Note: The SAR_proximity and touch_proximity sensors can still be exposed to
+       the OS via the NVS framework's NvspDriver structure.  However, unless
+       os_options is > 0, the OS will be tricked into thinking is has control.
+       In other words, when os_options is 0 (the default), the device will
+       always be enabled.
+- stream_mode: The device always triggers an interrupt on every read.
+  Note: As mentioned above, the IQS devices have an, um, interesting mechanism
+        for communication where there is a small window of time where the
+       device will respond to I2C commands (the reason for I2C transaction
+       stacking).  When stream mode is disabled, the driver uses a combination
+       of disabling/enabling the interrupt, which also doubles in forcing the
+       communication window, and reading the device's status and data.  The
+       mechanism allows the device to not interrupt the AP unless an event has
+       occured, thereby saving power.  However, depending on how the device is
+       configured by the DT commands, it may be desirable to disable this
+       feature and stream the data instead.
+- watchdog_timeout_ms: When streaming mode is disabled, a watchdog can
+                      periodically stream the data to confirm the device's
+                      status.
+  Note: The watchdog timer is actually recommended by Azoteq.
+       If this is not defined, the default will be 30 seconds.
+- i2c_retry: The number of times to try an I2C transaction before bailing.
+- gpio_rdy_retry: The number of times to try forcing a communication window.
+  Note: When I2C communication is attempted outside the communication window by
+       pulling the gpio_rdy GPIO low (the GPIO also doubles as the interrupt),
+       the i2c_retry and gpio_rdy_retry provide the limits before the driver
+       will consider the communication attempt a failure.
+       The defaults are 10 and 25 respectively.  The sequence of events for a
+       communication attempt are:
+       1. disable gpio_rdy interrupt
+       2. assert gpio_rdy GPIO low
+       3. wait 11ms according to Azotec spec
+       4. release gpio_rdy GPIO
+       5. gpio_rdy_retry--
+       5. wait ~750us according to Azotec spec
+       6. if gpio_rdy not low and gpio_rdy_retry > 0 then step 2.
+       If all is well so far, do I2C transaction(s), but if an I2C failure,
+       then repeat above steps. This is done i2c_retry times before exiting as
+       a failure.
+       BTW, this is all done according to the Azotec spec.
 
-Example:
+And finally, an example:
 
        iqs263@44 {
-               compatible = "azoteq,iqs263";
+               compatible = "azoteq,iqs2x3";
                reg = <0x44>;
                gpio_rdy = <&gpio TEGRA_GPIO(A, 1) GPIO_ACTIVE_LOW>;
                gpio_sar = <&gpio TEGRA_GPIO(V, 5) GPIO_ACTIVE_LOW>;
+               sar_assert_polarity = <0>;
+               SAR_proximity_no_suspend = <1>;
+               touch_proximity_no_suspend = <1>;
+               os_options = <0>;
+               263init_0 = [05 09 40 03 00 01 03 FF FF FF FF FF];
+               263init_1 = [01 0D 09 FF];
+               263init_2 = [01 01 00 FF];
+               263init_3 = [05 07 1B 08 08 00 11 FF FF FF FF FF];
+               263init_4 = [08 0A 08 10 10 02 04 08 14 3F FF FF FF FF FF FF FF FF];
+               263init_5 = [03 0B 00 64 80 FF FF FF];
+               263en_prox_0 = [01 09 10 18];
+               263en_prox_1 = [FF 00];
+               263en_prox_2 = [01 09 08 18];
+               263en_touch_0 = [01 09 10 18];
+               263en_touch_1 = [FF 00];
+               263en_touch_2 = [01 09 08 18];
        };
index 6386c7b..2246d2e 100644 (file)
                        reg = <0x44>;
                        gpio_rdy = <&gpio TEGRA_GPIO(A, 1) GPIO_ACTIVE_LOW>;
                        gpio_sar = <&gpio TEGRA_GPIO(V, 5) GPIO_ACTIVE_LOW>;
+                       SAR_proximity_no_suspend = <1>;
+                       touch_proximity_no_suspend = <1>;
+                       os_options = <0>;
+                       263init_0 = [05 09 40 03 00 01 03 FF FF FF FF FF];
+                       263init_1 = [01 0D 09 FF];
+                       263init_2 = [01 01 00 FF];
+                       263init_3 = [05 07 1B 08 08 00 11 FF FF FF FF FF];
+                       263init_4 = [08 0A 08 10 10 02 04 08 14 3F FF FF FF FF FF FF FF FF];
+                       263init_5 = [03 0B 00 64 80 FF FF FF];
+                       263en_prox_0 = [01 09 10 18];
+                       263en_prox_1 = [FF 00];
+                       263en_prox_2 = [01 09 08 18];
+                       263en_touch_0 = [01 09 10 18];
+                       263en_touch_1 = [FF 00];
+                       263en_touch_2 = [01 09 08 18];
                };
        };
 };