Re: [PATCH 3/4] iio: ABI: stm32-timer-trigger: Fuse unusual ABI into main doc.

[Jonathan Cameron <jic23@kernel.org>]

On Tue, 28 Jun 2022 06:51:19 +0100
Mauro Carvalho Chehab <mchehab@kernel.org> wrote:

> Em Mon, 27 Jun 2022 15:09:55 +0100
> Jonathan Cameron <Jonathan.Cameron@Huawei.com> escreveu:
> 
> > On Sun, 26 Jun 2022 23:37:45 +0100
> > Mauro Carvalho Chehab <mchehab@kernel.org> wrote:
> >   
> > > Em Sun, 26 Jun 2022 17:55:10 +0100
> > > Jonathan Cameron <jic23@kernel.org> escreveu:
> > >     
> > > > From: Jonathan Cameron <Jonathan.Cameron@huawei.com>
> > > > 
> > > > We can't duplicate the description of sampling_frequency. This device
> > > > has some unusual requirements which we solved by giving a
> > > > sampling_frequency of 0 special meaning. As such add a note
> > > > about this unusual usage to the main documentation.
> > > > 
> > > > Whilst I don't particularly like this resolution, it is the best
> > > > I could come up with given earlier discussion on this topic.
> > > > 
> > > > Link: https://lore.kernel.org/linux-iio/20210315101217.00002c50@Huawei.com/
> > > > Signed-off-by: Jonathan Cameron <Jonathan.Cameron@huawei.com>
> > > > Cc: Fabrice Gasnier <fabrice.gasnier@foss.st.com>
> > > > ---
> > > >  Documentation/ABI/testing/sysfs-bus-iio             | 3 +++
> > > >  Documentation/ABI/testing/sysfs-bus-iio-timer-stm32 | 8 --------
> > > >  2 files changed, 3 insertions(+), 8 deletions(-)
> > > > 
> > > > diff --git a/Documentation/ABI/testing/sysfs-bus-iio b/Documentation/ABI/testing/sysfs-bus-iio
> > > > index 3e00d7f7ee22..e81ba6f5e1c8 100644
> > > > --- a/Documentation/ABI/testing/sysfs-bus-iio
> > > > +++ b/Documentation/ABI/testing/sysfs-bus-iio
> > > > @@ -107,6 +107,9 @@ Description:
> > > >  		relevant directories.  If it affects all of the above
> > > >  		then it is to be found in the base device directory.
> > > >  
> > > > +		The stm32-timer-trigger has the additional characteristic that
> > > > +		a sampling_frequency of 0 is defined to stop sampling.
> > > > +      
> > > 
> > > I would actually say something like:
> > > 
> > > 		A ampling_frequency of 0 means to stop sampling,
> > > 		if supported by the driver.
> > >     
> > 
> > We actively want to stop people doing this without coming
> > to the list and explaining exactly why they need to. The discussion
> > around that one exception was long and involved. So we want
> > them to have to modify this doc to list their part thus raising
> > awareness of them doing this. So far it's in one driver our of many
> > (and to use this feature it needs custom userspace as it is
> > setting up a complex chain of devices, but for other more conventional
> > use, not allowing 0 is fine).
> > 
> > The source of this disagreement is the documentation serves two
> > purposes - for userspace code authors and for kernel developers.
> > Userspace can just not set the value to 0 if it is generic code.
> > 
> > We could add additional ABI element to make userspace aware, but
> > so far only this one device which will run with customer userspace
> > uses this.  Hence we rely on documentation.  
> 
> 
> OK!
> 
> This actually proves the point that duplicated symbols at ABI cause
> troubles, as different implementations could end abusing on what
> it would be expected, like in this case ;-)
> 
> Anyway, feel free to add my reviewed-by to this patch.
Picked up 2 and 3 of this series. 4 was fixed by someone else.

Thanks,

Jonathan

> 
> Regards,
> Mauro
> 
> > 
> > Jonathan
> >   
> > > Either way:
> > > 
> > > Reviewed-by: Mauro Carvalho Chehab <mchehab@kernel.org>
> > > 
> > >     
> > > >  What:		/sys/bus/iio/devices/iio:deviceX/sampling_frequency_available
> > > >  What:		/sys/bus/iio/devices/iio:deviceX/in_intensity_sampling_frequency_available
> > > >  What:		/sys/bus/iio/devices/iio:deviceX/in_proximity_sampling_frequency_available
> > > > diff --git a/Documentation/ABI/testing/sysfs-bus-iio-timer-stm32 b/Documentation/ABI/testing/sysfs-bus-iio-timer-stm32
> > > > index c4a4497c249a..05074c4a65e2 100644
> > > > --- a/Documentation/ABI/testing/sysfs-bus-iio-timer-stm32
> > > > +++ b/Documentation/ABI/testing/sysfs-bus-iio-timer-stm32
> > > > @@ -90,14 +90,6 @@ Description:
> > > >  		Reading returns the current master modes.
> > > >  		Writing set the master mode
> > > >  
> > > > -What:		/sys/bus/iio/devices/triggerX/sampling_frequency
> > > > -KernelVersion:	4.11
> > > > -Contact:	benjamin.gaignard@st.com
> > > > -Description:
> > > > -		Reading returns the current sampling frequency.
> > > > -		Writing an value different of 0 set and start sampling.
> > > > -		Writing 0 stop sampling.
> > > > -
> > > >  What:		/sys/bus/iio/devices/iio:deviceX/in_count0_preset
> > > >  KernelVersion:	4.12
> > > >  Contact:	benjamin.gaignard@st.com      
> >