From mboxrd@z Thu Jan 1 00:00:00 1970 Received: from mail-pj2-f4.google.com (mail-pj2-f4.google.com [74.125.227.132]) (using TLSv1.2 with cipher ECDHE-RSA-AES128-GCM-SHA256 (128/128 bits)) (No client certificate requested) by smtp.subspace.kernel.org (Postfix) with ESMTPS id 9C937383C95 for ; Tue, 6 Oct 2026 22:07:03 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=74.125.227.132 ARC-Seal:i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1791324425; cv=none; b=arVBTFC8OwB9hOs0BoriwedfirBeesKBAN2wBFbpuJefswSXdgoMIt4w7KpS20Ds5RjWcbQGLkDlDfTO7lY5VgI5pezL3u+6zXi5SB3o5Pc/LT/MOEHRwwqh1f+xXxB+mmcu65D4wXqQcOx8Z8xi3nA3B96K9cSjbYzU25G0Q88= ARC-Message-Signature:i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1791324425; c=relaxed/simple; bh=oLowqW4kTT1TNYX2A/gZw2hQoXAMth+pOFnbIsMCdaY=; h=Date:From:To:Cc:Subject:Message-ID:References:MIME-Version: Content-Type:Content-Disposition:In-Reply-To; b=nU1POd4zZC4oGYVTUbiG3EbCfc5oO18qHndoYhqwftrSsXaAxbD2r7IRd3oZdqqNO8X1DwVKDuqc3sr/MhoyFXPMJVtq0nI4ZyeJx+nmPAAyJdZE1Lw4RZffC8D9aE/xXlWPp7EKt+BsnhEPEjJL27zkdVXSJOcWvLjXxYxvNbs= ARC-Authentication-Results:i=1; smtp.subspace.kernel.org; dmarc=pass (p=none dis=none) header.from=gmail.com; spf=pass smtp.mailfrom=gmail.com; dkim=pass (2048-bit key) header.d=gmail.com header.i=@gmail.com header.b=IG54vHzI; arc=none smtp.client-ip=74.125.227.132 Authentication-Results: smtp.subspace.kernel.org; dmarc=pass (p=none dis=none) header.from=gmail.com Authentication-Results: smtp.subspace.kernel.org; spf=pass smtp.mailfrom=gmail.com Authentication-Results: smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=gmail.com header.i=@gmail.com header.b="IG54vHzI" Received: by mail-pj2-f4.google.com with SMTP id 98e67ed59e1d1-3a854dffb5dso509946a91.1 for ; Tue, 06 Oct 2026 15:07:03 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20251104; t=1791324423; x=1791929223; darn=vger.kernel.org; h=in-reply-to:content-transfer-encoding:content-disposition :content-type:mime-version:references:message-id:subject:cc:to:from :date:from:to:cc:subject:date:message-id:reply-to:content-type; bh=OGTI2frF8RrBIeT4/ePn5rUSGsgZXEb1V8OC+n96/mk=; b=IG54vHzImmmbr4Y8m8Xp5wLUFkdbL5HQMXRvk5+2kzRzDWQ1XYvbucB8zomHoFZEyN 2cxY0CzNuGA/CTE7qWYzflmyq43AaCW+NGmUJZEjahy8uJX4DMn8yRL02+S1WCj6I29r oCH0qxtCxvtbPBEGASxKTFqOnVuvtZKE060GVzbEkHeV7XMKByEcSA7yhChHP7mausVe mMcE9lLNvuBbc8q4bFyH9hcPnOlH3iDPtcPDk27UpjAFoGu5qhCt7bdUmkq5bW0tPUoe de40QR6/vQG6nelaYJ7WdooNLi+cI4AV7wpOmmvqApwCeteBDHcWTV7iX6Nydt+h4y6F n8GA== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20260707; t=1791324423; x=1791929223; h=in-reply-to:content-transfer-encoding:content-disposition :content-type:mime-version:references:message-id:subject:cc:to:from :date:x-gm-gg:x-gm-message-state:from:to:cc:subject:date:message-id :reply-to:content-type; bh=OGTI2frF8RrBIeT4/ePn5rUSGsgZXEb1V8OC+n96/mk=; b=woX2BGbzye62uJpaM5HwrdtgIdPHpym+7jTORF6f//BCf9jKpiwD79KKEb0clnjEG2 IXlU3BNnhkuupQ93oT1cRYhR1x5wvZAtMxG1uIxMlJJB/N1zfHztcBFph6w8iVpMVIUS UWuN/hskAEGKjWFswLFrHkcRY2kWDQst7AnTgEihinjdYSnoKPb1ZPRVbw9/azKFh+zH 7vdzwU4+j54NnMq0hg2490AAnjCXWUt0cqPdfUpdrv4uATyLKJPAGqGyObLt6oVwo+Gf U7MY42FBjqaNAeqFlSXtY4tK+YOc7ILZAkna15AWPSkipxpd+6HTL7Q37S1pk9asBaAn vsiQ== X-Forwarded-Encrypted: i=1; AKwUvBzRyBKdWdGPqvgePKc4pWtUv/URfnkNZFc30NTwTXVgbK6+lQJR2+F8+U+xuN8jR+f9abTfkS4U1qPVnBQ=@vger.kernel.org X-Gm-Message-State: AFq9FYKUtArUiX6WwkfekNry6GZUPjZ/BzpJNuvFiqfEfOqGkItgH3tV 6f+a/f5kA6fMY+5cs1pZ6GMqwDQvWW8ZMYIGkW2B07dXwQAmxCQ7lPiC X-Gm-Gg: AYBFou0TwOJ+ZhTkMGygHK8YWFWzmlYN8f7x4k8IiNTMny+7bnKzTWUhBKLpBir4ZDx Wt8ainLc/FuPQEiQobEnhjguA3WTDpXbldlzOTA2ewrAnBAytmM8/PI8woeeFuoN7PL/NQJj1al JCp4s+DLWQxlrDxtRK87LB2w/Q/kRTKNWZeeFx9J2cMgitEID/2mHB0HIHHCWqa+/8ByaQsn5qV Y91oghUKQOmNm5K/c1qJlu/YXl7G1G4dTDjGQy82zIchCPtanS349aHgK6cJwz8MVet5OVB5Wj+ q00BTiBMmIr8lAPR6Yfw43dzSavih9ytb+L+jMnT39yaYvrS8PDq/SnM97EYPlq9VdqStRJ8C2s qUNdAj45Oh9x/4d3oppm0FIPUuqaK0qn3L9+LutGCLM9Xd+gcsqXZereNJQ7EIU4I1S3QBVL5Q0 kCxt3lhilQNVBAHZWuNcfFqaPMEFzsBrlXsMtmTI8QYvPyzgGYLPZOC/H5L4VczAXk X-Received: by 2002:a17:90b:1c0a:b0:3a0:42a9:9c75 with SMTP id 98e67ed59e1d1-3a8a1b5d361mr332289a91.43.1791324422809; Tue, 06 Oct 2026 15:07:02 -0700 (PDT) Received: from localhost ([2a03:2880:2ff:54::]) by smtp.gmail.com with ESMTPSA id 98e67ed59e1d1-3a89d5ced5asm504062a91.0.2026.10.06.15.07.01 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Tue, 06 Oct 2026 15:07:01 -0700 (PDT) Date: Tue, 6 Oct 2026 15:02:42 -0700 From: Stanislav Fomichev To: Mina Almasry Cc: netdev@vger.kernel.org, linux-doc@vger.kernel.org, linux-kernel@vger.kernel.org, bpf@vger.kernel.org, "David S. Miller" , Eric Dumazet , Jakub Kicinski , Paolo Abeni , Simon Horman , Jonathan Corbet , Shuah Khan , Randy Dunlap , Jesper Dangaard Brouer , Ilias Apalodimas , Alexei Starovoitov , Daniel Borkmann , John Fastabend , Stanislav Fomichev , Luigi Rizzo , =?utf-8?B?QmrDtnJuIFTDtnBlbA==?= , Pavel Begunkov Subject: Re: [PATCH net-next v1 2/2] docs: netmem: document netmem and memory provider design principles Message-ID: References: <20261005004958.3603059-1-almasrymina@google.com> <20261005004958.3603059-3-almasrymina@google.com> Precedence: bulk X-Mailing-List: linux-kernel@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Disposition: inline Content-Transfer-Encoding: 8bit In-Reply-To: On 10/05, Mina Almasry wrote: > On Mon, Oct 5, 2026 at 9:19 AM Stanislav Fomichev 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 > > > Cc: Björn Töpel > > > Cc: Stanislav Fomichev > > > Cc: Pavel Begunkov > > > Signed-off-by: Mina Almasry > > > --- > > > 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!