[PATCH v3 4/4] docs: counter: Document character device interface
From: William Breathitt Gray
Date: Tue Jun 16 2020 - 21:41:02 EST
This patch adds high-level documentation about the Counter subsystem
character device interface.
Signed-off-by: William Breathitt Gray <vilhelm.gray@xxxxxxxxx>
---
Documentation/ABI/testing/sysfs-bus-counter | 31 +++++
Documentation/driver-api/generic-counter.rst | 132 ++++++++++++++-----
2 files changed, 127 insertions(+), 36 deletions(-)
diff --git a/Documentation/ABI/testing/sysfs-bus-counter b/Documentation/ABI/testing/sysfs-bus-counter
index 566bd99fe0a5..8533a8732544 100644
--- a/Documentation/ABI/testing/sysfs-bus-counter
+++ b/Documentation/ABI/testing/sysfs-bus-counter
@@ -193,6 +193,37 @@ Description:
both edges:
Any state transition.
+What: /sys/bus/counter/devices/counterX/chrdev_format
+KernelVersion: 5.9
+Contact: linux-iio@xxxxxxxxxxxxxxx
+Description:
+ Data format of the respective character device node of the
+ Counter. Reading this attribute returns the current data format
+ of the respective character device node; writing to this
+ attribute sets the current data format of the respective
+ character device node. This attribute interfaces via the
+ following format:
+
+ Components/extensions are specified by a character identifier
+ and an index offset; whitespace serves as delimiters. The
+ following character identifiers are supported:
+
+ C: Count
+ S: Signal
+ E: Extension
+ A: Synapse Action
+ F: Count Function
+
+ Count/Signal extensions may be specified by first specifying the
+ respective owning component then the desired extension
+ immediately following without delimiting whitespace; Synapse
+ Action and Count Function are specified in a similar manner.
+
+ For example, "C4 C2E6 C0F S7E1 C3A4 S5" would specify the
+ following data format: Count 4, Count 2's Extension 6, Count 0's
+ Count Function, Signal 7's Extension 1, Count 3's Synapse Action
+ 4, Signal 5.
+
What: /sys/bus/counter/devices/counterX/name
KernelVersion: 5.2
Contact: linux-iio@xxxxxxxxxxxxxxx
diff --git a/Documentation/driver-api/generic-counter.rst b/Documentation/driver-api/generic-counter.rst
index 8aaa6cd37fd4..d46ce65d1488 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
==========
@@ -378,13 +365,13 @@ driver is exemplified by the following::
+----------------------------+ |
| Processes data from device | -------------------
|----------------------------| / driver callbacks /
- | Type: unsigned long | -------------------
+ | Type: u64 | -------------------
| Value: 42 | |
+----------------------------+ |
| |
- ---------------- |
- / unsigned long / |
- ---------------- |
+ ---------- |
+ / u64 / |
+ ---------- |
| |
| V
| +----------------------+
@@ -399,25 +386,32 @@ driver is 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
+--------------------------------------------------+
@@ -426,7 +420,7 @@ driver is exemplified by the following::
\ Count: "42" /
--------------------------------------------------
-There are three primary components involved:
+There are four primary components involved:
Counter device driver
---------------------
@@ -446,3 +440,69 @@ 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.
+
+A `/sys/bus/counter/devices/counterX/chrdev_format` sysfs attribute is
+available to expose the character device data format.
+
+Users may write to this sysfs attribute to select the components they
+want to interface -- the layout can be determined as well from the
+order. For example::
+
+# echo "C0 C3 C2" > /sys/bus/counter/devices/counter0/chrdev_format
+
+This would select Counts 0, 3, and 2 (in that order) to be available
+in the `/dev/counter0` node as a contiguous memory region.
+
+Users can select extensions in a similar fashion::
+
+# echo "C4E2 S1E0" > /sys/bus/counter/devices/counter0/chrdev_format
+
+This would select extension 2 from Count 4, and extension 0 from
+Signal 1.
+
+Users may read from this `chrdev_format` sysfs attribute in order to see
+the currently configured format of the character device.
+
+Users may perform read/write operations on the `/dev/counterX` node
+directly; the layout of the data is what they user has configured via
+the chrdev_format sysfs attribute. For example::
+
+# echo "C0 C1 S0 S1" > /sys/bus/counter/devices/counter0/chrdev_format
+
+Yields the following `/dev/counter0` memory layout::
+
+ +-----------------+------------------+----------+----------+
+ | Byte 0 - Byte 7 | Byte 8 - Byte 15 | Byte 16 | Byte 17 |
+ +-----------------+------------------+----------+----------+
+ | Count 0 | Count 1 | Signal 0 | Signal 2 |
+ +-----------------+------------------+----------+----------+
+
+The number of bytes allotted for each component or extension is
+determined by its respective data type: u8 will have 1 byte allotted,
+u64 will have 8 bytes allotted, etc.
--
2.26.2