From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org X-Spam-Level: X-Spam-Status: No, score=-15.5 required=3.0 tests=BAYES_00,INCLUDES_CR_TRAILER, INCLUDES_PATCH,MAILING_LIST_MULTI,SPF_HELO_NONE,SPF_PASS,USER_AGENT_SANE_2 autolearn=unavailable autolearn_force=no version=3.4.0 Received: from mail.kernel.org (mail.kernel.org [198.145.29.99]) by smtp.lore.kernel.org (Postfix) with ESMTP id 45E2CC433E0 for ; Sun, 14 Feb 2021 17:49:33 +0000 (UTC) Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by mail.kernel.org (Postfix) with ESMTP id 0F6B064E4E for ; Sun, 14 Feb 2021 17:49:33 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S229788AbhBNRtQ (ORCPT ); Sun, 14 Feb 2021 12:49:16 -0500 Received: from mail.kernel.org ([198.145.29.99]:51160 "EHLO mail.kernel.org" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S229730AbhBNRtH (ORCPT ); Sun, 14 Feb 2021 12:49:07 -0500 Received: from archlinux (cpc108967-cmbg20-2-0-cust86.5-4.cable.virginm.net [81.101.6.87]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by mail.kernel.org (Postfix) with ESMTPSA id 528EC64DA5; Sun, 14 Feb 2021 17:48:23 +0000 (UTC) Date: Sun, 14 Feb 2021 17:48:19 +0000 From: Jonathan Cameron To: William Breathitt Gray Cc: kernel@pengutronix.de, linux-stm32@st-md-mailman.stormreply.com, a.fatoum@pengutronix.de, kamel.bouhara@bootlin.com, gwendal@chromium.org, alexandre.belloni@bootlin.com, david@lechnology.com, linux-iio@vger.kernel.org, linux-kernel@vger.kernel.org, linux-arm-kernel@lists.infradead.org, syednwaris@gmail.com, patrick.havelange@essensium.com, fabrice.gasnier@st.com, mcoquelin.stm32@gmail.com, alexandre.torgue@st.com, o.rempel@pengutronix.de Subject: Re: [PATCH v8 18/22] docs: counter: Document character device interface Message-ID: <20210214174819.6757e2b0@archlinux> In-Reply-To: <350cafba81d3220b64efdb019bd76c08eb1e5d10.1613131238.git.vilhelm.gray@gmail.com> References: <350cafba81d3220b64efdb019bd76c08eb1e5d10.1613131238.git.vilhelm.gray@gmail.com> X-Mailer: Claws Mail 3.17.8 (GTK+ 2.24.33; x86_64-pc-linux-gnu) MIME-Version: 1.0 Content-Type: text/plain; charset=US-ASCII Content-Transfer-Encoding: 7bit Precedence: bulk List-ID: X-Mailing-List: linux-kernel@vger.kernel.org On Fri, 12 Feb 2021 21:13:42 +0900 William Breathitt Gray wrote: > This patch adds high-level documentation about the Counter subsystem > character device interface. > > Signed-off-by: William Breathitt Gray > --- > Documentation/driver-api/generic-counter.rst | 243 +++++++++++++++--- > .../userspace-api/ioctl/ioctl-number.rst | 1 + > 2 files changed, 203 insertions(+), 41 deletions(-) > > diff --git a/Documentation/driver-api/generic-counter.rst b/Documentation/driver-api/generic-counter.rst > index f6397218aa4c..3be109dc81bb 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,170 @@ 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 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 4 -- 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: > + > +* COUNTER_ADD_WATCH_IOCTL: > + Queues a Counter watch for the specified event. The queued watches > + will not be applied until ``COUNTER_ENABLE_EVENTS_IOCTL`` is called. > + > +* COUNTER_ENABLE_EVENTS_IOCTL: > + Enables monitoring the events specified by the Counter watches that > + were queued by ``COUNTER_ADD_WATCH_IOCTL``. If events are already > + enabled, the new set of watches replaces the old one. Calling this > + ioctl also has the effect of clearing the queue of watches added by > + ``COUNTER_ADD_WATCH_IOCTL``. > + > +* COUNTER_DISABLE_EVENTS_IOCTL: > + Stops monitoring the previously enabled events. Is there a way to remove a watch? > + > +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. > + > +For example, the following userspace code opens ``/dev/counter0``, > +configures the ``COUNTER_EVENT_INDEX`` event channel 0 to gather Count 0 > +and Count 1, and prints out the data as it becomes available on the > +character device node:: > + Consider adding an example program under tools/ > + #include > + #include > + #include > + #include > + #include > + #include > + > + struct counter_watch watches[2] = { > + { > + .component.type = COUNTER_COMPONENT_COUNT, > + .component.scope = COUNTER_SCOPE_COUNT, > + .component.parent = 0, Good to add comments on what these elements actually are? > + .event = COUNTER_EVENT_INDEX, > + .channel = 0, > + }, > + { > + .component.type = COUNTER_COMPONENT_COUNT, > + .component.scope = COUNTER_SCOPE_COUNT, > + .component.parent = 1, > + .event = COUNTER_EVENT_INDEX, > + .channel = 0, > + }, > + }; > + > + int main(void) > + { > + int fd; > + struct counter_event event_data[2]; > + > + fd = open("/dev/counter0", O_RDWR); > + > + ioctl(fd, COUNTER_ADD_WATCH_IOCTL, watches); > + ioctl(fd, COUNTER_ADD_WATCH_IOCTL, watches + 1); > + ioctl(fd, COUNTER_ENABLE_EVENTS_IOCTL); > + > + for (;;) { > + read(fd, event_data, sizeof(event_data)); > + > + printf("Timestamp 0: %llu\tCount 0: %llu\n" > + "Error Message 0: %s\n" > + "Timestamp 1: %llu\tCount 1: %llu\n" > + "Error Message 1: %s\n", > + (unsigned long long)event_data[0].timestamp, > + (unsigned long long)event_data[0].value, > + strerror(event_data[0].status), > + (unsigned long long)event_data[1].timestamp, > + (unsigned long long)event_data[1].value, > + strerror(event_data[1].status)); > + } > + > + return 0; > + } > diff --git a/Documentation/userspace-api/ioctl/ioctl-number.rst b/Documentation/userspace-api/ioctl/ioctl-number.rst > index a4c75a28c839..8ddca931ec4e 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 > > 0x20 all drivers/cdrom/cm206.h > 0x22 all scsi/sg.h > +0x3E 00-0F linux/counter.h > '!' 00-1F uapi/linux/seccomp.h > '#' 00-3F IEEE 1394 Subsystem > Block for the entire subsystem From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org X-Spam-Level: X-Spam-Status: No, score=-15.5 required=3.0 tests=BAYES_00,DKIMWL_WL_HIGH, DKIM_SIGNED,DKIM_VALID,INCLUDES_CR_TRAILER,INCLUDES_PATCH,MAILING_LIST_MULTI, SPF_HELO_NONE,SPF_PASS,URIBL_BLOCKED,USER_AGENT_SANE_2 autolearn=unavailable autolearn_force=no version=3.4.0 Received: from mail.kernel.org (mail.kernel.org [198.145.29.99]) by smtp.lore.kernel.org (Postfix) with ESMTP id 281B7C433E0 for ; Sun, 14 Feb 2021 17:49:59 +0000 (UTC) Received: from merlin.infradead.org (merlin.infradead.org [205.233.59.134]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by mail.kernel.org (Postfix) with ESMTPS id 939CF64DA5 for ; Sun, 14 Feb 2021 17:49:57 +0000 (UTC) DMARC-Filter: OpenDMARC Filter v1.3.2 mail.kernel.org 939CF64DA5 Authentication-Results: mail.kernel.org; dmarc=fail (p=none dis=none) header.from=kernel.org Authentication-Results: mail.kernel.org; spf=none smtp.mailfrom=linux-arm-kernel-bounces+linux-arm-kernel=archiver.kernel.org@lists.infradead.org DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=lists.infradead.org; s=merlin.20170209; h=Sender:Content-Transfer-Encoding: Content-Type:Cc:List-Subscribe:List-Help:List-Post:List-Archive: List-Unsubscribe:List-Id:MIME-Version:References:In-Reply-To:Message-ID: Subject:To:From:Date:Reply-To:Content-ID:Content-Description:Resent-Date: Resent-From:Resent-Sender:Resent-To:Resent-Cc:Resent-Message-ID:List-Owner; bh=2XOxN6uBmwTIcLiB9UUd496ZaAzTeYEye7oX2l2pmxc=; b=wBxVB4ER0q2eTqpbz9/CSqNWe 8gMgcpJQSpZ/tvd2+ar1Knkf7wCMUmTAfB3jDOvuHT0C/W87Ze9dLB7aGXX45LwNduigfhM7ns4rw 0h+pLT4xioDoMdpuaqcQ3rvvIT46rr6q3uY3drU7y0w+BVPtjtdiqc0XldNl5RM/6zZBt0p+nxEyi l0ZKYbmva5NRM49iBBXprYcEGm3PIrvsmcVNUV/3O+voMLyMNoDUxy6uXIfQ4MZrrfDl8wlwqWTpJ cwVuQeNmU7zsPmiffG26AsEJV8vQhgYmojMA6xuRg5ZSEAZUhFfOe2yh0JiXSj4v7vf4RHZPQMyMf lwbiZdSng==; Received: from localhost ([::1] helo=merlin.infradead.org) by merlin.infradead.org with esmtp (Exim 4.92.3 #3 (Red Hat Linux)) id 1lBLVW-0005Xc-4W; Sun, 14 Feb 2021 17:48:30 +0000 Received: from mail.kernel.org ([198.145.29.99]) by merlin.infradead.org with esmtps (Exim 4.92.3 #3 (Red Hat Linux)) id 1lBLVT-0005X7-7a for linux-arm-kernel@lists.infradead.org; Sun, 14 Feb 2021 17:48:28 +0000 Received: from archlinux (cpc108967-cmbg20-2-0-cust86.5-4.cable.virginm.net [81.101.6.87]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by mail.kernel.org (Postfix) with ESMTPSA id 528EC64DA5; Sun, 14 Feb 2021 17:48:23 +0000 (UTC) Date: Sun, 14 Feb 2021 17:48:19 +0000 From: Jonathan Cameron To: William Breathitt Gray Subject: Re: [PATCH v8 18/22] docs: counter: Document character device interface Message-ID: <20210214174819.6757e2b0@archlinux> In-Reply-To: <350cafba81d3220b64efdb019bd76c08eb1e5d10.1613131238.git.vilhelm.gray@gmail.com> References: <350cafba81d3220b64efdb019bd76c08eb1e5d10.1613131238.git.vilhelm.gray@gmail.com> X-Mailer: Claws Mail 3.17.8 (GTK+ 2.24.33; x86_64-pc-linux-gnu) MIME-Version: 1.0 X-CRM114-Version: 20100106-BlameMichelson ( TRE 0.8.0 (BSD) ) MR-646709E3 X-CRM114-CacheID: sfid-20210214_124827_459036_88CD0D5C X-CRM114-Status: GOOD ( 39.07 ) X-BeenThere: linux-arm-kernel@lists.infradead.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Cc: kamel.bouhara@bootlin.com, gwendal@chromium.org, a.fatoum@pengutronix.de, david@lechnology.com, linux-iio@vger.kernel.org, patrick.havelange@essensium.com, alexandre.belloni@bootlin.com, mcoquelin.stm32@gmail.com, linux-kernel@vger.kernel.org, o.rempel@pengutronix.de, kernel@pengutronix.de, fabrice.gasnier@st.com, syednwaris@gmail.com, linux-stm32@st-md-mailman.stormreply.com, linux-arm-kernel@lists.infradead.org, alexandre.torgue@st.com Content-Type: text/plain; charset="us-ascii" Content-Transfer-Encoding: 7bit Sender: "linux-arm-kernel" Errors-To: linux-arm-kernel-bounces+linux-arm-kernel=archiver.kernel.org@lists.infradead.org On Fri, 12 Feb 2021 21:13:42 +0900 William Breathitt Gray wrote: > This patch adds high-level documentation about the Counter subsystem > character device interface. > > Signed-off-by: William Breathitt Gray > --- > Documentation/driver-api/generic-counter.rst | 243 +++++++++++++++--- > .../userspace-api/ioctl/ioctl-number.rst | 1 + > 2 files changed, 203 insertions(+), 41 deletions(-) > > diff --git a/Documentation/driver-api/generic-counter.rst b/Documentation/driver-api/generic-counter.rst > index f6397218aa4c..3be109dc81bb 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,170 @@ 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 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 4 -- 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: > + > +* COUNTER_ADD_WATCH_IOCTL: > + Queues a Counter watch for the specified event. The queued watches > + will not be applied until ``COUNTER_ENABLE_EVENTS_IOCTL`` is called. > + > +* COUNTER_ENABLE_EVENTS_IOCTL: > + Enables monitoring the events specified by the Counter watches that > + were queued by ``COUNTER_ADD_WATCH_IOCTL``. If events are already > + enabled, the new set of watches replaces the old one. Calling this > + ioctl also has the effect of clearing the queue of watches added by > + ``COUNTER_ADD_WATCH_IOCTL``. > + > +* COUNTER_DISABLE_EVENTS_IOCTL: > + Stops monitoring the previously enabled events. Is there a way to remove a watch? > + > +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. > + > +For example, the following userspace code opens ``/dev/counter0``, > +configures the ``COUNTER_EVENT_INDEX`` event channel 0 to gather Count 0 > +and Count 1, and prints out the data as it becomes available on the > +character device node:: > + Consider adding an example program under tools/ > + #include > + #include > + #include > + #include > + #include > + #include > + > + struct counter_watch watches[2] = { > + { > + .component.type = COUNTER_COMPONENT_COUNT, > + .component.scope = COUNTER_SCOPE_COUNT, > + .component.parent = 0, Good to add comments on what these elements actually are? > + .event = COUNTER_EVENT_INDEX, > + .channel = 0, > + }, > + { > + .component.type = COUNTER_COMPONENT_COUNT, > + .component.scope = COUNTER_SCOPE_COUNT, > + .component.parent = 1, > + .event = COUNTER_EVENT_INDEX, > + .channel = 0, > + }, > + }; > + > + int main(void) > + { > + int fd; > + struct counter_event event_data[2]; > + > + fd = open("/dev/counter0", O_RDWR); > + > + ioctl(fd, COUNTER_ADD_WATCH_IOCTL, watches); > + ioctl(fd, COUNTER_ADD_WATCH_IOCTL, watches + 1); > + ioctl(fd, COUNTER_ENABLE_EVENTS_IOCTL); > + > + for (;;) { > + read(fd, event_data, sizeof(event_data)); > + > + printf("Timestamp 0: %llu\tCount 0: %llu\n" > + "Error Message 0: %s\n" > + "Timestamp 1: %llu\tCount 1: %llu\n" > + "Error Message 1: %s\n", > + (unsigned long long)event_data[0].timestamp, > + (unsigned long long)event_data[0].value, > + strerror(event_data[0].status), > + (unsigned long long)event_data[1].timestamp, > + (unsigned long long)event_data[1].value, > + strerror(event_data[1].status)); > + } > + > + return 0; > + } > diff --git a/Documentation/userspace-api/ioctl/ioctl-number.rst b/Documentation/userspace-api/ioctl/ioctl-number.rst > index a4c75a28c839..8ddca931ec4e 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 > > 0x20 all drivers/cdrom/cm206.h > 0x22 all scsi/sg.h > +0x3E 00-0F linux/counter.h > '!' 00-1F uapi/linux/seccomp.h > '#' 00-3F IEEE 1394 Subsystem > Block for the entire subsystem _______________________________________________ linux-arm-kernel mailing list linux-arm-kernel@lists.infradead.org http://lists.infradead.org/mailman/listinfo/linux-arm-kernel