Introduction¶

Counter devices are prevalent among a diverse spectrum of industries.The ubiquitous presence of these devices necessitates a common interfaceand standard of interaction and exposure. This driver API attempts toresolve the issue of duplicate code found among existing counter devicedrivers by introducing a generic counter interface for consumption. TheGeneric Counter interface enables drivers to support and expose a commonset of components and functionality present in counter devices.

Theory¶

Counter devices can vary greatly in design, but regardless of whethersome devices are quadrature encoder counters or tally counters, allcounter devices consist of a core set of components. This core set ofcomponents, shared by all counter devices, is what forms the essence ofthe Generic Counter interface.

There are three core components to a counter:

• Signal:Stream of data to be evaluated by the counter.

• Synapse:Association of a Signal, and evaluation trigger, with a Count.

• Count:Accumulation of the effects of connected Synapses.

Paradigm¶

The most basic counter device may be expressed as a single Countassociated with a single Signal via a single Synapse. Take for examplea counter device which simply accumulates a count of rising edges on asource input line:

        Count                Synapse        Signal        -----                -------        ------+---------------------+| Data: Count         |    Rising Edge     ________| Function: Increase  |  <-------------   / Source \|                     |                  ____________+---------------------+

In this example, the Signal is a source input line with a pulsingvoltage, while the Count is a persistent count value which is repeatedlyincremented. The Signal is associated with the respective Count via aSynapse. The increase function is triggered by the Signal data conditionspecified by the Synapse -- in this case a rising edge condition on thevoltage input line. In summary, the counter device existence andbehavior is aptly represented by respective Count, Signal, and Synapsecomponents: a rising edge condition triggers an increase function on anaccumulating count datum.

A counter device is not limited to a single Signal; in fact, in theorymany Signals may be associated with even a single Count. For example, aquadrature encoder counter device can keep track of position based onthe states of two input lines:

           Count                 Synapse     Signal           -----                 -------     ------+-------------------------+| Data: Position          |    Both Edges     ___| Function: Quadrature x4 |  <------------   / A \|                         |                 _______|                         ||                         |    Both Edges     ___|                         |  <------------   / B \|                         |                 _______+-------------------------+

In this example, two Signals (quadrature encoder lines A and B) areassociated with a single Count: a rising or falling edge on either A orB triggers the “Quadrature x4” function which determines the directionof movement and updates the respective position data. The “Quadraturex4” function is likely implemented in the hardware of the quadratureencoder counter device; the Count, Signals, and Synapses simplyrepresent this hardware behavior and functionality.

Signals associated with the same Count can have differing Synapse actionmode conditions. For example, a quadrature encoder counter deviceoperating in a non-quadrature Pulse-Direction mode could have one inputline dedicated for movement and a second input line dedicated fordirection:

           Count                   Synapse      Signal           -----                   -------      ------+---------------------------+| Data: Position            |    Rising Edge     ___| Function: Pulse-Direction |  <-------------   / A \ (Movement)|                           |                  _______|                           ||                           |       None         ___|                           |  <-------------   / B \ (Direction)|                           |                  _______+---------------------------+

Only Signal A triggers the “Pulse-Direction” update function, but theinstantaneous state of Signal B is still required in order to know thedirection so that the position data may be properly updated. Ultimately,both Signals are associated with the same Count via two respectiveSynapses, but only one Synapse has an active action mode condition whichtriggers the respective count function while the other is left with a“None” condition action mode to indicate its respective Signal’savailability for state evaluation despite its non-triggering mode.

Keep in mind that the Signal, Synapse, and Count are abstractrepresentations which do not need to be closely married to theirrespective physical sources. This allows the user of a counter todivorce themselves from the nuances of physical components (such aswhether an input line is differential or single-ended) and instead focuson the core idea of what the data and process represent (e.g. positionas interpreted from quadrature encoding data).

Driver API¶

Driver authors may utilize the Generic Counter interface in their codeby including the include/linux/counter.h header file. This header fileprovides several core data structures, function prototypes, and macrosfor defining a counter device.

structcounter_comp¶

Counter component node

struct counter_comp {    enum counter_comp_type type;    const char *name;    void *priv;    union {        int (*action_read)(struct counter_device *counter, struct counter_count *count, struct counter_synapse *synapse, enum counter_synapse_action *action);        int (*device_u8_read)(struct counter_device *counter, u8 *val);        int (*count_u8_read)(struct counter_device *counter, struct counter_count *count, u8 *val);        int (*signal_u8_read)(struct counter_device *counter, struct counter_signal *signal, u8 *val);        int (*device_u32_read)(struct counter_device *counter, u32 *val);        int (*count_u32_read)(struct counter_device *counter, struct counter_count *count, u32 *val);        int (*signal_u32_read)(struct counter_device *counter, struct counter_signal *signal, u32 *val);        int (*device_u64_read)(struct counter_device *counter, u64 *val);        int (*count_u64_read)(struct counter_device *counter, struct counter_count *count, u64 *val);        int (*signal_u64_read)(struct counter_device *counter, struct counter_signal *signal, u64 *val);        int (*signal_array_u32_read)(struct counter_device *counter, struct counter_signal *signal, size_t idx, u32 *val);        int (*device_array_u64_read)(struct counter_device *counter, size_t idx, u64 *val);        int (*count_array_u64_read)(struct counter_device *counter, struct counter_count *count, size_t idx, u64 *val);        int (*signal_array_u64_read)(struct counter_device *counter, struct counter_signal *signal, size_t idx, u64 *val);    };    union {        int (*action_write)(struct counter_device *counter, struct counter_count *count, struct counter_synapse *synapse, enum counter_synapse_action action);        int (*device_u8_write)(struct counter_device *counter, u8 val);        int (*count_u8_write)(struct counter_device *counter, struct counter_count *count, u8 val);        int (*signal_u8_write)(struct counter_device *counter, struct counter_signal *signal, u8 val);        int (*device_u32_write)(struct counter_device *counter, u32 val);        int (*count_u32_write)(struct counter_device *counter, struct counter_count *count, u32 val);        int (*signal_u32_write)(struct counter_device *counter, struct counter_signal *signal, u32 val);        int (*device_u64_write)(struct counter_device *counter, u64 val);        int (*count_u64_write)(struct counter_device *counter, struct counter_count *count, u64 val);        int (*signal_u64_write)(struct counter_device *counter, struct counter_signal *signal, u64 val);        int (*signal_array_u32_write)(struct counter_device *counter, struct counter_signal *signal, size_t idx, u32 val);        int (*device_array_u64_write)(struct counter_device *counter, size_t idx, u64 val);        int (*count_array_u64_write)(struct counter_device *counter, struct counter_count *count, size_t idx, u64 val);        int (*signal_array_u64_write)(struct counter_device *counter, struct counter_signal *signal, size_t idx, u64 val);    };};

structcounter_signal¶

Counter Signal node

struct counter_signal {    int id;    const char *name;    struct counter_comp *ext;    size_t num_ext;};

structcounter_synapse¶

Counter Synapse node

struct counter_synapse {    const enum counter_synapse_action *actions_list;    size_t num_actions;    struct counter_signal *signal;};

structcounter_count¶

Counter Count node

struct counter_count {    int id;    const char *name;    const enum counter_function *functions_list;    size_t num_functions;    struct counter_synapse *synapses;    size_t num_synapses;    struct counter_comp *ext;    size_t num_ext;};

structcounter_event_node¶

Counter Event node

struct counter_event_node {    struct list_head l;    u8 event;    u8 channel;    struct list_head comp_list;};

structcounter_ops¶

Callbacks from driver

struct counter_ops {    int (*signal_read)(struct counter_device *counter, struct counter_signal *signal, enum counter_signal_level *level);    int (*count_read)(struct counter_device *counter, struct counter_count *count, u64 *value);    int (*count_write)(struct counter_device *counter, struct counter_count *count, u64 value);    int (*function_read)(struct counter_device *counter, struct counter_count *count, enum counter_function *function);    int (*function_write)(struct counter_device *counter, struct counter_count *count, enum counter_function function);    int (*action_read)(struct counter_device *counter, struct counter_count *count, struct counter_synapse *synapse, enum counter_synapse_action *action);    int (*action_write)(struct counter_device *counter, struct counter_count *count, struct counter_synapse *synapse, enum counter_synapse_action action);    int (*events_configure)(struct counter_device *counter);    int (*watch_validate)(struct counter_device *counter, const struct counter_watch *watch);};

structcounter_device¶

Counter data structure

struct counter_device {    const char *name;    struct device *parent;    const struct counter_ops *ops;    struct counter_signal *signals;    size_t num_signals;    struct counter_count *counts;    size_t num_counts;    struct counter_comp *ext;    size_t num_ext;    struct device dev;    struct cdev chrdev;    struct list_head events_list;    spinlock_t events_list_lock;    struct list_head next_events_list;    struct mutex n_events_list_lock;    struct counter_event *events;    wait_queue_head_t events_wait;    spinlock_t events_in_lock;    struct mutex events_out_lock;    struct mutex ops_exist_lock;};

void*counter_priv(conststructcounter_device*constcounter)¶

access counter device private data

structcounter_device*counter_alloc(size_tsizeof_priv)¶

allocate a counter_device

intcounter_add(structcounter_device*counter)¶

complete registration of a counter

voidcounter_unregister(structcounter_device*constcounter)¶

unregister Counter from the system

structcounter_device*devm_counter_alloc(structdevice*dev,size_tsizeof_priv)¶

allocate a counter_device

intdevm_counter_add(structdevice*dev,structcounter_device*constcounter)¶

complete registration of a counter

voidcounter_push_event(structcounter_device*constcounter,constu8event,constu8channel)¶

queue event for userspace reading

Driver Implementation¶

To support a counter device, a driver must first allocate the availableCounter Signals via counter_signal structures. These Signals shouldbe stored as an array and set to the signals array member of anallocated counter_device structure before the Counter is registered tothe system.

Counter Counts may be allocated via counter_count structures, andrespective Counter Signal associations (Synapses) made viacounter_synapse structures. Associated counter_synapse structures arestored as an array and set to the synapses array member of therespective counter_count structure. These counter_count structures areset to the counts array member of an allocated counter_device structurebefore the Counter is registered to the system.

Driver callbacks must be provided to the counter_device structure inorder to communicate with the device: to read and write various Signalsand Counts, and to set and get the “action mode” and “function mode” forvarious Synapses and Counts respectively.

A counter_device structure is allocated usingcounter_alloc() and thenregistered to the system by passing it to thecounter_add() function, andunregistered by passing it to the counter_unregister function. There aredevice managed variants of these functions:devm_counter_alloc() anddevm_counter_add().

Thestructcounter_comp structure is used to define counter extensionsfor Signals, Synapses, and Counts.

The “type” member specifies the type of high-level data (e.g. BOOL,COUNT_DIRECTION, etc.) handled by this extension. The “*_read” and“*_write” members can then be set by the counter device driver withcallbacks to handle that data using native C data types (i.e. u8, u64,etc.).

Convenience macros such asCOUNTER_COMP_COUNT_U64 are provided foruse by driver authors. In particular, driver authors are expected to usethe provided macros for standard Counter subsystem attributes in orderto maintain a consistent interface for userspace. For example, a counterdevice driver may define several standard attributes like so:

struct counter_comp count_ext[] = {        COUNTER_COMP_DIRECTION(count_direction_read),        COUNTER_COMP_ENABLE(count_enable_read, count_enable_write),        COUNTER_COMP_CEILING(count_ceiling_read, count_ceiling_write),};

This makes it simple to see, add, and modify the attributes that aresupported by this driver (“direction”, “enable”, and “ceiling”) and tomaintain this code without getting lost in a web ofstructbraces.

Callbacks must match the function type expected for the respectivecomponent or extension. These function types are defined in thestructcounter_comp structure as the “*_read” and “*_write”unionmembers.

The corresponding callback prototypes for the extensions mentioned inthe previous example above would be:

int count_direction_read(struct counter_device *counter,                         struct counter_count *count,                         enum counter_count_direction *direction);int count_enable_read(struct counter_device *counter,                      struct counter_count *count, u8 *enable);int count_enable_write(struct counter_device *counter,                       struct counter_count *count, u8 enable);int count_ceiling_read(struct counter_device *counter,                       struct counter_count *count, u64 *ceiling);int count_ceiling_write(struct counter_device *counter,                        struct counter_count *count, u64 ceiling);

Determining the type of extension to create is a matter of scope.

• Signal extensions are attributes that expose information/controlspecific to a Signal. These types of attributes will exist under aSignal’s directory in sysfs.

  For example, if you have an invert feature for a Signal, you can havea Signal extension called “invert” that toggles that feature:/sys/bus/counter/devices/counterX/signalY/invert

• Count extensions are attributes that expose information/controlspecific to a Count. These type of attributes will exist under aCount’s directory in sysfs.

  For example, if you want to pause/unpause a Count from updating, youcan have a Count extension called “enable” that toggles such:/sys/bus/counter/devices/counterX/countY/enable

• Device extensions are attributes that expose information/controlnon-specific to a particular Count or Signal. This is where you wouldput your global features or other miscellaneous functionality.

  For example, if your device has an overtemp sensor, you can report thechip overheated via a device extension called “error_overtemp”:/sys/bus/counter/devices/counterX/error_overtemp

Subsystem Architecture¶

Counter drivers pass and take data natively (i.e.u8,u64, etc.)and the shared counter module handles the translation between the sysfsinterface. This guarantees a standard userspace interface for allcounter drivers, and enables a Generic Counter chrdev interface via ageneralized device driver ABI.

A high-level view of how a count value is passed down from a counterdriver is exemplified by the following. The driver callbacks are firstregistered to the Counter core component for use by the Counteruserspace interface components:

Driver callbacks registration:~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~                +----------------------------+                | Counter device driver      |                +----------------------------+                | Processes data from device |                +----------------------------+                        |                 -------------------                / driver callbacks /                -------------------                        |                        V                +----------------------+                | Counter core         |                +----------------------+                | Routes device driver |                | callbacks to the     |                | userspace interfaces |                +----------------------+                        |                 -------------------                / driver callbacks /                -------------------                        |        +---------------+---------------+        |                               |        V                               V+--------------------+          +---------------------+| Counter sysfs      |          | Counter chrdev      |+--------------------+          +---------------------+| Translates to the  |          | Translates to the   || standard Counter   |          | standard Counter    || sysfs output       |          | character device    |+--------------------+          +---------------------+

Thereafter, data can be transferred directly between the Counter devicedriver and Counter userspace interface:

Count data request:~~~~~~~~~~~~~~~~~~~                 ----------------------                / Counter device       \                +----------------------+                | Count register: 0x28 |                +----------------------+                        |                 -----------------                / raw count data /                -----------------                        |                        V                +----------------------------+                | Counter device driver      |                +----------------------------+                | Processes data from device |                |----------------------------|                | Type: u64                  |                | Value: 42                  |                +----------------------------+                        |                 ----------                / u64     /                ----------                        |        +---------------+---------------+        |                               |        V                               V+--------------------+          +---------------------+| Counter sysfs      |          | Counter chrdev      |+--------------------+          +---------------------+| Translates to the  |          | Translates to the   || standard Counter   |          | standard Counter    || sysfs output       |          | character device    ||--------------------|          |---------------------|| Type: const char * |          | Type: u64           || Value: "42"        |          | Value: 42           |+--------------------+          +---------------------+        |                               | ---------------                 -----------------------/ const char * /                / struct counter_event /---------------                 -----------------------        |                               |        |                               V        |                       +-----------+        |                       | read      |        |                       +-----------+        |                       \ Count: 42 /        |                        -----------        |        V+--------------------------------------------------+| `/sys/bus/counter/devices/counterX/countY/count` |+--------------------------------------------------+\ Count: "42"                                      / --------------------------------------------------

There are four primary components involved:

Sysfs Interface¶

Several sysfs attributes are generated by the Generic Counter interface,and reside under the/sys/bus/counter/devices/counterX directory,whereX is to the respective counter device id. Please seeABI file testing/sysfs-bus-counter for detailed informationon each Generic Counter interface sysfs attribute.

Through these sysfs attributes, programs and scripts may interact withthe Generic Counter paradigm Counts, Signals, and Synapses of respectivecounter devices.

Counter Character Device¶

Counter character device nodes are created under the/dev directoryascounterX, whereX is the respective counter device id.Defines for the standard Counter data types are exposed via theuserspaceinclude/uapi/linux/counter.h file.

void counter_push_event(struct counter_device *const counter, const u8 event,                        const u8 channel);