Orange Pi5 kernel

^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300   1) .. SPDX-License-Identifier: GPL-2.0
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300   2) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300   3) =========================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300   4) Generic Counter Interface
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300   5) =========================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300   6) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300   7) Introduction
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300   8) ============
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300   9) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  10) Counter devices are prevalent among a diverse spectrum of industries.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  11) The ubiquitous presence of these devices necessitates a common interface
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  12) and standard of interaction and exposure. This driver API attempts to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  13) resolve the issue of duplicate code found among existing counter device
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  14) drivers by introducing a generic counter interface for consumption. The
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  15) Generic Counter interface enables drivers to support and expose a common
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  16) set of components and functionality present in counter devices.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  17) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  18) Theory
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  19) ======
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  20) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  21) Counter devices can vary greatly in design, but regardless of whether
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  22) some devices are quadrature encoder counters or tally counters, all
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  23) counter devices consist of a core set of components. This core set of
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  24) components, shared by all counter devices, is what forms the essence of
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  25) the Generic Counter interface.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  26) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  27) There are three core components to a counter:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  28) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  29) * Signal:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  30)   Stream of data to be evaluated by the counter.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  31) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  32) * Synapse:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  33)   Association of a Signal, and evaluation trigger, with a Count.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  34) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  35) * Count:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  36)   Accumulation of the effects of connected Synapses.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  37) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  38) SIGNAL
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  39) ------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  40) A Signal represents a stream of data. This is the input data that is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  41) evaluated by the counter to determine the count data; e.g. a quadrature
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  42) signal output line of a rotary encoder. Not all counter devices provide
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  43) user access to the Signal data, so exposure is optional for drivers.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  44) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  45) When the Signal data is available for user access, the Generic Counter
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  46) interface provides the following available signal values:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  47) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  48) * SIGNAL_LOW:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  49)   Signal line is in a low state.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  50) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  51) * SIGNAL_HIGH:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  52)   Signal line is in a high state.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  53) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  54) A Signal may be associated with one or more Counts.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  55) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  56) SYNAPSE
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  57) -------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  58) A Synapse represents the association of a Signal with a Count. Signal
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  59) data affects respective Count data, and the Synapse represents this
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  60) relationship.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  61) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  62) The Synapse action mode specifies the Signal data condition that
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  63) triggers the respective Count's count function evaluation to update the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  64) count data. The Generic Counter interface provides the following
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  65) available action modes:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  66) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  67) * None:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  68)   Signal does not trigger the count function. In Pulse-Direction count
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  69)   function mode, this Signal is evaluated as Direction.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  70) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  71) * Rising Edge:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  72)   Low state transitions to high state.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  73) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  74) * Falling Edge:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  75)   High state transitions to low state.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  76) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  77) * Both Edges:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  78)   Any state transition.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  79) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  80) A counter is defined as a set of input signals associated with count
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  81) data that are generated by the evaluation of the state of the associated
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  82) input signals as defined by the respective count functions. Within the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  83) context of the Generic Counter interface, a counter consists of Counts
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  84) each associated with a set of Signals, whose respective Synapse
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  85) instances represent the count function update conditions for the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  86) associated Counts.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  87) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  88) A Synapse associates one Signal with one Count.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  89) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  90) COUNT
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  91) -----
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  92) A Count represents the accumulation of the effects of connected
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  93) Synapses; i.e. the count data for a set of Signals. The Generic
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  94) Counter interface represents the count data as a natural number.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  95) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  96) A Count has a count function mode which represents the update behavior
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  97) for the count data. The Generic Counter interface provides the following
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  98) available count function modes:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  99) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 100) * Increase:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 101)   Accumulated count is incremented.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 102) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 103) * Decrease:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 104)   Accumulated count is decremented.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 105) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 106) * Pulse-Direction:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 107)   Rising edges on signal A updates the respective count. The input level
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 108)   of signal B determines direction.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 109) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 110) * Quadrature:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 111)   A pair of quadrature encoding signals are evaluated to determine
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 112)   position and direction. The following Quadrature modes are available:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 113) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 114)   - x1 A:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 115)     If direction is forward, rising edges on quadrature pair signal A
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 116)     updates the respective count; if the direction is backward, falling
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 117)     edges on quadrature pair signal A updates the respective count.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 118)     Quadrature encoding determines the direction.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 119) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 120)   - x1 B:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 121)     If direction is forward, rising edges on quadrature pair signal B
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 122)     updates the respective count; if the direction is backward, falling
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 123)     edges on quadrature pair signal B updates the respective count.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 124)     Quadrature encoding determines the direction.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 125) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 126)   - x2 A:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 127)     Any state transition on quadrature pair signal A updates the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 128)     respective count. Quadrature encoding determines the direction.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 129) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 130)   - x2 B:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 131)     Any state transition on quadrature pair signal B updates the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 132)     respective count. Quadrature encoding determines the direction.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 133) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 134)   - x4:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 135)     Any state transition on either quadrature pair signals updates the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 136)     respective count. Quadrature encoding determines the direction.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 137) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 138) A Count has a set of one or more associated Synapses.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 139) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 140) Paradigm
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 141) ========
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 142) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 143) The most basic counter device may be expressed as a single Count
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 144) associated with a single Signal via a single Synapse. Take for example
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 145) a counter device which simply accumulates a count of rising edges on a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 146) source input line::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 147) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 148)                 Count                Synapse        Signal
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 149)                 -----                -------        ------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 150)         +---------------------+
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 151)         | Data: Count         |    Rising Edge     ________
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 152)         | Function: Increase  |  <-------------   / Source \
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 153)         |                     |                  ____________
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 154)         +---------------------+
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 155) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 156) In this example, the Signal is a source input line with a pulsing
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 157) voltage, while the Count is a persistent count value which is repeatedly
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 158) incremented. The Signal is associated with the respective Count via a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 159) Synapse. The increase function is triggered by the Signal data condition
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 160) specified by the Synapse -- in this case a rising edge condition on the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 161) voltage input line. In summary, the counter device existence and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 162) behavior is aptly represented by respective Count, Signal, and Synapse
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 163) components: a rising edge condition triggers an increase function on an
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 164) accumulating count datum.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 165) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 166) A counter device is not limited to a single Signal; in fact, in theory
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 167) many Signals may be associated with even a single Count. For example, a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 168) quadrature encoder counter device can keep track of position based on
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 169) the states of two input lines::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 170) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 171)                    Count                 Synapse     Signal
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 172)                    -----                 -------     ------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 173)         +-------------------------+
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 174)         | Data: Position          |    Both Edges     ___
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 175)         | Function: Quadrature x4 |  <------------   / A \
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 176)         |                         |                 _______
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 177)         |                         |
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 178)         |                         |    Both Edges     ___
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 179)         |                         |  <------------   / B \
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 180)         |                         |                 _______
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 181)         +-------------------------+
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 182) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 183) In this example, two Signals (quadrature encoder lines A and B) are
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 184) associated with a single Count: a rising or falling edge on either A or
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 185) B triggers the "Quadrature x4" function which determines the direction
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 186) of movement and updates the respective position data. The "Quadrature
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 187) x4" function is likely implemented in the hardware of the quadrature
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 188) encoder counter device; the Count, Signals, and Synapses simply
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 189) represent this hardware behavior and functionality.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 190) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 191) Signals associated with the same Count can have differing Synapse action
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 192) mode conditions. For example, a quadrature encoder counter device
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 193) operating in a non-quadrature Pulse-Direction mode could have one input
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 194) line dedicated for movement and a second input line dedicated for
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 195) direction::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 196) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 197)                    Count                   Synapse      Signal
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 198)                    -----                   -------      ------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 199)         +---------------------------+
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 200)         | Data: Position            |    Rising Edge     ___
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 201)         | Function: Pulse-Direction |  <-------------   / A \ (Movement)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 202)         |                           |                  _______
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 203)         |                           |
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 204)         |                           |       None         ___
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 205)         |                           |  <-------------   / B \ (Direction)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 206)         |                           |                  _______
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 207)         +---------------------------+
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 208) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 209) Only Signal A triggers the "Pulse-Direction" update function, but the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 210) instantaneous state of Signal B is still required in order to know the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 211) direction so that the position data may be properly updated. Ultimately,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 212) both Signals are associated with the same Count via two respective
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 213) Synapses, but only one Synapse has an active action mode condition which
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 214) triggers the respective count function while the other is left with a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 215) "None" condition action mode to indicate its respective Signal's
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 216) availability for state evaluation despite its non-triggering mode.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 217) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 218) Keep in mind that the Signal, Synapse, and Count are abstract
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 219) representations which do not need to be closely married to their
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 220) respective physical sources. This allows the user of a counter to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 221) divorce themselves from the nuances of physical components (such as
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 222) whether an input line is differential or single-ended) and instead focus
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 223) on the core idea of what the data and process represent (e.g. position
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 224) as interpreted from quadrature encoding data).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 225) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 226) Userspace Interface
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 227) ===================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 228) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 229) Several sysfs attributes are generated by the Generic Counter interface,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 230) and reside under the /sys/bus/counter/devices/counterX directory, where
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 231) counterX refers to the respective counter device. Please see
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 232) Documentation/ABI/testing/sysfs-bus-counter for detailed
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 233) information on each Generic Counter interface sysfs attribute.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 234) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 235) Through these sysfs attributes, programs and scripts may interact with
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 236) the Generic Counter paradigm Counts, Signals, and Synapses of respective
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 237) counter devices.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 238) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 239) Driver API
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 240) ==========
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 241) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 242) Driver authors may utilize the Generic Counter interface in their code
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 243) by including the include/linux/counter.h header file. This header file
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 244) provides several core data structures, function prototypes, and macros
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 245) for defining a counter device.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 246) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 247) .. kernel-doc:: include/linux/counter.h
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 248)    :internal:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 249) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 250) .. kernel-doc:: drivers/counter/counter.c
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 251)    :export:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 252) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 253) Implementation
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 254) ==============
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 255) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 256) To support a counter device, a driver must first allocate the available
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 257) Counter Signals via counter_signal structures. These Signals should
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 258) be stored as an array and set to the signals array member of an
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 259) allocated counter_device structure before the Counter is registered to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 260) the system.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 261) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 262) Counter Counts may be allocated via counter_count structures, and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 263) respective Counter Signal associations (Synapses) made via
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 264) counter_synapse structures. Associated counter_synapse structures are
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 265) stored as an array and set to the synapses array member of the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 266) respective counter_count structure. These counter_count structures are
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 267) set to the counts array member of an allocated counter_device structure
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 268) before the Counter is registered to the system.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 269) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 270) Driver callbacks should be provided to the counter_device structure via
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 271) a constant counter_ops structure in order to communicate with the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 272) device: to read and write various Signals and Counts, and to set and get
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 273) the "action mode" and "function mode" for various Synapses and Counts
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 274) respectively.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 275) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 276) A defined counter_device structure may be registered to the system by
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 277) passing it to the counter_register function, and unregistered by passing
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 278) it to the counter_unregister function. Similarly, the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 279) devm_counter_register and devm_counter_unregister functions may be used
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 280) if device memory-managed registration is desired.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 281) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 282) Extension sysfs attributes can be created for auxiliary functionality
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 283) and data by passing in defined counter_device_ext, counter_count_ext,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 284) and counter_signal_ext structures. In these cases, the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 285) counter_device_ext structure is used for global/miscellaneous exposure
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 286) and configuration of the respective Counter device, while the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 287) counter_count_ext and counter_signal_ext structures allow for auxiliary
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 288) exposure and configuration of a specific Count or Signal respectively.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 289) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 290) Determining the type of extension to create is a matter of scope.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 291) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 292) * Signal extensions are attributes that expose information/control
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 293)   specific to a Signal. These types of attributes will exist under a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 294)   Signal's directory in sysfs.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 295) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 296)   For example, if you have an invert feature for a Signal, you can have
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 297)   a Signal extension called "invert" that toggles that feature:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 298)   /sys/bus/counter/devices/counterX/signalY/invert
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 299) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 300) * Count extensions are attributes that expose information/control
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 301)   specific to a Count. These type of attributes will exist under a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 302)   Count's directory in sysfs.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 303) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 304)   For example, if you want to pause/unpause a Count from updating, you
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 305)   can have a Count extension called "enable" that toggles such:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 306)   /sys/bus/counter/devices/counterX/countY/enable
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 307) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 308) * Device extensions are attributes that expose information/control
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 309)   non-specific to a particular Count or Signal. This is where you would
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 310)   put your global features or other miscellanous functionality.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 311) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 312)   For example, if your device has an overtemp sensor, you can report the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 313)   chip overheated via a device extension called "error_overtemp":
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 314)   /sys/bus/counter/devices/counterX/error_overtemp
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 315) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 316) Architecture
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 317) ============
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 318) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 319) When the Generic Counter interface counter module is loaded, the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 320) counter_init function is called which registers a bus_type named
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 321) "counter" to the system. Subsequently, when the module is unloaded, the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 322) counter_exit function is called which unregisters the bus_type named
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 323) "counter" from the system.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 324) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 325) Counter devices are registered to the system via the counter_register
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 326) function, and later removed via the counter_unregister function. The
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 327) counter_register function establishes a unique ID for the Counter
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 328) device and creates a respective sysfs directory, where X is the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 329) mentioned unique ID:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 330) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 331)     /sys/bus/counter/devices/counterX
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 332) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 333) Sysfs attributes are created within the counterX directory to expose
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 334) functionality, configurations, and data relating to the Counts, Signals,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 335) and Synapses of the Counter device, as well as options and information
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 336) for the Counter device itself.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 337) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 338) Each Signal has a directory created to house its relevant sysfs
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 339) attributes, where Y is the unique ID of the respective Signal:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 340) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 341)     /sys/bus/counter/devices/counterX/signalY
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 342) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 343) Similarly, each Count has a directory created to house its relevant
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 344) sysfs attributes, where Y is the unique ID of the respective Count:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 345) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 346)     /sys/bus/counter/devices/counterX/countY
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 347) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 348) For a more detailed breakdown of the available Generic Counter interface
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 349) sysfs attributes, please refer to the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 350) Documentation/ABI/testing/sysfs-bus-counter file.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 351) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 352) The Signals and Counts associated with the Counter device are registered
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 353) to the system as well by the counter_register function. The
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 354) signal_read/signal_write driver callbacks are associated with their
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 355) respective Signal attributes, while the count_read/count_write and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 356) function_get/function_set driver callbacks are associated with their
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 357) respective Count attributes; similarly, the same is true for the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 358) action_get/action_set driver callbacks and their respective Synapse
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 359) attributes. If a driver callback is left undefined, then the respective
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 360) read/write permission is left disabled for the relevant attributes.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 361) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 362) Similarly, extension sysfs attributes are created for the defined
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 363) counter_device_ext, counter_count_ext, and counter_signal_ext
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 364) structures that are passed in.