[PATCH v7 00/10] Introduce the Counter subsystem

[William Breathitt Gray]

Changes in v7:
 - Use git-format-patch "-M" switch option to format renames properly
   (apologies to Jonathan for reviewing delete/add pairs in past revs)
 - Remove superfluous license boilerplate in favor of SPDX lines
 - Rename functions to match <noun>_<action> naming convention; e.g.
   signal_read_value_set, count_read_value_set, etc.
 - Rename COUNT_POSITION_UNSIGNED to COUNT_POSITION, and remove
   COUNT_POSITION_SIGNED
 - Inline local variables that are only used once
 - Remove COUNT_FUNCTION_QUADRATURE_X2_RISING and
   COUNT_FUNCTION_QUADRATURE_X2_FALLING; these can be reintroduced when
   a practical use-case is determined
 - Explicitly free allocated attribute pointers on error in
   counter_device_groups_prepare
 - Remove pretty tab alignment for symbol declarations in counter.h
 - Fix kernel-doc syntax typos ("groups_list" and "groups" missing ':')
 - Clarify in kernel-doc comments the use of "val" parameter for the
   signal_read, count_read, and count_write callbacks
 - Cleanup Generic Counter attributes documentation (explain preset
   registers, remove superfluous text, etc.)
 - Cleanup Generic Counter driver API documentation (improve formatting
   by reorganizing options into intended sections, fix typos, etc.)
 - Utilize register defines to remove dependence on magic numbers in
   104-QUAD-8 counter driver
 - Update Kconfig description for the 104-QUAD-8 counter driver to
   describe its Generic Counter interface
 - Remove "mode" wording from STM32 Timer dt-bindings documentation;
   STM32 Timer features a proper quadrature encoder counter device
 - Fix typo in STM32 Timer documentation: IN1/IN2 pins are CH1/CH2 pins

Hi Greg,

This patchset is stabilizing so I hope you can take a look over it and
advise. This patchset introduces the Counter subsystem and the Generic
Counter driver API.

Last year, the STM32 LPTimer IIO driver authored by Fabrice Gasnier
opened up a discussion about the architecture of the IIO Counter
interface. The IIO Counter interface was developed to provide support
for the 104-QUAD-8 IIO driver -- several new IIO attributes were
implemented to support the functionality of the 104-QUAD-8 device. When
the STM32 LPTimer IIO driver was introduced, it too attempted to utilize
the IIO Counter interface to support the counter functionality of the
STM32 LPTimer device.

However, there were some difficulties with the IIO Counter interface.
For example, the 104-QUAD-8 device features a pulse-direction counter
and quadrature encoder counter (which can be toggled via the
quadrature_mode attribute), as well as three quadrature encoder modes
(x1, x2, and x4) which are set via the existing IIO scale attribute.
While this method works for the 104-QUAD-8, the STM32 LPTimer featured a
slightly different Quadrature x2 mode with different state machine
behavior -- as such there is ambiguity over what behavior "quadrature
x2" represents in the IIO Counter interface.

I decided to strip down these devices to arrive at the core essence of
what constitutes a "counter device" and therefore design a "generic
counter" abstraction to better represent these devices and prevent the
ambiguity we discovered with the existing IIO Counter interface. This
abstraction became the Generic Counter paradigm, which is explained in
detail within the Documentation/driver-api/generic-counter.rst file
introduced by this patchset.

Initially we attempted to further extend the IIO Counter interface in
order to integrate the Generic Counter API as part of the IIO subsystem,
but the outcome wasn't as clean as we desired. The results of our
efforts proved to grow increasingly complicated, sparsed with hacks, and
more often than not fought with the IIO subsystem rather than
complemented it. I decided to separate the Generic Counter API from the
IIO subsystem, and give it its own Counter subsystem in which to reside.
This allowed us to streamline development and avoid jeopardizing the
integrity of the IIO subsystem (we no longer have to bend the IIO API to
support our needs, but can instead implement the necessary
functionalities in the Counter subsystem as required).

The Counter subsystem has three consuming drivers thus far: two ported
from the IIO subsystem (104-QUAD-8 and STM32 LPTimer counter) and one
unique to the Counter subsystem (STM32 Timer counter). In userspace, the
Generic Counter interface is rather intuitive:

    * /sys/bus/counter/devices/
      - enumerated directories for counter devices
    * /sys/bus/counter/devices/counterX/
      - attributes for counterX where X is the enumeration ID
    * /sys/bus/counter/devices/counterX/signalY
      - attributes for signal Y where Y is the enumeration ID
    * /sys/bus/counter/devices/counterX/countY
      - attributes for count Y where Y is the enumeration ID

Although at this point the Counter subsystem is functionally separate
from the IIO subsystem, I believe it would be prudent to merge this
introduction patchset via the IIO tree due to the historical context of
these counter drivers and the development of this patchset. Are there
any additions or changes you believe I should make to this patchset
going forward?

Sincerely,

William Breathitt Gray

Benjamin Gaignard (2):
  counter: Add STM32 Timer quadrature encoder
  dt-bindings: counter: Document stm32 quadrature encoder

Fabrice Gasnier (2):
  counter: stm32-lptimer: add counter device
  dt-bindings: counter: Adjust dt-bindings for STM32 lptimer move

William Breathitt Gray (6):
  counter: Introduce the Generic Counter interface
  counter: Documentation: Add Generic Counter sysfs documentation
  docs: Add Generic Counter interface documentation
  counter: 104-quad-8: Add Generic Counter interface support
  counter: 104-quad-8: Documentation: Add Generic Counter sysfs
    documentation
  iio: counter: Add deprecation markings for IIO Counter attributes

 Documentation/ABI/testing/sysfs-bus-counter   |  230 +++
 .../ABI/testing/sysfs-bus-counter-104-quad-8  |   36 +
 Documentation/ABI/testing/sysfs-bus-iio       |    8 +
 .../testing/sysfs-bus-iio-counter-104-quad-8  |   16 +
 .../{iio => }/counter/stm32-lptimer-cnt.txt   |    0
 .../bindings/counter/stm32-timer-cnt.txt      |   31 +
 .../devicetree/bindings/mfd/stm32-lptimer.txt |    2 +-
 .../devicetree/bindings/mfd/stm32-timers.txt  |    7 +
 Documentation/driver-api/generic-counter.rst  |  342 ++++
 Documentation/driver-api/index.rst            |    1 +
 MAINTAINERS                                   |   14 +-
 drivers/Kconfig                               |    2 +
 drivers/Makefile                              |    1 +
 drivers/{iio => }/counter/104-quad-8.c        |  782 ++++++++-
 drivers/counter/Kconfig                       |   59 +
 drivers/{iio => }/counter/Makefile            |    6 +-
 drivers/counter/generic-counter.c             | 1519 +++++++++++++++++
 drivers/{iio => }/counter/stm32-lptimer-cnt.c |  361 +++-
 drivers/counter/stm32-timer-cnt.c             |  390 +++++
 drivers/iio/Kconfig                           |    1 -
 drivers/iio/Makefile                          |    1 -
 drivers/iio/counter/Kconfig                   |   34 -
 include/linux/counter.h                       |  534 ++++++
 23 files changed, 4292 insertions(+), 85 deletions(-)
 create mode 100644 Documentation/ABI/testing/sysfs-bus-counter
 create mode 100644 Documentation/ABI/testing/sysfs-bus-counter-104-quad-8
 rename Documentation/devicetree/bindings/{iio => }/counter/stm32-lptimer-cnt.txt (100%)
 create mode 100644 Documentation/devicetree/bindings/counter/stm32-timer-cnt.txt
 create mode 100644 Documentation/driver-api/generic-counter.rst
 rename drivers/{iio => }/counter/104-quad-8.c (44%)
 create mode 100644 drivers/counter/Kconfig
 rename drivers/{iio => }/counter/Makefile (52%)
 create mode 100644 drivers/counter/generic-counter.c
 rename drivers/{iio => }/counter/stm32-lptimer-cnt.c (48%)
 create mode 100644 drivers/counter/stm32-timer-cnt.c
 delete mode 100644 drivers/iio/counter/Kconfig
 create mode 100644 include/linux/counter.h

-- 
2.17.1