From nobody Fri Sep 20 13:26:10 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 1C206C05052 for ; Mon, 14 Aug 2023 13:00:43 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S231435AbjHNNAV (ORCPT ); Mon, 14 Aug 2023 09:00:21 -0400 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:51060 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S231289AbjHNM7v (ORCPT ); Mon, 14 Aug 2023 08:59:51 -0400 Received: from szxga01-in.huawei.com (szxga01-in.huawei.com [45.249.212.187]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id 61202E5E; Mon, 14 Aug 2023 05:59:47 -0700 (PDT) Received: from dggpemm500005.china.huawei.com (unknown [172.30.72.55]) by szxga01-in.huawei.com (SkyGuard) with ESMTP id 4RPZFt43mpzrSLj; Mon, 14 Aug 2023 20:58:26 +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; Mon, 14 Aug 2023 20:59:44 +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 v6 5/6] page_pool: update document about frag API Date: Mon, 14 Aug 2023 20:56:42 +0800 Message-ID: <20230814125643.59334-6-linyunsheng@huawei.com> X-Mailer: git-send-email 2.33.0 In-Reply-To: <20230814125643.59334-1-linyunsheng@huawei.com> References: <20230814125643.59334-1-linyunsheng@huawei.com> MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable X-Originating-IP: [10.69.192.56] X-ClientProxiedBy: dggems701-chm.china.huawei.com (10.3.19.178) 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 | 58 +++++++++++++++++++++++--- 2 files changed, 55 insertions(+), 7 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 b920224f6584..0f1eaa2986f9 100644 --- a/include/net/page_pool/helpers.h +++ b/include/net/page_pool/helpers.h @@ -8,13 +8,28 @@ /** * 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. + * + * 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 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 + * 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 @@ -100,6 +115,14 @@ static inline struct page *page_pool_alloc_frag(struct= page_pool *pool, return __page_pool_alloc_frag(pool, offset, size, gfp); } =20 +/** + * page_pool_dev_alloc_frag() - allocate a page frag. + * @pool[in] pool from which to allocate + * @offset[out] offset to the allocated page + * @size[in] requested size + * + * Get a page frag from the page allocator or page_pool caches. + */ static inline struct page *page_pool_dev_alloc_frag(struct page_pool *pool, unsigned int *offset, unsigned int size) @@ -143,6 +166,14 @@ 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[in]: pool from which to allocate + * @offset[out]: offset to the allocated page + * @size[in, out]: 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. + */ static inline struct page *page_pool_dev_alloc(struct page_pool *pool, unsigned int *offset, unsigned int *size) @@ -165,6 +196,13 @@ 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[in]: pool from which to allocate + * @size[in, out]: in as the requested size, out as the allocated size + * + * Get a cache from the page allocator or page_pool caches. + */ static inline void *page_pool_dev_cache_alloc(struct page_pool *pool, unsigned int *size) { @@ -316,6 +354,14 @@ static inline void page_pool_recycle_direct(struct pag= e_pool *pool, page_pool_put_full_page(pool, page, true); } =20 +/** + * page_pool_cache_free() - free a cache into the page_pool + * @pool[in]: pool from which cache was allocated + * @data[in]: cache to free + * @allow_direct[in]: 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