linux-kernel - Re: [PATCH v14 4/4] Documentation: trace/objtrace: Add documentation for objtrace

lists.openwall.net		lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC
Open Source and information security mailing list archives
Hash Suite: Windows password security audit tool. GUI, reports in PDF.
[<prev] [next>] [<thread-prev] [day] [month] [year] [list]
Message-ID: <CAEXW_YTJGbGWZkmCndVqXaM=N_6ZuvmcxDrcgTaHjCEMyvXeuQ@mail.gmail.com>
Date:   Thu, 18 Aug 2022 14:55:47 -0400
From:   Joel Fernandes <joel@...lfernandes.org>
To:     Jeff Xie <xiehuan09@...il.com>
Cc:     Steven Rostedt <rostedt@...dmis.org>,
        Ingo Molnar <mingo@...hat.com>,
        Masami Hiramatsu <mhiramat@...nel.org>,
        Tom Zanussi <zanussi@...nel.org>,
        LKML <linux-kernel@...r.kernel.org>, chensong_2000@....cn,
        Jonathan Corbet <corbet@....net>,
        Bagas Sanjaya <bagasdotme@...il.com>,
        "open list:DOCUMENTATION" <linux-doc@...r.kernel.org>
Subject: Re: [PATCH v14 4/4] Documentation: trace/objtrace: Add documentation
 for objtrace

On Thu, Aug 18, 2022 at 1:34 PM Jeff Xie <xiehuan09@...il.com> wrote:
>
> Hi Joel,
>
> On Fri, Aug 19, 2022 at 1:05 AM Joel Fernandes <joel@...lfernandes.org> wrote:
> >
> > On Thu, Aug 18, 2022 at 12:38 PM Jeff Xie <xiehuan09@...il.com> wrote:
> > >
> > > Hi Joel,
> > >
> > > Thank you for your review.
> > >
> > > On Thu, Aug 18, 2022 at 11:53 PM Joel Fernandes <joel@...lfernandes.org> wrote:
> > > >
> > > > On Tue, Jun 28, 2022 at 10:55:52PM +0800, Jeff Xie wrote:
> > > > > Add documentation explaining how to use objtrace trigger to get the value
> > > > > of the object.
> > > > >
> > > > > Cc: Jonathan Corbet <corbet@....net>
> > > > > Cc: Bagas Sanjaya <bagasdotme@...il.com>
> > > > > Cc: linux-doc@...r.kernel.org
> > > > > Signed-off-by: Jeff Xie <xiehuan09@...il.com>
> > > > > Reviewed-by: Masami Hiramatsu (Google) <mhiramat@...nel.org>
> > > > > ---
> > > > > Changelog:
> > > > > v14:
> > > > > - make documentation more readable and fix literal code block by Bagas Sanjaya
> > > > >
> > > > >  Documentation/trace/events.rst | 87 ++++++++++++++++++++++++++++++++++
> > > > >  1 file changed, 87 insertions(+)
> > > > >
> > > > > diff --git a/Documentation/trace/events.rst b/Documentation/trace/events.rst
> > > > > index c47f381d0c00..c15f1d25d4a0 100644
> > > > > --- a/Documentation/trace/events.rst
> > > > > +++ b/Documentation/trace/events.rst
> > > > > @@ -546,6 +546,93 @@ The following commands are supported:
> > > > >
> > > > >    See Documentation/trace/histogram.rst for details and examples.
> > > > >
> > > > > +- objtrace
> > > > > +
> > > > > +  This command provides a way to get the value of any object, The object
> > > > > +  can be obtained from the dynamic event (kprobe_event/uprobe_event) or the
> > > > > +  static event (tracepoint).
> > > > > +
> > > > > +  Usage:
> > > > > +  When using the kprobe event, by only need to set the objtrace (a new
> > > > > +  trigger), we can get the value of object that is set by kprobe event.
> > > > > +
> > > > > +  For example, for the function bio_add_page():
> > > > > +
> > > > > +  .. code-block:: c
> > > > > +
> > > > > +     int bio_add_page(struct bio *bio, struct page *page,
> > > > > +                   unsigned int len, unsigned int offset)
> > > > > +
> > > > > +  Firstly, we can set the base of the object as first parameter (arg1) to
> > > > > +  to the function:
> > > > > +
> > > > > +  .. code-block::
> > > > > +
> > > > > +     # echo 'p bio_add_page arg1=$arg1' > ./kprobe_events
> > > > > +
> > > > > +  Secondly, we can get the value dynamically based on the object:
> > > > > +
> > > > > +  .. code-block::
> > > > > +
> > > > > +     find the offset of the bi_size in struct bio:
> > > > > +     $ gdb vmlinux
> > > > > +     (gdb) p &(((struct bio *)0)->bi_iter.bi_size)
> > > > > +     $1 = (unsigned int *) 0x28
> > > > > +
> > > > > +     # echo 'objtrace:add:arg1,0x28:u32:1 if comm == "cat"' > ./events/kprobes/ \
> > > > > +       p_bio_add_page_0/trigger
> > > > > +
> > > > > +     # cd /sys/kernel/debug/tracing/
> > > > > +     # echo 'p bio_add_page arg1=$arg1' > ./kprobe_events
> > > > > +     # echo 'objtrace:add:arg1,0x28:u32:1 if comm == "cat"' > ./events/kprobes/p_bio_add_page_0/trigger
> > > >
> > > > No offense but this documentation is not well written and hard to read.
> > > >
> > > > Admittedly though I am just casually browsing through, so apologies.
> > > >
> > > > So basically, 0x28 is the offset of the u32 within the bio, that you want to
> > > > track down, as it passes through functions?
> > >
> > > Yes, Not only track the bio, but also get a value with an offset of
> > > 0x28 relative to the bio.
> >
> > Right.
> >
> > > >
> > > > The example is good, but I suggest breakdown each of the commands separated
> > > > by ':' and document those as well.
> > >
> > > I don't know how to explain it in more detail, maybe need to be
> > > familiar with kprobe event and trigger in advance ;-)
> >
> > That's not a strong argument IMO.
> >
> > Shouldn't it be super easy to add the following to the documentation
> > since you already mentioned it in the commit log? Or am I missing
> > something?
> >
> > Syntax:
> >         objtrace:add:obj[,offset][:type][:count][if <filter>]
>
> I'am so sorry, I misunderstood you, I thought it needed to be
> explained every word like this, e.g.
> objtrace:
>     ...
> add:
>     ...
> ...
>
> Thanks,  I will add the above syntax in the next version.
>

Yeah no problem, I am also OK with that being a follow-up patch
instead of the series if it matches with Steven's review timing
better.

Thanks,

 - Joel