[v8,01/22] docs: counter: Consolidate Counter sysfs attributes documentation

Commit Message

William Breathitt Gray Feb. 12, 2021, 12:13 p.m. UTC

Duplicate ABIs are not valid, so let's consolidate these sysfs
attributes into the main sysfs-bus-counter documentation file.

Cc: Patrick Havelange <[e-mail]>
Signed-off-by: William Breathitt Gray <[e-mail]>
---
 Documentation/ABI/testing/sysfs-bus-counter   | 76 ++++++++++++++++++-
 .../ABI/testing/sysfs-bus-counter-104-quad-8  | 61 ---------------
 .../ABI/testing/sysfs-bus-counter-ftm-quaddec | 16 ----
 MAINTAINERS                                   |  4 +-
 4 files changed, 75 insertions(+), 82 deletions(-)
 delete mode 100644 Documentation/ABI/testing/sysfs-bus-counter-104-quad-8
 delete mode 100644 Documentation/ABI/testing/sysfs-bus-counter-ftm-quaddec

Comments

Jonathan Cameron Feb. 14, 2021, 4:57 p.m. UTC | #1

On Fri, 12 Feb 2021 21:13:25 +0900
William Breathitt Gray <[e-mail]> wrote:

> Duplicate ABIs are not valid, so let's consolidate these sysfs
> attributes into the main sysfs-bus-counter documentation file.

This is sensible to do, but is there any duplicate ABI?  I went
looking for any resulting build problems and couldn't see what was
actually duplicated.

Jonathan
> 
> Cc: Patrick Havelange <[e-mail]>
> Signed-off-by: William Breathitt Gray <[e-mail]>
> ---
>  Documentation/ABI/testing/sysfs-bus-counter   | 76 ++++++++++++++++++-
>  .../ABI/testing/sysfs-bus-counter-104-quad-8  | 61 ---------------
>  .../ABI/testing/sysfs-bus-counter-ftm-quaddec | 16 ----
>  MAINTAINERS                                   |  4 +-
>  4 files changed, 75 insertions(+), 82 deletions(-)
>  delete mode 100644 Documentation/ABI/testing/sysfs-bus-counter-104-quad-8
>  delete mode 100644 Documentation/ABI/testing/sysfs-bus-counter-ftm-quaddec
> 
> diff --git a/Documentation/ABI/testing/sysfs-bus-counter b/Documentation/ABI/testing/sysfs-bus-counter
> index 566bd99fe0a5..29f54484183f 100644
> --- a/Documentation/ABI/testing/sysfs-bus-counter
> +++ b/Documentation/ABI/testing/sysfs-bus-counter
> @@ -57,6 +57,7 @@ Description:
>  What:		/sys/bus/counter/devices/counterX/countY/count_mode_available
>  What:		/sys/bus/counter/devices/counterX/countY/error_noise_available
>  What:		/sys/bus/counter/devices/counterX/countY/function_available
> +What:		/sys/bus/counter/devices/counterX/countY/prescaler_available
>  What:		/sys/bus/counter/devices/counterX/countY/signalZ_action_available
>  KernelVersion:	5.2
>  Contact:	[e-mail]
> @@ -154,6 +155,15 @@ Description:
>  		Count Y. If possible, this should match the name of the
>  		respective channel as it appears in the device datasheet.
>  
> +What:		/sys/bus/counter/devices/counterX/countY/prescaler
> +KernelVersion:	5.2
> +Contact:	[e-mail]
> +Description:
> +		Configure the prescaler value associated with Count Y.
> +		On the FlexTimer, the counter clock source passes through a
> +		prescaler (i.e. a counter). This acts like a clock
> +		divider.
> +
>  What:		/sys/bus/counter/devices/counterX/countY/preset
>  KernelVersion:	5.2
>  Contact:	[e-mail]
> @@ -215,11 +225,45 @@ Description:
>  		Read-only attribute that indicates the total number of Signals
>  		belonging to the Counter.
>  
> -What:		/sys/bus/counter/devices/counterX/signalY/signal
> +What:		/sys/bus/counter/devices/counterX/signalY/cable_fault
> +KernelVersion:	5.7
> +Contact:	[e-mail]
> +Description:
> +		Read-only attribute that indicates whether a differential
> +		encoder cable fault (not connected or loose wires) is detected
> +		for the respective channel of Signal Y. Valid attribute values
> +		are boolean. Detection must first be enabled via the
> +		corresponding cable_fault_enable attribute.
> +
> +What:		/sys/bus/counter/devices/counterX/signalY/cable_fault_enable
> +KernelVersion:	5.7
> +Contact:	[e-mail]
> +Description:
> +		Whether detection of differential encoder cable faults for the
> +		respective channel of Signal Y is enabled. Valid attribute
> +		values are boolean.
> +
> +What:		/sys/bus/counter/devices/counterX/signalY/filter_clock_prescaler
> +KernelVersion:	5.7
> +Contact:	[e-mail]
> +Description:
> +		Filter clock factor for input Signal Y. This prescaler value
> +		affects the inputs of both quadrature pair signals.
> +
> +What:		/sys/bus/counter/devices/counterX/signalY/index_polarity
>  KernelVersion:	5.2
>  Contact:	[e-mail]
>  Description:
> -		Signal data of Signal Y represented as a string.
> +		Active level of index input Signal Y; irrelevant in
> +		non-synchronous load mode.
> +
> +What:		/sys/bus/counter/devices/counterX/signalY/index_polarity_available
> +What:		/sys/bus/counter/devices/counterX/signalY/synchronous_mode_available
> +KernelVersion:	5.2
> +Contact:	[e-mail]
> +Description:
> +		Discrete set of available values for the respective Signal Y
> +		configuration are listed in this file.
>  
>  What:		/sys/bus/counter/devices/counterX/signalY/name
>  KernelVersion:	5.2
> @@ -228,3 +272,31 @@ Description:
>  		Read-only attribute that indicates the device-specific name of
>  		Signal Y. If possible, this should match the name of the
>  		respective signal as it appears in the device datasheet.
> +
> +What:		/sys/bus/counter/devices/counterX/signalY/signal
> +KernelVersion:	5.2
> +Contact:	[e-mail]
> +Description:
> +		Signal data of Signal Y represented as a string.
> +
> +What:		/sys/bus/counter/devices/counterX/signalY/synchronous_mode
> +KernelVersion:	5.2
> +Contact:	[e-mail]
> +Description:
> +		Configure the counter associated with Signal Y for
> +		non-synchronous or synchronous load mode. Synchronous load mode
> +		cannot be selected in non-quadrature (Pulse-Direction) clock
> +		mode.
> +
> +		non-synchronous:
> +			A logic low level is the active level at this index
> +			input. The index function (as enabled via preset_enable)
> +			is performed directly on the active level of the index
> +			input.
> +
> +		synchronous:
> +			Intended for interfacing with encoder Index output in
> +			quadrature clock mode. The active level is configured
> +			via index_polarity. The index function (as enabled via
> +			preset_enable) is performed synchronously with the
> +			quadrature clock on the active level of the index input.
> diff --git a/Documentation/ABI/testing/sysfs-bus-counter-104-quad-8 b/Documentation/ABI/testing/sysfs-bus-counter-104-quad-8
> deleted file mode 100644
> index eac32180c40d..000000000000
> --- a/Documentation/ABI/testing/sysfs-bus-counter-104-quad-8
> +++ /dev/null
> @@ -1,61 +0,0 @@
> -What:		/sys/bus/counter/devices/counterX/signalY/cable_fault
> -KernelVersion:	5.7
> -Contact:	[e-mail]
> -Description:
> -		Read-only attribute that indicates whether a differential
> -		encoder cable fault (not connected or loose wires) is detected
> -		for the respective channel of Signal Y. Valid attribute values
> -		are boolean. Detection must first be enabled via the
> -		corresponding cable_fault_enable attribute.
> -
> -What:		/sys/bus/counter/devices/counterX/signalY/cable_fault_enable
> -KernelVersion:	5.7
> -Contact:	[e-mail]
> -Description:
> -		Whether detection of differential encoder cable faults for the
> -		respective channel of Signal Y is enabled. Valid attribute
> -		values are boolean.
> -
> -What:		/sys/bus/counter/devices/counterX/signalY/filter_clock_prescaler
> -KernelVersion:	5.7
> -Contact:	[e-mail]
> -Description:
> -		Filter clock factor for input Signal Y. This prescaler value
> -		affects the inputs of both quadrature pair signals.
> -
> -What:		/sys/bus/counter/devices/counterX/signalY/index_polarity
> -KernelVersion:	5.2
> -Contact:	[e-mail]
> -Description:
> -		Active level of index input Signal Y; irrelevant in
> -		non-synchronous load mode.
> -
> -What:		/sys/bus/counter/devices/counterX/signalY/index_polarity_available
> -What:		/sys/bus/counter/devices/counterX/signalY/synchronous_mode_available
> -KernelVersion:	5.2
> -Contact:	[e-mail]
> -Description:
> -		Discrete set of available values for the respective Signal Y
> -		configuration are listed in this file.
> -
> -What:		/sys/bus/counter/devices/counterX/signalY/synchronous_mode
> -KernelVersion:	5.2
> -Contact:	[e-mail]
> -Description:
> -		Configure the counter associated with Signal Y for
> -		non-synchronous or synchronous load mode. Synchronous load mode
> -		cannot be selected in non-quadrature (Pulse-Direction) clock
> -		mode.
> -
> -		non-synchronous:
> -			A logic low level is the active level at this index
> -			input. The index function (as enabled via preset_enable)
> -			is performed directly on the active level of the index
> -			input.
> -
> -		synchronous:
> -			Intended for interfacing with encoder Index output in
> -			quadrature clock mode. The active level is configured
> -			via index_polarity. The index function (as enabled via
> -			preset_enable) is performed synchronously with the
> -			quadrature clock on the active level of the index input.
> diff --git a/Documentation/ABI/testing/sysfs-bus-counter-ftm-quaddec b/Documentation/ABI/testing/sysfs-bus-counter-ftm-quaddec
> deleted file mode 100644
> index 7d2e7b363467..000000000000
> --- a/Documentation/ABI/testing/sysfs-bus-counter-ftm-quaddec
> +++ /dev/null
> @@ -1,16 +0,0 @@
> -What:		/sys/bus/counter/devices/counterX/countY/prescaler_available
> -KernelVersion:	5.2
> -Contact:	[e-mail]
> -Description:
> -		Discrete set of available values for the respective Count Y
> -		configuration are listed in this file. Values are delimited by
> -		newline characters.
> -
> -What:		/sys/bus/counter/devices/counterX/countY/prescaler
> -KernelVersion:	5.2
> -Contact:	[e-mail]
> -Description:
> -		Configure the prescaler value associated with Count Y.
> -		On the FlexTimer, the counter clock source passes through a
> -		prescaler (i.e. a counter). This acts like a clock
> -		divider.
> diff --git a/MAINTAINERS b/MAINTAINERS
> index e697044d34d6..d858582c917b 100644
> --- a/MAINTAINERS
> +++ b/MAINTAINERS
> @@ -297,7 +297,6 @@ M:	William Breathitt Gray <[e-mail]>
>  M:	Syed Nayyar Waris <[e-mail]>
>  L:	[e-mail]
>  S:	Maintained
> -F:	Documentation/ABI/testing/sysfs-bus-counter-104-quad-8
>  F:	drivers/counter/104-quad-8.c
>  
>  ACCES PCI-IDIO-16 GPIO DRIVER
> @@ -4540,7 +4539,7 @@ COUNTER SUBSYSTEM
>  M:	William Breathitt Gray <[e-mail]>
>  L:	[e-mail]
>  S:	Maintained
> -F:	Documentation/ABI/testing/sysfs-bus-counter*
> +F:	Documentation/ABI/testing/sysfs-bus-counter
>  F:	Documentation/driver-api/generic-counter.rst
>  F:	drivers/counter/
>  F:	include/linux/counter.h
> @@ -6925,7 +6924,6 @@ FLEXTIMER FTM-QUADDEC DRIVER
>  M:	Patrick Havelange <[e-mail]>
>  L:	[e-mail]
>  S:	Maintained
> -F:	Documentation/ABI/testing/sysfs-bus-counter-ftm-quaddec
>  F:	Documentation/devicetree/bindings/counter/ftm-quaddec.txt
>  F:	drivers/counter/ftm-quaddec.c
>

William Breathitt Gray Feb. 15, 2021, 11:05 a.m. UTC | #2

On Sun, Feb 14, 2021 at 04:57:52PM +0000, Jonathan Cameron wrote:
> On Fri, 12 Feb 2021 21:13:25 +0900
> William Breathitt Gray <[e-mail]> wrote:
> 
> > Duplicate ABIs are not valid, so let's consolidate these sysfs
> > attributes into the main sysfs-bus-counter documentation file.
> 
> This is sensible to do, but is there any duplicate ABI?  I went
> looking for any resulting build problems and couldn't see what was
> actually duplicated.
> 
> Jonathan

There's no duplication currently, so this is just a preventative
measure. These files were started for the purpose of permitting future
duplication; now that duplication is explicitly disallowed, we're better
off consolidating these now in order to prevent fragmentation of the
documentation.

William Breathitt Gray

David Lechner Feb. 20, 2021, 4:25 p.m. UTC | #3

On 2/12/21 6:13 AM, William Breathitt Gray wrote:
> Duplicate ABIs are not valid, so let's consolidate these sysfs
> attributes into the main sysfs-bus-counter documentation file.
> 
> Cc: Patrick Havelange <[e-mail]>
> Signed-off-by: William Breathitt Gray <[e-mail]>
> ---

Reviewed-by: David Lechner <[e-mail]>

Patch

diff --git a/Documentation/ABI/testing/sysfs-bus-counter b/Documentation/ABI/testing/sysfs-bus-counter
index 566bd99fe0a5..29f54484183f 100644
--- a/Documentation/ABI/testing/sysfs-bus-counter
+++ b/Documentation/ABI/testing/sysfs-bus-counter
@@ -57,6 +57,7 @@  Description:
 What:		/sys/bus/counter/devices/counterX/countY/count_mode_available
 What:		/sys/bus/counter/devices/counterX/countY/error_noise_available
 What:		/sys/bus/counter/devices/counterX/countY/function_available
+What:		/sys/bus/counter/devices/counterX/countY/prescaler_available
 What:		/sys/bus/counter/devices/counterX/countY/signalZ_action_available
 KernelVersion:	5.2
 Contact:	[e-mail]
@@ -154,6 +155,15 @@  Description:
 		Count Y. If possible, this should match the name of the
 		respective channel as it appears in the device datasheet.
 
+What:		/sys/bus/counter/devices/counterX/countY/prescaler
+KernelVersion:	5.2
+Contact:	[e-mail]
+Description:
+		Configure the prescaler value associated with Count Y.
+		On the FlexTimer, the counter clock source passes through a
+		prescaler (i.e. a counter). This acts like a clock
+		divider.
+
 What:		/sys/bus/counter/devices/counterX/countY/preset
 KernelVersion:	5.2
 Contact:	[e-mail]
@@ -215,11 +225,45 @@  Description:
 		Read-only attribute that indicates the total number of Signals
 		belonging to the Counter.
 
-What:		/sys/bus/counter/devices/counterX/signalY/signal
+What:		/sys/bus/counter/devices/counterX/signalY/cable_fault
+KernelVersion:	5.7
+Contact:	[e-mail]
+Description:
+		Read-only attribute that indicates whether a differential
+		encoder cable fault (not connected or loose wires) is detected
+		for the respective channel of Signal Y. Valid attribute values
+		are boolean. Detection must first be enabled via the
+		corresponding cable_fault_enable attribute.
+
+What:		/sys/bus/counter/devices/counterX/signalY/cable_fault_enable
+KernelVersion:	5.7
+Contact:	[e-mail]
+Description:
+		Whether detection of differential encoder cable faults for the
+		respective channel of Signal Y is enabled. Valid attribute
+		values are boolean.
+
+What:		/sys/bus/counter/devices/counterX/signalY/filter_clock_prescaler
+KernelVersion:	5.7
+Contact:	[e-mail]
+Description:
+		Filter clock factor for input Signal Y. This prescaler value
+		affects the inputs of both quadrature pair signals.
+
+What:		/sys/bus/counter/devices/counterX/signalY/index_polarity
 KernelVersion:	5.2
 Contact:	[e-mail]
 Description:
-		Signal data of Signal Y represented as a string.
+		Active level of index input Signal Y; irrelevant in
+		non-synchronous load mode.
+
+What:		/sys/bus/counter/devices/counterX/signalY/index_polarity_available
+What:		/sys/bus/counter/devices/counterX/signalY/synchronous_mode_available
+KernelVersion:	5.2
+Contact:	[e-mail]
+Description:
+		Discrete set of available values for the respective Signal Y
+		configuration are listed in this file.
 
 What:		/sys/bus/counter/devices/counterX/signalY/name
 KernelVersion:	5.2
@@ -228,3 +272,31 @@  Description:
 		Read-only attribute that indicates the device-specific name of
 		Signal Y. If possible, this should match the name of the
 		respective signal as it appears in the device datasheet.
+
+What:		/sys/bus/counter/devices/counterX/signalY/signal
+KernelVersion:	5.2
+Contact:	[e-mail]
+Description:
+		Signal data of Signal Y represented as a string.
+
+What:		/sys/bus/counter/devices/counterX/signalY/synchronous_mode
+KernelVersion:	5.2
+Contact:	[e-mail]
+Description:
+		Configure the counter associated with Signal Y for
+		non-synchronous or synchronous load mode. Synchronous load mode
+		cannot be selected in non-quadrature (Pulse-Direction) clock
+		mode.
+
+		non-synchronous:
+			A logic low level is the active level at this index
+			input. The index function (as enabled via preset_enable)
+			is performed directly on the active level of the index
+			input.
+
+		synchronous:
+			Intended for interfacing with encoder Index output in
+			quadrature clock mode. The active level is configured
+			via index_polarity. The index function (as enabled via
+			preset_enable) is performed synchronously with the
+			quadrature clock on the active level of the index input.
diff --git a/Documentation/ABI/testing/sysfs-bus-counter-104-quad-8 b/Documentation/ABI/testing/sysfs-bus-counter-104-quad-8
deleted file mode 100644
index eac32180c40d..000000000000
--- a/Documentation/ABI/testing/sysfs-bus-counter-104-quad-8
+++ /dev/null
@@ -1,61 +0,0 @@ 
-What:		/sys/bus/counter/devices/counterX/signalY/cable_fault
-KernelVersion:	5.7
-Contact:	[e-mail]
-Description:
-		Read-only attribute that indicates whether a differential
-		encoder cable fault (not connected or loose wires) is detected
-		for the respective channel of Signal Y. Valid attribute values
-		are boolean. Detection must first be enabled via the
-		corresponding cable_fault_enable attribute.
-
-What:		/sys/bus/counter/devices/counterX/signalY/cable_fault_enable
-KernelVersion:	5.7
-Contact:	[e-mail]
-Description:
-		Whether detection of differential encoder cable faults for the
-		respective channel of Signal Y is enabled. Valid attribute
-		values are boolean.
-
-What:		/sys/bus/counter/devices/counterX/signalY/filter_clock_prescaler
-KernelVersion:	5.7
-Contact:	[e-mail]
-Description:
-		Filter clock factor for input Signal Y. This prescaler value
-		affects the inputs of both quadrature pair signals.
-
-What:		/sys/bus/counter/devices/counterX/signalY/index_polarity
-KernelVersion:	5.2
-Contact:	[e-mail]
-Description:
-		Active level of index input Signal Y; irrelevant in
-		non-synchronous load mode.
-
-What:		/sys/bus/counter/devices/counterX/signalY/index_polarity_available
-What:		/sys/bus/counter/devices/counterX/signalY/synchronous_mode_available
-KernelVersion:	5.2
-Contact:	[e-mail]
-Description:
-		Discrete set of available values for the respective Signal Y
-		configuration are listed in this file.
-
-What:		/sys/bus/counter/devices/counterX/signalY/synchronous_mode
-KernelVersion:	5.2
-Contact:	[e-mail]
-Description:
-		Configure the counter associated with Signal Y for
-		non-synchronous or synchronous load mode. Synchronous load mode
-		cannot be selected in non-quadrature (Pulse-Direction) clock
-		mode.
-
-		non-synchronous:
-			A logic low level is the active level at this index
-			input. The index function (as enabled via preset_enable)
-			is performed directly on the active level of the index
-			input.
-
-		synchronous:
-			Intended for interfacing with encoder Index output in
-			quadrature clock mode. The active level is configured
-			via index_polarity. The index function (as enabled via
-			preset_enable) is performed synchronously with the
-			quadrature clock on the active level of the index input.
diff --git a/Documentation/ABI/testing/sysfs-bus-counter-ftm-quaddec b/Documentation/ABI/testing/sysfs-bus-counter-ftm-quaddec
deleted file mode 100644
index 7d2e7b363467..000000000000
--- a/Documentation/ABI/testing/sysfs-bus-counter-ftm-quaddec
+++ /dev/null
@@ -1,16 +0,0 @@ 
-What:		/sys/bus/counter/devices/counterX/countY/prescaler_available
-KernelVersion:	5.2
-Contact:	[e-mail]
-Description:
-		Discrete set of available values for the respective Count Y
-		configuration are listed in this file. Values are delimited by
-		newline characters.
-
-What:		/sys/bus/counter/devices/counterX/countY/prescaler
-KernelVersion:	5.2
-Contact:	[e-mail]
-Description:
-		Configure the prescaler value associated with Count Y.
-		On the FlexTimer, the counter clock source passes through a
-		prescaler (i.e. a counter). This acts like a clock
-		divider.
diff --git a/MAINTAINERS b/MAINTAINERS
index e697044d34d6..d858582c917b 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -297,7 +297,6 @@  M:	William Breathitt Gray <[e-mail]>
 M:	Syed Nayyar Waris <[e-mail]>
 L:	[e-mail]
 S:	Maintained
-F:	Documentation/ABI/testing/sysfs-bus-counter-104-quad-8
 F:	drivers/counter/104-quad-8.c
 
 ACCES PCI-IDIO-16 GPIO DRIVER
@@ -4540,7 +4539,7 @@  COUNTER SUBSYSTEM
 M:	William Breathitt Gray <[e-mail]>
 L:	[e-mail]
 S:	Maintained
-F:	Documentation/ABI/testing/sysfs-bus-counter*
+F:	Documentation/ABI/testing/sysfs-bus-counter
 F:	Documentation/driver-api/generic-counter.rst
 F:	drivers/counter/
 F:	include/linux/counter.h
@@ -6925,7 +6924,6 @@  FLEXTIMER FTM-QUADDEC DRIVER
 M:	Patrick Havelange <[e-mail]>
 L:	[e-mail]
 S:	Maintained
-F:	Documentation/ABI/testing/sysfs-bus-counter-ftm-quaddec
 F:	Documentation/devicetree/bindings/counter/ftm-quaddec.txt
 F:	drivers/counter/ftm-quaddec.c