Return-Path: Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1753663AbdLNUxK (ORCPT ); Thu, 14 Dec 2017 15:53:10 -0500 Received: from mail-yb0-f194.google.com ([209.85.213.194]:38909 "EHLO mail-yb0-f194.google.com" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1753390AbdLNUxD (ORCPT ); Thu, 14 Dec 2017 15:53:03 -0500 X-Google-Smtp-Source: ACJfBovU3frkHaGd86FFJTxP8Ro0ig8pGAB1+DQM7/2ZK64ygWj0EpyirgQd+cZL7MOzxMTY2XlPEg== From: William Breathitt Gray To: jic23@kernel.org, knaack.h@gmx.de, lars@metafoo.de, pmeerw@pmeerw.net Cc: benjamin.gaignard@linaro.org, linux-iio@vger.kernel.org, linux-kernel@vger.kernel.org, William Breathitt Gray Subject: [PATCH v4 10/11] docs: Add Quadrature Counter interface documentation Date: Thu, 14 Dec 2017 15:52:56 -0500 Message-Id: <07b51f505f59ff24fa9234e550fa4d7f7cc5c01d.1513266127.git.vilhelm.gray@gmail.com> X-Mailer: git-send-email 2.15.1 In-Reply-To: References: Sender: linux-kernel-owner@vger.kernel.org List-ID: X-Mailing-List: linux-kernel@vger.kernel.org Content-Length: 21543 Lines: 471 This patch adds high-level documentation about the Quadrature Counter interface. Signed-off-by: William Breathitt Gray --- Documentation/driver-api/iio/index.rst | 1 + Documentation/driver-api/iio/quad-counter.rst | 444 ++++++++++++++++++++++++++ 2 files changed, 445 insertions(+) create mode 100644 Documentation/driver-api/iio/quad-counter.rst diff --git a/Documentation/driver-api/iio/index.rst b/Documentation/driver-api/iio/index.rst index 60e17f16cfb8..db1e2d7e7b87 100644 --- a/Documentation/driver-api/iio/index.rst +++ b/Documentation/driver-api/iio/index.rst @@ -17,3 +17,4 @@ Contents: triggered-buffers generic-counter simple-counter + quad-counter diff --git a/Documentation/driver-api/iio/quad-counter.rst b/Documentation/driver-api/iio/quad-counter.rst new file mode 100644 index 000000000000..4800feafd6ba --- /dev/null +++ b/Documentation/driver-api/iio/quad-counter.rst @@ -0,0 +1,444 @@ +============================ +Quadrature Counter Interface +============================ + +Introduction +============ + +A common use for counter devices is position tracking. There are several +protocols for the communication of position changes, but one of the most +popular is the quadrature encoding system utilized commonly by rotary +encoder and linear encoder devices. + +A quadrature counter device is a counter device that tracks positions +based on pairs of quadrature encoder inputs. A Quadrature Counter device +may be expressed as consisting of single Counts each associated with a +pair of Signals via respective Synapses. + +This driver API provides a basic Counter interface and standard of +interaction and exposure for these quadrature counter devices. The +Quadrature Counter interface enables drivers to support and expose +quadrature counter devices in a more apt and well-defined way, without +the hassles and imprecisions of utilizing a more generic interface. + +Theory +====== + +The Quadrature Counter interface may be considered a subclass of the +Generic Counter interface; the same paradigm core components apply: +Counts, Signals, and Synapses. However, the Quadrature Counter interface +goes a bit further and defines aspects of those core components to +properly represent Quadrature Counter devices. + +The three core components of a Quadrature Counter: + + COUNT + ----- + A Count represents the count data for a set of Signals. The + count data for a Quadrature Counter is a signed integer + representing the position. + + A Count has a count function mode which represents the update + behavior for the count data. The following four count function + modes are possible for a Quadrature Count: + + * Pulse-Direction: + Rising edges on quadrature pair signal A updates + the respective count. The input level of + quadrature pair signal B determines direction. + * Quadrature x1: + If direction is forward, rising edges on + quadrature pair signal A updates the respective + count; if the direction is backward, falling + edges on quadrature pair signal A updates the + respective count. Quadrature encoding determines + the direction. + * Quadrature x2: + Any state transition on quadrature pair signal A + updates the respective count. Quadrature + encoding determines the direction. + * Quadrature x4: + Any state transition on either quadrature pair + signals updates the respective count. Quadrature + encoding determines the direction. + + A Quadrature Count has a pair associated Quadrature Signals. + + SIGNAL + ------ + A Signal represents a counter input data; this is the data that + is typically analyzed by the counter to determine the count + data. A Quadrature Signal represents a quadrature counter input + line with two possible states: + + * Low + * High + + A Quadrature Signal is associated to a Quadrature Count. + + 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. There are four possible action modes + for a Quadrature Counter: + + * 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. + +Paradigm +======== + +Quadrature Counter devices consist of a single Count associated with a +pair of Signals via respective Synapses. Take for example a quadrature +counter device which tracks position via the evaluation of a pair of +quadrature encoder 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) are +associated to a single Count: a rising or falling edge on either A or B +triggers the "Quadrature x4" function which determines the direction of +movement and updates the respective position data. The "Quadrature x4" +function is likely implemented in the hardware of the quadrature encoder +counter device; the Count, Signals, and Synapses simply represent this +hardware behavior and functionality. + +In addition, a quadrature encoder counter device operating in a +non-quadrature Pulse-Direction mode could have one input line dedicated +for movement and a second input line dedicated for direction. + + 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 the +instantaneous state of Signal B is still required in order to know the +direction so that the position data may be properly updated. Ultimately, +both Signals are associated to the same Count via two respective +Synapses, but only one Synapse has an active action mode condition which +triggers the respective count function while the other is left with a +"None" condition action mode to indicate its respective Signal's +availability for state evaluation despite its non-triggering mode. + +Userspace Interface +=================== + +Several sysfs attributes are generated by the Quadrature Counter +interface, and reside under the /sys/bus/counter/devices/counterX +directory, where counterX refers to the respective counter device. +Please see Documentation/ABI/testing/sys-bus-counter-quadrature-sysfs +for detailed information on each Quadrature Counter interface sysfs +attribute. + +In addition, several sysfs attributes are generated by the underlying +Generic Counter interface, and also reside under the +/sys/bus/counter/devices/counterX directory, where counterX refers to +the respective counter device. Please see +Documentation/ABI/testing/sys-bus-counter-generic-sysfs for detailed +information on each Generic Counter interface sysfs attribute. + +Through these sysfs attributes, programs and scripts may interact with +the Quadrature Counter paradigm Counts, Signals, and Synapses of +respective counter devices. + +Driver API +========== + +Driver authors may utilize the Quadrature Counter interface in their +code by including the include/linux/iio/counter.h header file. This +header file provides several core data structures and function +prototypes for defining a quadrature counter. + + +struct quad_counter_signal_ext +------------------------------ + +This structure defines a Quadrature Counter Signal extension attribute. +These attributes expose auxiliary configuration and functionality +specific to the respective Quadrature Counter Signal. + + name: attribute name + read: read callback for this attribute; may be NULL + write: write callback for this attribute; may be NULL + priv: data private to the driver + +struct quad_counter_signal +-------------------------- + +This structure defines a Quadrature Counter Signal component. Typically, +this will correlate with a quadrature encoding line input channel on a +physical counter device. This structure is the simplest of the +Quadrature Counter paradigm core components to define with only two +structure members which require explicit configuration: + + id: unique ID used to identify signal + name: device-specific signal name + ext: optional array of Quadrature Counter Signal + extensions + num_ext: number of Quadrature Counter Signal extensions + specified in @ext + priv: optional private data supplied by driver + +enum quad_counter_signal_level +------------------------------ + +This enum defines enumeration constants to represent the possible +Quadrature Signal data level states. + + QUAD_COUNTER_SIGNAL_LOW: Low + QUAD_COUNTER_SIGNAL_HIGH: High + +enum quad_counter_function +-------------------------- + +This enum defines enumeration constants to represent the possible +Quadrature Counter count function modes. + + QUAD_COUNTER_FUNCTION_PULSE_DIRECTION: Pulse-Direction + QUAD_COUNTER_FUNCTION_QUADRATURE_X1: Quadrature x1 + QUAD_COUNTER_FUNCTION_QUADRATURE_X2: Quadrature x2 + QUAD_COUNTER_FUNCTION_QUADRATURE_X4: Quadrature x4 + +enum quad_counter_direction +-------------------------- + +This enum defines enumeration constants to represent the possible +Quadrature Counter directions. + + QUAD_COUNTER_DIRECTION_FORWARD: Forward + QUAD_COUNTER_DIRECTION_BACKWARD: Backward + +struct quad_counter_count_ext +------------------------------- + +This structure defines a Quadrature Counter Count extension attribute. +These attributes expose auxiliary configuration and functionality +specific to the respective Quadrature Counter Count. + + name: attribute name + read: read callback for this attribute; may be NULL + write: write callback for this attribute; may be NULL + priv: data private to the driver + +struct quad_counter_count +------------------------- + +This structure defines a Quadrature Counter Count component. Typically, +this will correlate with the read data (the "position" value) provided +by a physical counter device. This structure requires the explicit +configuration of an ID, name, and the pair of Quadrature Signals +associated with this Quadrature Count. + + id: unique ID used to identify Count + name: device-specific Count name + function: current function mode + direction: current direction state + signal_a: associated quadrature A signal + signal_b: associated quadrature B signal + ext: optional array of Quadrature Counter Count + extensions + num_ext: number of Quadrature Counter Count extensions + specified in @ext + priv: optional private data supplied by driver + +struct quad_counter_device_ext +------------------------------ + +This structure defines a Quadrature Counter extension attribute. These +attributes expose auxiliary configuration and functionality specific to +the respective Quadrature Counter. + + name: attribute name + read: read callback for this attribute; may be NULL + write: write callback for this attribute; may be NULL + priv: data private to the driver + +struct quad_counter_device +-------------------------- + +This is the main data structure for a Quadrature Counter device. Access +to all respective Counts, Signals, and Synapses is possible from this +structure. This structure requires the configuration of a name and +Quadrature Counter Counts: + + name: name of the device + parent: optional parent device providing the counters + signal_read: read callback for Signal attribute; may be NULL. + Returns 0 on success and negative error code on + error. The respective Signal's returned level + should be passed back via the level parameter. + count_read: read callback for Count attribute; may be NULL. + Returns 0 on success and negative error code on + error. The respective Count's returned value + should be passed back via the val parameter. + count_write: write callback for Count attribute; may be NULL + function_get: function to get the current count function mode. + Returns 0 on success and negative error code on + error. The respective Count's returned function + mode should be passed back via the function + parameter. + function_set: function to set the count function mode + direction_get: function to get the current direction. Returns 0 + on success and negative error code on error. The + respective Count's returned direction should be + passed back via the direction parameter. + counts: array of Quadrature Counter Counts + num_counts: number of Quadrature Counter Counts specified in + @counts + ext: optional array of Quadrature Counter device + extensions + num_ext: number of Quadrature Counter device extensions + specified in @ext + priv: optional private data supplied by driver + +Registration functions +---------------------- + +A quadrature counter device is registered to the system by passing the +respective initialized quad_counter_device structure to the +quad_counter_register function; similarly, the quad_counter_unregister +function unregisters the respective Quadrature Counter. The +devm_quad_counter_register and devm_quad_counter_unregister functions +serve as device memory-managed versions of the quad_counter_register and +quad_counter_unregister functions respectively. + +Implementation +============== + +To use the Quadrature Counter interface, create an array of +quad_counter_count structures to represent the desired Counts and +Signals of the quadrature counter device; the signal_a member of a +quad_counter_count structure should define the Channel A signal of the +respective quadrature encoding pair, and similarly the signal_b member +should define Channel B. The defined quad_counter_count array may then +be added to a quad_counter_device structure for registration to the +system. + + Quad Count Count Signal + ---------- ----- ------ ++-------------------------+ +-------------------------+ +| Data: Position | -> | Data: Position | +| Function: Quadrature x4 | | Function: Quadrature x4 | +| | +-------------------------+ +| | ++-------------------------+ ________ +| Signal: Quad A | ----------------------------> / Quad A \ +| | ____________ +| | ++-------------------------+ ________ +| Signal: Quad B | ----------------------------> / Quad B \ +| | ____________ ++-------------------------+ + +Driver callbacks should be provided to the quad_counter_device structure +in order to communicate with the device: to read and write various +Counts, to read various Signals, to get and set the "function mode" for +various Counts, and to get the direction for various Counts. + +A defined quad_counter_device structure may be registered to the system +by passing it to the quad_counter_register function, and unregistered by +passing it to the quad_counter_unregister function. Similarly, the +devm_quad_counter_register and devm_quad_counter_unregister functions +may be used if device memory-managed registration is desired. + +Extension sysfs attributes can be created for auxiliary functionality +and data by passing in defined quad_counter_device_ext, +quad_counter_count_ext, and quad_counter_signal_ext structures. In +these cases, the quad_counter_device_ext structure is used for global +configuration of the respective Counter device, while the +quad_counter_count_ext and quad_counter_signal_ext structures allow +for auxiliary exposure and configuration of a specific Count or Signal +respectively. + +Architecture +============ + +The Quadrature Counter interface is a subclass of the Generic Counter +interface, and the Quadrature Counter interface functions serve as +mappings onto the Generic Counter interface functions to simplify and +aptly define support for quadrature counter devices. + +In this vein, the Generic Counter interface functions are ultimately +called when the Quadrature Counter interface functions are utilized. For +more information on the architecture of the Generic Counter interface, +please refer to the Documentation/driver-api/iio/generic-counter.rst +file. + +Quadrature Counter devices are registered to the system via the +quad_counter_register function, and later removed via the +quad_counter_unregister function. The quad_counter_register function +will allocate a counter_device structure, populate it with the required +Generic Counter structures and data required to represent the Quadrature +Counter components, and register it to the system via a counter_register +call. + + _____________________ +-----------------------+ + / quad_counter_device \ --> | quad_counter_register | +_________________________ +-----------------------+ + | + +------------------------------+ + | + V + ________________ +------------------+ + / counter_device \ --> | counter_register | +____________________ +------------------+ + +The signal_read driver callback, the count_read/count_write and +function_get/function_set driver callbacks, and the direction_get driver +callbacks are mapped to the allocated internal counter_device structure +via appropriate hook functions. + + Quad Counter Remap Function Generic Counter + ------------ -------------- --------------- + + signal_read quad_counter_signal_read signal_read + count_read quad_counter_count_read count_read + count_write quad_counter_count_write count_write + function_get quad_counter_function_get function_get + function_set quad_counter_function_set function_set + direction_get quad_counter_action_get action_get + +This is how Generic Counter interface sysfs attributes are inherited and +extended by the Quadrature Counter interface. If a driver callback is +left undefined, then the respective read/write permission is left +disabled for the relevant attributes. The quad_counter_action_get +function in particular depends on both direction_get and function_get -- +so if either driver callback is undefined, the internal counter_device +action_get function pointer is left as NULL. + +Similarly, quad_counter_device_ext, quad_counter_count_ext, and +quad_counter_signal_ext structures are mapped to respective +counter_device_ext, counter_count_ext, and counter_signal_ext structures +via appropriate hook functions, and then added to the allocated internal +counter_device structure for registration. -- 2.15.1