Documentation/driver-api/generic-counter.rst

4 Generic Counter Interface
10 Counter devices are prevalent among a diverse spectrum of industries.
13 resolve the issue of duplicate code found among existing counter device
14 drivers by introducing a generic counter interface for consumption. The
15 Generic Counter interface enables drivers to support and expose a common
16 set of components and functionality present in counter devices.
21 Counter devices can vary greatly in design, but regardless of whether
23 counter devices consist of a core set of components. This core set of
24 components, shared by all counter devices, is what forms the essence of
25 the Generic Counter interface.
27 There are three core components to a counter:
30   Stream of data to be evaluated by the counter.
41 evaluated by the counter to determine the count data; e.g. a quadrature
42 signal output line of a rotary encoder. Not all counter devices provide
45 When the Signal data is available for user access, the Generic Counter
64 count data. The Generic Counter interface provides the following
80 A counter is defined as a set of input signals associated with count
83 context of the Generic Counter interface, a counter consists of Counts
94 Counter interface represents the count data as a natural number.
97 for the count data. The Generic Counter interface provides the following
143 The most basic counter device may be expressed as a single Count
145 a counter device which simply accumulates a count of rising edges on a
161 voltage input line. In summary, the counter device existence and
166 A counter device is not limited to a single Signal; in fact, in theory
168 quadrature encoder counter device can keep track of position based on
188 encoder counter device; the Count, Signals, and Synapses simply
192 mode conditions. For example, a quadrature encoder counter device
220 respective physical sources. This allows the user of a counter to
229 Several sysfs attributes are generated by the Generic Counter interface,
230 and reside under the /sys/bus/counter/devices/counterX directory, where
231 counterX refers to the respective counter device. Please see
232 Documentation/ABI/testing/sysfs-bus-counter for detailed
233 information on each Generic Counter interface sysfs attribute.
236 the Generic Counter paradigm Counts, Signals, and Synapses of respective
237 counter devices.
242 Driver authors may utilize the Generic Counter interface in their code
243 by including the include/linux/counter.h header file. This header file
245 for defining a counter device.
247 .. kernel-doc:: include/linux/counter.h
250 .. kernel-doc:: drivers/counter/counter.c
256 To support a counter device, a driver must first allocate the available
257 Counter Signals via counter_signal structures. These Signals should
259 allocated counter_device structure before the Counter is registered to
262 Counter Counts may be allocated via counter_count structures, and
263 respective Counter Signal associations (Synapses) made via
268 before the Counter is registered to the system.
286 and configuration of the respective Counter device, while the
298   /sys/bus/counter/devices/counterX/signalY/invert
306   /sys/bus/counter/devices/counterX/countY/enable
314   /sys/bus/counter/devices/counterX/error_overtemp
319 When the Generic Counter interface counter module is loaded, the
321 "counter" to the system. Subsequently, when the module is unloaded, the
323 "counter" from the system.
325 Counter devices are registered to the system via the counter_register
327 counter_register function establishes a unique ID for the Counter
331     /sys/bus/counter/devices/counterX
335 and Synapses of the Counter device, as well as options and information
336 for the Counter device itself.
341     /sys/bus/counter/devices/counterX/signalY
346     /sys/bus/counter/devices/counterX/countY
348 For a more detailed breakdown of the available Generic Counter interface
350 Documentation/ABI/testing/sysfs-bus-counter file.
352 The Signals and Counts associated with the Counter device are registered