[PATCH 4/4] docs: counter: Document character device interface
From: William Breathitt Gray
Date: Wed Apr 29 2020 - 14:12:07 EST
This patch adds high-level documentation about the Counter subsystem
character device interface. The 0x3E major number and respective minor
number range is reserved for Counter character device interface ioctl
calls.
Signed-off-by: William Breathitt Gray <vilhelm.gray@xxxxxxxxx>
---
Documentation/driver-api/generic-counter.rst | 87 ++++++++++++-------
.../userspace-api/ioctl/ioctl-number.rst | 1 +
2 files changed, 56 insertions(+), 32 deletions(-)
diff --git a/Documentation/driver-api/generic-counter.rst b/Documentation/driver-api/generic-counter.rst
index 3ab8125b9c05..959c4074078c 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
==========
@@ -409,25 +396,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: unsigned long |
+ | Value: "42" | | Value: 42 |
+ +--------------------+ +---------------------+
| |
- | +---------------+
- | |
- V |
- +--------------------+ |
- | Counter sysfs |<-+
- +--------------------+
- | Translates to the |
- | standard Counter |
- | sysfs output |
- |--------------------|
- | Type: const char * |
- | Value: "42" |
- +--------------------+
- |
- ---------------
- / const char * /
- ---------------
+ --------------- ----------------
+ / const char * / / unsigned long /
+ --------------- ----------------
+ | |
+ | V
+ | +-----------+
+ | | ioctl |
+ | +-----------+
+ | \ Count: 42 /
+ | -----------
|
V
+--------------------------------------------------+
@@ -436,7 +430,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
---------------------
@@ -456,3 +450,32 @@ 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 ioctl 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. Device
+information and control is exposed via a set of standard Counter
+subsystem ioctl commands.
+
+.. kernel-doc:: include/uapi/linux/counter.h
+ :internal:
diff --git a/Documentation/userspace-api/ioctl/ioctl-number.rst b/Documentation/userspace-api/ioctl/ioctl-number.rst
index f759edafd938..8136a26fb81c 100644
--- a/Documentation/userspace-api/ioctl/ioctl-number.rst
+++ b/Documentation/userspace-api/ioctl/ioctl-number.rst
@@ -88,6 +88,7 @@ Code Seq# Include File Comments
<http://infiniband.sourceforge.net/>
0x20 all drivers/cdrom/cm206.h
0x22 all scsi/sg.h
+0x3E 00-1F linux/counter.h <mailto:linux-iio@xxxxxxxxxxxxxxx>
'!' 00-1F uapi/linux/seccomp.h
'#' 00-3F IEEE 1394 Subsystem
Block for the entire subsystem
--
2.26.2