[PATCH v15 07/13] docs: counter: Document character device interface

[Jonathan Cameron]

On Mon,  9 Aug 2021 21:37:32 +0900
William Breathitt Gray <vilhelm.gray at gmail.com> wrote:

> This patch adds high-level documentation about the Counter subsystem
> character device interface.
> 
> Signed-off-by: William Breathitt Gray <vilhelm.gray at gmail.com>

Hi William,

Trivial probable typo inline.

I'm struggling somewhat with these interfaces because I simply don't know
enough about how people use counters to know whether they provide everything
people will want. They feel similar to the event handling type functions you
can set up in motor drives, so they may well make sense, but ideally
we need review from someone (other than yourself!) who actually uses this
stuff on a regular basis.

If we don't get any additional review I guess we go ahead anyway
next cycle.

Jonathan

> ---

> +
> +Counter events can be configured by users to report various Counter
> +data of interest. This can be conceptualized as a list of Counter
> +component read calls to perform. For example:
> +
> +        +-------------------------------------------------+
> +        | COUNTER_EVENT_OVERFLOW | COUNTER_EVENT_INDEX    |
> +        +========================+========================+
> +        | Channel 0              | Channel 0              |
> +        +------------------------+------------------------+
> +        | * Count 0              | * Signal 0             |
> +        | * Count 1              | * Signal 0 Extension 0 |
> +        | * Signal 3             | * Extension 4          |
> +        | * Count 4 Extension 2  +------------------------+
> +        | * Signal 5 Extension 0 | Channel 1              |
> +        |                        +------------------------+
> +        |                        | * Signal 4             |
> +        |                        | * Signal 4 Extension 0 |
> +        |                        | * Count 7              |
> +        +------------------------+------------------------+
> +
> +When ``counter_push_event(counter, COUNTER_EVENT_INDEX, 1)`` is called
> +for example, it will go down the list for the ``COUNTER_EVENT_INDEX``
> +event channel 1 and execute the read callbacks for Signal 4, Signal 4
> +Extension 0, and Count 4 -- the data returned for each is pushed to a

Count 7?

> +kfifo as a ``struct counter_event``, which userspace can retrieve via a
> +standard read operation on the respective character device node.
> +

>                                                                       Block for the entire subsystem