Re: [PATCH v8 09/12] user_events: Add documentation file

[Beau Belgrave]

On Wed, Dec 22, 2021 at 11:18:34PM +0900, Masami Hiramatsu wrote:
> Hi Beau,
> 
> On Thu, 16 Dec 2021 09:35:08 -0800
> Beau Belgrave <beaub@xxxxxxxxxxxxxxxxxxx> wrote:
> 
> > Add a documentation file about user_events with example code, etc.
> > explaining how it may be used.
> > 
> > Signed-off-by: Beau Belgrave <beaub@xxxxxxxxxxxxxxxxxxx>
> > ---
> >  Documentation/trace/index.rst       |   1 +
> >  Documentation/trace/user_events.rst | 195 ++++++++++++++++++++++++++++
> >  2 files changed, 196 insertions(+)
> >  create mode 100644 Documentation/trace/user_events.rst
> > 
> > diff --git a/Documentation/trace/index.rst b/Documentation/trace/index.rst
> > index 3769b9b7aed8..3a47aa8341c6 100644
> > --- a/Documentation/trace/index.rst
> > +++ b/Documentation/trace/index.rst
> > @@ -30,3 +30,4 @@ Linux Tracing Technologies
> >     stm
> >     sys-t
> >     coresight/index
> > +   user_events
> > diff --git a/Documentation/trace/user_events.rst b/Documentation/trace/user_events.rst
> > new file mode 100644
> > index 000000000000..36104b537476
> > --- /dev/null
> > +++ b/Documentation/trace/user_events.rst
> > @@ -0,0 +1,195 @@
> > +=========================================
> > +user_events: User-based Event Tracing
> > +=========================================

[..]

> > +Registering
> > +-----------
> > +Registering within a user process is done via ioctl() out to the
> > +/sys/kernel/debug/tracing/user_events_data file. The command to issue is
> > +DIAG_IOCSREG. This command takes a struct user_reg as an argument.
> > +
> 
> Could you add the user_reg data structure here?
> 

Sure thing.

> > +The struct user_reg requires two values, the first is the size of the structure
> > +to ensure forward and backward compatibility. The second is the command string
> > +to issue for registering.
> 
> This explanation may be a bit out of date? 
> user_reg has 4 fields. 2 for input, 2 for output.
> 

Yeah, it only requires 2 inputs to work. I'll try to make this clearer.

> And could you add a section for DIAG_IOCSDEL?
> 

Sure thing.

> > +
> > +User based events show up under tracefs like any other event under the
> > +subsystem named "user_events". This means tools that wish to attach to the
> > +events need to use /sys/kernel/debug/tracing/events/user_events/[name]/enable
> > +or perf record -e user_events:[name] when attaching/recording.
> > +
> > +**NOTE:** *The write_index returned is only valid for the FD that was used*
> > +

[..]

> > +Example Code
> > +------------
> > +See sample code in samples/user_events.
> 
> Maybe tools/testing/selftests/user_events ?
> 

Previously I was asked to put the sample code in samples/user_events, so
it lives there.

Thanks,
-Beau