From patchwork Thu Dec 14 20:51:16 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: 10113287 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 8D13F602B3 for ; Thu, 14 Dec 2017 20:51:27 +0000 (UTC) Received: from mail.wl.linuxfoundation.org (localhost [127.0.0.1]) by mail.wl.linuxfoundation.org (Postfix) with ESMTP id 7E6B029745 for ; Thu, 14 Dec 2017 20:51:27 +0000 (UTC) Received: by mail.wl.linuxfoundation.org (Postfix, from userid 486) id 72CA529D37; Thu, 14 Dec 2017 20:51:27 +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 0F5F829CF2 for ; Thu, 14 Dec 2017 20:51:26 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1752751AbdLNUvZ (ORCPT ); Thu, 14 Dec 2017 15:51:25 -0500 Received: from mail-yb0-f171.google.com ([209.85.213.171]:42986 "EHLO mail-yb0-f171.google.com" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1752403AbdLNUvY (ORCPT ); Thu, 14 Dec 2017 15:51:24 -0500 Received: by mail-yb0-f171.google.com with SMTP id t127so4516404ybf.9; Thu, 14 Dec 2017 12:51:24 -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=qnG8aICCrayMGrEPiuPXe1gH89Fk7UagXXH0q1XV1QU=; b=oBXKuwZEWNoB+M00Ndmrjy26Aqt2CHVCTnMmOnjDUkZ3AKMLB+z7ljCRq1uQ9peH5d pnako5iKvKCtKWanbUUk9cKt6t/0w7g72mx7kGUjd+c+q7YuItNmLsuKzvtLEYR7AqRn M5eR7+lElWel1VcKrSPyDmb7YbOMCwLopg8UYtgfKOXin693zeD5ct8EKATQtM7PHn9v jxrq9qH1Go+GrR59Kxfr1etWK4J5VaGYlsnh4U9e2Xntj3BASjEjXQ/k+qEwAjNpqJ2P gr9vd4JoMaIpfMl8T6FeNB3JRTRyR2+oTEnu4RogWD4LUmahk7eB8jeAGThkA9z9/nOU HteQ== 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=qnG8aICCrayMGrEPiuPXe1gH89Fk7UagXXH0q1XV1QU=; b=iCAAG2jtGME+W0pcwgJgva+yGOLaQcP9mpqLkxh/mEB+LjpErEJSVV5jb8Oncq1OJ7 iI+2hpqPlXc7TPKS6jJyXaXm9VdFkx3hUc6jyUqMr67SD8vK6C62Dlnu+xsELVKk92Cm uXuxGIQDmiGvv4OXRl4brcojsFtKNqvSK0deVu1i85eJh2cY+oXURQ//89KBi2JTNQkV rzz+XmxWk3gV5Br9+ykQiV8cIR+4cwODMXPb2tSurixAF6UVZNaQnhOAOKZVRd6kGQ8I Po3iw9OuYLpxn1QzWEidFPqKb8Nv9nu5Uqt2tSkQA+OKTpHwQenos79jT5rCooraUBCO 9ZTg== X-Gm-Message-State: AKGB3mK84/LH4tCoAtgoKQoyPLe2CWVLbyZB8IVp9fo2ZtpouF1ivYog jENaAUe3c2itxt1deDPAzuMHAw== X-Google-Smtp-Source: ACJfBovdUpBtchZeALzXeF25p26IUDzdpq4DZsD4BFcO4Ipa25k8u6UWDgAJ3Limox6bFFZAanaCSQ== X-Received: by 10.129.235.5 with SMTP id n5mr5423949ywm.399.1513284683406; Thu, 14 Dec 2017 12:51:23 -0800 (PST) Received: from localhost ([72.188.97.40]) by smtp.gmail.com with ESMTPSA id n1sm1224214ywe.79.2017.12.14.12.51.22 (version=TLS1_2 cipher=ECDHE-RSA-AES128-GCM-SHA256 bits=128/128); Thu, 14 Dec 2017 12:51:22 -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 03/11] docs: Add Generic Counter interface documentation Date: Thu, 14 Dec 2017 15:51:16 -0500 Message-Id: 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 Generic Counter interface. Signed-off-by: William Breathitt Gray --- Documentation/driver-api/iio/generic-counter.rst | 434 +++++++++++++++++++++++ Documentation/driver-api/iio/index.rst | 1 + MAINTAINERS | 1 + 3 files changed, 436 insertions(+) create mode 100644 Documentation/driver-api/iio/generic-counter.rst diff --git a/Documentation/driver-api/iio/generic-counter.rst b/Documentation/driver-api/iio/generic-counter.rst new file mode 100644 index 000000000000..219c571e90ce --- /dev/null +++ b/Documentation/driver-api/iio/generic-counter.rst @@ -0,0 +1,434 @@ +========================= +Generic Counter Interface +========================= + +Introduction +============ + +Counter devices are prevalent within a diverse spectrum of industries. +The ubiquitous presence of these devices necessitates a common interface +and standard of interaction and exposure. This driver API attempts to +resolve the issue of duplicate code found among existing counter device +drivers by introducing a generic counter interface for consumption. The +Generic Counter interface enables drivers to support and expose a common +set of components and functionality present in counter devices. + +Theory +====== + +Counter devices can vary greatly in design, but regardless of whether +some devices are quadrature encoder counters or tally counters, all +counter devices consist of a core set of components. This core set of +components, shared by all counter devices, is what forms the essence of +the Generic Counter interface. + +There are three core components to a counter: + + COUNT + ----- + A Count represents the count data for a set of Signals. A Count + has a count function mode (e.g. "increase" or "quadrature x4") + which represents the update behavior for the count data. A Count + also has a set of one or more associated 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 Signal may be associated to one or more Counts. + + 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 (e.g. "rising edge" or "double pulse") specifies the Signal + data condition which triggers the respective Count's count + function evaluation to update the count data. It is possible for + the Synapse action mode to be "none" if a Signal is associated + with a Count but does not trigger the count function (e.g. the + direction signal line for a Pulse-Direction encoding counter). + +A counter is defined as a set of input signals associated to count data +that are generated by the evaluation of the state of the associated +input signals as defined by the respective count functions. Within the +context of the Generic Counter interface, a counter consists of Counts +each associated to a set of Signals, whose respective Synapse instances +represent the count function update conditions for the associated +Counts. + +Paradigm +======== + +The most basic counter device may be expressed as a single Count +associated with a single Signal via a single Synapse. Take for example +a counter device which simply accumulates a count of rising edges on a +source input line. + + Count Synapse Signal + ----- ------- ------ ++---------------------+ +| Data: Count | Rising Edge ________ +| Function: Increase | <------------- / Source \ +| | ____________ ++---------------------+ + +In this example, the Signal is a source input line with a pulsing +voltage, while the Count is a persistent count value which is repeatedly +incremented. The Signal is associated with the respective Count via a +Synapse. The increase function is triggered by the Signal data condition +specified by the Synapse -- in this case a rising edge condition on the +voltage input line. In summary, the counter device existence and +behavior is aptly represented by respective Count, Signal, and Synapse +components: a rising edge condition triggers an increase function on an +accumulating count datum. + +A counter device is not limited to a single Signal; in fact, in theory +many number of Signals may be associated with even a single Count. For +example, a quadrature encoder counter device can keep track of position +based on the 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) 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. + +Signals associated to the same Count can have differing Synapse action +mode conditions. For example, 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. + +The flexibility of Synapses allows for the representation of counters +whose respective Count Signal relationships would be difficult to +represent as isolated inputs. For example a tri-color LED color counter +can easily be represented with three Synapses: + + Count Synapse Signal + ----- ------- ------ ++------------------+ +| Data: Count | Both Edges _______ +| Function: Purple | <------------ / Red \ +| | ___________ +| | +| | Both Edges _______ +| | <------------ / Green \ +| | ___________ +| | +| | Both Edges _______ +| | <------------ / Blue \ +| | ___________ ++------------------+ + +This counter accumulates the number of times the tri-color LED has +turned to purple. By utilizing the Synapses to associate the three color +Signals to the single Count, the count function evaluation relationship +becomes apparent: combined color is checked when an individual color is +turned on or off, and if only Red and Blue are active then Count datum +is incremented to indicate the color has now turned to Purple. + +Although the examples thus far have been representations of physical +devices, this is not a necessity. A counter simply represent the +evaluation (Count) of input data (Signals) triggered by specific +conditions (Synapses). A counter can be the representation of more +abstract components. + +For example, suppose a counter representation is desired for a DNA +sequence analysizer which detects possible genetic diseases. + + Count Synapse Signal + ----- ------- ------ ++---------------------+ +| Data: Diseases | Gene Transcript (EST) _____ +| Function: Cancers | <----------------------- / DNA \ (GAAGTGC...) +| | _________ ++---------------------+ + +In this scenario, the Signal is a stream of DNA nucleotide bases (As, +Ts, Cs, and Gs), the Synapse action modes consist of the various +expressed sequence tags (ESTs), and the Count is a list of diseases +discovered (in this particular example the function is evaluating for +possible cancers). Note how the Signal in this example does not +represent a physical voltage line, nor does the Synapse action mode +represent a physical voltage line state change, nor does the Count +represent a strictly decimal data value. + +The DNA sequence analysizer example is contrived to illustrate the +flexibility of the generic counter paradigm by demonstrating its +capability of representing abstract concepts; however, physical devices +are likely to be more fitting for such a representation. + +The key concept is that the Signal, Synapse, and Count are abstract +representations which do not need to be closely married to their +respective physical sources. This allows the user of a counter to +divorce themselves from the nuances of physical components (such as +whether an input line is differential or single-ended) and focus on the +core idea of what the data and process represent (e.g. an accumulated +count of rising edges). + +Userspace Interface +=================== + +Several sysfs attributes are generated by the Generic 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-generic-sysfs for detailed +information on each Generic Counter interface sysfs attribute. + +Through these sysfs attributes, programs and scripts may interact with +the Generic Counter paradigm Counts, Signals, and Synapses of respective +counter devices. + +Driver API +========== + +Driver authors may utilize the Generic 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 generic counter. + + +struct counter_signal_ext +------------------------- + +This structure defines a Generic Counter Signal extension attribute. +These attributes expose auxiliary configuration and functionality +specific to the respective Generic 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 counter_signal +--------------------- + +This structure defines a Generic Counter Signal component. Typically, +this will correlate with an input channel on a physical counter device. +This structure is the simplest of the Generic 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 Counter Signal extensions + num_ext: number of Counter Signal extensions specified in + ext + priv: optional private data supplied by driver + +struct counter_synapse +---------------------- + +This structure defines a Generic Counter Synapse component. To properly +utilize this structure, action modes and an associated Signal must be +defined: + + action: current action mode + actions: available action modes + num_actions: number of action modes specified in actions + signal: pointer to associated signal + +struct counter_count_ext +------------------------ + +This structure defines a Generic Counter Count extension attribute. +These attributes expose auxiliary configuration and functionality +specific to the respective Generic 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 counter_count +-------------------- + +This structure defines a Generic Counter Count component. Typically, +this will correlate with the read data (the "count" value) provided by a +physical counter device. This structure requires the explicit +configuration of an ID, name, function modes (the function triggered on +a Synapse action condition), and a set of Synapses for the associated +Signals: + + id: unique ID used to identify Count + name: device-specific Count name + function: current function mode + functions: available function modes + num_functions: number of functions specified in @functions + synapses: array of synapses for initialization + num_synapses: number of synapses specified in @synapses + ext: optional array of Counter Count extensions + num_ext: number of Counter Count extensions specified in + ext + priv: optional private data supplied by driver + +struct counter_device_ext +------------------------- + +This structure defines a Generic Counter extension attribute. These +attributes expose auxiliary configuration and functionality specific to +the respective Generic 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 counter_device +--------------------- + +This is the main data structure for a Generic Counter device. Access to +all respective Counts, Signals, and Synapses is possible from this +structure. This structure requires the configuration of a name, Generic +Counter Signals, and Generic Counter Counts: + +name: name of the device +parent: optional parent device providing the counters +signal_read: read callback for Signal attribute; may be NULL +signal_write: write callback for Signal attribute; may be NULL +count_read: read callback for Count attribute; may be NULL +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 index + of the respective Count's returned function mode should + be passed back via the function parameter. +function_set: function to set the count function mode. function is the + index of the requested function mode from the respective + Count's functions array. +action_get: function to get the current action mode. Returns 0 on + success and negative error code on error. The index of + the respective Signal's returned action mode should be + passed back via the action parameter. +action_set: function to set the action mode. action is the index of + the requested action mode from the respective Synapse's + actions array. +signals: array of Signals +num_signals: number of Signals specified in @signals +counts: array of Counts +num_counts: number of Counts specified in @counts +ext: optional array of Counter device extensions +num_ext: number of Counter device extensions specified in ext +priv: optional private data supplied by driver + +Registration functions +---------------------- + +A counter device is registered to the system by passing the respective +initialized counter_device structure to the counter_register function; +similarly, the counter_unregister function unregisters the respective +Counter. The devm_counter_register and devm_counter_unregister functions +serve as device memory-managed versions of the counter_register and +counter_unregister functions respectively. + +Implementation +============== + +To support a counter device, a driver must first allocate the available +Counter Signals via counter_signal structures. These Signals should +be stored as an array and set to the signals array member of an +allocated counter_device structure before the Counter is registered to +the system. + +Counter Counts may be allocated via counter_count structures, and +respective Counter Signal associations (Synapses) made via +counter_synapse structures. Associated counter_synapse structures are +stored as an array and set to the the synapses array member of the +respective counter_count structure. These counter_count structures are +set to the counts array member of an allocated counter_device structure +before the Counter is registered to the system. + +Driver callbacks should be provided to the counter_device structure in +order to communicate with the device: to read and write various Signals +and Counts, and to set and get the "action mode" and "function mode" for +various Synapses and Counts respectively. + +A defined counter_device structure may be registered to the system by +passing it to the counter_register function, and unregistered by passing +it to the counter_unregister function. Similarly, the +devm_counter_register and devm_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 counter_device_ext, counter_count_ext, +and counter_signal_ext structures. In these cases, the +counter_device_ext structure is used for global configuration of the +respective Counter device, while the counter_count_ext and +counter_signal_ext structures allow for auxiliary exposure and +configuration of a specific Count or Signal respectively. + +Architecture +============ + +The counter_init function is called when the generic-counter module is +loaded on the system. At this point, a bus_type named "counter" is +registered and a dedicated "counter" chrdev region is allocated; these +are removed and cleaned-up in the counter_exit function called when the +generic-counter module is unloaded from the system. + +Counter devices are registered to the system via the counter_register +function, and later removed via the counter_unregister function. The +counter_register function establishes a unique ID for the Counter device +and creates an associated device node under /dev called counterX, where +X is the mentioned unique ID. A respective sysfs directory is created +for the Counter device with a similar naming scheme: + + /sys/bus/counter/devices/counterX + +Sysfs attributes are created within the counterX directory to expose +functionality, configurations, and data relating to the Counts, Signals, +and Synapses of the Counter device, as well as options and information +for the Counter device itself. + +For a more detailed breakdown of the available Generic Counter interface +sysfs attributes, please refer to the +Documentation/ABI/testing/sys-bus-counter-generic-sysfs file. + +The Signals and Counts associated with the Counter device are registered +to the system as well by the counter_register function. The +signal_read/signal_write driver callbacks are associated to their +respective Signal attributes, while the count_read/count_write and +function_get/function_set driver callbacks are associated to their +respective Count attributes; similarly, the same is true for the +action_get/action_set driver callbacks and their respective Synapse +attributes. If a driver callback is left undefined, then the respective +read/write permission is left disabled for the relevant attributes. + +Similarly, extension sysfs attributes are created for the defined +counter_device_ext, counter_count_ext, and counter_signal_ext +structures that are passed in. diff --git a/Documentation/driver-api/iio/index.rst b/Documentation/driver-api/iio/index.rst index e5c3922d1b6f..e6c5b75c2e03 100644 --- a/Documentation/driver-api/iio/index.rst +++ b/Documentation/driver-api/iio/index.rst @@ -15,3 +15,4 @@ Contents: buffers triggers triggered-buffers + generic-counter diff --git a/MAINTAINERS b/MAINTAINERS index 38da1bc615b3..08eba78057e4 100644 --- a/MAINTAINERS +++ b/MAINTAINERS @@ -3665,6 +3665,7 @@ COUNTER INTERFACE M: William Breathitt Gray L: linux-iio@vger.kernel.org S: Maintained +F: Documentation/driver-api/counter/ F: Documentation/ABI/testing/sysfs-bus-counter-* F: drivers/iio/counter/ F: include/linux/iio/counter.h