From: Yunsheng Lin <linyunsheng@huawei.com>
To: <davem@davemloft.net>, <kuba@kernel.org>, <pabeni@redhat.com>
Cc: <netdev@vger.kernel.org>, <linux-kernel@vger.kernel.org>,
Yunsheng Lin <linyunsheng@huawei.com>,
Lorenzo Bianconi <lorenzo@kernel.org>,
Alexander Duyck <alexander.duyck@gmail.com>,
Liang Chen <liangchen.linux@gmail.com>,
Alexander Lobakin <aleksander.lobakin@intel.com>,
Jesper Dangaard Brouer <hawk@kernel.org>,
Ilias Apalodimas <ilias.apalodimas@linaro.org>,
Eric Dumazet <edumazet@google.com>,
Jonathan Corbet <corbet@lwn.net>,
Alexei Starovoitov <ast@kernel.org>,
Daniel Borkmann <daniel@iogearbox.net>,
John Fastabend <john.fastabend@gmail.com>,
<linux-doc@vger.kernel.org>, <bpf@vger.kernel.org>
Subject: [PATCH v5 RFC 5/6] page_pool: update document about frag API
Date: Thu, 29 Jun 2023 20:02:25 +0800 [thread overview]
Message-ID: <20230629120226.14854-6-linyunsheng@huawei.com> (raw)
In-Reply-To: <20230629120226.14854-1-linyunsheng@huawei.com>
As more drivers begin to use the frag API, update the
document about how to decide which API to use for the
driver author.
Also it seems there is a similar document in page_pool.h,
so remove it to avoid the duplication.
Signed-off-by: Yunsheng Lin <linyunsheng@huawei.com>
CC: Lorenzo Bianconi <lorenzo@kernel.org>
CC: Alexander Duyck <alexander.duyck@gmail.com>
CC: Liang Chen <liangchen.linux@gmail.com>
CC: Alexander Lobakin <aleksander.lobakin@intel.com>
---
Documentation/networking/page_pool.rst | 34 ++++++++++++++++++++++----
include/net/page_pool.h | 22 -----------------
2 files changed, 29 insertions(+), 27 deletions(-)
diff --git a/Documentation/networking/page_pool.rst b/Documentation/networking/page_pool.rst
index 873efd97f822..18b13d659c98 100644
--- a/Documentation/networking/page_pool.rst
+++ b/Documentation/networking/page_pool.rst
@@ -4,12 +4,27 @@
Page Pool API
=============
-The page_pool allocator is optimized for the XDP mode that uses one frame
-per-page, but it can fallback on the regular page allocator APIs.
+The page_pool allocator is optimized for recycling page or page frag used by skb
+packet and xdp frame.
-Basic use involves replacing alloc_pages() calls with the
-page_pool_alloc_pages() call. Drivers should use page_pool_dev_alloc_pages()
-replacing dev_alloc_pages().
+Basic use involves replacing napi_alloc_frag() and alloc_pages() calls with
+page_pool_cache_alloc() and page_pool_alloc(), which allocate memory with or
+without page splitting depending on the requested memory size.
+
+If the driver knows that it always requires full pages or its allocates are
+always smaller than half a page, it can use one of the more specific API calls:
+
+1. page_pool_alloc_pages(): allocate memory without page splitting when driver
+ knows that the memory it need is always bigger than half of the page
+ allocated from page pool. There is no cache line dirtying for 'struct page'
+ when a page is recycled back to the page pool.
+
+2. page_pool_alloc_frag(): allocate memory with page splitting when driver knows
+ that the memory it need is always smaller than or equal to half of the page
+ allocated from page pool. Page splitting enables memory saving and thus avoid
+ TLB/cache miss for data access, but there also is some cost to implement page
+ splitting, mainly some cache line dirtying/bouncing for 'struct page' and
+ atomic operation for page->pp_frag_count.
API keeps track of in-flight pages, in order to let API user know
when it is safe to free a page_pool object. Thus, API users
@@ -93,6 +108,15 @@ a page will cause no race conditions is enough.
* page_pool_dev_alloc_pages(): Get a page from the page allocator or page_pool
caches.
+* page_pool_dev_alloc_frag(): Get a page frag from the page allocator or
+ page_pool caches.
+
+* page_pool_dev_alloc(): Get a page or page frag from the page allocator or
+ page_pool caches.
+
+* page_pool_dev_cache_alloc(): Get a cache from the page allocator or page_pool
+ caches.
+
* page_pool_get_dma_addr(): Retrieve the stored DMA address.
* page_pool_get_dma_dir(): Retrieve the stored DMA direction.
diff --git a/include/net/page_pool.h b/include/net/page_pool.h
index e9fb95d62ed5..2b7db9992fc0 100644
--- a/include/net/page_pool.h
+++ b/include/net/page_pool.h
@@ -5,28 +5,6 @@
* Copyright (C) 2016 Red Hat, Inc.
*/
-/**
- * DOC: page_pool allocator
- *
- * This page_pool allocator is optimized for the XDP mode that
- * uses one-frame-per-page, but have fallbacks that act like the
- * regular page allocator APIs.
- *
- * Basic use involve replacing alloc_pages() calls with the
- * page_pool_alloc_pages() call. Drivers should likely use
- * page_pool_dev_alloc_pages() replacing dev_alloc_pages().
- *
- * API keeps track of in-flight pages, in-order to let API user know
- * when it is safe to dealloactor page_pool object. Thus, API users
- * must make sure to call page_pool_release_page() when a page is
- * "leaving" the page_pool. Or call page_pool_put_page() where
- * appropiate. For maintaining correct accounting.
- *
- * API user must only call page_pool_put_page() once on a page, as it
- * will either recycle the page, or in case of elevated refcnt, it
- * will release the DMA mapping and in-flight state accounting. We
- * hope to lift this requirement in the future.
- */
#ifndef _NET_PAGE_POOL_H
#define _NET_PAGE_POOL_H
--
2.33.0
next prev parent reply other threads:[~2023-06-29 12:04 UTC|newest]
Thread overview: 6+ messages / expand[flat|nested] mbox.gz Atom feed top
2023-06-29 12:02 [PATCH v5 RFC 0/6] introduce page_pool_alloc() API Yunsheng Lin
2023-06-29 12:02 ` Yunsheng Lin [this message]
2023-06-29 20:30 ` [PATCH v5 RFC 5/6] page_pool: update document about frag API Randy Dunlap
2023-06-29 12:02 ` [PATCH v5 RFC 6/6] net: veth: use newly added page pool API for veth with xdp Yunsheng Lin
2023-06-29 14:26 ` [PATCH v5 RFC 0/6] introduce page_pool_alloc() API Alexander Lobakin
2023-06-30 11:57 ` Yunsheng Lin
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=20230629120226.14854-6-linyunsheng@huawei.com \
--to=linyunsheng@huawei.com \
--cc=aleksander.lobakin@intel.com \
--cc=alexander.duyck@gmail.com \
--cc=ast@kernel.org \
--cc=bpf@vger.kernel.org \
--cc=corbet@lwn.net \
--cc=daniel@iogearbox.net \
--cc=davem@davemloft.net \
--cc=edumazet@google.com \
--cc=hawk@kernel.org \
--cc=ilias.apalodimas@linaro.org \
--cc=john.fastabend@gmail.com \
--cc=kuba@kernel.org \
--cc=liangchen.linux@gmail.com \
--cc=linux-doc@vger.kernel.org \
--cc=linux-kernel@vger.kernel.org \
--cc=lorenzo@kernel.org \
--cc=netdev@vger.kernel.org \
--cc=pabeni@redhat.com \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).