docs: counter: Document character device interface
This patch adds high-level documentation about the Counter subsystem character device interface. Signed-off-by: William Breathitt Gray <vilhelm.gray@gmail.com> Link: https://lore.kernel.org/r/7a71dff2868195901d074ae2ec1b5611838d4b24.1632884256.git.vilhelm.gray@gmail.com Signed-off-by: Jonathan Cameron <Jonathan.Cameron@huawei.com>
This commit is contained in:
William Breathitt Gray
Jonathan Cameron
parent
b6c50affda
commit
a8a28737c2
|
|
@ -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 events to the standard Counter character device; data
|
||||
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.
|
||||
|
|
|
|||
|
|
@ -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@vger.kernel.org>
|
||||
'!' 00-1F uapi/linux/seccomp.h
|
||||
'#' 00-3F IEEE 1394 Subsystem
|
||||
Block for the entire subsystem
|
||||
|
|
|
|||
Loading…
Reference in New Issue