From nobody Thu Nov 14 17:25:46 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 3F568EB64DC for ; Thu, 29 Jun 2023 12:05:10 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S232227AbjF2MFH (ORCPT ); Thu, 29 Jun 2023 08:05:07 -0400 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:46968 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S232048AbjF2ME6 (ORCPT ); Thu, 29 Jun 2023 08:04:58 -0400 Received: from szxga03-in.huawei.com (szxga03-in.huawei.com [45.249.212.189]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id EAD1430E5; Thu, 29 Jun 2023 05:04:56 -0700 (PDT) Received: from dggpemm500005.china.huawei.com (unknown [172.30.72.55]) by szxga03-in.huawei.com (SkyGuard) with ESMTP id 4QsHBw62q1zLnNr; Thu, 29 Jun 2023 20:02:48 +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.27; Thu, 29 Jun 2023 20:04:55 +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 v5 RFC 5/6] page_pool: update document about frag API Date: Thu, 29 Jun 2023 20:02:25 +0800 Message-ID: <20230629120226.14854-6-linyunsheng@huawei.com> X-Mailer: git-send-email 2.33.0 In-Reply-To: <20230629120226.14854-1-linyunsheng@huawei.com> References: <20230629120226.14854-1-linyunsheng@huawei.com> MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable X-Originating-IP: [10.69.192.56] X-ClientProxiedBy: dggems702-chm.china.huawei.com (10.3.19.179) 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. Also it seems there is a similar document in page_pool.h, so remove it to avoid the duplication. Signed-off-by: Yunsheng Lin CC: Lorenzo Bianconi CC: Alexander Duyck CC: Liang Chen CC: Alexander Lobakin --- 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/network= ing/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 =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D =20 -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. =20 -Basic use involves replacing alloc_pages() calls with the -page_pool_alloc_pages() call. Drivers should use page_pool_dev_alloc_page= s() -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 c= alls: + +1. page_pool_alloc_pages(): allocate memory without page splitting when dr= iver + 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 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 implemen= t page + splitting, mainly some cache line dirtying/bouncing for 'struct page' a= nd + atomic operation for page->pp_frag_count. =20 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. =20 +* 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. =20 * 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. */ =20 -/** - * 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 =20 --=20 2.33.0