From nobody Fri Sep 20 11:47:34 2024 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by smtp.lore.kernel.org (Postfix) with ESMTP id F2613CE79CF for ; Wed, 20 Sep 2023 12:02:48 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S235141AbjITMCx (ORCPT ); Wed, 20 Sep 2023 08:02:53 -0400 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:49404 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S235067AbjITMCe (ORCPT ); Wed, 20 Sep 2023 08:02:34 -0400 Received: from szxga02-in.huawei.com (szxga02-in.huawei.com [45.249.212.188]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id A131593; Wed, 20 Sep 2023 05:02:27 -0700 (PDT) Received: from dggpemm500005.china.huawei.com (unknown [172.30.72.54]) by szxga02-in.huawei.com (SkyGuard) with ESMTP id 4RrH9q2gLSzNnNk; Wed, 20 Sep 2023 19:58:39 +0800 (CST) Received: from localhost.localdomain (10.69.192.56) by dggpemm500005.china.huawei.com (7.185.36.74) with Microsoft SMTP Server (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256) id 15.1.2507.31; Wed, 20 Sep 2023 20:02:25 +0800 From: Yunsheng Lin To: , , CC: , , Yunsheng Lin , Lorenzo Bianconi , Alexander Duyck , Liang Chen , Alexander Lobakin , Jesper Dangaard Brouer , Ilias Apalodimas , Eric Dumazet , Jonathan Corbet , Alexei Starovoitov , Daniel Borkmann , John Fastabend , , Subject: [PATCH net-next v9 5/6] page_pool: update document about frag API Date: Wed, 20 Sep 2023 19:58:54 +0800 Message-ID: <20230920115855.27631-6-linyunsheng@huawei.com> X-Mailer: git-send-email 2.33.0 In-Reply-To: <20230920115855.27631-1-linyunsheng@huawei.com> References: <20230920115855.27631-1-linyunsheng@huawei.com> MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable X-Originating-IP: [10.69.192.56] X-ClientProxiedBy: dggems703-chm.china.huawei.com (10.3.19.180) To dggpemm500005.china.huawei.com (7.185.36.74) X-CFilter-Loop: Reflected Precedence: bulk List-ID: X-Mailing-List: linux-kernel@vger.kernel.org Content-Type: text/plain; charset="utf-8" As more drivers begin to use the frag API, update the document about how to decide which API to use for the driver author. Signed-off-by: Yunsheng Lin CC: Lorenzo Bianconi CC: Alexander Duyck CC: Liang Chen CC: Alexander Lobakin --- Documentation/networking/page_pool.rst | 4 +- include/net/page_pool/helpers.h | 88 ++++++++++++++++++++++---- 2 files changed, 79 insertions(+), 13 deletions(-) diff --git a/Documentation/networking/page_pool.rst b/Documentation/network= ing/page_pool.rst index 215ebc92752c..0c0705994f51 100644 --- a/Documentation/networking/page_pool.rst +++ b/Documentation/networking/page_pool.rst @@ -58,7 +58,9 @@ a page will cause no race conditions is enough. =20 .. kernel-doc:: include/net/page_pool/helpers.h :identifiers: page_pool_put_page page_pool_put_full_page - page_pool_recycle_direct page_pool_dev_alloc_pages + page_pool_recycle_direct page_pool_cache_free + page_pool_dev_alloc_pages page_pool_dev_alloc_frag + page_pool_dev_alloc page_pool_dev_cache_alloc page_pool_get_dma_addr page_pool_get_dma_dir =20 .. kernel-doc:: net/core/page_pool.c diff --git a/include/net/page_pool/helpers.h b/include/net/page_pool/helper= s.h index c0e6c7d1b219..b20afe22c17d 100644 --- a/include/net/page_pool/helpers.h +++ b/include/net/page_pool/helpers.h @@ -8,23 +8,47 @@ /** * DOC: page_pool allocator * - * 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 us= ed 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 wi= th or + * without page splitting depending on the requested memory size. * - * 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 + * If the driver knows that it always requires full pages or its allocatio= ns 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 p= age' + * when a page is recycled back to the page pool. + * + * 2. page_pool_alloc_frag(): allocate memory with page splitting when dri= ver + * knows that the memory it need is always smaller than or equal to half o= f the + * page allocated from page pool. Page splitting enables memory saving and= thus + * avoids 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, the API users must call page_pool_put_= page() + * or page_pool_cache_free() to free the pp page or the pp buffer, or atta= ch the + * pp page or the pp buffer 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 + * page_pool_put_page() may be called multi times on the same page if a pa= ge is + * split into multi frags. For the last frag, see page_pool_is_last_frag()= , it + * will either recycle the page, or in case of page->_refcount > 1, it will * release the DMA mapping and in-flight state accounting. + * + * dma_sync_single_range_for_device() is only called for the last pp page = user + * when page_pool is created with PP_FLAG_DMA_SYNC_DEV flag, so it depend = on the + * last freed frag to do the sync_for_device operation for all frags in th= e same + * page when a page is split, the API user must setup pool->p.max_len and + * pool->p.offset correctly and ensure that page_pool_put_page() is called= with + * dma_sync_size being -1 for page_pool_alloc(), page_pool_cache_alloc() a= nd + * page_pool_alloc_frag() API. */ #ifndef _NET_PAGE_POOL_HELPERS_H #define _NET_PAGE_POOL_HELPERS_H @@ -73,6 +97,17 @@ static inline struct page *page_pool_dev_alloc_pages(str= uct page_pool *pool) return page_pool_alloc_pages(pool, gfp); } =20 +/** + * page_pool_dev_alloc_frag() - allocate a page frag. + * @pool: pool from which to allocate + * @offset: offset to the allocated page + * @size: requested size + * + * Get a page frag from the page allocator or page_pool caches. + * + * Return: + * Returns allocated page frag, otherwise return NULL. + */ static inline struct page *page_pool_dev_alloc_frag(struct page_pool *pool, unsigned int *offset, unsigned int size) @@ -111,6 +146,17 @@ static inline struct page *page_pool_alloc(struct page= _pool *pool, return page; } =20 +/** + * page_pool_dev_alloc() - allocate a page or a page frag. + * @pool: pool from which to allocate + * @offset: offset to the allocated page + * @size: in as the requested size, out as the allocated size + * + * Get a page or a page frag from the page allocator or page_pool caches. + * + * Return: + * Returns a page or a page frag, otherwise return NULL. + */ static inline struct page *page_pool_dev_alloc(struct page_pool *pool, unsigned int *offset, unsigned int *size) @@ -133,6 +179,16 @@ static inline void *page_pool_cache_alloc(struct page_= pool *pool, return page_address(page) + offset; } =20 +/** + * page_pool_dev_cache_alloc() - allocate a cache. + * @pool: pool from which to allocate + * @size: in as the requested size, out as the allocated size + * + * Get a cache from the page allocator or page_pool caches. + * + * Return: + * Returns the addr for the allocated cache, otherwise return NULL. + */ static inline void *page_pool_dev_cache_alloc(struct page_pool *pool, unsigned int *size) { @@ -281,6 +337,14 @@ static inline void page_pool_recycle_direct(struct pag= e_pool *pool, #define PAGE_POOL_32BIT_ARCH_WITH_64BIT_DMA \ (sizeof(dma_addr_t) > sizeof(unsigned long)) =20 +/** + * page_pool_cache_free() - free a cache into the page_pool + * @pool: pool from which cache was allocated + * @data: addr of cache to be free + * @allow_direct: freed by the consumer, allow lockless caching + * + * Free a cache allocated from page_pool_dev_cache_alloc(). + */ static inline void page_pool_cache_free(struct page_pool *pool, void *data, bool allow_direct) { --=20 2.33.0