[PATCH v5 0/3] Simplify count_read/count_write/signal_read

From: William Breathitt Gray
Date: Sun Oct 06 2019 - 16:03:49 EST


Changes in v5:
- Add changes and additions to generic-counter.rst to clarify theory
and use of the Generic Counter interface
- Fix typo in counter.h action_get description comment

The changes in this patchset will not affect the userspace interface.
Rather, these changes are intended to simplify the kernelspace Counter
callbacks for counter device driver authors.

The following main changes are proposed:

* Retire the opaque counter_count_read_value/counter_count_write_value
structures and simply represent count data as an unsigned integer.

* Retire the opaque counter_signal_read_value structure and represent
Signal data as a counter_signal_value enum.

These changes should reduce some complexity and code in the use and
implementation of the count_read, count_write, and signal_read
callbacks.

The opaque structures for Count data and Signal data were introduced
originally in anticipation of supporting various representations of
counter data (e.g. arbitrary-precision tallies, floating-point spherical
coordinate positions, etc). However, with the counter device drivers
that have appeared, it's become apparent that utilizing opaque
structures in kernelspace is not the best approach to take.

I believe it is best to let userspace applications decide how to
interpret the count data they receive. There are a couple of reasons why
it would be good to do so:

* Users use their devices in unexpected ways.

For example, a quadrature encoder counter device is typically used to
keep track of the position of a motor, but a user could set the device
in a pulse-direction mode and instead use it to count sporadic rising
edges from an arbitrary signal line unrelated to positioning. Users
should have the freedom to decide what their data represents.

* Most counter devices represent data as unsigned integers anyway.

For example, whether the device is a tally counter or position
counter, the count data is represented to the user as an unsigned
integer value. So specifying that one device is representing tallies
while the other specifies positions does not provide much utility from
an interface perspective.

For these reasons, the count_read and count_write callbacks have been
redefined to pass count data directly as unsigned long instead of passed
via opaque structures:

count_read(struct counter_device *counter,
struct counter_count *count, unsigned long *val);
count_write(struct counter_device *counter,
struct counter_count *count, unsigned long val);

Similarly, the signal_read is redefined to pass Signal data directly as
a counter_signal_value enum instead of via an opaque structure:

signal_read(struct counter_device *counter,
struct counter_signal *signal,
enum counter_signal_value *val);

The counter_signal_value enum is simply the counter_signal_level enum
redefined to remove the references to the Signal data "level" data type.

William Breathitt Gray (3):
counter: Simplify the count_read and count_write callbacks
docs: driver-api: generic-counter: Update Count and Signal data types
counter: Fix typo in action_get description

Documentation/driver-api/generic-counter.rst | 162 +++++++++++--------
drivers/counter/104-quad-8.c | 33 ++--
drivers/counter/counter.c | 101 ++----------
drivers/counter/ftm-quaddec.c | 14 +-
drivers/counter/stm32-lptimer-cnt.c | 5 +-
drivers/counter/stm32-timer-cnt.c | 17 +-
drivers/counter/ti-eqep.c | 19 +--
include/linux/counter.h | 76 ++-------
8 files changed, 144 insertions(+), 283 deletions(-)


base-commit: 0c3aa63a842d84990bd02622f2fa50d2bd33c652
prerequisite-patch-id: ebe284609b3db8d4130ea2915f7f7b185c743a70
prerequisite-patch-id: cbe857759f10d875690df125d18bc04f585ac7c9
prerequisite-patch-id: 21f2660dc88627387ee4666d08044c63dd961dae
--
2.23.0