Linux-Hwmon Archive on lore.kernel.org
 help / color / Atom feed
From: Jeff LaBundy <jeff@labundy.com>
To: Jonathan Cameron <jic23@kernel.org>
Cc: lee.jones@linaro.org, dmitry.torokhov@gmail.com,
	jdelvare@suse.com, linux@roeck-us.net, thierry.reding@gmail.com,
	devicetree@vger.kernel.org, linux-input@vger.kernel.org,
	linux-hwmon@vger.kernel.org, u.kleine-koenig@pengutronix.de,
	linux-pwm@vger.kernel.org, knaack.h@gmx.de, lars@metafoo.de,
	pmeerw@pmeerw.net, linux-iio@vger.kernel.org, robh+dt@kernel.org,
	mark.rutland@arm.com
Subject: Re: [PATCH 1/8] dt-bindings: mfd: iqs62x: Add bindings
Date: Tue, 22 Oct 2019 22:36:46 -0500
Message-ID: <20191023033646.GB4458@labundy.com> (raw)
In-Reply-To: <20191022120051.686ed9f9@archlinux>

Hi Jonathan,

On Tue, Oct 22, 2019 at 12:00:51PM +0100, Jonathan Cameron wrote:
> On Sun, 20 Oct 2019 23:11:16 -0500
> Jeff LaBundy <jeff@labundy.com> wrote:
> 
> > 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>
> 
> I'm not sure if Lee has made the switch for mfd entirely yet, but
> mostly new dt bindings need to be in yaml format as it allows
> automated parsing of the examples + bindings using them for
> correctness.
> 

I'll wait for Lee or Rob's cue, but I'm happy to move to yaml if it's time
to make the switch here.

> One comment inline.  I'm far from an expert on most of the stuff here
> so will leave it for others!
> 
> Jonathan
> 
> 
> > ---
> >  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.
> This one is certainly interesting.  Does it always make sense to
> set this only at boot?  Of could we control this from userspace?
> 
> It sits somewhere between a hardware requirement that we should
> put in DT and a policy decision.  I can conceive of devices where both
> options make sense, but also ones where only one does.
> 

I've given this some thought, and I think this needs to move to a runtime control
that can be adjusted from user space.

I originally made this a binding simply because a similar decision is offered for
Hall-effect switches in the input driver (lid switch, dock switch, etc.). In that
case, the decision is based on industrial design (distance from magnet, enclosure
thickness, etc.). so that one makes sense as a binding.

IR proximity reporting represents a different use case (in-ear detection, etc.) and
I can forsee instances where narrow vs. wide range decision needs to be dynamically
controlled.

Most importantly, the corresponding iio driver already allows the selected detection
threshold to be adjusted from user space. So it only makes sense that the particular
threshold to be used can be selected from user space as well.

I'll drop the binding and add a "touch" vs. "proximity" attribute to the iio driver.

> > +
> > +[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>;
> > +			};
> > +		};
> > +
> > +		/* ... */
> > +	};
> 
> 

Kind regards,
Jeff LaBundy

  reply index

Thread overview: 37+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2019-10-21  4:11 [PATCH 0/8] Add support for Azoteq IQS620A/621/622/624/625 Jeff LaBundy
2019-10-21  4:11 ` [PATCH 1/8] dt-bindings: mfd: iqs62x: Add bindings Jeff LaBundy
2019-10-22 11:00   ` Jonathan Cameron
2019-10-23  3:36     ` Jeff LaBundy [this message]
2019-10-23  9:30       ` Lee Jones
2019-10-24  2:38         ` Jeff LaBundy
2019-10-21  4:11 ` [PATCH 2/8] mfd: Add support for Azoteq IQS620A/621/622/624/625 Jeff LaBundy
2019-10-31 13:44   ` Lee Jones
2019-10-31 18:42     ` Dmitry Torokhov
2019-11-01  4:59     ` Jeff LaBundy
2019-11-01  8:56       ` Lee Jones
2019-11-02  2:49         ` Jeff LaBundy
2019-10-21  4:11 ` [PATCH 3/8] input: keyboard: " Jeff LaBundy
2019-10-23  0:22   ` Dmitry Torokhov
2019-10-23  1:29     ` Jeff LaBundy
2019-10-23 23:08       ` Dmitry Torokhov
2019-10-21  4:11 ` [PATCH 4/8] hwmon: Add support for Azoteq IQS620AT temperature sensor Jeff LaBundy
2019-10-21 15:38   ` Guenter Roeck
2019-10-22  2:26     ` Jeff LaBundy
2019-10-22  3:22       ` Guenter Roeck
2019-10-22 11:38         ` Jonathan Cameron
2019-10-23  2:04           ` Jeff LaBundy
2019-10-21  4:11 ` [PATCH 5/8] pwm: Add support for Azoteq IQS620A PWM generator Jeff LaBundy
2019-10-21  7:34   ` Uwe Kleine-König
2019-10-22  4:36     ` Jeff LaBundy
2019-10-22  6:54       ` Uwe Kleine-König
2019-10-23  2:45         ` Jeff LaBundy
2019-10-23  7:23           ` Uwe Kleine-König
2019-10-24  3:02             ` Jeff LaBundy
2019-10-21  4:11 ` [PATCH 6/8] iio: light: Add support for Azoteq IQS621 ambient light sensor Jeff LaBundy
2019-10-22 11:23   ` Jonathan Cameron
2019-10-23  2:59     ` Jeff LaBundy
2019-10-21  4:11 ` [PATCH 7/8] iio: proximity: Add support for Azoteq IQS622 proximity sensor Jeff LaBundy
2019-10-22 11:23   ` Jonathan Cameron
2019-10-23  3:09     ` Jeff LaBundy
2019-10-21  4:11 ` [PATCH 8/8] iio: position: Add support for Azoteq IQS624/625 angle sensor Jeff LaBundy
2019-10-22 11:28   ` Jonathan Cameron

Reply instructions:

You may reply publically to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:
  https://en.wikipedia.org/wiki/Posting_style#Interleaved_style

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to=20191023033646.GB4458@labundy.com \
    --to=jeff@labundy.com \
    --cc=devicetree@vger.kernel.org \
    --cc=dmitry.torokhov@gmail.com \
    --cc=jdelvare@suse.com \
    --cc=jic23@kernel.org \
    --cc=knaack.h@gmx.de \
    --cc=lars@metafoo.de \
    --cc=lee.jones@linaro.org \
    --cc=linux-hwmon@vger.kernel.org \
    --cc=linux-iio@vger.kernel.org \
    --cc=linux-input@vger.kernel.org \
    --cc=linux-pwm@vger.kernel.org \
    --cc=linux@roeck-us.net \
    --cc=mark.rutland@arm.com \
    --cc=pmeerw@pmeerw.net \
    --cc=robh+dt@kernel.org \
    --cc=thierry.reding@gmail.com \
    --cc=u.kleine-koenig@pengutronix.de \
    /path/to/YOUR_REPLY

  https://kernel.org/pub/software/scm/git/docs/git-send-email.html

* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link

Linux-Hwmon Archive on lore.kernel.org

Archives are clonable:
	git clone --mirror https://lore.kernel.org/linux-hwmon/0 linux-hwmon/git/0.git

	# If you have public-inbox 1.1+ installed, you may
	# initialize and index your mirror using the following commands:
	public-inbox-init -V2 linux-hwmon linux-hwmon/ https://lore.kernel.org/linux-hwmon \
		linux-hwmon@vger.kernel.org
	public-inbox-index linux-hwmon

Example config snippet for mirrors

Newsgroup available over NNTP:
	nntp://nntp.lore.kernel.org/org.kernel.vger.linux-hwmon


AGPL code for this site: git clone https://public-inbox.org/public-inbox.git