On Fri, 27 Aug 2021 12:47:52 +0900 William Breathitt Gray <vilhelm.gray@xxxxxxxxx> wrote: > This patch adds high-level documentation about the Counter subsystem > character device interface. > > Signed-off-by: William Breathitt Gray <vilhelm.gray@xxxxxxxxx> One trivial suggestion inline. This document is very good. Jonathan > --- > Documentation/driver-api/generic-counter.rst | 177 ++++++++++++++---- > .../userspace-api/ioctl/ioctl-number.rst | 1 + > 2 files changed, 137 insertions(+), 41 deletions(-) > > diff --git a/Documentation/driver-api/generic-counter.rst b/Documentation/driver-api/generic-counter.rst > index f6397218aa4c..6ecb5d1942c7 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 > ========== > > @@ -388,16 +375,16 @@ userspace interface components:: > / driver callbacks / > ------------------- > | > - +---------------+ > - | > - V > - +--------------------+ > - | Counter sysfs | > - +--------------------+ > - | Translates to the | > - | standard Counter | > - | sysfs output | > - +--------------------+ > + +---------------+---------------+ > + | | > + V V > + +--------------------+ +---------------------+ > + | Counter sysfs | | Counter chrdev | > + +--------------------+ +---------------------+ > + | Translates to the | | Translates to the | > + | standard Counter | | standard Counter | > + | sysfs output | | character device | > + +--------------------+ +---------------------+ > > Thereafter, data can be transferred directly between the Counter device > driver and Counter userspace interface:: > @@ -428,23 +415,30 @@ driver and Counter userspace interface:: > / u64 / > ---------- > | > - +---------------+ > - | > - V > - +--------------------+ > - | Counter sysfs | > - +--------------------+ > - | Translates to the | > - | standard Counter | > - | sysfs output | > - |--------------------| > - | Type: const char * | > - | Value: "42" | > - +--------------------+ > - | > - --------------- > - / const char * / > - --------------- > + +---------------+---------------+ > + | | > + 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 | > + +--------------------+ +---------------------+ > + | | > + --------------- ----------------------- > + / const char * / / struct counter_event / > + --------------- ----------------------- > + | | > + | V > + | +-----------+ > + | | read | > + | +-----------+ > + | \ Count: 42 / > + | ----------- > | > V > +--------------------------------------------------+ > @@ -453,7 +447,7 @@ driver and Counter userspace interface:: > \ Count: "42" / > -------------------------------------------------- > > -There are three primary components involved: > +There are four primary components involved: > > Counter device driver > --------------------- > @@ -473,3 +467,104 @@ 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 Whilst it is clear when you read on, perhaps change "data" to "Counter events" here. > +is transferred via standard character device read calls, while Counter > +events are configured 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. > +Defines for the standard Counter data types are exposed via the > +userspace ``include/uapi/linux/counter.h`` file. > + > +Counter events > +-------------- > +Counter device drivers can support Counter events by utilizing the > +``counter_push_event`` function:: > + > + void counter_push_event(struct counter_device *const counter, const u8 event, > + const u8 channel); > + > +The event id is specified by the ``event`` parameter; the event channel > +id is specified by the ``channel`` parameter. When this function is > +called, the Counter data associated with the respective event is > +gathered, and a ``struct counter_event`` is generated for each datum and > +pushed to userspace. > + > +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 7 -- the data returned for each is pushed to a > +kfifo as a ``struct counter_event``, which userspace can retrieve via a > +standard read operation on the respective character device node. > + > +Userspace > +--------- > +Userspace applications can configure Counter events via ioctl operations > +on the Counter character device node. There following ioctl codes are > +supported and provided by the ``linux/counter.h`` userspace header file: > + > +* :c:macro:`COUNTER_ADD_WATCH_IOCTL` > + > +* :c:macro:`COUNTER_ENABLE_EVENTS_IOCTL` > + > +* :c:macro:`COUNTER_DISABLE_EVENTS_IOCTL` > + > +To configure events to gather Counter data, users first populate a > +``struct counter_watch`` with the relevant event id, event channel id, > +and the information for the desired Counter component from which to > +read, and then pass it via the ``COUNTER_ADD_WATCH_IOCTL`` ioctl > +command. > + > +Note that an event can be watched without gathering Counter data by > +setting the ``component.type`` member equal to > +``COUNTER_COMPONENT_NONE``. With this configuration the Counter > +character device will simply populate the event timestamps for those > +respective ``struct counter_event`` elements and ignore the component > +value. > + > +The ``COUNTER_ADD_WATCH_IOCTL`` command will buffer these Counter > +watches. When ready, the ``COUNTER_ENABLE_EVENTS_IOCTL`` ioctl command > +may be used to activate these Counter watches. > + > +Userspace applications can then execute a ``read`` operation (optionally > +calling ``poll`` first) on the Counter character device node to retrieve > +``struct counter_event`` elements with the desired data. > diff --git a/Documentation/userspace-api/ioctl/ioctl-number.rst b/Documentation/userspace-api/ioctl/ioctl-number.rst > index 1409e40e6345..fc4ccc79b1b8 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-0F linux/counter.h <mailto:linux-iio@xxxxxxxxxxxxxxx> > '!' 00-1F uapi/linux/seccomp.h > '#' 00-3F IEEE 1394 Subsystem > Block for the entire subsystem
