Re: [PATCH v5 3/8] docs: Add Generic Counter interface documentation

[Jonathan Cameron]

On Fri,  9 Mar 2018 13:42:48 -0500
William Breathitt Gray  wrote:

> This patch adds high-level documentation about the Generic Counter
> interface.
> 
> Signed-off-by: William Breathitt Gray 
Other than the little issues Randy raised and one more inline from
me this looks good to me.

I would suggest you check whitespace in general to make sure there
are not other odd mixes of tabs and spaces hiding in here.

Reviewed-by: Jonathan Cameron 

> ---
>  Documentation/driver-api/generic-counter.rst | 321 
> +++
>  Documentation/driver-api/index.rst   |   1 +
>  MAINTAINERS  |   1 +
>  3 files changed, 323 insertions(+)
>  create mode 100644 Documentation/driver-api/generic-counter.rst
> 
> diff --git a/Documentation/driver-api/generic-counter.rst 
> b/Documentation/driver-api/generic-counter.rst
> new file mode 100644
> index ..bce0cbc31963
> --- /dev/null
> +++ b/Documentation/driver-api/generic-counter.rst
> @@ -0,0 +1,321 @@
> +=
> +Generic Counter Interface
> +=
> +
> +Introduction
> +
> +
> +Counter devices are prevalent within a diverse spectrum of industries.
> +The ubiquitous presence of these devices necessitates a common interface
> +and standard of interaction and exposure. This driver API attempts to
> +resolve the issue of duplicate code found among existing counter device
> +drivers by introducing a generic counter interface for consumption. The
> +Generic Counter interface enables drivers to support and expose a common
> +set of components and functionality present in counter devices.
> +
> +Theory
> +==
> +
> +Counter devices can vary greatly in design, but regardless of whether
> +some devices are quadrature encoder counters or tally counters, all
> +counter devices consist of a core set of components. This core set of
> +components, shared by all counter devices, is what forms the essence of
> +the Generic Counter interface.
> +
> +There are three core components to a counter:
> +
> +COUNT
> +-
> +A Count represents the count data for a set of Signals. The
> +Generic Counter interface provides the following available count
> +data types:
> +
> + * COUNT_POSITION_UNSIGNED:
> + Unsigned integer value representing position.
> +
> + * COUNT_POSITION_SIGNED:
> + Signed integer value representing position.
> +
> +A Count has a count function mode which represents the update
> +behavior for the count data. The Generic Counter interface
> +provides the following available count function modes:
> +
> + * Increase:
> + Accumulated count is incremented.
> +
> + * Decrease:
> + Accumulated count is decremented.
> +
> + * Pulse-Direction:
> + Rising edges on quadrature pair signal A updates
> +the respective count. The input level of
> +quadrature pair signal B determines direction.
> +
> + * Quadrature x1:
> + If direction is forward, rising edges on
> +quadrature pair signal A updates the respective
> +count; if the direction is backward, falling
> +edges on quadrature pair signal A updates the
> +respective count. Quadrature encoding determines
> +the direction.
> +
> + * Quadrature x2:
> + Any state transition on quadrature pair signal A
> +updates the respective count. Quadrature
> +encoding determines the direction.
> +
> + * Quadrature x4:
> + Any state transition on either quadrature pair
> +signals updates  the respective count. Quadrature
> +encoding determines the direction.
> +
> +A Count has a set of one or more associated Signals.
> +
> +SIGNAL
> +--
> +A Signal represents a counter input data; this is the input data
> +that is analyzed by the counter to determine the count data;
> +e.g. a quadrature signal output line of a rotary encoder. Not
> +all counter devices provide user access to the Signal data.
> +
> +The Generic Counter interface provides the following available
> +signal data types for when the Signal data is available for user
> +access:
> +
> + * SIGNAL_LEVEL_LOW:
> +Signal line is in a low state.
> +
> +* SIGNAL_LEVEL_HIGH:
> +Signal line is in a high state.

Something odd in formatting here as those two bullet points should

Re: [PATCH v5 3/8] docs: Add Generic Counter interface documentation

[Jonathan Cameron]

On Fri,  9 Mar 2018 13:42:48 -0500
William Breathitt Gray  wrote:

> This patch adds high-level documentation about the Generic Counter
> interface.
> 
> Signed-off-by: William Breathitt Gray 
Other than the little issues Randy raised and one more inline from
me this looks good to me.

I would suggest you check whitespace in general to make sure there
are not other odd mixes of tabs and spaces hiding in here.

Reviewed-by: Jonathan Cameron 

> ---
>  Documentation/driver-api/generic-counter.rst | 321 
> +++
>  Documentation/driver-api/index.rst   |   1 +
>  MAINTAINERS  |   1 +
>  3 files changed, 323 insertions(+)
>  create mode 100644 Documentation/driver-api/generic-counter.rst
> 
> diff --git a/Documentation/driver-api/generic-counter.rst 
> b/Documentation/driver-api/generic-counter.rst
> new file mode 100644
> index ..bce0cbc31963
> --- /dev/null
> +++ b/Documentation/driver-api/generic-counter.rst
> @@ -0,0 +1,321 @@
> +=
> +Generic Counter Interface
> +=
> +
> +Introduction
> +
> +
> +Counter devices are prevalent within a diverse spectrum of industries.
> +The ubiquitous presence of these devices necessitates a common interface
> +and standard of interaction and exposure. This driver API attempts to
> +resolve the issue of duplicate code found among existing counter device
> +drivers by introducing a generic counter interface for consumption. The
> +Generic Counter interface enables drivers to support and expose a common
> +set of components and functionality present in counter devices.
> +
> +Theory
> +==
> +
> +Counter devices can vary greatly in design, but regardless of whether
> +some devices are quadrature encoder counters or tally counters, all
> +counter devices consist of a core set of components. This core set of
> +components, shared by all counter devices, is what forms the essence of
> +the Generic Counter interface.
> +
> +There are three core components to a counter:
> +
> +COUNT
> +-
> +A Count represents the count data for a set of Signals. The
> +Generic Counter interface provides the following available count
> +data types:
> +
> + * COUNT_POSITION_UNSIGNED:
> + Unsigned integer value representing position.
> +
> + * COUNT_POSITION_SIGNED:
> + Signed integer value representing position.
> +
> +A Count has a count function mode which represents the update
> +behavior for the count data. The Generic Counter interface
> +provides the following available count function modes:
> +
> + * Increase:
> + Accumulated count is incremented.
> +
> + * Decrease:
> + Accumulated count is decremented.
> +
> + * Pulse-Direction:
> + Rising edges on quadrature pair signal A updates
> +the respective count. The input level of
> +quadrature pair signal B determines direction.
> +
> + * Quadrature x1:
> + If direction is forward, rising edges on
> +quadrature pair signal A updates the respective
> +count; if the direction is backward, falling
> +edges on quadrature pair signal A updates the
> +respective count. Quadrature encoding determines
> +the direction.
> +
> + * Quadrature x2:
> + Any state transition on quadrature pair signal A
> +updates the respective count. Quadrature
> +encoding determines the direction.
> +
> + * Quadrature x4:
> + Any state transition on either quadrature pair
> +signals updates  the respective count. Quadrature
> +encoding determines the direction.
> +
> +A Count has a set of one or more associated Signals.
> +
> +SIGNAL
> +--
> +A Signal represents a counter input data; this is the input data
> +that is analyzed by the counter to determine the count data;
> +e.g. a quadrature signal output line of a rotary encoder. Not
> +all counter devices provide user access to the Signal data.
> +
> +The Generic Counter interface provides the following available
> +signal data types for when the Signal data is available for user
> +access:
> +
> + * SIGNAL_LEVEL_LOW:
> +Signal line is in a low state.
> +
> +* SIGNAL_LEVEL_HIGH:
> +Signal line is in a high state.

Something odd in formatting here as those two bullet points should
be aligned.

> +
> +A Signal may be associated to one or more 

Re: [PATCH v5 3/8] docs: Add Generic Counter interface documentation

[Randy Dunlap]

On 03/09/2018 10:42 AM, William Breathitt Gray wrote:
> This patch adds high-level documentation about the Generic Counter
> interface.
> 
> Signed-off-by: William Breathitt Gray 
> ---
>  Documentation/driver-api/generic-counter.rst | 321 
> +++
>  Documentation/driver-api/index.rst   |   1 +
>  MAINTAINERS  |   1 +
>  3 files changed, 323 insertions(+)
>  create mode 100644 Documentation/driver-api/generic-counter.rst
> 
> diff --git a/Documentation/driver-api/generic-counter.rst 
> b/Documentation/driver-api/generic-counter.rst
> new file mode 100644
> index ..bce0cbc31963
> --- /dev/null
> +++ b/Documentation/driver-api/generic-counter.rst
> @@ -0,0 +1,321 @@

[snip]

> +There are three core components to a counter:
> +
> +COUNT
> +-
> +A Count represents the count data for a set of Signals. The
> +Generic Counter interface provides the following available count
> +data types:
> +
> + * COUNT_POSITION_UNSIGNED:
> + Unsigned integer value representing position.
> +
> + * COUNT_POSITION_SIGNED:
> + Signed integer value representing position.
> +
> +A Count has a count function mode which represents the update
> +behavior for the count data. The Generic Counter interface
> +provides the following available count function modes:
> +
> + * Increase:
> + Accumulated count is incremented.
> +
> + * Decrease:
> + Accumulated count is decremented.
> +
> + * Pulse-Direction:
> + Rising edges on quadrature pair signal A updates
> +the respective count. The input level of
> +quadrature pair signal B determines direction.
> +
> + * Quadrature x1:
> + If direction is forward, rising edges on
> +quadrature pair signal A updates the respective
> +count; if the direction is backward, falling
> +edges on quadrature pair signal A updates the
> +respective count. Quadrature encoding determines
> +the direction.
> +
> + * Quadrature x2:
> + Any state transition on quadrature pair signal A
> +updates the respective count. Quadrature
> +encoding determines the direction.
> +
> + * Quadrature x4:
> + Any state transition on either quadrature pair
> +signals updates  the respective count. Quadrature

   change  ^^^ to 

> +encoding determines the direction.
> +
> +A Count has a set of one or more associated Signals.
> +
> +SIGNAL
> +--
> +A Signal represents a counter input data; this is the input data
> +that is analyzed by the counter to determine the count data;
> +e.g. a quadrature signal output line of a rotary encoder. Not
> +all counter devices provide user access to the Signal data.
> +
> +The Generic Counter interface provides the following available
> +signal data types for when the Signal data is available for user
> +access:
> +
> + * SIGNAL_LEVEL_LOW:
> +Signal line is in a low state.
> +
> +* SIGNAL_LEVEL_HIGH:
> +Signal line is in a high state.
> +
> +A Signal may be associated to one or more Counts.

  with (?)

Hm, there are around 8 or so instances of "associated to" here -- and at least
one of "associated with" (to my surprise :).  But it's no big deal.


Reviewed-by: Randy Dunlap 

thanks,
-- 
~Randy

Re: [PATCH v5 3/8] docs: Add Generic Counter interface documentation

[Randy Dunlap]

On 03/09/2018 10:42 AM, William Breathitt Gray wrote:
> This patch adds high-level documentation about the Generic Counter
> interface.
> 
> Signed-off-by: William Breathitt Gray 
> ---
>  Documentation/driver-api/generic-counter.rst | 321 
> +++
>  Documentation/driver-api/index.rst   |   1 +
>  MAINTAINERS  |   1 +
>  3 files changed, 323 insertions(+)
>  create mode 100644 Documentation/driver-api/generic-counter.rst
> 
> diff --git a/Documentation/driver-api/generic-counter.rst 
> b/Documentation/driver-api/generic-counter.rst
> new file mode 100644
> index ..bce0cbc31963
> --- /dev/null
> +++ b/Documentation/driver-api/generic-counter.rst
> @@ -0,0 +1,321 @@

[snip]

> +There are three core components to a counter:
> +
> +COUNT
> +-
> +A Count represents the count data for a set of Signals. The
> +Generic Counter interface provides the following available count
> +data types:
> +
> + * COUNT_POSITION_UNSIGNED:
> + Unsigned integer value representing position.
> +
> + * COUNT_POSITION_SIGNED:
> + Signed integer value representing position.
> +
> +A Count has a count function mode which represents the update
> +behavior for the count data. The Generic Counter interface
> +provides the following available count function modes:
> +
> + * Increase:
> + Accumulated count is incremented.
> +
> + * Decrease:
> + Accumulated count is decremented.
> +
> + * Pulse-Direction:
> + Rising edges on quadrature pair signal A updates
> +the respective count. The input level of
> +quadrature pair signal B determines direction.
> +
> + * Quadrature x1:
> + If direction is forward, rising edges on
> +quadrature pair signal A updates the respective
> +count; if the direction is backward, falling
> +edges on quadrature pair signal A updates the
> +respective count. Quadrature encoding determines
> +the direction.
> +
> + * Quadrature x2:
> + Any state transition on quadrature pair signal A
> +updates the respective count. Quadrature
> +encoding determines the direction.
> +
> + * Quadrature x4:
> + Any state transition on either quadrature pair
> +signals updates  the respective count. Quadrature

   change  ^^^ to 

> +encoding determines the direction.
> +
> +A Count has a set of one or more associated Signals.
> +
> +SIGNAL
> +--
> +A Signal represents a counter input data; this is the input data
> +that is analyzed by the counter to determine the count data;
> +e.g. a quadrature signal output line of a rotary encoder. Not
> +all counter devices provide user access to the Signal data.
> +
> +The Generic Counter interface provides the following available
> +signal data types for when the Signal data is available for user
> +access:
> +
> + * SIGNAL_LEVEL_LOW:
> +Signal line is in a low state.
> +
> +* SIGNAL_LEVEL_HIGH:
> +Signal line is in a high state.
> +
> +A Signal may be associated to one or more Counts.

  with (?)

Hm, there are around 8 or so instances of "associated to" here -- and at least
one of "associated with" (to my surprise :).  But it's no big deal.


Reviewed-by: Randy Dunlap 

thanks,
-- 
~Randy

[PATCH v5 3/8] docs: Add Generic Counter interface documentation

[William Breathitt Gray]

This patch adds high-level documentation about the Generic Counter
interface.

Signed-off-by: William Breathitt Gray 
---
 Documentation/driver-api/generic-counter.rst | 321 +++
 Documentation/driver-api/index.rst   |   1 +
 MAINTAINERS  |   1 +
 3 files changed, 323 insertions(+)
 create mode 100644 Documentation/driver-api/generic-counter.rst

diff --git a/Documentation/driver-api/generic-counter.rst 
b/Documentation/driver-api/generic-counter.rst
new file mode 100644
index ..bce0cbc31963
--- /dev/null
+++ b/Documentation/driver-api/generic-counter.rst
@@ -0,0 +1,321 @@
+=
+Generic Counter Interface
+=
+
+Introduction
+
+
+Counter devices are prevalent within a diverse spectrum of industries.
+The ubiquitous presence of these devices necessitates a common interface
+and standard of interaction and exposure. This driver API attempts to
+resolve the issue of duplicate code found among existing counter device
+drivers by introducing a generic counter interface for consumption. The
+Generic Counter interface enables drivers to support and expose a common
+set of components and functionality present in counter devices.
+
+Theory
+==
+
+Counter devices can vary greatly in design, but regardless of whether
+some devices are quadrature encoder counters or tally counters, all
+counter devices consist of a core set of components. This core set of
+components, shared by all counter devices, is what forms the essence of
+the Generic Counter interface.
+
+There are three core components to a counter:
+
+COUNT
+-
+A Count represents the count data for a set of Signals. The
+Generic Counter interface provides the following available count
+data types:
+
+   * COUNT_POSITION_UNSIGNED:
+   Unsigned integer value representing position.
+
+   * COUNT_POSITION_SIGNED:
+   Signed integer value representing position.
+
+A Count has a count function mode which represents the update
+behavior for the count data. The Generic Counter interface
+provides the following available count function modes:
+
+   * Increase:
+   Accumulated count is incremented.
+
+   * Decrease:
+   Accumulated count is decremented.
+
+   * Pulse-Direction:
+   Rising edges on quadrature pair signal A updates
+the respective count. The input level of
+quadrature pair signal B determines direction.
+
+   * Quadrature x1:
+   If direction is forward, rising edges on
+quadrature pair signal A updates the respective
+count; if the direction is backward, falling
+edges on quadrature pair signal A updates the
+respective count. Quadrature encoding determines
+the direction.
+
+   * Quadrature x2:
+   Any state transition on quadrature pair signal A
+updates the respective count. Quadrature
+encoding determines the direction.
+
+   * Quadrature x4:
+   Any state transition on either quadrature pair
+signals updatesthe respective count. Quadrature
+encoding determines the direction.
+
+A Count has a set of one or more associated Signals.
+
+SIGNAL
+--
+A Signal represents a counter input data; this is the input data
+that is analyzed by the counter to determine the count data;
+e.g. a quadrature signal output line of a rotary encoder. Not
+all counter devices provide user access to the Signal data.
+
+The Generic Counter interface provides the following available
+signal data types for when the Signal data is available for user
+access:
+
+   * SIGNAL_LEVEL_LOW:
+Signal line is in a low state.
+
+* SIGNAL_LEVEL_HIGH:
+Signal line is in a high state.
+
+A Signal may be associated to one or more Counts.
+
+SYNAPSE
+---
+A Synapse represents the association of a Signal with a
+respective Count. Signal data affects respective Count data, and
+the Synapse represents this relationship.
+
+The Synapse action mode specifies the Signal data condition
+which triggers the respective Count's count function evaluation
+to update the count data. The Generic Counter interface provides
+the following available action modes:
+
+* None:
+Signal does not 

[PATCH v5 3/8] docs: Add Generic Counter interface documentation

[William Breathitt Gray]

This patch adds high-level documentation about the Generic Counter
interface.

Signed-off-by: William Breathitt Gray 
---
 Documentation/driver-api/generic-counter.rst | 321 +++
 Documentation/driver-api/index.rst   |   1 +
 MAINTAINERS  |   1 +
 3 files changed, 323 insertions(+)
 create mode 100644 Documentation/driver-api/generic-counter.rst

diff --git a/Documentation/driver-api/generic-counter.rst 
b/Documentation/driver-api/generic-counter.rst
new file mode 100644
index ..bce0cbc31963
--- /dev/null
+++ b/Documentation/driver-api/generic-counter.rst
@@ -0,0 +1,321 @@
+=
+Generic Counter Interface
+=
+
+Introduction
+
+
+Counter devices are prevalent within a diverse spectrum of industries.
+The ubiquitous presence of these devices necessitates a common interface
+and standard of interaction and exposure. This driver API attempts to
+resolve the issue of duplicate code found among existing counter device
+drivers by introducing a generic counter interface for consumption. The
+Generic Counter interface enables drivers to support and expose a common
+set of components and functionality present in counter devices.
+
+Theory
+==
+
+Counter devices can vary greatly in design, but regardless of whether
+some devices are quadrature encoder counters or tally counters, all
+counter devices consist of a core set of components. This core set of
+components, shared by all counter devices, is what forms the essence of
+the Generic Counter interface.
+
+There are three core components to a counter:
+
+COUNT
+-
+A Count represents the count data for a set of Signals. The
+Generic Counter interface provides the following available count
+data types:
+
+   * COUNT_POSITION_UNSIGNED:
+   Unsigned integer value representing position.
+
+   * COUNT_POSITION_SIGNED:
+   Signed integer value representing position.
+
+A Count has a count function mode which represents the update
+behavior for the count data. The Generic Counter interface
+provides the following available count function modes:
+
+   * Increase:
+   Accumulated count is incremented.
+
+   * Decrease:
+   Accumulated count is decremented.
+
+   * Pulse-Direction:
+   Rising edges on quadrature pair signal A updates
+the respective count. The input level of
+quadrature pair signal B determines direction.
+
+   * Quadrature x1:
+   If direction is forward, rising edges on
+quadrature pair signal A updates the respective
+count; if the direction is backward, falling
+edges on quadrature pair signal A updates the
+respective count. Quadrature encoding determines
+the direction.
+
+   * Quadrature x2:
+   Any state transition on quadrature pair signal A
+updates the respective count. Quadrature
+encoding determines the direction.
+
+   * Quadrature x4:
+   Any state transition on either quadrature pair
+signals updatesthe respective count. Quadrature
+encoding determines the direction.
+
+A Count has a set of one or more associated Signals.
+
+SIGNAL
+--
+A Signal represents a counter input data; this is the input data
+that is analyzed by the counter to determine the count data;
+e.g. a quadrature signal output line of a rotary encoder. Not
+all counter devices provide user access to the Signal data.
+
+The Generic Counter interface provides the following available
+signal data types for when the Signal data is available for user
+access:
+
+   * SIGNAL_LEVEL_LOW:
+Signal line is in a low state.
+
+* SIGNAL_LEVEL_HIGH:
+Signal line is in a high state.
+
+A Signal may be associated to one or more Counts.
+
+SYNAPSE
+---
+A Synapse represents the association of a Signal with a
+respective Count. Signal data affects respective Count data, and
+the Synapse represents this relationship.
+
+The Synapse action mode specifies the Signal data condition
+which triggers the respective Count's count function evaluation
+to update the count data. The Generic Counter interface provides
+the following available action modes:
+
+* None:
+Signal does not trigger the count