On Sat, 14 Dec 2024 16:24:34 +0100
"Javier Carrasco" <javier.carrasco.cruz@xxxxxxxxx> wrote:
> On Thu Nov 28, 2024 at 1:26 PM CET, Javier Carrasco wrote:
> > On 22/10/2024 20:28, Jonathan Cameron wrote:
> > > On Mon, 21 Oct 2024 22:21:22 +0200
> > > Javier Carrasco <javier.carrasco.cruz@xxxxxxxxx> wrote:
> > >
> > >> On 21/10/2024 20:39, Jonathan Cameron wrote:
> > >>> On Sun, 20 Oct 2024 21:12:17 +0200
> > >>> Javier Carrasco <javier.carrasco.cruz@xxxxxxxxx> wrote:
> > >>>
> > >>>> The Vishay veml3235 is a low-power ambient light sensor with I2C
> > >>>> interface. It provides a minimum detectable intensity of
> > >>>> 0.0021 lx/cnt, configurable integration time and gain, and an additional
> > >>>> white channel to distinguish between different light sources.
> > >>>>
> > >>>> Signed-off-by: Javier Carrasco <javier.carrasco.cruz@xxxxxxxxx>
> > >>> Hi Javier,
> > >>>
> > >>> I missed one thing on previous review...
> > >>> There is no obvious reason this driver needs to provide raw and processed
> > >>> values. Unless I'm missing something, just provide raw and let userspace
> > >>> do the maths for us.
> > >>>
> > >>> Jonathan
> > >>>
> > >> Sure, I will drop that for v3. I added it because this driver took the
> > >> veml6030 as a reference, and that driver provides the processed value. I
> > >> guess that the veml6030 should have not provided processed values
> > >> either, but it's late to remove them after the driver was released.
> > >>
> > >> Now that we are at it, what is the rule (of thumb?) to provide processed
> > >> values? Those that can't be obtained from the raw data and simple
> > >> operations with the scale/offset/integration time/whatever userspace can
> > >> see?
> > >
> > > Yes. If the conversion is linear, then leave it to userspace (with scale
> > > and offset provided). If it's not linear then in kernel because currently
> > > we have no other choice.
> > >
> > > There are some historical quirks where a processed only interface got in
> > > then we had to add raw later (typically when we added buffered output
> > > where scale and offset are important because processed values normally
> > > don't pack well).
> > >
> > > Jonathan
> > >
> > >
> >
> > Hi Jonathan, I am bringing this back because I am not sure if dropping
> > the processed values was the right approach here. I would like to
> > clarify before propagating some approach that might not be accurate.
> >
> > This sensor is linear, and the processed value can be obtained by simple
> > multiplications, but not just raw * scale as documented in the ABI.
> >
> > This driver is based on the veml6030, whose processed value is obtained
> > as raw * resolution, where the resolution is completely linear and is
> > obtained as sensor_resolution * integration_time / scale.
> >
> > That means that the scale is actually a gain, and the user needs to know
> > the sensor resolution provided in the datasheet (see cur_resolution in
> > veml6030.c) to get the processed value. There is a sensor resolution for
> > every pair { gain, integration_time } in the datasheet, so there is no
> > need to calculate anything, yet the resolution is not provided by the
> > driver.
Ah. The ABI is defined such that the _scale should always be the value that
you multiply _raw by to get a the defined base units. That means it
has to take into account anything that affects that - in this case that
means it incorporates the effect of that resolution table as well.
> >
> > Nevertheless, your comment on this matter was the following:
> >
> > > Why both raw + scale and processed?
> > >
> > > We normally only provide raw and processed for light sensors if:
> > > 1) The conversion is non linear and hard to reverse.
> > > 2) There are events that are thresholds on the raw value.
> > >
> > > Here it is linear so just provide _RAW.
> >
> > That is still true in this case, because it is a linear, easy to reverse
> > conversion. Nevertheless, the user needs to look for the sensor
> > resolution in the datasheet and then use the given integration_time and
> > scale.
> >
> > Is that ok and desired for light sensors?
If we are talking about illuminance or other well defined scaled channels then
no it is not. They must give a value in Lux when we multiply _raw * _scale
(ignoring offset). It is messily defined for intensity channels as they
have no base units to target, but the principle should be the same.
> I think that a more accurate
> > approach would have been treating the gain as a HARDWAREGAIN, which
> > would have been used to calculate the scale i.e. resolution to directly
> > apply to the raw value. In its current form, the processed value is not
> > what you get if you do raw * scale.
That sounds like a bug that needs fixing because it is not compliant
with the define ABI. It is messy as stated for intensity because in that
case PROCESSED in the ABI as it's largely meaningless.
> But as you specifically mentioned
> > light sensors in your comment, that might not apply here. Moreover,
> > there are only two drivers (si1133.c and vl6180.c) that use HARDWAREGAIN
> > for IIO_LIGHT, which makes me think I am over-complicating thing here.
Hardware gain must not be part of what is necessary to compute a value
in userspace. It is not the ABI specified way of doing it which means
zero software will do it right. Any change to that is a break in
backwards compatibility of the ABI. The cardinal rule of Linux is we
never ever do that. Note not breaking the subsystem ABI comes above
not breaking backwards compatibility of a given driver.
We have relaxed things a bit to say that in some cases it can be used
to provide some useful 'debug' info on a channel setup, but _scale * _raw
is still the only way to get to the defined ABI.
> >
> > By the way, in_illuminance_hardwaregain is not documented in the ABI,
> > only out_voltageY and in_intensity. But that is another topic.
We should indeed add it.
> >
> > The veml6030 has been around for some time and there is no way around
> > without breaking ABI, and the veml3235 has been only applied to your
> > tree and maybe it could wait to be released.
If the reporting is wrong wrt to the defined userspace ABI then it's
a bug fix and unfortunately that means we might break users :( There
is no good way to fix these.
> >
> > If everything is ok as it is, then that's the end of the story, but if
> > the processed = raw * scale operation should apply, the veml3235 could
> > still be fixed. And when it is too late for that one too, then I could
> > follow a different approach for the veml6031x00 I recently sent to avoid
> > propagating the issue.
Definitely good to fix the veml3235 and we can also fix the older driver
as this is simply a bug (one of the few valid reasons for an ABI change).
> >
> > Thanks and best regards,
> > Javier Carrasco
>
> Hi Jonathan, this email might have gone unnoticed.
Yup. Sorry. I had an email sanfu and ended up with my whole inbox marked read.
May have missed a few mails as a result.
>
> This issue is relevant for the veml6030 and veml3235, and also for the
> veml6031x00 under review, as it follows the same pattern. Do you think
> they are ok as they are? Probably not, as they don't follow the ABI
> documentation, and after reading some other reviews, HARDWAREGAIN is
> usually not the fix for something like this.
> Should the gts helpers be used instead?
They need to be fixed so they follow the ABI. GTS may well help with that
as Matti wrote it to address this complexity of too many ways of making
changes that affect the scale. It is also valid under the ABI to restrict
things to simpler case of integration time etc being controlled directly
and the _scale just updating when you change them as long as you update
scale_avail as well. That's ugly interface but not 'wrong' which is why
Matti created something more user friendly.
Jonathan
>
> Thanks and best regards,
> Javier Carrasco
