mirror of
https://github.com/torvalds/linux.git
synced 2024-11-22 12:11:40 +00:00
docs: driver-api: generic-counter: Update Count and Signal data types
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> Signed-off-by: Jonathan Cameron <Jonathan.Cameron@huawei.com>
This commit is contained in:
William Breathitt Gray
Jonathan Cameron
parent
d49e6ee2d6
commit
e58cbfd20a
@ -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
|
||||
============
|
||||
|
||||
Loading…
Reference in New Issue
Block a user