Re: [PATCH v5 2/3] Documentation: ABI: added filter mode doc in sysfs-bus-iio

[Jonathan Cameron]

On Fri, 13 Sep 2024 20:36:32 +0300
Andy Shevchenko <andy.shevchenko@xxxxxxxxx> wrote:

> On Fri, Sep 13, 2024 at 02:06:48PM +0000, Nechita, Ramona wrote:
> > >>
> > >> The filter mode / filter type property is used for ad4130 and ad7779
> > >> drivers, therefore the ABI doc file for ad4130 was removed, merging
> > >> both of them in the sysfs-bus-iio.  
> 
> ...
> 
> > >> +What:          /sys/bus/iio/devices/iio:deviceX/filter_type_available
> > >> +What:          /sys/bus/iio/devices/iio:deviceX/in_voltage-voltage_filter_mode_available
> > >> +KernelVersion: 6.1  
> > >
> > >I believe I have already commented on this. The commit message keeps silent about version changes. Why?  
> > 
> > I mentioned it in the cover-letter, since the attributes of two devices were
> > merged, and one of them was available in 6.1 ad the other in 6.2, it felt
> > appropriate to leave it as 6.1.
> > I was wondering if this is ok or if it should be kept as 6.2. Should this be
> > mentioned in the commit message as well?  
> 
> Please, mention in the commit message.
> 
> > >> +Contact:       linux-iio@xxxxxxxxxxxxxxx
> > >> +Description:
> > >> +               Reading returns a list with the possible filter modes. Options
> > >> +               for the attribute:
> > >> +                       * "sinc3"       - The digital sinc3 filter. Moderate 1st conversion time.
> > >> +                   Good noise performance.
> > >> +                       * "sinc4"       - Sinc 4. Excellent noise performance. Long
> > >> +                       1st conversion time.
> > >> +                       * "sinc5"       - The digital sinc5 filter. Excellent noise performance
> > >> +                       * "sinc4+sinc1" - Sinc4 + averaging by 8. Low 1st conversion
> > >> +                   time.
> > >> +                       * "sinc3+rej60" - Sinc3 + 60Hz rejection.
> > >> +                       * "sinc3+sinc1" - Sinc3 + averaging by 8. Low 1st conversion
> > >> +                   time.
> > >> +                       * "sinc3+pf1"   - Sinc3 + device specific Post Filter 1.
> > >> +                       * "sinc3+pf2"   - Sinc3 + device specific Post Filter 2.
> > >> +                       * "sinc3+pf3"   - Sinc3 + device specific Post Filter 3.
> > >> +                       * "sinc3+pf4"   - Sinc3 + device specific Post Filter 4.  
> > >
> > >Also, the original file was more verbose for the complex cases, like
> > >"sinc3+pfX", why has this been changed?  
> > 
> > Since this is a more generic file I was advised to leave out specific
> > details, should I include them just as they were in the original file?  
> 
> I would leave the examples for the mentioned chip in the parentheses. But it's
> up to Jonathan, I have no such device anyway, so personally I'm not affected
> :-)

It gets tricky as we gain more and more devices.  Nice to have that data somewhere, but
maybe a device specific document is more appropriate than keeping it in here?
(i.e. not in the ABI docs, but in general IIO per device documentation similar to the
 docs added recently for various other ADI parts).

Jonathan

>