[PATCH 1/8] dt-bindings: mfd: iqs62x: Add bindings

Jeff LaBundy
2019-10-21T04:19:14Z

This patch adds binding documentation for six-channel members of the
Azoteq ProxFusion family of sensor devices.

Signed-off-by: Jeff LaBundy <jeff@labundy.com>
---
Documentation/devicetree/bindings/mfd/iqs62x.txt | 242 +++++++++++++++++++++++
1 file changed, 242 insertions(+)
create mode 100644 Documentation/devicetree/bindings/mfd/iqs62x.txt

diff --git a/Documentation/devicetree/bindings/mfd/iqs62x.txt b/Documentation/devicetree/bindings/mfd/iqs62x.txt
new file mode 100644
index 0000000..089f567
--- /dev/null
+++ b/Documentation/devicetree/bindings/mfd/iqs62x.txt
@@ -0,0 +1,242 @@
+Azoteq IQS620A/621/622/624/625 ProxFusion Sensor Family
+
+Required properties:
+
+- compatible : Must be equal to one of the following:
+ "azoteq,iqs620a"
+ "azoteq,iqs621"
+ "azoteq,iqs622"
+ "azoteq,iqs624"
+ "azoteq,iqs625"
+
+- reg : I2C slave address for the device.
+
+- interrupts : GPIO to which the device's active-low RDY
+ output is connected (see [0]).
+
+Optional properties:
+
+- linux,fw-file : Specifies the name of the calibration and
+ configuration file selected by the driver.
+ If this property is omitted, the filename
+ is selected based on the device name with
+ ".bin" as the extension (e.g. iqs620a.bin
+ for IQS620A).
+
+All devices accommodate a child node (e.g. "keys") that represents touch key
+support. Required properties for the "keys" child node include:
+
+- compatible : Must be equal to one of the following:
+ "azoteq,iqs620a-keys"
+ "azoteq,iqs621-keys"
+ "azoteq,iqs622-keys"
+ "azoteq,iqs624-keys"
+ "azoteq,iqs625-keys"
+
+- linux,keycodes : Specifies an array of up to 16 numeric key-
+ codes corresponding to each available touch
+ or proximity event. An 'x' in the following
+ table indicates an event is supported for a
+ given device; specify 0 for unused events.
+
+ ----------------------------------------------------------------------------
+ | # | Event | IQS620A | IQS621 | IQS622 | IQS624 | IQS625 |
+ ----------------------------------------------------------------------------
+ | 0 | CH0 Touch | x | x | x | x | x |
+ | | Antenna 1 Touch* | x | | | | |
+ ----------------------------------------------------------------------------
+ | 1 | CH0 Proximity | x | x | x | x | x |
+ | | Antenna 1 Proximity* | x | | | | |
+ ----------------------------------------------------------------------------
+ | 2 | CH1 Touch | x | x | x | x | x |
+ | | Antenna 1 Deep Touch* | x | | | | |
+ ----------------------------------------------------------------------------
+ | 3 | CH1 Proximity | x | x | x | x | x |
+ ----------------------------------------------------------------------------
+ | 4 | CH2 Touch | x | | | | |
+ ----------------------------------------------------------------------------
+ | 5 | CH2 Proximity | x | | | | |
+ | | Antenna 2 Proximity* | x | | | | |
+ ----------------------------------------------------------------------------
+ | 6 | Metal (+) Touch** | x | x | | | |
+ | | Antenna 2 Deep Touch* | x | | | | |
+ ----------------------------------------------------------------------------
+ | 7 | Metal (+) Proximity** | x | x | | | |
+ | | Antenna 2 Touch* | x | | | | |
+ ----------------------------------------------------------------------------
+ | 8 | Metal (-) Touch** | x | x | | | |
+ ----------------------------------------------------------------------------
+ | 9 | Metal (-) Proximity** | x | x | | | |
+ ----------------------------------------------------------------------------
+ | 10 | SAR Active*** | x | | x | | |
+ ----------------------------------------------------------------------------
+ | 11 | SAR Quick Release*** | x | | x | | |
+ ----------------------------------------------------------------------------
+ | 12 | SAR Movement*** | x | | x | | |
+ ----------------------------------------------------------------------------
+ | 13 | SAR Filter Halt*** | x | | x | | |
+ ----------------------------------------------------------------------------
+ | 14 | Wheel Up | | | | x | |
+ ----------------------------------------------------------------------------
+ | 15 | Wheel Down | | | | x | |
+ ----------------------------------------------------------------------------
+ * Dual-channel SAR. Replaces CH0-2 and metal touch and proximity events if
+ enabled via firmware.
+ ** "+" and "-" refer to the polarity of the channel's delta (LTA - counts),
+ where "LTA" is defined as the channel's long-term average.
+ *** Single-channel SAR. Replaces CH0-2 touch and proximity events if enabled
+ via firmware.
+
+The "keys" child node supports "hall_switch_north" and "hall_switch_south"
+child nodes that represent north-field and south-field Hall-effect sensor
+events, respectively (IQS620A/621/622 only). Required properties include:
+
+- linux,code : Numeric switch code.
+
+Optional properties for the "hall_switch_north" and "hall_switch_south" nodes:
+
+- azoteq,use-prox : Boolean to specify that Hall-effect sensor
+ reporting must use the device's wide-range
+ proximity threshold instead of its narrow-
+ range touch threshold.
+
+Note: North/south-field orientation is reversed on the IQS620AXzCSR device due
+ to its flip-chip package.
+
+The IQS620A supports a PWM controller node; required properties include:
+
+- compatible : Must be equal to "azoteq,iqs620a-pwm".
+
+- #pwm-cells : Must be equal to 2 (see [1]).
+
+The IQS622 supports an additional child node (e.g. "prox") that represents
+active IR detection; required properties include:
+
+- compatible : Must be equal to "azoteq,iqs622-prox".
+
+Optional properties for the "prox" child node:
+
+- azoteq,use-prox : Boolean to specify that IR threshold event
+ reporting must use the device's wide-range
+ proximity threshold instead of its narrow-
+ range touch threshold.
+
+[0]: Documentation/devicetree/bindings/interrupt-controller/interrupts.txt
+[1]: Documentation/devicetree/bindings/pwm/pwm.txt
+
+Example 1: Dual capacitive buttons with additional "air button," unipolar lid
+ switch and panel-mounted LED.
+
+ &i2c1 {
+ /* ... */
+
+ iqs620a: iqs620a@44 {
+ compatible = "azoteq,iqs620a";
+ reg = <0x44>;
+ interrupt-parent = <&gpio>;
+ interrupts = <17 IRQ_TYPE_LEVEL_LOW>;
+
+ iqs620a_keys: keys {
+ compatible = "azoteq,iqs620a-keys";
+
+ linux,keycodes = <KEY_SELECT>,
+ <KEY_MENU>,
+ <KEY_OK>,
+ <KEY_MENU>;
+
+ hall_switch_south {
+ linux,code = <SW_LID>;
+ azoteq,use-prox;
+ };
+ };
+
+ iqs620a_pwm: pwm {
+ compatible = "azoteq,iqs620a-pwm";
+ #pwm-cells = <2>;
+ };
+ };
+
+ /* ... */
+ };
+
+ pwmleds {
+ compatible = "pwm-leds";
+
+ panel {
+ pwms = <&iqs620a_pwm 0 1000000>;
+ max-brightness = <255>;
+ };
+ };
+
+Example 2: Single inductive button with bipolar dock/tablet-mode switch.
+
+ &i2c1 {
+ /* ... */
+
+ iqs620a: iqs620a@44 {
+ compatible = "azoteq,iqs620a";
+ reg = <0x44>;
+ interrupt-parent = <&gpio>;
+ interrupts = <17 IRQ_TYPE_LEVEL_LOW>;
+
+ linux,fw-file = "iqs620a_coil.bin";
+
+ iqs620a_keys: keys {
+ compatible = "azoteq,iqs620a-keys";
+
+ linux,keycodes = <0>,
+ <0>,
+ <0>,
+ <0>,
+ <0>,
+ <0>,
+ <KEY_MUTE>;
+
+ hall_switch_north {
+ linux,code = <SW_DOCK>;
+ };
+
+ hall_switch_south {
+ linux,code = <SW_TABLET_MODE>;
+ };
+ };
+ };
+
+ /* ... */
+ };
+
+Example 3: Dual capacitive buttons with volume knob.
+
+ &i2c1 {
+ /* ... */
+
+ iqs624: iqs624@44 {
+ compatible = "azoteq,iqs624";
+ reg = <0x44>;
+ interrupt-parent = <&gpio>;
+ interrupts = <17 IRQ_TYPE_LEVEL_LOW>;
+
+ iqs624_keys: keys {
+ compatible = "azoteq,iqs624-keys";
+
+ linux,keycodes = <BTN_0>,
+ <0>,
+ <BTN_1>,
+ <0>,
+ <0>,
+ <0>,
+ <0>,
+ <0>,
+ <0>,
+ <0>,
+ <0>,
+ <0>,
+ <0>,
+ <0>,
+ <KEY_VOLUMEUP>,
+ <KEY_VOLUMEDOWN>;
+ };
+ };
+
+ /* ... */
+ };
--
2.7.4