Re: [PATCH 0/3] iio: Introduce the generic counter interface

[Jonathan Cameron]

On Mon, 28 Aug 2017 10:16:33 -0400
William Breathitt Gray  wrote:

> On Sun, Aug 20, 2017 at 01:00:16PM +0100, Jonathan Cameron wrote:
> >On Mon, 31 Jul 2017 12:02:45 -0400
> >William Breathitt Gray  wrote:
> >  
> >> Summary
> >> ===  
> >
> >I'd like to see some of this brought out as proper documentation files
> >in future sets.  In particular the sysfs interface needs full docs.  
> 
> I'll write up some proper documentation for the interface and
> implementation for version 2 of this patchset; it should help elucidate
> some of the concepts here a bit better.
> 
> >> 
> >> 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 patchset 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 pedometers, 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:
> >> 
> >> VALUE
> >> -
> >> A Value represents the count data for a set of Signals. A Value
> >> has a count function mode (e.g. "increment" or "quadrature x4")
> >> which respresents the update behavior for the count data. A
> >> Value also has a set of one or more associated Signals.
> >> 
> >> SIGNAL
> >> --
> >> A Signal represents a count input line. A Signal may be
> >>associated to one or more Values.
> >> 
> >> TRIGGER
> >>---
> >> A Trigger represents a Value's count function trigger condition
> >> mode (e.g. "rising edge" or "double pulse") for an associated
> >> Signal.If a Signal is associated with a Value, a respective
> >> Triggerinstance for that association exists -- albeit perhaps
> >> with a trigger condition mode of "none."
> >> 
> >> A counter is defined as a set of input signals associated to count data
> >> that are generated by the evaluation of the state of the associated
> >> input signals as defined by the respective count functions. Within the
> >> context of the generic counter interface, a counter consists of Values
> >> each associated to a set of Signals, whose respective Trigger instances
> >> represent the count function update conditions for the associated
> >> Values.
> >> 
> >> Implementation
> >> ==
> >> 
> >> The IIO generic counter interface piggybacks off of the IIO core. This
> >> is primarily used to leverage the existing sysfs setup: the IIO_COUNT
> >> channel attributes represent the "counter value," while the IIO_SIGNAL
> >> channel attributes represent the "counter signal;" auxilary IIO_COUNT
> >> attributes represent the "counter signal" connections and their
> >> respective state change configurations which trigger an associated
> >> "counter function" evaluation.
> >> 
> >> The iio_counter_ops structure serves as a container for driver callbacks
> >> to communicate with the device; function callbacks are provided to read
> >> and write various "counter signals" and "counter values," and set and
> >> get the "trigger mode" and "function mode" for various "counter signals"
> >> and "counter values" respectively.
> >> 
> >> To support a counter device, a driver must first allocate the available
> >> "counter signals" via iio_counter_signal structures. These "counter
> >> signals" should be stored as an array and set to the init_signals member
> >> of an allocated iio_counter structure before the counter is registered.
> >> 
> >> "Counter values" may be allocated via iio_counter_value structures, and
> >> respective "counter signal" associations made via iio_counter_trigger
> >> structures. Initial associated iio_counter_trigger structures may be
> >> stored as an array and set to the the init_triggers member of the
> >> respective iio_counter_value structure. These iio_counter_value
> >> structures may be set to the init_values member of an allocated
> >> iio_counter structure before the counter is registered if so desired.
> >> 
> >> A counter device is registered to the system by passing the respective
> >> initialized iio_counter structure to the iio_counter_register function;
> >> similarly, the iio_counter_unregister function unregisters the
> >> respective counter.
> >> 
> >> Userspace Interface
> >> ===
> >> 
> >> Several 

Re: [PATCH 0/3] iio: Introduce the generic counter interface

[Jonathan Cameron]

On Mon, 28 Aug 2017 10:16:33 -0400
William Breathitt Gray  wrote:

> On Sun, Aug 20, 2017 at 01:00:16PM +0100, Jonathan Cameron wrote:
> >On Mon, 31 Jul 2017 12:02:45 -0400
> >William Breathitt Gray  wrote:
> >  
> >> Summary
> >> ===  
> >
> >I'd like to see some of this brought out as proper documentation files
> >in future sets.  In particular the sysfs interface needs full docs.  
> 
> I'll write up some proper documentation for the interface and
> implementation for version 2 of this patchset; it should help elucidate
> some of the concepts here a bit better.
> 
> >> 
> >> 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 patchset 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 pedometers, 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:
> >> 
> >> VALUE
> >> -
> >> A Value represents the count data for a set of Signals. A Value
> >> has a count function mode (e.g. "increment" or "quadrature x4")
> >> which respresents the update behavior for the count data. A
> >> Value also has a set of one or more associated Signals.
> >> 
> >> SIGNAL
> >> --
> >> A Signal represents a count input line. A Signal may be
> >>associated to one or more Values.
> >> 
> >> TRIGGER
> >>---
> >> A Trigger represents a Value's count function trigger condition
> >> mode (e.g. "rising edge" or "double pulse") for an associated
> >> Signal.If a Signal is associated with a Value, a respective
> >> Triggerinstance for that association exists -- albeit perhaps
> >> with a trigger condition mode of "none."
> >> 
> >> A counter is defined as a set of input signals associated to count data
> >> that are generated by the evaluation of the state of the associated
> >> input signals as defined by the respective count functions. Within the
> >> context of the generic counter interface, a counter consists of Values
> >> each associated to a set of Signals, whose respective Trigger instances
> >> represent the count function update conditions for the associated
> >> Values.
> >> 
> >> Implementation
> >> ==
> >> 
> >> The IIO generic counter interface piggybacks off of the IIO core. This
> >> is primarily used to leverage the existing sysfs setup: the IIO_COUNT
> >> channel attributes represent the "counter value," while the IIO_SIGNAL
> >> channel attributes represent the "counter signal;" auxilary IIO_COUNT
> >> attributes represent the "counter signal" connections and their
> >> respective state change configurations which trigger an associated
> >> "counter function" evaluation.
> >> 
> >> The iio_counter_ops structure serves as a container for driver callbacks
> >> to communicate with the device; function callbacks are provided to read
> >> and write various "counter signals" and "counter values," and set and
> >> get the "trigger mode" and "function mode" for various "counter signals"
> >> and "counter values" respectively.
> >> 
> >> To support a counter device, a driver must first allocate the available
> >> "counter signals" via iio_counter_signal structures. These "counter
> >> signals" should be stored as an array and set to the init_signals member
> >> of an allocated iio_counter structure before the counter is registered.
> >> 
> >> "Counter values" may be allocated via iio_counter_value structures, and
> >> respective "counter signal" associations made via iio_counter_trigger
> >> structures. Initial associated iio_counter_trigger structures may be
> >> stored as an array and set to the the init_triggers member of the
> >> respective iio_counter_value structure. These iio_counter_value
> >> structures may be set to the init_values member of an allocated
> >> iio_counter structure before the counter is registered if so desired.
> >> 
> >> A counter device is registered to the system by passing the respective
> >> initialized iio_counter structure to the iio_counter_register function;
> >> similarly, the iio_counter_unregister function unregisters the
> >> respective counter.
> >> 
> >> Userspace Interface
> >> ===
> >> 
> >> Several sysfs attributes are generated by the generic 

Re: [PATCH 0/3] iio: Introduce the generic counter interface

[William Breathitt Gray]

On Sun, Aug 20, 2017 at 01:00:16PM +0100, Jonathan Cameron wrote:
>On Mon, 31 Jul 2017 12:02:45 -0400
>William Breathitt Gray  wrote:
>
>> Summary
>> ===
>
>I'd like to see some of this brought out as proper documentation files
>in future sets.  In particular the sysfs interface needs full docs.

I'll write up some proper documentation for the interface and
implementation for version 2 of this patchset; it should help elucidate
some of the concepts here a bit better.

>> 
>> 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 patchset 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 pedometers, 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:
>> 
>> VALUE
>> -
>> A Value represents the count data for a set of Signals. A Value
>> has a count function mode (e.g. "increment" or "quadrature x4")
>> which respresents the update behavior for the count data. A
>> Value also has a set of one or more associated Signals.
>> 
>> SIGNAL
>> --
>> A Signal represents a count input line. A Signal may be
>>  associated to one or more Values.
>> 
>> TRIGGER
>>  ---
>> A Trigger represents a Value's count function trigger condition
>> mode (e.g. "rising edge" or "double pulse") for an associated
>> Signal.  If a Signal is associated with a Value, a respective
>> Trigger  instance for that association exists -- albeit perhaps
>> with a trigger condition mode of "none."
>> 
>> A counter is defined as a set of input signals associated to count data
>> that are generated by the evaluation of the state of the associated
>> input signals as defined by the respective count functions. Within the
>> context of the generic counter interface, a counter consists of Values
>> each associated to a set of Signals, whose respective Trigger instances
>> represent the count function update conditions for the associated
>> Values.
>> 
>> Implementation
>> ==
>> 
>> The IIO generic counter interface piggybacks off of the IIO core. This
>> is primarily used to leverage the existing sysfs setup: the IIO_COUNT
>> channel attributes represent the "counter value," while the IIO_SIGNAL
>> channel attributes represent the "counter signal;" auxilary IIO_COUNT
>> attributes represent the "counter signal" connections and their
>> respective state change configurations which trigger an associated
>> "counter function" evaluation.
>> 
>> The iio_counter_ops structure serves as a container for driver callbacks
>> to communicate with the device; function callbacks are provided to read
>> and write various "counter signals" and "counter values," and set and
>> get the "trigger mode" and "function mode" for various "counter signals"
>> and "counter values" respectively.
>> 
>> To support a counter device, a driver must first allocate the available
>> "counter signals" via iio_counter_signal structures. These "counter
>> signals" should be stored as an array and set to the init_signals member
>> of an allocated iio_counter structure before the counter is registered.
>> 
>> "Counter values" may be allocated via iio_counter_value structures, and
>> respective "counter signal" associations made via iio_counter_trigger
>> structures. Initial associated iio_counter_trigger structures may be
>> stored as an array and set to the the init_triggers member of the
>> respective iio_counter_value structure. These iio_counter_value
>> structures may be set to the init_values member of an allocated
>> iio_counter structure before the counter is registered if so desired.
>> 
>> A counter device is registered to the system by passing the respective
>> initialized iio_counter structure to the iio_counter_register function;
>> similarly, the iio_counter_unregister function unregisters the
>> respective counter.
>> 
>> Userspace Interface
>> ===
>> 
>> Several sysfs attributes are generated by the generic counter interface,
>> and reside under the /sys/bus/iio/devices/iio:deviceX directory.
>> 
>> Each counter has a respective set of countX-Y and signalX-Y prefixed
>> attributes, where X is the id set in the counter structure, and Y is the
>> id of 

Re: [PATCH 0/3] iio: Introduce the generic counter interface

[William Breathitt Gray]

On Sun, Aug 20, 2017 at 01:00:16PM +0100, Jonathan Cameron wrote:
>On Mon, 31 Jul 2017 12:02:45 -0400
>William Breathitt Gray  wrote:
>
>> Summary
>> ===
>
>I'd like to see some of this brought out as proper documentation files
>in future sets.  In particular the sysfs interface needs full docs.

I'll write up some proper documentation for the interface and
implementation for version 2 of this patchset; it should help elucidate
some of the concepts here a bit better.

>> 
>> 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 patchset 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 pedometers, 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:
>> 
>> VALUE
>> -
>> A Value represents the count data for a set of Signals. A Value
>> has a count function mode (e.g. "increment" or "quadrature x4")
>> which respresents the update behavior for the count data. A
>> Value also has a set of one or more associated Signals.
>> 
>> SIGNAL
>> --
>> A Signal represents a count input line. A Signal may be
>>  associated to one or more Values.
>> 
>> TRIGGER
>>  ---
>> A Trigger represents a Value's count function trigger condition
>> mode (e.g. "rising edge" or "double pulse") for an associated
>> Signal.  If a Signal is associated with a Value, a respective
>> Trigger  instance for that association exists -- albeit perhaps
>> with a trigger condition mode of "none."
>> 
>> A counter is defined as a set of input signals associated to count data
>> that are generated by the evaluation of the state of the associated
>> input signals as defined by the respective count functions. Within the
>> context of the generic counter interface, a counter consists of Values
>> each associated to a set of Signals, whose respective Trigger instances
>> represent the count function update conditions for the associated
>> Values.
>> 
>> Implementation
>> ==
>> 
>> The IIO generic counter interface piggybacks off of the IIO core. This
>> is primarily used to leverage the existing sysfs setup: the IIO_COUNT
>> channel attributes represent the "counter value," while the IIO_SIGNAL
>> channel attributes represent the "counter signal;" auxilary IIO_COUNT
>> attributes represent the "counter signal" connections and their
>> respective state change configurations which trigger an associated
>> "counter function" evaluation.
>> 
>> The iio_counter_ops structure serves as a container for driver callbacks
>> to communicate with the device; function callbacks are provided to read
>> and write various "counter signals" and "counter values," and set and
>> get the "trigger mode" and "function mode" for various "counter signals"
>> and "counter values" respectively.
>> 
>> To support a counter device, a driver must first allocate the available
>> "counter signals" via iio_counter_signal structures. These "counter
>> signals" should be stored as an array and set to the init_signals member
>> of an allocated iio_counter structure before the counter is registered.
>> 
>> "Counter values" may be allocated via iio_counter_value structures, and
>> respective "counter signal" associations made via iio_counter_trigger
>> structures. Initial associated iio_counter_trigger structures may be
>> stored as an array and set to the the init_triggers member of the
>> respective iio_counter_value structure. These iio_counter_value
>> structures may be set to the init_values member of an allocated
>> iio_counter structure before the counter is registered if so desired.
>> 
>> A counter device is registered to the system by passing the respective
>> initialized iio_counter structure to the iio_counter_register function;
>> similarly, the iio_counter_unregister function unregisters the
>> respective counter.
>> 
>> Userspace Interface
>> ===
>> 
>> Several sysfs attributes are generated by the generic counter interface,
>> and reside under the /sys/bus/iio/devices/iio:deviceX directory.
>> 
>> Each counter has a respective set of countX-Y and signalX-Y prefixed
>> attributes, where X is the id set in the counter structure, and Y is the
>> id of the respective Value or 

Re: [PATCH 0/3] iio: Introduce the generic counter interface

[Jonathan Cameron]

On Mon, 31 Jul 2017 12:02:45 -0400
William Breathitt Gray  wrote:

> Summary
> ===

I'd like to see some of this brought out as proper documentation files
in future sets.  In particular the sysfs interface needs full docs.
> 
> 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 patchset 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 pedometers, 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:
> 
> VALUE
> -
> A Value represents the count data for a set of Signals. A Value
> has a count function mode (e.g. "increment" or "quadrature x4")
> which respresents the update behavior for the count data. A
> Value also has a set of one or more associated Signals.
> 
> SIGNAL
> --
> A Signal represents a count input line. A Signal may be
>   associated to one or more Values.
> 
> TRIGGER
>   ---
> A Trigger represents a Value's count function trigger condition
> mode (e.g. "rising edge" or "double pulse") for an associated
> Signal.   If a Signal is associated with a Value, a respective
> Trigger   instance for that association exists -- albeit perhaps
> with a trigger condition mode of "none."
> 
> A counter is defined as a set of input signals associated to count data
> that are generated by the evaluation of the state of the associated
> input signals as defined by the respective count functions. Within the
> context of the generic counter interface, a counter consists of Values
> each associated to a set of Signals, whose respective Trigger instances
> represent the count function update conditions for the associated
> Values.
> 
> Implementation
> ==
> 
> The IIO generic counter interface piggybacks off of the IIO core. This
> is primarily used to leverage the existing sysfs setup: the IIO_COUNT
> channel attributes represent the "counter value," while the IIO_SIGNAL
> channel attributes represent the "counter signal;" auxilary IIO_COUNT
> attributes represent the "counter signal" connections and their
> respective state change configurations which trigger an associated
> "counter function" evaluation.
> 
> The iio_counter_ops structure serves as a container for driver callbacks
> to communicate with the device; function callbacks are provided to read
> and write various "counter signals" and "counter values," and set and
> get the "trigger mode" and "function mode" for various "counter signals"
> and "counter values" respectively.
> 
> To support a counter device, a driver must first allocate the available
> "counter signals" via iio_counter_signal structures. These "counter
> signals" should be stored as an array and set to the init_signals member
> of an allocated iio_counter structure before the counter is registered.
> 
> "Counter values" may be allocated via iio_counter_value structures, and
> respective "counter signal" associations made via iio_counter_trigger
> structures. Initial associated iio_counter_trigger structures may be
> stored as an array and set to the the init_triggers member of the
> respective iio_counter_value structure. These iio_counter_value
> structures may be set to the init_values member of an allocated
> iio_counter structure before the counter is registered if so desired.
> 
> A counter device is registered to the system by passing the respective
> initialized iio_counter structure to the iio_counter_register function;
> similarly, the iio_counter_unregister function unregisters the
> respective counter.
> 
> Userspace Interface
> ===
> 
> Several sysfs attributes are generated by the generic counter interface,
> and reside under the /sys/bus/iio/devices/iio:deviceX directory.
> 
> Each counter has a respective set of countX-Y and signalX-Y prefixed
> attributes, where X is the id set in the counter structure, and Y is the
> id of the respective Value or Signal.
> 
> The generic counter interface sysfs attributes are as follows:
> 
> countX-Y_function: count function mode
> countX-Y_function_available: available count function modes
> countX-Y_name: Value name
> countX-Y_raw: Value data
> countX-Y_triggers: Value's 

Re: [PATCH 0/3] iio: Introduce the generic counter interface

[Jonathan Cameron]

On Mon, 31 Jul 2017 12:02:45 -0400
William Breathitt Gray  wrote:

> Summary
> ===

I'd like to see some of this brought out as proper documentation files
in future sets.  In particular the sysfs interface needs full docs.
> 
> 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 patchset 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 pedometers, 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:
> 
> VALUE
> -
> A Value represents the count data for a set of Signals. A Value
> has a count function mode (e.g. "increment" or "quadrature x4")
> which respresents the update behavior for the count data. A
> Value also has a set of one or more associated Signals.
> 
> SIGNAL
> --
> A Signal represents a count input line. A Signal may be
>   associated to one or more Values.
> 
> TRIGGER
>   ---
> A Trigger represents a Value's count function trigger condition
> mode (e.g. "rising edge" or "double pulse") for an associated
> Signal.   If a Signal is associated with a Value, a respective
> Trigger   instance for that association exists -- albeit perhaps
> with a trigger condition mode of "none."
> 
> A counter is defined as a set of input signals associated to count data
> that are generated by the evaluation of the state of the associated
> input signals as defined by the respective count functions. Within the
> context of the generic counter interface, a counter consists of Values
> each associated to a set of Signals, whose respective Trigger instances
> represent the count function update conditions for the associated
> Values.
> 
> Implementation
> ==
> 
> The IIO generic counter interface piggybacks off of the IIO core. This
> is primarily used to leverage the existing sysfs setup: the IIO_COUNT
> channel attributes represent the "counter value," while the IIO_SIGNAL
> channel attributes represent the "counter signal;" auxilary IIO_COUNT
> attributes represent the "counter signal" connections and their
> respective state change configurations which trigger an associated
> "counter function" evaluation.
> 
> The iio_counter_ops structure serves as a container for driver callbacks
> to communicate with the device; function callbacks are provided to read
> and write various "counter signals" and "counter values," and set and
> get the "trigger mode" and "function mode" for various "counter signals"
> and "counter values" respectively.
> 
> To support a counter device, a driver must first allocate the available
> "counter signals" via iio_counter_signal structures. These "counter
> signals" should be stored as an array and set to the init_signals member
> of an allocated iio_counter structure before the counter is registered.
> 
> "Counter values" may be allocated via iio_counter_value structures, and
> respective "counter signal" associations made via iio_counter_trigger
> structures. Initial associated iio_counter_trigger structures may be
> stored as an array and set to the the init_triggers member of the
> respective iio_counter_value structure. These iio_counter_value
> structures may be set to the init_values member of an allocated
> iio_counter structure before the counter is registered if so desired.
> 
> A counter device is registered to the system by passing the respective
> initialized iio_counter structure to the iio_counter_register function;
> similarly, the iio_counter_unregister function unregisters the
> respective counter.
> 
> Userspace Interface
> ===
> 
> Several sysfs attributes are generated by the generic counter interface,
> and reside under the /sys/bus/iio/devices/iio:deviceX directory.
> 
> Each counter has a respective set of countX-Y and signalX-Y prefixed
> attributes, where X is the id set in the counter structure, and Y is the
> id of the respective Value or Signal.
> 
> The generic counter interface sysfs attributes are as follows:
> 
> countX-Y_function: count function mode
> countX-Y_function_available: available count function modes
> countX-Y_name: Value name
> countX-Y_raw: Value data
> countX-Y_triggers: Value's associated Signals
> 

[PATCH 0/3] iio: Introduce the generic counter interface

[William Breathitt Gray]

Summary
===

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 patchset 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 pedometers, 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:

VALUE
-
A Value represents the count data for a set of Signals. A Value
has a count function mode (e.g. "increment" or "quadrature x4")
which respresents the update behavior for the count data. A
Value also has a set of one or more associated Signals.

SIGNAL
--
A Signal represents a count input line. A Signal may be
associated to one or more Values.

TRIGGER
---
A Trigger represents a Value's count function trigger condition
mode (e.g. "rising edge" or "double pulse") for an associated
Signal. If a Signal is associated with a Value, a respective
Trigger instance for that association exists -- albeit perhaps
with a trigger condition mode of "none."

A counter is defined as a set of input signals associated to count data
that are generated by the evaluation of the state of the associated
input signals as defined by the respective count functions. Within the
context of the generic counter interface, a counter consists of Values
each associated to a set of Signals, whose respective Trigger instances
represent the count function update conditions for the associated
Values.

Implementation
==

The IIO generic counter interface piggybacks off of the IIO core. This
is primarily used to leverage the existing sysfs setup: the IIO_COUNT
channel attributes represent the "counter value," while the IIO_SIGNAL
channel attributes represent the "counter signal;" auxilary IIO_COUNT
attributes represent the "counter signal" connections and their
respective state change configurations which trigger an associated
"counter function" evaluation.

The iio_counter_ops structure serves as a container for driver callbacks
to communicate with the device; function callbacks are provided to read
and write various "counter signals" and "counter values," and set and
get the "trigger mode" and "function mode" for various "counter signals"
and "counter values" respectively.

To support a counter device, a driver must first allocate the available
"counter signals" via iio_counter_signal structures. These "counter
signals" should be stored as an array and set to the init_signals member
of an allocated iio_counter structure before the counter is registered.

"Counter values" may be allocated via iio_counter_value structures, and
respective "counter signal" associations made via iio_counter_trigger
structures. Initial associated iio_counter_trigger structures may be
stored as an array and set to the the init_triggers member of the
respective iio_counter_value structure. These iio_counter_value
structures may be set to the init_values member of an allocated
iio_counter structure before the counter is registered if so desired.

A counter device is registered to the system by passing the respective
initialized iio_counter structure to the iio_counter_register function;
similarly, the iio_counter_unregister function unregisters the
respective counter.

Userspace Interface
===

Several sysfs attributes are generated by the generic counter interface,
and reside under the /sys/bus/iio/devices/iio:deviceX directory.

Each counter has a respective set of countX-Y and signalX-Y prefixed
attributes, where X is the id set in the counter structure, and Y is the
id of the respective Value or Signal.

The generic counter interface sysfs attributes are as follows:

countX-Y_function: count function mode
countX-Y_function_available: available count function modes
countX-Y_name: Value name
countX-Y_raw: Value data
countX-Y_triggers: Value's associated Signals
countX-Y_trigger_signalX-Z: Value Y trigger mode for Signal Z
countX-Y_trigger_signalX-Z_available: available Value Y trigger
  modes for Signal Z
signalX-Y_name: Signal name
signalX-Y_raw: Signal data

Future Development
==

This patchset is focused on providing the core functionality required to
introduce a usable generic counter 

[PATCH 0/3] iio: Introduce the generic counter interface

[William Breathitt Gray]

Summary
===

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 patchset 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 pedometers, 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:

VALUE
-
A Value represents the count data for a set of Signals. A Value
has a count function mode (e.g. "increment" or "quadrature x4")
which respresents the update behavior for the count data. A
Value also has a set of one or more associated Signals.

SIGNAL
--
A Signal represents a count input line. A Signal may be
associated to one or more Values.

TRIGGER
---
A Trigger represents a Value's count function trigger condition
mode (e.g. "rising edge" or "double pulse") for an associated
Signal. If a Signal is associated with a Value, a respective
Trigger instance for that association exists -- albeit perhaps
with a trigger condition mode of "none."

A counter is defined as a set of input signals associated to count data
that are generated by the evaluation of the state of the associated
input signals as defined by the respective count functions. Within the
context of the generic counter interface, a counter consists of Values
each associated to a set of Signals, whose respective Trigger instances
represent the count function update conditions for the associated
Values.

Implementation
==

The IIO generic counter interface piggybacks off of the IIO core. This
is primarily used to leverage the existing sysfs setup: the IIO_COUNT
channel attributes represent the "counter value," while the IIO_SIGNAL
channel attributes represent the "counter signal;" auxilary IIO_COUNT
attributes represent the "counter signal" connections and their
respective state change configurations which trigger an associated
"counter function" evaluation.

The iio_counter_ops structure serves as a container for driver callbacks
to communicate with the device; function callbacks are provided to read
and write various "counter signals" and "counter values," and set and
get the "trigger mode" and "function mode" for various "counter signals"
and "counter values" respectively.

To support a counter device, a driver must first allocate the available
"counter signals" via iio_counter_signal structures. These "counter
signals" should be stored as an array and set to the init_signals member
of an allocated iio_counter structure before the counter is registered.

"Counter values" may be allocated via iio_counter_value structures, and
respective "counter signal" associations made via iio_counter_trigger
structures. Initial associated iio_counter_trigger structures may be
stored as an array and set to the the init_triggers member of the
respective iio_counter_value structure. These iio_counter_value
structures may be set to the init_values member of an allocated
iio_counter structure before the counter is registered if so desired.

A counter device is registered to the system by passing the respective
initialized iio_counter structure to the iio_counter_register function;
similarly, the iio_counter_unregister function unregisters the
respective counter.

Userspace Interface
===

Several sysfs attributes are generated by the generic counter interface,
and reside under the /sys/bus/iio/devices/iio:deviceX directory.

Each counter has a respective set of countX-Y and signalX-Y prefixed
attributes, where X is the id set in the counter structure, and Y is the
id of the respective Value or Signal.

The generic counter interface sysfs attributes are as follows:

countX-Y_function: count function mode
countX-Y_function_available: available count function modes
countX-Y_name: Value name
countX-Y_raw: Value data
countX-Y_triggers: Value's associated Signals
countX-Y_trigger_signalX-Z: Value Y trigger mode for Signal Z
countX-Y_trigger_signalX-Z_available: available Value Y trigger
  modes for Signal Z
signalX-Y_name: Signal name
signalX-Y_raw: Signal data

Future Development
==

This patchset is focused on providing the core functionality required to
introduce a usable generic counter