Re: [PATCH v2 bpf-next] bpf: Document bpf_inspect drgn tool

[Andrey Ignatov <rdna@fb.com>]

Daniel Borkmann <daniel@iogearbox.net> [Tue, 2020-03-17 12:57 -0700]:
> Hey Andrey,

Hey Daniel,


> On 3/14/20 1:39 AM, Andrey Ignatov wrote:
> > It's a follow-up for discussion in [1].
> > 
> > drgn tool bpf_inspect.py was merged to drgn repo in [2]. Document it in
> > kernel tree to make BPF developers aware that the tool exists and can
> > help with getting BPF state unavailable via UAPI.
> > 
> > For now it's just one tool but the doc is written in a way that allows
> > to cover more tools in the future if needed.
> > 
> > Please refer to the doc itself for more details.
> > 
> > The patch was tested by `make htmldocs` and sanity-checking that
> > resulting html looks good.
> > 
> > [1]
> > https://lore.kernel.org/bpf/20200228201514.GB51456@rdna-mbp/T/#mefed65e8a98116bd5d07d09a570a3eac46724951
> > [2] https://github.com/osandov/drgn/pull/49
> > 
> > Signed-off-by: Andrey Ignatov <rdna@fb.com>
> > ---
> >   Documentation/bpf/drgn.rst  | 39 +++++++++++++++++++++++++++++++++++++
> >   Documentation/bpf/index.rst |  5 +++--
> >   2 files changed, 42 insertions(+), 2 deletions(-)
> >   create mode 100644 Documentation/bpf/drgn.rst
> > 
> > diff --git a/Documentation/bpf/drgn.rst b/Documentation/bpf/drgn.rst
> > new file mode 100644
> > index 000000000000..2ff9ef3e0b58
> > --- /dev/null
> > +++ b/Documentation/bpf/drgn.rst
> > @@ -0,0 +1,39 @@
> > +.. SPDX-License-Identifier: (LGPL-2.1 OR BSD-2-Clause)
> > +
> > +==============
> > +BPF drgn tools
> > +==============
> > +
> > +drgn scripts is a convenient and easy to use mechanism to retrieve arbitrary
> > +kernel data structures. drgn is not relying on kernel UAPI to read the data.
> > +Instead it's reading directly from ``/proc/kcore`` or vmcore and pretty prints
> > +the data based on DWARF debug information from vmlinux.
> > +
> > +This document describes BPF related drgn tools.
> > +
> > +See `drgn/tools`_ for all tools available at the moment and `drgn/doc`_ for
> > +more details on drgn itself.
> > +
> > +bpf_inspect.py
> > +**************
> > +
> > +`bpf_inspect.py`_ is a tool intended to inspect BPF programs and maps. It can
> > +iterate over all programs and maps in the system and print basic information
> > +about these objects, including id, type and name.
> > +
> > +The main use-case `bpf_inspect.py`_ covers is to show BPF programs of types
> > +``BPF_PROG_TYPE_EXT`` and ``BPF_PROG_TYPE_TRACING`` attached to other BPF
> > +programs via ``freplace``/``fentry``/``fexit`` mechanisms, since there is no
> > +user-space API to get this information.
> > +
> > +Any developer can edit the tool and get any piece of ``struct bpf_prog`` or
> > +``struct bpf_map`` they're interested in, e.g. the whole ``struct
> > +bpf_prog_aux``.
> > +
> > +See ``--help`` for more details.
> 
> I do like bcc's explicit usage examples/recipes so one can immediately grok
> whether it fits to a given use-case (e.g. [0]). Given this is targeted for
> developers perhaps it makes sense to add an example usage as you have described
> in [1] to the doc as well here?
> 
> Maybe last two paragraphs are not that useful. Could we structure each tool
> we're going to add here with two sub-headers "Description", "Getting Started"
> where the former has the first two paragraphs and then the latter has a usage
> example that shows e.g. [1] or as you write in your last paragraph a modification
> to dump the whole ``struct bpf_prog_aux``, for example?


I like the idea. Will split into these two sections, add examples and
send v3.

Thanks.


> Thanks,
> Daniel
> 
>   [0] https://github.com/iovisor/bcc/blob/master/tools/bpflist_example.txt
>   [1] https://github.com/osandov/drgn/pull/49
> 
> > +.. Links
> > +.. _drgn/doc: https://urldefense.proofpoint.com/v2/url?u=https-3A__drgn.readthedocs.io_en_latest_&d=DwICaQ&c=5VD0RTtNlTh3ycd41b3MUw&r=3jAokpHyGuCuJ834j-tttQ&m=w0lb_NHL_dnKmx1BCxQa-nVyCGAmWxQxlGS28F4ah5w&s=IbEuBhH7sEDU3POS5E-0wx_hQWbsgrbKdOynGQFDQTs&e=
> > +.. _drgn/tools: https://github.com/osandov/drgn/tree/master/tools
> > +.. _bpf_inspect.py:
> > +   https://github.com/osandov/drgn/blob/master/tools/bpf_inspect.py
> > diff --git a/Documentation/bpf/index.rst b/Documentation/bpf/index.rst
> > index 4f5410b61441..7be43c5f2dcf 100644
> > --- a/Documentation/bpf/index.rst
> > +++ b/Documentation/bpf/index.rst
> > @@ -47,12 +47,13 @@ Program types
> >      prog_flow_dissector
> > -Testing BPF
> > -===========
> > +Testing and debugging BPF
> > +=========================
> >   .. toctree::
> >      :maxdepth: 1
> > +   drgn
> >      s390
> > 
> 

-- 
Andrey Ignatov