Re: [PATCH v2 4/4] docs: counter: Document character device interface

[Jonathan Cameron <jic23@kernel.org>]

On Sat, 16 May 2020 15:20:02 -0400
William Breathitt Gray <vilhelm.gray@gmail.com> wrote:

> This patch adds high-level documentation about the Counter subsystem
> character device interface.
> 
> Signed-off-by: William Breathitt Gray <vilhelm.gray@gmail.com>
> ---
>  Documentation/driver-api/generic-counter.rst | 112 +++++++++++++------
>  1 file changed, 76 insertions(+), 36 deletions(-)
> 
> diff --git a/Documentation/driver-api/generic-counter.rst b/Documentation/driver-api/generic-counter.rst
> index 8f85c30dea0b..58045b33b576 100644
> --- a/Documentation/driver-api/generic-counter.rst
> +++ b/Documentation/driver-api/generic-counter.rst
> @@ -223,19 +223,6 @@ whether an input line is differential or single-ended) and instead focus
>  on the core idea of what the data and process represent (e.g. position
>  as interpreted from quadrature encoding data).
>  
> -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/sysfs-bus-counter 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
>  ==========
>  
> @@ -377,13 +364,13 @@ driver can be exemplified by the following::
>                  +----------------------------+          |
>                  | Processes data from device |   -------------------
>                  |----------------------------|  / driver callbacks /
> -                | Type: unsigned long        |  -------------------
> +                | Type: u64                  |  -------------------
>                  | Value: 42                  |          |
>                  +----------------------------+          |
>                          |                               |
> -                 ----------------                       |
> -                / unsigned long /                       |
> -                ----------------                        |
> +                 ----------                             |
> +                / u64     /                             |
> +                ----------                              |
>                          |                               |
>                          |                               V
>                          |               +----------------------+
> @@ -398,25 +385,32 @@ driver can be exemplified by the following::
>                          |               / driver callbacks /
>                          |               -------------------
>                          |                       |
> -                +-------+                       |
> +                +-------+---------------+       |
> +                |                       |       |
> +                |               +-------|-------+
> +                |               |       |
> +                V               |       V
> +        +--------------------+  |  +---------------------+
> +        | Counter sysfs      |<-+->| Counter chrdev      |
> +        +--------------------+     +---------------------+
> +        | Translates to the  |     | Translates to the   |
> +        | standard Counter   |     | standard Counter    |
> +        | sysfs output       |     | character device    |
> +        |--------------------|     |---------------------+
> +        | Type: const char * |     | Type: u64           |
> +        | Value: "42"        |     | Value: 42           |
> +        +--------------------+     +---------------------+
>                  |                               |
> -                |               +---------------+
> -                |               |
> -                V               |
> -        +--------------------+  |
> -        | Counter sysfs      |<-+
> -        +--------------------+
> -        | Translates to the  |
> -        | standard Counter   |
> -        | sysfs output       |
> -        |--------------------|
> -        | Type: const char * |
> -        | Value: "42"        |
> -        +--------------------+
> -                |
> -         ---------------
> -        / const char * /
> -        ---------------
> +         ---------------                 ----------
> +        / const char * /                / u64     /
> +        ---------------                 ----------
> +                |                               |
> +                |                               V
> +                |                       +-----------+
> +                |                       | read      |
> +                |                       +-----------+
> +                |                       \ Count: 42 /
> +                |                        -----------
>                  |
>                  V
>          +--------------------------------------------------+
> @@ -425,7 +419,7 @@ driver can be exemplified by the following::
>          \ Count: "42"                                      /
>           --------------------------------------------------
>  
> -There are three primary components involved:
> +There are four primary components involved:
>  
>  Counter device driver
>  ---------------------
> @@ -445,3 +439,49 @@ and vice versa.
>  Please refer to the `Documentation/ABI/testing/sysfs-bus-counter` file
>  for a detailed breakdown of the available Generic Counter interface
>  sysfs attributes.
> +
> +Counter chrdev
> +--------------
> +Translates counter data to the standard Counter character device; data
> +is transferred via standard character device read/write calls.
> +
> +Sysfs Interface
> +===============
> +
> +Several sysfs attributes are generated by the Generic Counter interface,
> +and reside under the `/sys/bus/counter/devices/counterX` directory,
> +where `X` is to the respective counter device id. Please see
> +Documentation/ABI/testing/sysfs-bus-counter 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.
> +
> +Counter Character Device
> +========================
> +
> +Counter character device nodes are created under the `/dev` directory as
> +`counterX`, where `X` is the respective counter device id. Defines for
> +the standard Counter data types are exposed via the userspace
> +`include/uapi/linux/counter-types.h` file.
> +
> +The first 196095 bytes of the character device serve as a control
> +selection area where control exposure of desired Counter components and
> +extensions may be selected. Each byte serves as a boolean selection
> +indicator for a respective Counter component or extension. The format of
> +this area is as follows:
> +
> +* For each device extension, a byte is required.
> +* For each Signal, a byte is reserved for the Signal component, and a
> +  byte is reserved for each Signal extension.
> +* For each Count, a byte is reserved for the Count component, a byte is
> +  reserved for the count function, a byte is reserved for each Synapse
> +  action, and byte is reserved for each Count extension.
> +
> +The selected Counter components and extensions may then be interfaced
> +after the first 196095 bytes via standard character device read/write
> +operations. The number of bytes available for each component or
> +extension is dependent on their respective data type: u8 will have 1
> +byte available, u64 will have 8 bytes available, strings will have 64
> +bytes available, etc.

From what I recall of the earlier conversation, I'm not sure this is what
was being suggested.  I 'think' what people were after was a simple
read interface for just the counters  (+ timestamps). This would also
include the option to use select / poll on the counter.

Simply moving over to a read / write really doesn't help for ease of use.
I'm not sure what the right control approach is, or perhaps if we even
need one (could just output all counts provided by hardware once the
chrdev is opened). 

Jonathan