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 <vilhelm.gray@xxxxxxxxx>
> ---
>  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 000000000000..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 <TAB> ^^^ to <SPACE>

> +                        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 <rdunlap@xxxxxxxxxxxxx>

thanks,
-- 
~Randy