Re: [PATCH RFC v2 9/9] Documentation: describe RPC server transport classes and the BPF classifier

[Benjamin Coddington <ben.coddington@hammerspace.com>]

On 8 Oct 2026, at 14:42, Jeff Layton wrote:

> On Wed, 2026-10-07 at 15:59 -0400, Benjamin Coddington wrote:
>> From: Benjamin Coddington <bcodding@hammerspace.com>
>>
>> Dispatch round-robin across clients changes how a service shares its
>> threads, and the classes come from a BPF program the administrator
>> loads, so the administrator needs the model, the class word, and the
>> procedure.  Add a page with those: install a classifier with
>> svc-classify (build, attach, fill the map, check, change, remove, keep
>> across reboots), six class maps and the share each gives its clients,
>> the tracepoint that shows the class, and how the hook, the program and
>> the attach model work underneath.
>>
>> Signed-off-by: Benjamin Coddington <bcodding@hammerspace.com>
>> ---
>>  Documentation/filesystems/nfs/index.rst       |   1 +
>>  .../filesystems/nfs/rpc-server-clients.rst    | 394 ++++++++++++++++++
>>  2 files changed, 395 insertions(+)
>>  create mode 100644 Documentation/filesystems/nfs/rpc-server-clients.rst
>>
>> diff --git a/Documentation/filesystems/nfs/index.rst b/Documentation/filesystems/nfs/index.rst
>> index a29a212b5b4d..57a61ce0533d 100644
>> --- a/Documentation/filesystems/nfs/index.rst
>> +++ b/Documentation/filesystems/nfs/index.rst
>> @@ -16,3 +16,4 @@ NFS
>>     nfsd-io-modes
>>     knfsd-stats
>>     reexport
>> +   rpc-server-clients
>> diff --git a/Documentation/filesystems/nfs/rpc-server-clients.rst b/Documentation/filesystems/nfs/rpc-server-clients.rst
>> new file mode 100644
>> index 000000000000..b08351a88314
>> --- /dev/null
>> +++ b/Documentation/filesystems/nfs/rpc-server-clients.rst
>> @@ -0,0 +1,394 @@
>> +.. SPDX-License-Identifier: GPL-2.0
>> +
>> +======================================================
>> +RPC server: per-client dispatch and transport classes
>> +======================================================
>> +
>> +An RPC service thread pool serves its ready transports in FIFO order,
>> +one request per turn.  A peer with many connections (``nconnect``, a
>> +deep NFSv4.1 slot table, a data mover with a thread per file) takes a
>> +turn per connection, and a peer with one connection waits behind all
>> +of them.
>> +
>> +With a classifier attached, the pool instead serves its *clients* round
>> +robin: each client with work queued gets one request per round, however
>> +many connections it holds.  Which transports form a client is decided
>> +by a BPF program the administrator loads, once per accepted connection.
>> +With no program loaded nothing changes.
>> +
>> +This document describes the model, how to install a classifier with
>> +the ``svc-classify`` tool, what some class maps do, and how it works
>> +underneath.
>> +
>> +Clients, classes and turns
>> +==========================
>> +
>> +A *client* is a set of transports that share one turn.  Every service
>> +(nfsd, lockd, the NFSv4 callback service) keeps its own clients, found
>> +by *class* and network namespace, or by class, namespace and peer
>> +address.
>> +
>> +The classifier returns a 32-bit class word for each accepted transport:
>> +
>> +``0``
>> +    ``SVC_CLASS_NONE``: the transport stays on the service's *anonymous
>> +    client*.
>> +
>> +``N``, 1 to 2^31 - 1
>> +    one client for every transport of class ``N``.
>> +
>> +``N | SVC_CLASS_PER_ADDR``
>> +    one client per peer address within class ``N``.  ``N`` may be 0, so
>> +    ``SVC_CLASS_PER_ADDR`` alone means one client per peer address.
>> +
>> +``SVC_CLASS_PER_ADDR`` is bit 31.  ``svc-classify`` and this document
>> +write a class word with the bit set as ``N+addr``; ``svc-classify``
>> +also accepts ``addr`` for ``0+addr``.
>> +
>> +Dispatch rules:
>> +
>> +- A pool serves the clients that have transports queued round robin,
>> +  one request per client per round.
>> +- Within a client, transports are served in FIFO order, except that a
>> +  transport needing a connection accepted, closed, or a TLS handshake
>> +  run goes ahead of transports with data, though not two such turns in
>> +  a row while data waits.
>> +- A client's share of the pool does not grow with its connection count.
>> +  A client with one connection and a client with thirty get the same
>> +  number of turns while both have work queued.
>> +
>> +Things that follow from the rules and are easy to get wrong:
>> +
>> +- The anonymous client is one client.  Once any classifier is attached,
>> +  every transport whose class is ``0`` shares a single turn with every
>> +  other such transport of that service.  Within that one client the old
>> +  FIFO order applies, so those peers share the turn in proportion to
>> +  their connection counts.  A map that classifies only the hosts it
>> +  cares about and leaves the rest at ``0`` gives "the rest" one turn
>> +  in total (see example 5 below).
>> +- Per-address clients ignore the port.  Only IPv4 and IPv6 peers can be
>> +  keyed by address; a transport whose peer is anything else is left on
>> +  the anonymous client.
>> +- Listeners and UDP sockets are never classified; UDP traffic is served
>> +  from the anonymous client.
>> +- A transport keeps the class it was given when accepted.  Changing the
>> +  map, or replacing or removing the classifier, affects connections
>> +  accepted afterwards.  A connection that must be reclassified has to
>> +  reconnect.
>> +- nfsd has one service per network namespace, so its anonymous client
>> +  is per namespace.  lockd and the NFSv4 callback service are one
>> +  service for all namespaces; their anonymous clients span namespaces.
>> +- With no classifier attached anywhere, the pool uses a single FIFO;
>> +  the per-request cost of the feature is then a static branch on
>> +  enqueue and one empty-queue test on dequeue.
>> +  ``CONFIG_SUNRPC_BPF_CLASSIFY`` (default y) builds the hook; without
>> +  it there is no classification.
>> +
>> +Installing a classifier
>> +=======================
>> +
>> +There is one tool to do it with: ``svc-classify``, in
>> +``tools/net/sunrpc/svc-classify`` of the kernel source.  It carries the
>> +classifier program inside the binary, attaches it, and manages the
>> +class map by address prefix.  ``bpftool`` is not needed, and its
>> +``struct_ops`` subcommands cannot be used in its place (see "How it
>> +works").
>> +
>
> "There is one tool to do it with: ..."

barf.

> The obviously LLM-written documentation gives me the Ick and I stopped
> reading. There is also a lot of info in this doc that is not
> particularly helpful, like "the things that follow from the rules and
> are easy to get wrong".
>
> If you want humans to actually read this, then it probably needs to be
> written by a human. If you think the LLM slop is actually useful for
> other LLMs, then maybe put those bits at the end in a clearly-
> delineated section.

Yeah, you're right.  This really got spit out of the AI tubes without a lot
of refinement by me - thanks for reading even this far.

Ben