Re: [PATCH 2/4] iio: inkern: Add a helper to query an available minimum raw value

[Jonathan Cameron <jic23@kernel.org>]

> > > diff --git a/include/linux/iio/consumer.h b/include/linux/iio/consumer.h
> > > index 6802596b017c..956120d8b5a3 100644
> > > --- a/include/linux/iio/consumer.h
> > > +++ b/include/linux/iio/consumer.h
> > > @@ -297,6 +297,17 @@ int iio_write_channel_raw(struct iio_channel *chan, int val);
> > >   */
> > >  int iio_read_max_channel_raw(struct iio_channel *chan, int *val);
> > >  
> > > +/**
> > > + * iio_read_min_channel_raw() - read minimum available raw value from a given
> > > + *				channel, i.e. the minimum possible value.
> > > + * @chan:		The channel being queried.
> > > + * @val:		Value read back.
> > > + *
> > > + * Note raw reads from iio channels are in adc counts and hence
> > > + * scale will need to be applied if standard units are required.    
> > 
> > Hmm. That comment is almost always true, but not quite.  Not related to
> > your patch but some cleanup of this documentation and pushing it down next
> > to implementations should be done at some point.  If anyone is really
> > bored and wants to take this on that's fine. If not, another one for the
> > todo list ;)  
> 
> If you are ok, I can change every where in consumer.h the following:
>   * Note raw reads from iio channels are in adc counts and hence
>   * scale will need to be applied if standard units required.
> by
>   * Note raw reads from iio channels are not in standards units and
>   * hence scale will need to be applied if standard units required.

If going to the effort, we should include offset and make it clear how
they are applied.

    * Note, if standard units are required, raw reads from iio channels
    * need the offset (default 0) and scale (default 1) to be applied
    * as (raw + offset) * scale.
 

> 
> Also the same for raw writes:
>   * Note raw writes to iio channels are in dac counts and hence
>   * scale will need to be applied if standard units required.
> by
>   * Note raw writes to iio channels are not in standards units and
>   * hence scale will need to be applied if standard units required.
This one is more interesting because you kind of need to apply the opposite
logic. Perhaps text such as.

    * Note that for raw writes to iio channels, if the value provided is
    * in standard units, the affect of the scale and offset must be removed
    * as (value / scale) - offset.

My slight concern is that we'll spend longer arguing about these comments
than we spend on the rest of the patch set.  Might be worth delaying
fixing the others for a separate series after this one.

Jonathan

> 
> >   
> > > + */
> > > +int iio_read_min_channel_raw(struct iio_channel *chan, int *val);
> > > +
> > >  /**
> > >   * iio_read_avail_channel_raw() - read available raw values from a given channel
> > >   * @chan:		The channel being queried.    
> >   
> 
> Thanks for the review,
> Hervé
>