docs: net: page_pool: de-duplicate the intro comment
Subsystems (4)
Jakub Kicinski
maintainerPATCH 1/1 docs: net: page_pool: de-duplicate the intro comment
In commit 82e896d992fa ("docs: net: page_pool: use kdoc to avoid duplicating the information") I shied away from using the DOC:
comments when moving to kdoc for documenting page_pool API, because I wasn't sure how familiar people are with it.
Turns out there is already a DOC: comment for the intro, which is the same in both places, modulo what looks like minor rewording. Use the version from Documentation/ but keep the contents with the code.
---
CC: [email protected]
CC: [email protected]
CC: [email protected]
CC: [email protected]
--- Documentation/networking/page_pool.rst | 18 ++---------------- include/net/page_pool/helpers.h | 24 ++++++++++++------------ 2 files changed, 14 insertions(+), 28 deletions(-)
Documentation/networking/page_pool.rst +2 -16
@@ -4,22 +4,8 @@ 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. - -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(). - -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 -must call page_pool_put_page() to free the page, or attach -the page to a page_pool-aware objects like skbs marked with -skb_mark_for_recycle(). - -API user must call page_pool_put_page() once on a page, as it -will either recycle the page, or in case of refcnt > 1, it will -release the DMA mapping and in-flight state accounting. +.. kernel-doc:: include/net/page_pool/helpers.h + :doc: page_pool allocator Architecture overview =====================
include/net/page_pool/helpers.h +12 -12
@@ -8,23 +8,23 @@/** * 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 +* 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. * -* Basic use involve replacing alloc_pages() calls with the -* page_pool_alloc_pages() call. Drivers should likely use +* 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(). * -* 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 call page_pool_put_page() where appropriate and only attach -* the page to a page_pool-aware objects, like skbs marked for recycling. +* 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 +* must call page_pool_put_page() to free the page, or attach +* the page to a page_pool-aware objects like skbs marked with +* skb_mark_for_recycle(). * -* 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. +* API user must call page_pool_put_page() once on a page, as it +* will either recycle the page, or in case of refcnt > 1, it will +* release the DMA mapping and in-flight state accounting. */ #ifndef _NET_PAGE_POOL_HELPERS_H#define _NET_PAGE_POOL_HELPERS_H
Signature · 1 line
2.41.0
Quoted 5 lines · Jakub Kicinski
In commit
82e896d992fa("docs: net:page_pool: use kdoc to avoid duplicating the information") I shied away from using the DOC:
comments when moving to kdoc for documentingpage_poolAPI, because I wasn't sure how familiar people are with it.
Quoted 8 lines
Turns out there is already a DOC: comment for the intro, which is the same in both places, modulo what looks like minor rewording. Use the version from
Documentation/but keep the contents with the code.Signed-off-by Jakub Kicinski <[email protected]>---
CC: [email protected]
Quoted 66 lines
Documentation/networking/page_pool.rst | 18 ++---------------- include/net/page_pool/helpers.h | 24 ++++++++++++------------ 2 files changed, 14 insertions(+), 28 deletions(-)Documentation/networking/page_pool.rst +2
-16@@ -4,22 +4,8 @@ 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. - -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(). - -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 -must call page_pool_put_page() to free the page, or attach -the page to a page_pool-aware objects like skbs marked with -skb_mark_for_recycle(). - -API user must call page_pool_put_page() once on a page, as it -will either recycle the page, or in case of refcnt > 1, it will -release the DMA mapping and in-flight state accounting. +.. kernel-doc:: include/net/page_pool/helpers.h + :doc: page_pool allocator Architecture overview =====================include/net/page_pool/helpers.h +9
-8@@ -8,23 +8,23 @@/** * 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 +* 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. * -* Basic use involve replacing alloc_pages() calls with the -* page_pool_alloc_pages() call. Drivers should likely use +* 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(). * -* 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 call page_pool_put_page() where appropriate and only attach -* the page to a page_pool-aware objects, like skbs marked for recycling. +* 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 +* must call page_pool_put_page() to free the page, or attach +* the page to a page_pool-aware objects like skbs marked with +* skb_mark_for_recycle(). *
include/net/page_pool/helpers.h line 30
Quoted 10 lines
include/net/page_pool/helpers.h +3
-4-* 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. +* API user must call page_pool_put_page() once on a page, as it +* will either recycle the page, or in case of refcnt > 1, it will +* release the DMA mapping and in-flight state accounting. */ #ifndef _NET_PAGE_POOL_HELPERS_H#define _NET_PAGE_POOL_HELPERS_H
Adjustments looks good to me :-)
--Jesoer
This patch was applied to netdev/net-next.git (main) by Jakub Kicinski <[email protected]>:
Hello:
This patch was applied to netdev/net-next.git (main) by Jakub Kicinski <[email protected]>:
Quoted 11 lines · On Mon, 7 Aug 2023 14:00:51 -0700 you wrote:
In commit
82e896d992fa("docs: net:page_pool: use kdoc to avoid duplicating the information") I shied away from using the DOC:
comments when moving to kdoc for documentingpage_poolAPI, because I wasn't sure how familiar people are with it.Turns out there is already a DOC: comment for the intro, which is the same in both places, modulo what looks like minor rewording. Use the version from
Documentation/but keep the contents with the code.[...]
Here is the summary with links:
- [net-next] docs: net: page_pool: de-duplicate the intro comment
https://git.kernel.org/netdev/net-next/c/2c2b88748fd5
You are awesome, thank you!
Signature · 2 lines
Deet-doot-dot, I am a bot. https://korg.docs.kernel.org/patchwork/pwbot.html