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

Commit Message

Jonathan Cameron June 26, 2022, 4:55 p.m. UTC

From: Jonathan Cameron <[e-mail]>

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/[e-mail]/
Signed-off-by: Jonathan Cameron <[e-mail]>
Cc: Fabrice Gasnier <[e-mail]>
---
 Documentation/ABI/testing/sysfs-bus-iio             | 3 +++
 Documentation/ABI/testing/sysfs-bus-iio-timer-stm32 | 8 --------
 2 files changed, 3 insertions(+), 8 deletions(-)

Comments

Mauro Carvalho Chehab June 26, 2022, 10:37 p.m. UTC | #1

Em Sun, 26 Jun 2022 17:55:10 +0100
Jonathan Cameron <[e-mail]> escreveu:

> From: Jonathan Cameron <[e-mail]>
> 
> 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/[e-mail]/
> Signed-off-by: Jonathan Cameron <[e-mail]>
> Cc: Fabrice Gasnier <[e-mail]>
> ---
>  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.

Either way:

Reviewed-by: Mauro Carvalho Chehab <[e-mail]>


>  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:	[e-mail]
> -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:	[e-mail]

Jonathan Cameron June 27, 2022, 2:09 p.m. UTC | #2

On Sun, 26 Jun 2022 23:37:45 +0100
Mauro Carvalho Chehab <[e-mail]> wrote:

> Em Sun, 26 Jun 2022 17:55:10 +0100
> Jonathan Cameron <[e-mail]> escreveu:
> 
> > From: Jonathan Cameron <[e-mail]>
> > 
> > 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/[e-mail]/
> > Signed-off-by: Jonathan Cameron <[e-mail]>
> > Cc: Fabrice Gasnier <[e-mail]>
> > ---
> >  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.

Jonathan

> Either way:
> 
> Reviewed-by: Mauro Carvalho Chehab <[e-mail]>
> 
> 
> >  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:	[e-mail]
> > -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:	[e-mail]

Mauro Carvalho Chehab June 28, 2022, 5:51 a.m. UTC | #3

Em Mon, 27 Jun 2022 15:09:55 +0100
Jonathan Cameron <[e-mail]> escreveu:

> On Sun, 26 Jun 2022 23:37:45 +0100
> Mauro Carvalho Chehab <[e-mail]> wrote:
> 
> > Em Sun, 26 Jun 2022 17:55:10 +0100
> > Jonathan Cameron <[e-mail]> escreveu:
> >   
> > > From: Jonathan Cameron <[e-mail]>
> > > 
> > > 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/[e-mail]/
> > > Signed-off-by: Jonathan Cameron <[e-mail]>
> > > Cc: Fabrice Gasnier <[e-mail]>
> > > ---
> > >  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.

Regards,
Mauro

> 
> Jonathan
> 
> > Either way:
> > 
> > Reviewed-by: Mauro Carvalho Chehab <[e-mail]>
> > 
> >   
> > >  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:	[e-mail]
> > > -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:	[e-mail]    
>

Jonathan Cameron July 18, 2022, 5:39 p.m. UTC | #4

On Tue, 28 Jun 2022 06:51:19 +0100
Mauro Carvalho Chehab <[e-mail]> wrote:

> Em Mon, 27 Jun 2022 15:09:55 +0100
> Jonathan Cameron <[e-mail]> escreveu:
> 
> > On Sun, 26 Jun 2022 23:37:45 +0100
> > Mauro Carvalho Chehab <[e-mail]> wrote:
> >   
> > > Em Sun, 26 Jun 2022 17:55:10 +0100
> > > Jonathan Cameron <[e-mail]> escreveu:
> > >     
> > > > From: Jonathan Cameron <[e-mail]>
> > > > 
> > > > 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/[e-mail]/
> > > > Signed-off-by: Jonathan Cameron <[e-mail]>
> > > > Cc: Fabrice Gasnier <[e-mail]>
> > > > ---
> > > >  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 <[e-mail]>
> > > 
> > >     
> > > >  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:	[e-mail]
> > > > -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:	[e-mail]      
> >

Patch

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.
+
 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:	[e-mail]
-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:	[e-mail]