[PATCH v8 18/22] docs: counter: Document character device interface

[William Breathitt Gray]

On Mon, Feb 22, 2021 at 11:11:33AM +0100, Pavel Machek wrote:
> Hi!
> 
> > > +* 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? 
> 
> Is there a way to eat all kernel memory and crash the system by adding
> too many watches?

There can only ever be as many watches as there are Counter components
for the respective Counter device. This is enforced by
counter_set_event_node() which checks whether a particular watch has
been created before and returns an EINVAL if it so has.

> > > +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 <fcntl.h>
> > > +        #include <linux/counter.h>
> > > +        #include <stdio.h>
> > > +        #include <string.h>
> > > +        #include <sys/ioctl.h>
> > > +        #include <unistd.h>
> > > +
> > > +        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?
> 
> > > +                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));
> 
> If this goes to tools it really should have error handling and
> handling of short read.
> 
> Best regards,
> 							Pavel
> 
> -- 
> http://www.livejournal.com/~pavelmachek

Ack. I'll improve the error handling for this.

William Breathitt Gray
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 833 bytes
Desc: not available
URL: <http://lists.infradead.org/pipermail/linux-arm-kernel/attachments/20210226/fefe1627/attachment-0001.sig>