Received-SPF: pass (google.com: domain of linux-kernel-owner@vger.kernel.org designates 23.128.96.18 as permitted sender) client-ip=23.128.96.18;
Subject: Re: [PATCH v7 4/5] docs: counter: Document character device interface
To:     William Breathitt Gray <vilhelm.gray@gmail.com>, jic23@kernel.org
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,
        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
References: <cover.1608935587.git.vilhelm.gray@gmail.com>
 <1e69b7beae4cf352bddb379220d0d52b20db0634.1608935587.git.vilhelm.gray@gmail.com>
From:   David Lechner <david@lechnology.com>
Message-ID: <416fe56e-bfb3-3f46-7f03-17009fa27dee@lechnology.com>
Date:   Wed, 30 Dec 2020 12:18:48 -0600
User-Agent: Mozilla/5.0 (X11; Linux x86_64; rv:68.0) Gecko/20100101
 Thunderbird/68.10.0
MIME-Version: 1.0
In-Reply-To: <1e69b7beae4cf352bddb379220d0d52b20db0634.1608935587.git.vilhelm.gray@gmail.com>
Content-Type: text/plain; charset=utf-8; format=flowed
Content-Language: en-US
Content-Transfer-Encoding: 7bit
Precedence: bulk

On 12/25/20 6:15 PM, William Breathitt Gray wrote:

> +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_CLEAR_WATCHES_IOCTL:
> +  Clear all Counter watches from all events
> +
> +* COUNTER_ADD_WATCH_IOCTL:
> +  Add a Counter watch for the specified event
> +
> +* COUNTER_LOAD_WATCHES_IOCTL:
> +  Activates the Counter watches added earlier

Would it make more sense to call the last and first ones
COUNTER_ENABLE_EVENTS_IOCTL and COUNTER_DISABLE_EVENTS_IOCTL?
In any case, more explanation would be helpful.

* 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.

> +
> +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.

for restructured text, two backticks are needed for ``code`` formatting