From patchwork Thu Dec 14 20:52:56 2017 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: William Breathitt Gray X-Patchwork-Id: 10113315 Return-Path: Received: from mail.wl.linuxfoundation.org (pdx-wl-mail.web.codeaurora.org [172.30.200.125]) by pdx-korg-patchwork.web.codeaurora.org (Postfix) with ESMTP id 697FD602B3 for ; Thu, 14 Dec 2017 20:53:09 +0000 (UTC) Received: from mail.wl.linuxfoundation.org (localhost [127.0.0.1]) by mail.wl.linuxfoundation.org (Postfix) with ESMTP id 5A55028E8F for ; Thu, 14 Dec 2017 20:53:09 +0000 (UTC) Received: by mail.wl.linuxfoundation.org (Postfix, from userid 486) id 58D2A29D2C; Thu, 14 Dec 2017 20:53:09 +0000 (UTC) X-Spam-Checker-Version: SpamAssassin 3.3.1 (2010-03-16) on pdx-wl-mail.web.codeaurora.org X-Spam-Level: X-Spam-Status: No, score=-6.8 required=2.0 tests=BAYES_00, DKIM_ADSP_CUSTOM_MED, DKIM_SIGNED, FREEMAIL_FROM, RCVD_IN_DNSWL_HI, T_DKIM_INVALID autolearn=ham version=3.3.1 Received: from vger.kernel.org (vger.kernel.org [209.132.180.67]) by mail.wl.linuxfoundation.org (Postfix) with ESMTP id 13AB728E8F for ; Thu, 14 Dec 2017 20:53:08 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1752361AbdLNUxH (ORCPT ); Thu, 14 Dec 2017 15:53:07 -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 Received: by mail-yb0-f194.google.com with SMTP id h28so4527364ybj.5; Thu, 14 Dec 2017 12:53:03 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20161025; h=from:to:cc:subject:date:message-id:in-reply-to:references; bh=aLnkFLn+zIvW40Vq18Lpfim0Wqxr4d9ygtsTdpON8SQ=; b=OLA1aCLM5e5tdtA7EEcn4jOsC8HKhyju4o38/iu1VSjvVi6bgIQmNE3iPkJUfgIEpr T9GglQ+u6Cci34Q2EOkhyheRF4cURPE4sr4Vej6/t2EowgETq9pTWgru7XfgaUw4x8Fd iPd+jLsr/f01kV2zvVy5Hx0DBPfVcXIHb28pzeibZNs6Tr7NKpzI0TcSF4zcSrzlOPov iszAf4qmph84c2vKVEDZcaXzoLj/KkOzENc07ZMzRqvVsOzmy5nHlpOYEet8KLwX4QUv RSpz5JBhrEubHlnEdAsXo8osVqnttAGSd+dXiyvnD2muMFueppeRzIOqfIcKCb0A6+Ix 0rHw== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:from:to:cc:subject:date:message-id:in-reply-to :references; bh=aLnkFLn+zIvW40Vq18Lpfim0Wqxr4d9ygtsTdpON8SQ=; b=rT70Vwdt7Xe6qfUwPcecxTMB5BskKGYSh2d6Tnu7bwMJ5N7mWXN75mrY3Xrjf1UmKu 8B9ZTgkeprzVeLE1bAwSt0L39rsBDh/CV0FR05/FS/igXYqX/Uh29dcMUSWkKwkKqs0j lyn4oplnPGxRTWn/ndH55JeYwEAaDJLEICnqwwA8ZKCZL7aFbSrxDL3KEN1Y6vf1XXuF lh4g82QfFbLw5DuyGmRQJT2KE4HDtEwqL9Ohc5lJVq84dWkjqoh5PVYbQ0NXH+WoUU9e 0BXpfU9g8Wc4gbTXXiEOxtHdIzpuOUsOqM8XnizQdEq+A0pG3tZafVXv33zpU5CZFBKP 51Nw== X-Gm-Message-State: AKGB3mKfnttbLaFy5oG83mpMDsyPTHzOH5+akp4+7e+XfEfg1SRBPfAe 4zTAAu0PZpUjBOM7A9mb9mIvRA== X-Google-Smtp-Source: ACJfBovU3frkHaGd86FFJTxP8Ro0ig8pGAB1+DQM7/2ZK64ygWj0EpyirgQd+cZL7MOzxMTY2XlPEg== X-Received: by 10.13.217.202 with SMTP id b193mr5265213ywe.147.1513284782311; Thu, 14 Dec 2017 12:53:02 -0800 (PST) Received: from localhost ([72.188.97.40]) by smtp.gmail.com with ESMTPSA id i207sm2135589ywe.38.2017.12.14.12.53.01 (version=TLS1_2 cipher=ECDHE-RSA-AES128-GCM-SHA256 bits=128/128); Thu, 14 Dec 2017 12:53:01 -0800 (PST) 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-iio-owner@vger.kernel.org Precedence: bulk List-ID: X-Mailing-List: linux-iio@vger.kernel.org X-Virus-Scanned: ClamAV using ClamSMTP 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.