Re: [PATCH net-next v1 2/2] docs: netmem: document netmem and memory provider design principles

[Stanislav Fomichev <sdf.kernel@gmail.com>]

On 10/05, Mina Almasry wrote:
> On Mon, Oct 5, 2026 at 9:19 AM Stanislav Fomichev <sdf.kernel@gmail.com> wrote:
> >
> > On 10/05, Mina Almasry wrote:
> > > Add a Design Principles section to Documentation/networking/netmem.rst
> > > covering the netmem_ref abstraction, the prohibition on direct
> > > downcasting in callers, decoupling memory providers from net_iov,
> > > decoupling net_iov from unreadability, delegating provider/type logic to
> > > memory_provider_ops and netmem helpers, and the homogeneous skb fragment
> > > memory type invariant.
> > >
> > > Cc: Luigi Rizzo <lrizzo@google.com>
> > > Cc: Björn Töpel <bjorn@kernel.org>
> > > Cc: Stanislav Fomichev <sdf@fomichev.me>
> > > Cc: Pavel Begunkov <asml.silence@gmail.com>
> > > Signed-off-by: Mina Almasry <almasrymina@google.com>
> > > ---
> > >  Documentation/networking/netmem.rst | 46 +++++++++++++++++++++++++++++
> > >  1 file changed, 46 insertions(+)
> > >
> > > diff --git a/Documentation/networking/netmem.rst b/Documentation/networking/netmem.rst
> > > index 217869d1108dd..57e52a947663d 100644
> > > --- a/Documentation/networking/netmem.rst
> > > +++ b/Documentation/networking/netmem.rst
> > > @@ -19,6 +19,52 @@ Benefits of Netmem :
> > >  * Simplified Development: Drivers interact with a consistent API,
> > >    regardless of the underlying memory implementation.
> > >
> > > +Design Principles
> > > +=================
> > > +
> > > +Memory providers (or the default ``page_pool`` allocator) allocate underlying
> > > +memory (``struct net_iov`` or ``struct page``), cast it to ``netmem_ref``, and
> > > +supply it to ``page_pool``. The ``page_pool``, drivers, and networking stack
> > > +operate on ``netmem_ref`` as the abstract type. Existing ``page_pool`` APIs
> > > +that allocate or free ``struct page`` are legacy compatibility wrappers for
> > > +drivers that do not yet support ``netmem_ref``. Code that is not yet
> > > +``netmem``-aware should be converted to ``netmem_ref`` unless it will never
> > > +need to support ``netmem``.
> > > +
> > > +1. **Operate on netmem_ref, do not downcast**: ``page_pool``, drivers, and the
> > > +   core networking stack should deal with ``netmem_ref`` rather than
> > > +   ``struct net_iov`` or ``struct page``. Downcasting ``netmem_ref`` to
> > > +   ``struct net_iov`` or ``struct page`` is not allowed unless a code path
> > > +   strictly cannot function without knowing the underlying memory type (for
> > > +   example, ``kmap_local_page()``). In those cases, to keep call sites simple,
> > > +   add a ``netmem`` helper that performs the operation on behalf of the caller,
> > > +   cleanly handles all ``net_iov`` and ``page`` cases, and returns an error if
> > > +   the ``netmem`` type cannot support the requested operation.
> >
> > [..]
> >
> > > +2. **Decouple memory providers from net_iov**: Memory providers are not limited
> > > +   to ``struct net_iov``. A memory provider that returns ``struct page``-backed
> > > +   ``netmem_ref``\ s to upper layers is allowed. Code must not assume that using
> > > +   a memory provider implies ``net_iov`` memory.
> > > +
> > > +3. **Decouple net_iov from unreadability**: ``struct net_iov`` is flexible and
> > > +   has no inherent restrictions. While current ``net_iov`` implementations are
> > > +   unreadable by the CPU, future readable ``net_iov`` implementations are
> > > +   allowed. Code must not assume ``net_iov`` is unreadable; check readability
> > > +   via ``netmem_address()`` or ``skb_frags_readable()`` instead.
> >
> > For these, idk, I do agree in principle, but it is not true right now? And
> > there needs to be a bunch of work to generalize?
> >
> 
> I may have misunderstood, but I think Bjorn is creating readable
> net_iovs for his work (patch 5). And I think that's great work and I
> plan to support the series. So this will become true very soon.
> 
> https://lore.kernel.org/netdev/20261002190018.696925-1-bjorn@kernel.org/
> 
> > Should we document where we are right now (mp return niov, niov == unreadable)
> > and where we wanna be (mp can return whatever, niov can imply readable or
> > unreadable). And when Bjorn's xsk work lands, he can update the mp section.
> > And sometime later maybe we'll lift niov == unreadable.
> 
> I think that's a good idea with 1 addendum. I'll say something like,
> "This is where we are right now, but new code should, as much as
> possible, update existing limitations to generalize and match the
> design principles.""I basically don't want LLMs lazily reward hacking
> and say "I'll just write code matching where we are right now and
> ignore the design principles." WDYT?

SGTM!