diff mbox series

[v2,1/2] dt-bindings: iio: light: isl76682: Document ISL76682

Message ID 20231118000614.186558-1-marex@denx.de
State Not Applicable
Headers show
Series [v2,1/2] dt-bindings: iio: light: isl76682: Document ISL76682 | expand

Checks

Context Check Description
robh/checkpatch success
robh/patch-applied success
robh/dtbs-check warning build log
robh/dt-meta-schema success

Commit Message

Marek Vasut Nov. 18, 2023, 12:06 a.m. UTC 
The ISL76682 is very basic ALS which only supports ALS or IR mode
in four ranges, 1k/4k/16k/64k LUX. There is no IRQ support or any
other fancy functionality. Document it as trivial device.

Acked-by: Conor Dooley <conor.dooley@microchip.com>
Signed-off-by: Marek Vasut <marex@denx.de>
---
Cc: Alexander Stein <alexander.stein@ew.tq-group.com>
Cc: Andre Werner <andre.werner@systec-electronic.com>
Cc: Andy Shevchenko <andriy.shevchenko@linux.intel.com>
Cc: Bjorn Helgaas <bhelgaas@google.com>
Cc: Conor Dooley <conor+dt@kernel.org>
Cc: Fabio Estevam <festevam@denx.de>
Cc: Guenter Roeck <linux@roeck-us.net>
Cc: Jonathan Cameron <jic23@kernel.org>
Cc: Krzysztof Kozlowski <krzysztof.kozlowski+dt@linaro.org>
Cc: Lars-Peter Clausen <lars@metafoo.de>
Cc: Luca Ceresoli <luca.ceresoli@bootlin.com>
Cc: Mark Brown <broonie@kernel.org>
Cc: Matti Vaittinen <mazziesaccount@gmail.com>
Cc: Naresh Solanki <naresh.solanki@9elements.com>
Cc: Patrick Rudolph <patrick.rudolph@9elements.com>
Cc: Rob Herring <robh+dt@kernel.org>
Cc: Stefan Windfeldt-Prytz <stefan.windfeldt-prytz@axis.com>
Cc: Vincent Tremblay <vincent@vtremblay.dev>
Cc: devicetree@vger.kernel.org
Cc: linux-iio@vger.kernel.org
---
V2: Add AB from Conor
---
 Documentation/devicetree/bindings/trivial-devices.yaml | 2 ++
 1 file changed, 2 insertions(+)

Comments

Jonathan Cameron Nov. 19, 2023, 3:07 p.m. UTC | #1 
On Sat, 18 Nov 2023 01:06:09 +0100
Marek Vasut <marex@denx.de> wrote:

> The ISL76682 is very basic ALS which only supports ALS or IR mode
> in four ranges, 1k/4k/16k/64k LUX. There is no IRQ support or any
> other fancy functionality. Document it as trivial device.
> 
> Acked-by: Conor Dooley <conor.dooley@microchip.com>
> Signed-off-by: Marek Vasut <marex@denx.de>

I'm always a bit in 2 minds about trivial-devices as it doesn't
include a basic power supply.  In this case vdd which I'd prefer
to see documented even on such a simple device as this.
Not everyone is going to leave it powered up all the time!

Still I'm not that fussed. Maybe it's worth allowing vdd-supply in
trivial-devices.yaml?

Jonathan

> ---
> Cc: Alexander Stein <alexander.stein@ew.tq-group.com>
> Cc: Andre Werner <andre.werner@systec-electronic.com>
> Cc: Andy Shevchenko <andriy.shevchenko@linux.intel.com>
> Cc: Bjorn Helgaas <bhelgaas@google.com>
> Cc: Conor Dooley <conor+dt@kernel.org>
> Cc: Fabio Estevam <festevam@denx.de>
> Cc: Guenter Roeck <linux@roeck-us.net>
> Cc: Jonathan Cameron <jic23@kernel.org>
> Cc: Krzysztof Kozlowski <krzysztof.kozlowski+dt@linaro.org>
> Cc: Lars-Peter Clausen <lars@metafoo.de>
> Cc: Luca Ceresoli <luca.ceresoli@bootlin.com>
> Cc: Mark Brown <broonie@kernel.org>
> Cc: Matti Vaittinen <mazziesaccount@gmail.com>
> Cc: Naresh Solanki <naresh.solanki@9elements.com>
> Cc: Patrick Rudolph <patrick.rudolph@9elements.com>
> Cc: Rob Herring <robh+dt@kernel.org>
> Cc: Stefan Windfeldt-Prytz <stefan.windfeldt-prytz@axis.com>
> Cc: Vincent Tremblay <vincent@vtremblay.dev>
> Cc: devicetree@vger.kernel.org
> Cc: linux-iio@vger.kernel.org
> ---
> V2: Add AB from Conor
> ---
>  Documentation/devicetree/bindings/trivial-devices.yaml | 2 ++
>  1 file changed, 2 insertions(+)
> 
> diff --git a/Documentation/devicetree/bindings/trivial-devices.yaml b/Documentation/devicetree/bindings/trivial-devices.yaml
> index c3190f2a168a2..27164e9219276 100644
> --- a/Documentation/devicetree/bindings/trivial-devices.yaml
> +++ b/Documentation/devicetree/bindings/trivial-devices.yaml
> @@ -179,6 +179,8 @@ properties:
>            - isil,isl29030
>              # Intersil ISL68137 Digital Output Configurable PWM Controller
>            - isil,isl68137
> +            # Intersil ISL76682 Ambient Light Sensor
> +          - isil,isl76682
>              # Linear Technology LTC2488
>            - lineartechnology,ltc2488
>              # 5 Bit Programmable, Pulse-Width Modulator
Jonathan Cameron Nov. 19, 2023, 3:54 p.m. UTC | #2 
On Sat, 18 Nov 2023 01:06:10 +0100
Marek Vasut <marex@denx.de> wrote:

> The ISL76682 is very basic ALS which only supports ALS or IR mode
> in four ranges, 1k/4k/16k/64k LUX. There is no IRQ support or any
> other fancy functionality.
> 
> Signed-off-by: Marek Vasut <marex@denx.de>

Hi Marek

A few comments inline,

Jonathan

>  drivers/iio/light/Kconfig    |   8 +
>  drivers/iio/light/Makefile   |   1 +
>  drivers/iio/light/isl76682.c | 336 +++++++++++++++++++++++++++++++++++
>  3 files changed, 345 insertions(+)
>  create mode 100644 drivers/iio/light/isl76682.c
> 
> diff --git a/drivers/iio/light/Kconfig b/drivers/iio/light/Kconfig
> index 45edba797e4c7..124c45f509754 100644
> --- a/drivers/iio/light/Kconfig
> +++ b/drivers/iio/light/Kconfig
> @@ -252,6 +252,14 @@ config ISL29125
>  	  To compile this driver as a module, choose M here: the module will be
>  	  called isl29125.
>  
> +config ISL76682
> +	tristate "Intersil ISL76682 Light Sensor"
> +	depends on I2C
> +	select REGMAP_I2C
> +	help
> +	  Provides driver for the Intersil's ISL76682 device. This driver
> +	  supports the sysfs interface to get the ALS and IR intensity.
> +
One of the bots tends to moan about short descriptions + it can be useful
to let someone know the module name. Hence I'd add the usual boilerplate description
for that here.

> diff --git a/drivers/iio/light/isl76682.c b/drivers/iio/light/isl76682.c
> new file mode 100644
> index 0000000000000..64ec8b8fe71ee
> --- /dev/null
> +++ b/drivers/iio/light/isl76682.c
> @@ -0,0 +1,336 @@
> +// SPDX-License-Identifier: GPL-2.0-only
> +/*
> + * IIO driver for the light sensor ISL76682.
> + * ISL76682 is Ambient Light Sensor
> + *
> + * Copyright (c) 2023 Marek Vasut <marex@denx.de>
> + */
> +
> +#include <linux/delay.h>
> +#include <linux/err.h>
> +#include <linux/i2c.h>
> +#include <linux/module.h>
> +#include <linux/mutex.h>
> +#include <linux/regmap.h>
> +
> +#include <linux/iio/iio.h>
> +#include <linux/iio/sysfs.h>

After changes below, this sysfs.h include should not be needed.

> +
> +#define ISL76682_REG_COMMAND			0x00
> +
> +#define ISL76682_COMMAND_EN			BIT(7)
> +#define ISL76682_COMMAND_MODE_CONTINUOUS	BIT(6)
> +#define ISL76682_COMMAND_LIGHT_IR		BIT(5)
> +
> +#define ISL76682_COMMAND_RANGE_LUX_1K		0
> +#define ISL76682_COMMAND_RANGE_LUX_4K		(1 << 0)
> +#define ISL76682_COMMAND_RANGE_LUX_16K		(2 << 0)
> +#define ISL76682_COMMAND_RANGE_LUX_64K		(3 << 0)
As you are writing these into a field with a mask, 0, 1, 2, 3 should
be fine as the shift is done by FIELD_PREP()

> +#define ISL76682_COMMAND_RANGE_LUX_MASK		GENMASK(1, 0)

> +struct isl76682_chip {
> +	struct mutex			lock;
A lock needs a comment on what scope it covers.  Be as specific as you can
as you need to distinguish it from the locks in regmap or the underlying bus code.
> +	struct regmap			*regmap;
> +	u8				range;
> +	u8				command;
> +};

> +static int isl76682_write_raw(struct iio_dev *indio_dev,
> +			      struct iio_chan_spec const *chan,
> +			      int val, int val2, long mask)
> +{
> +	struct isl76682_chip *chip = iio_priv(indio_dev);
> +	u8 range;
> +
> +	if (chan->type != IIO_LIGHT)
> +		return -EINVAL;
> +
> +	if (mask != IIO_CHAN_INFO_SCALE)
> +		return -EINVAL;
> +
> +	if (val != 0)
> +		return -EINVAL;
> +
> +	if (chan->type == IIO_LIGHT) {
> +		if (val2 == 15000)		/* 0.015 ... 1000 lux */

As below, I'd prefer these to be lookups in the same table used for read_avail()
callback.

> +			range = ISL76682_COMMAND_RANGE_LUX_1K;
> +		else if (val2 == 60000)		/* 0.060 ... 4000 lux */
> +			range = ISL76682_COMMAND_RANGE_LUX_4K;
> +		else if (val2 == 240000)	/* 0.240 ... 16000 lux */
> +			range = ISL76682_COMMAND_RANGE_LUX_16K;
> +		else if (val2 == 960000)	/* 0.960 ... 64000 lux */
> +			range = ISL76682_COMMAND_RANGE_LUX_64K;
> +		else
> +			return -EINVAL;
> +	} else if (chan->type == IIO_INTENSITY) {
> +		if (val2 == 10500)		/* 0.0105 .. 1000 lux */
> +			range = ISL76682_COMMAND_RANGE_LUX_1K;
> +		else if (val2 == 42000)		/* 0.042 ... 4000 lux */
> +			range = ISL76682_COMMAND_RANGE_LUX_4K;
> +		else if (val2 == 168000)	/* 0.168 ... 16000 lux */
> +			range = ISL76682_COMMAND_RANGE_LUX_16K;
> +		else if (val2 == 673000)	/* 0.673 ... 64000 lux */
> +			range = ISL76682_COMMAND_RANGE_LUX_64K;
> +		else
> +			return -EINVAL;
> +	} else {
> +		return -EINVAL;
> +	}
> +
> +	mutex_lock(&chip->lock);

scoped_guard(mutex, &chip->lock); or guard(mutex)(&chip->lock);
nice here as well.

> +	chip->range = range;
> +	mutex_unlock(&chip->lock);
> +
> +	return 0;
> +}
> +
> +static int isl76682_read_raw(struct iio_dev *indio_dev,
> +			     struct iio_chan_spec const *chan,
> +			     int *val, int *val2, long mask)
> +{
> +	struct isl76682_chip *chip = iio_priv(indio_dev);
> +	int ret = -EINVAL;
> +
> +	mutex_lock(&chip->lock);
guard(mutex)(&chip->lock);

Will allow you to make direct returns instead of breaking to where the
unlock is, generally simplifying the code flow.

> +
> +	switch (mask) {
> +	case IIO_CHAN_INFO_RAW:
> +		switch (chan->type) {
> +		case IIO_LIGHT:
> +			ret = isl76682_get(chip, false, val);
> +			break;
> +		case IIO_INTENSITY:
> +			ret = isl76682_get(chip, true, val);
> +			break;
> +		default:
> +			break;
> +		}
> +
> +		if (ret < 0)
> +			break;
> +
> +		ret = IIO_VAL_INT;
> +		break;
> +	case IIO_CHAN_INFO_SCALE:
> +		*val = 0;
> +		switch (chan->type) {
> +		case IIO_LIGHT:
> +			if (chip->range == ISL76682_COMMAND_RANGE_LUX_1K)
> +				*val2 = 15000;
> +			else if (chip->range == ISL76682_COMMAND_RANGE_LUX_4K)
> +				*val2 = 60000;
> +			else if (chip->range == ISL76682_COMMAND_RANGE_LUX_16K)
> +				*val2 = 240000;
> +			else if (chip->range == ISL76682_COMMAND_RANGE_LUX_64K)
> +				*val2 = 960000;
> +			else
> +				break;
> +			ret = IIO_VAL_INT_PLUS_MICRO;
> +			break;
> +		case IIO_INTENSITY:
> +			if (chip->range == ISL76682_COMMAND_RANGE_LUX_1K)
> +				*val2 = 10500;
> +			else if (chip->range == ISL76682_COMMAND_RANGE_LUX_4K)
> +				*val2 = 42000;
> +			else if (chip->range == ISL76682_COMMAND_RANGE_LUX_16K)
> +				*val2 = 168000;
> +			else if (chip->range == ISL76682_COMMAND_RANGE_LUX_64K)
> +				*val2 = 673000;
> +			else
> +				break;
> +			ret = IIO_VAL_INT_PLUS_MICRO;
> +			break;
> +		default:
> +			break;
> +		}
> +		break;
> +	default:
> +		break;
> +	}
> +
> +	mutex_unlock(&chip->lock);
> +
> +	return ret;
> +}
> +
> +static IIO_CONST_ATTR(in_illuminance_scale_available, "0.015 0.06 0.24 0.96");
> +static IIO_CONST_ATTR(in_intensity_scale_available, "0.0105 0.042 0.168 0.673");
> +static IIO_CONST_ATTR(integration_time_available, "0.090");	/* 90 ms */
> +
> +static struct attribute *isl76682_attributes[] = {
> +	&iio_const_attr_in_illuminance_scale_available.dev_attr.attr,
> +	&iio_const_attr_in_intensity_scale_available.dev_attr.attr,
> +	&iio_const_attr_integration_time_available.dev_attr.attr,
Please use the read_avail() callback and matching bitmaps for these.
Doing them with custom attributes is something we are trying to move away
from as it prevents any sensible in kernel access to the values and tends
to end up with duplication of data (and potential inconsistencies)
given you also have to match against the values.

There are lots of older drivers that predate that callback being added
that we haven't converted over yet.

> +	NULL,
> +};
> +

...

> +static void isl76682_remove(struct i2c_client *client)
> +{
> +	struct iio_dev *indio_dev = i2c_get_clientdata(client);
> +	struct isl76682_chip *chip = iio_priv(indio_dev);
> +
> +	iio_device_unregister(indio_dev);
> +
> +	isl76682_clear_configure_reg(chip);

Use a devm_add_action_or_reset() call with a custom callback to unwind this
automatically... As they you can use devm_iio_device_register() and
get rid of the need for any remove function at all.

I am a little curious as to why it needs to be called here as it doesn't obviously
match a call in probe that is being unwound.  As such a comment on 'why' would
also be good.


> +}
> +
Marek Vasut Nov. 19, 2023, 6:08 p.m. UTC | #3 
On 11/19/23 16:07, Jonathan Cameron wrote:
> On Sat, 18 Nov 2023 01:06:09 +0100
> Marek Vasut <marex@denx.de> wrote:
> 
>> The ISL76682 is very basic ALS which only supports ALS or IR mode
>> in four ranges, 1k/4k/16k/64k LUX. There is no IRQ support or any
>> other fancy functionality. Document it as trivial device.
>>
>> Acked-by: Conor Dooley <conor.dooley@microchip.com>
>> Signed-off-by: Marek Vasut <marex@denx.de>
> 
> I'm always a bit in 2 minds about trivial-devices as it doesn't
> include a basic power supply.  In this case vdd which I'd prefer
> to see documented even on such a simple device as this.
> Not everyone is going to leave it powered up all the time!
> 
> Still I'm not that fussed. Maybe it's worth allowing vdd-supply in
> trivial-devices.yaml?

The hardware I have is powered all the time, so I'd be adding completely 
untested code which is no less useless for me (at least right now). Lets 
postpone this until there is a need for it, can we ?

I addressed all the other comments in 2/2.
Jonathan Cameron Nov. 20, 2023, 5:28 p.m. UTC | #4 
On Sun, 19 Nov 2023 19:08:45 +0100
Marek Vasut <marex@denx.de> wrote:

> On 11/19/23 16:07, Jonathan Cameron wrote:
> > On Sat, 18 Nov 2023 01:06:09 +0100
> > Marek Vasut <marex@denx.de> wrote:
> >   
> >> The ISL76682 is very basic ALS which only supports ALS or IR mode
> >> in four ranges, 1k/4k/16k/64k LUX. There is no IRQ support or any
> >> other fancy functionality. Document it as trivial device.
> >>
> >> Acked-by: Conor Dooley <conor.dooley@microchip.com>
> >> Signed-off-by: Marek Vasut <marex@denx.de>  
> > 
> > I'm always a bit in 2 minds about trivial-devices as it doesn't
> > include a basic power supply.  In this case vdd which I'd prefer
> > to see documented even on such a simple device as this.
> > Not everyone is going to leave it powered up all the time!
> > 
> > Still I'm not that fussed. Maybe it's worth allowing vdd-supply in
> > trivial-devices.yaml?  
> 
> The hardware I have is powered all the time, so I'd be adding completely 
> untested code which is no less useless for me (at least right now). Lets 
> postpone this until there is a need for it, can we ?

It's untested but trivial code (one call and an error code check) but fair enough.
Previous experience says that we'll soon see it added... Its probably the most common
follow up patch for a new driver.

> 
> I addressed all the other comments in 2/2.
>
diff mbox series

Patch

diff --git a/Documentation/devicetree/bindings/trivial-devices.yaml b/Documentation/devicetree/bindings/trivial-devices.yaml
index c3190f2a168a2..27164e9219276 100644
--- a/Documentation/devicetree/bindings/trivial-devices.yaml
+++ b/Documentation/devicetree/bindings/trivial-devices.yaml
@@ -179,6 +179,8 @@  properties:
           - isil,isl29030
             # Intersil ISL68137 Digital Output Configurable PWM Controller
           - isil,isl68137
+            # Intersil ISL76682 Ambient Light Sensor
+          - isil,isl76682
             # Linear Technology LTC2488
           - lineartechnology,ltc2488
             # 5 Bit Programmable, Pulse-Width Modulator