generic-counter.rst 15 KB

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