Daniel Borkmann <daniel@xxxxxxxxxxxxx> [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@xxxxxx> > > --- > > 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
