@@ -7,7 +7,7 @@ Generic Counter Interface
Introduction
============
-Counter devices are prevalent within a diverse spectrum of industries.
+Counter devices are prevalent among 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
@@ -26,23 +26,72 @@ the Generic Counter interface.
There are three core components to a counter:
-* Count:
- Count data for a set of Signals.
-
* Signal:
- Input data that is evaluated by the counter to determine the count
- data.
+ Stream of data to be evaluated by the counter.
* Synapse:
- The association of a Signal with a respective Count.
+ Association of a Signal, and evaluation trigger, with a Count.
+
+* Count:
+ Accumulation of the effects of connected Synapses.
+
+SIGNAL
+------
+A Signal represents a stream of data. This is the input data that is
+evaluated 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, so exposure is optional for drivers.
+
+When the Signal data is available for user access, the Generic Counter
+interface provides the following available signal values:
+
+* SIGNAL_LOW:
+ Signal line is in a low state.
+
+* SIGNAL_HIGH:
+ Signal line is in a high state.
+
+A Signal may be associated with one or more Counts.
+
+SYNAPSE
+-------
+A Synapse represents the association of a Signal with a Count. Signal
+data affects respective Count data, and the Synapse represents this
+relationship.
+
+The Synapse action mode specifies the Signal data condition that
+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 function. In Pulse-Direction count
+ function mode, this Signal is evaluated as Direction.
+
+* Rising Edge:
+ Low state transitions to high state.
+
+* Falling Edge:
+ High state transitions to low state.
+
+* Both Edges:
+ Any state transition.
+
+A counter is defined as a set of input signals associated with 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 Counts
+each associated with a set of Signals, whose respective Synapse
+instances represent the count function update conditions for the
+associated Counts.
+
+A Synapse associates one Signal with one Count.
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 integer value representing position.
+A Count represents the accumulation of the effects of connected
+Synapses; i.e. the count data for a set of Signals. The Generic
+Counter interface represents the count data as a natural number.
A Count has a count function mode which represents the update behavior
for the count data. The Generic Counter interface provides the following
@@ -86,60 +135,7 @@ available count function modes:
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
-evaluated 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:
- Signal line state level. The following states are possible:
-
- - 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 with 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 function. In Pulse-Direction count
- function mode, this Signal is evaluated as Direction.
-
-* Rising Edge:
- Low state transitions to high state.
-
-* Falling Edge:
- High state transitions to low state.
-
-* Both Edges:
- Any state transition.
-
-A counter is defined as a set of input signals associated with 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 Counts
-each associated with a set of Signals, whose respective Synapse
-instances represent the count function update conditions for the
-associated Counts.
+A Count has a set of one or more associated Synapses.
Paradigm
========
@@ -286,10 +282,36 @@ if device memory-managed registration is desired.
Extension sysfs attributes can be created for auxiliary functionality
and data by passing in defined counter_device_ext, counter_count_ext,
and counter_signal_ext structures. In these cases, the
-counter_device_ext structure is used for global configuration of the
-respective Counter device, while the counter_count_ext and
-counter_signal_ext structures allow for auxiliary exposure and
-configuration of a specific Count or Signal respectively.
+counter_device_ext structure is used for global/miscellaneous exposure
+and configuration of the respective Counter device, while the
+counter_count_ext and counter_signal_ext structures allow for auxiliary
+exposure and configuration of a specific Count or Signal respectively.
+
+Determining the type of extension to create is a matter of scope.
+
+* Signal extensions are attributes that expose information/control
+ specific to a Signal. These types of attributes will exist under a
+ Signal's directory in sysfs.
+
+ For example, if you have an invert feature for a Signal, you can have
+ a Signal extension called "invert" that toggles that feature:
+ /sys/bus/counter/devices/counterX/signalY/invert
+
+* Count extensions are attributes that expose information/control
+ specific to a Count. These type of attributes will exist under a
+ Count's directory in sysfs.
+
+ For example, if you want to pause/unpause a Count from updating, you
+ can have a Count extension called "enable" that toggles such:
+ /sys/bus/counter/devices/counterX/countY/enable
+
+* Device extensions are attributes that expose information/control
+ non-specific to a particular Count or Signal. This is where you would
+ put your global features or other miscellanous functionality.
+
+ For example, if your device has an overtemp sensor, you can report the
+ chip overheated via a device extension called "error_overtemp":
+ /sys/bus/counter/devices/counterX/error_overtemp
Architecture
============
Count data is now always represented as an unsigned integer, while Signal data is either SIGNAL_LOW or SIGNAL_HIGH. In addition, clarification changes and additions are made to better explain the theory of the Generic Counter interface and its use. Signed-off-by: William Breathitt Gray <vilhelm.gray@gmail.com> --- Documentation/driver-api/generic-counter.rst | 162 +++++++++++-------- 1 file changed, 92 insertions(+), 70 deletions(-)