[RFC PATCH v2 0/1] bpf, docs: structured overview of verifier

[RFC PATCH v2 0/1] bpf, docs: structured overview of verifier

[Burak Emir]

This is an RFC for adding overview documentation for the BPF verifier.

The existing verifier.rst has detail but IMHO it lacks structure and
background. Here is my humble proposal to make the verifier docs
more helpful for newcomers.

Finding a balance between overview and detail in documentation is 
never easy. The idea here is to describe abstract interpretation and have
enough information that anyone interested can learn what is going on. 

Please let me know what you think. I used Gemini 3 to get a first draft,
which I then checked word-for-word and reworked.

Differences to v1:
* Formatting fix for top, bottom
* Fixed some wrong identifiers that I had missed.

Burak Emir (1):
  bpf, docs: structured docs for the verifier

 Documentation/bpf/index.rst                   |  1 +
 .../bpf/verifier-overview-1-abstr-interp.rst  | 74 +++++++++++++++
 .../bpf/verifier-overview-2-domain.rst        | 91 +++++++++++++++++++
 .../bpf/verifier-overview-3-dataflow.rst      | 83 +++++++++++++++++
 .../bpf/verifier-overview-4-pruning.rst       | 59 ++++++++++++
 .../bpf/verifier-overview-5-advanced.rst      | 70 ++++++++++++++
 Documentation/bpf/verifier-overview-index.rst | 17 ++++
 7 files changed, 395 insertions(+)
 create mode 100644 Documentation/bpf/verifier-overview-1-abstr-interp.rst
 create mode 100644 Documentation/bpf/verifier-overview-2-domain.rst
 create mode 100644 Documentation/bpf/verifier-overview-3-dataflow.rst
 create mode 100644 Documentation/bpf/verifier-overview-4-pruning.rst
 create mode 100644 Documentation/bpf/verifier-overview-5-advanced.rst
 create mode 100644 Documentation/bpf/verifier-overview-index.rst

-- 
2.53.0.473.g4a7958ca14-goog

Re: [RFC PATCH v2 0/1] bpf, docs: structured overview of verifier

[Jonathan Corbet]

Burak Emir <bqe@google.com> writes:

> This is an RFC for adding overview documentation for the BPF verifier.
>
> The existing verifier.rst has detail but IMHO it lacks structure and
> background. Here is my humble proposal to make the verifier docs
> more helpful for newcomers.
>
> Finding a balance between overview and detail in documentation is 
> never easy. The idea here is to describe abstract interpretation and have
> enough information that anyone interested can learn what is going on. 
>
> Please let me know what you think. I used Gemini 3 to get a first draft,
> which I then checked word-for-word and reworked.

I only got the cover letter for the second version, so these overall
comments are based on the first.

- Please stick to the 80-column line limit for text material; we want
  people to be able read it.

- Why split this into five different files?  It is not a massive amount
  of material; spreading it out just makes the reader work harder.

- It is overly heavy on the markup.  If nothing else, function
  references should just be function(), without ``literal`` markup; that
  lets the automarkup code do its thing.  Same with "struct foo".

Hopefully the BPF folks can take a more substantive look as well.

jon

Re: [RFC PATCH v2 0/1] bpf, docs: structured overview of verifier

[Alexei Starovoitov]

On Mon, Mar 9, 2026 at 7:47 AM Jonathan Corbet <corbet@lwn.net> wrote:
>
> Burak Emir <bqe@google.com> writes:
>
> > This is an RFC for adding overview documentation for the BPF verifier.
> >
> > The existing verifier.rst has detail but IMHO it lacks structure and
> > background. Here is my humble proposal to make the verifier docs
> > more helpful for newcomers.
> >
> > Finding a balance between overview and detail in documentation is
> > never easy. The idea here is to describe abstract interpretation and have
> > enough information that anyone interested can learn what is going on.
> >
> > Please let me know what you think. I used Gemini 3 to get a first draft,
> > which I then checked word-for-word and reworked.
>
> I only got the cover letter for the second version, so these overall
> comments are based on the first.

Jon,
don't bother.
This is a no go.