netdev - Re: [PATCH net-next] docs: net: page_pool: de-duplicate the intro comment

lists.openwall.net		lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC
Open Source and information security mailing list archives

Hash Suite for Android: free password hash cracker in your pocket

[<prev] [next>] [<thread-prev] [thread-next>] [day] [month] [year] [list]

Message-ID: <47355d72-837d-213a-b6b1-f202c753de80@kernel.org>
Date: Tue, 8 Aug 2023 11:27:26 +0200
From: Jesper Dangaard Brouer <hawk@...nel.org>
To: Jakub Kicinski <kuba@...nel.org>, davem@...emloft.net
Cc: netdev@...r.kernel.org, edumazet@...gle.com, pabeni@...hat.com,
 hawk@...nel.org, ilias.apalodimas@...aro.org, corbet@....net,
 linux-doc@...r.kernel.org
Subject: Re: [PATCH net-next] docs: net: page_pool: de-duplicate the intro
 comment



On 07/08/2023 23.00, Jakub Kicinski 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 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.
> 
> Signed-off-by: Jakub Kicinski <kuba@...nel.org>
> ---
> CC: hawk@...nel.org

Acked-by: Jesper Dangaard Brouer <hawk@...nel.org>


> CC: ilias.apalodimas@...aro.org
> CC: corbet@....net
> CC: linux-doc@...r.kernel.org > ---
>   Documentation/networking/page_pool.rst | 18 ++----------------
>   include/net/page_pool/helpers.h        | 24 ++++++++++++------------
>   2 files changed, 14 insertions(+), 28 deletions(-)
> 
> diff --git a/Documentation/networking/page_pool.rst b/Documentation/networking/page_pool.rst
> index 68b82cea13e4..215ebc92752c 100644
> --- a/Documentation/networking/page_pool.rst
> +++ b/Documentation/networking/page_pool.rst
> @@ -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
>   =====================
> diff --git a/include/net/page_pool/helpers.h b/include/net/page_pool/helpers.h
> index 78df91804c87..94231533a369 100644
> --- a/include/net/page_pool/helpers.h
> +++ b/include/net/page_pool/helpers.h
> @@ -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

Adjustments looks good to me :-)

--Jesoer