[PATCH v2 4/4] docs: counter: Document character device interface
From: William Breathitt Gray
Date: Sat May 16 2020 - 15:20:53 EST
This patch adds high-level documentation about the Counter subsystem
character device interface.
Signed-off-by: William Breathitt Gray <vilhelm.gray@xxxxxxxxx>
---
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.
--
2.26.2