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

[Pavel Begunkov <asml.silence@gmail.com>]

On 10/5/26 01:49, 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.
> +
> +4. **Delegate complexity to the lowest layer**: Each layer must respect its
> +   abstraction boundary. ``page_pool`` must not implement per-memory-provider
> +   custom logic in its main code; instead, it delegates provider-specific
> +   handling to ``struct memory_provider_ops``. Similarly, core networking code
> +   should avoid per-``netmem``-type branching and instead delegate operations
> +   to ``netmem`` helpers that handle the underlying memory type.
> +
> +5. **Homogeneous skb fragment memory types**: An ``sk_buff``'s ``frags[]`` are
> +   always backed by ``netmem_ref``\ s of the same memory type. Mixing fragments
> +   from different memory types within a single ``sk_buff`` is not allowed,
> +   keeping ``sk_buff`` handling simple. Consequently, coalescing ``sk_buff``\ s
> +   with different fragment memory types must not happen.

Would be good to expand on what's the memory type here. We have netmem
vs net_iov, and there are different memory provider types, but we need
to restrict it even further, sth in the lines of "if an skb contains a
frag from a memory provider, all its frags should be belong to the same
memory provider".

Otherwise,

Reviewed-by: Pavel Begunkov <asml.silence@gmail.com>

-- 
Pavel Begunkov