From mboxrd@z Thu Jan 1 00:00:00 1970 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 kanga.kvack.org (kanga.kvack.org [205.233.56.17]) by smtp.lore.kernel.org (Postfix) with ESMTP id DBAC5D3C927 for ; Sun, 20 Oct 2024 10:02:53 +0000 (UTC) Received: by kanga.kvack.org (Postfix) id C10E86B007B; Sun, 20 Oct 2024 06:02:52 -0400 (EDT) Received: by kanga.kvack.org (Postfix, from userid 40) id BC0C46B0082; Sun, 20 Oct 2024 06:02:52 -0400 (EDT) X-Delivered-To: int-list-linux-mm@kvack.org Received: by kanga.kvack.org (Postfix, from userid 63042) id A883B6B0083; Sun, 20 Oct 2024 06:02:52 -0400 (EDT) X-Delivered-To: linux-mm@kvack.org Received: from relay.hostedemail.com (smtprelay0010.hostedemail.com [216.40.44.10]) by kanga.kvack.org (Postfix) with ESMTP id 8A9E26B007B for ; Sun, 20 Oct 2024 06:02:52 -0400 (EDT) Received: from smtpin16.hostedemail.com (a10.router.float.18 [10.200.18.1]) by unirelay09.hostedemail.com (Postfix) with ESMTP id 08E33810EB for ; Sun, 20 Oct 2024 10:02:40 +0000 (UTC) X-FDA: 82693541490.16.BE37F18 Received: from mail-pl1-f170.google.com (mail-pl1-f170.google.com [209.85.214.170]) by imf22.hostedemail.com (Postfix) with ESMTP id EF08CC000A for ; Sun, 20 Oct 2024 10:02:33 +0000 (UTC) Authentication-Results: imf22.hostedemail.com; dkim=pass header.d=gmail.com header.s=20230601 header.b=OE9Cttd0; spf=pass (imf22.hostedemail.com: domain of bagasdotme@gmail.com designates 209.85.214.170 as permitted sender) smtp.mailfrom=bagasdotme@gmail.com; dmarc=pass (policy=none) header.from=gmail.com ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=hostedemail.com; s=arc-20220608; t=1729418495; h=from:from:sender:reply-to:subject:subject:date:date: message-id:message-id:to:to:cc:cc:mime-version:mime-version: content-type:content-type:content-transfer-encoding: in-reply-to:in-reply-to:references:references:dkim-signature; bh=sLv1WNe4x555lLPO/CsQHB1qpygJDPAMQIxtHZM5Cng=; b=2MbMZ168cGc0QV9pjkxmeEs/LzESfX/fnJm1UWaCvKttd0UmdwrCGAQ/2+SsVW0kmzAfJr s/XY4xmgd/lAlRfRrLJ/cKUFwhhQUwCuREndCd4PGUGE/rrhri/tWdy0L8qQKqZTtjbZVx EZ7jq5FGuV/Lbe76fQOyS4Xt1VIS37k= ARC-Authentication-Results: i=1; imf22.hostedemail.com; dkim=pass header.d=gmail.com header.s=20230601 header.b=OE9Cttd0; spf=pass (imf22.hostedemail.com: domain of bagasdotme@gmail.com designates 209.85.214.170 as permitted sender) smtp.mailfrom=bagasdotme@gmail.com; dmarc=pass (policy=none) header.from=gmail.com ARC-Seal: i=1; s=arc-20220608; d=hostedemail.com; t=1729418495; a=rsa-sha256; cv=none; b=X144JBL+qzeplW2sKX/3SHonRHdmTSMtF7jX20AX1GTuG5VEV2Lcm7qL/DkhDkoSx/a7J/ HGARiiOQ3cakhnGTibWuRiiJ33i+PgVAzt4eM9U7X6NJDsAxnoEY1oNoCHAB/JggPyrcmE 562SGGovzTomktkZ8uDfd7L8jcY6bSM= Received: by mail-pl1-f170.google.com with SMTP id d9443c01a7336-20cdda5cfb6so36571015ad.3 for ; Sun, 20 Oct 2024 03:02:49 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20230601; t=1729418569; x=1730023369; darn=kvack.org; h=in-reply-to:content-disposition:mime-version:references:message-id :subject:cc:to:from:date:from:to:cc:subject:date:message-id:reply-to; bh=sLv1WNe4x555lLPO/CsQHB1qpygJDPAMQIxtHZM5Cng=; b=OE9Cttd02Z4Zz8cpauG73wJxVXAM5+KNzndcXnSp1qWpPNlVwwKhIxUeCWJrmwYtTy GlIsTZ4e6s6Icc70BSltpZ4VTQrFPVBQ28M/DX4OWQCYjhZa6bTR8DUGxeq1I0iWXfBE RaSyYqH6YikvgcQNh89KDh0BbyGwQQ2nnWGHckoxlAE9lKVaqNtcG52ywjDI6UL170RU LzYWqPQY4ihuBLwXkU4lOWuXJQQi6+bufz8Btfzeh1Qd3SVvjCM66KcdwhJtlDq9Y5DC NeEiOkapCY5bu62/UFQIZXcJdGtj+hyVl/aV9U7JR1Tc/Q3pe6gZoq4F3TrDCS7iJvTu d9mQ== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1729418569; x=1730023369; h=in-reply-to:content-disposition:mime-version:references:message-id :subject:cc:to:from:date:x-gm-message-state:from:to:cc:subject:date :message-id:reply-to; bh=sLv1WNe4x555lLPO/CsQHB1qpygJDPAMQIxtHZM5Cng=; b=R5Ia7ORh0e0HhGfROG2ypQ9J4uP6WYouKcxesJGNus1p46M/OddJDUuuxN7Js1XZ8H wAaPSSnnG5FcFZraXwOO/q0lEWDOV9IHcqAYYE6iEIPFATNtGEHokqGkXJA9l4c9VWMW UrA6RNttakBnkhzSjTzrTyr7UZ8MSY/jOC55y/k5kJY5jAU/wC/iSEZfxv4uRuv++/Th lA/c7FQrx5IZMAjvaZ1nHiIb0oCsu6X5uV6oYAAadvcmyCoKiP9V0TVFOXUjYGzTic2g DBYEF7o59nsB8T9/mjXvrnst+3VNGclVuoUTHc/MbkULu+GcgaV6aN+9QeU7johbELaM dmJw== X-Forwarded-Encrypted: i=1; AJvYcCXQ0vrlDDSCNqoyQUJVm673gyyh6UT1x162zda53hCkr2+ifI176yRrGukAowwxTt3tYWGktrAaMw==@kvack.org X-Gm-Message-State: AOJu0Yy7XlCjNemRt1/rp+HR0rta4EE1QIgiJLPhtpqP6XoZaI+SFI3E jYFdreh/6Yghun9FpTVtd8WnFDRqLGeH4LO8iAT3Vgj74QCOHSOM X-Google-Smtp-Source: AGHT+IFIiG5yzV9iBxkwwESuSB+cKcM/T6OPAsFcmrr2YC16cMPsS58jEon7/L82qkM9BAGoFq0f0Q== X-Received: by 2002:a05:6a21:6e41:b0:1d9:28f8:f27d with SMTP id adf61e73a8af0-1d92c5757e9mr11584284637.38.1729418568723; Sun, 20 Oct 2024 03:02:48 -0700 (PDT) Received: from archie.me ([103.124.138.155]) by smtp.gmail.com with ESMTPSA id d2e1a72fcca58-71ec140781fsm907431b3a.185.2024.10.20.03.02.47 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Sun, 20 Oct 2024 03:02:47 -0700 (PDT) Received: by archie.me (Postfix, from userid 1000) id 776E6437667D; Sun, 20 Oct 2024 17:02:45 +0700 (WIB) Date: Sun, 20 Oct 2024 17:02:45 +0700 From: Bagas Sanjaya To: Yunsheng Lin , davem@davemloft.net, kuba@kernel.org, pabeni@redhat.com Cc: netdev@vger.kernel.org, linux-kernel@vger.kernel.org, Alexander Duyck , Jonathan Corbet , Andrew Morton , linux-doc@vger.kernel.org, linux-mm@kvack.org Subject: Re: [PATCH net-next v22 13/14] mm: page_frag: update documentation for page_frag Message-ID: References: <20241018105351.1960345-1-linyunsheng@huawei.com> <20241018105351.1960345-14-linyunsheng@huawei.com> MIME-Version: 1.0 Content-Type: multipart/signed; micalg=pgp-sha512; protocol="application/pgp-signature"; boundary="x4TvRmf7dRhYSYeH" Content-Disposition: inline In-Reply-To: <20241018105351.1960345-14-linyunsheng@huawei.com> X-Rspamd-Server: rspam03 X-Rspam-User: X-Rspamd-Queue-Id: EF08CC000A X-Stat-Signature: kpbp3utta1xjcmrhx4mnagttr7s395sr X-HE-Tag: 1729418553-856757 X-HE-Meta: U2FsdGVkX1+KA03yuMwvYIA/gLwSaEY4dkuSqtn6ffr3ph0hZQSOxGRFrl8AlcV5w0mO2sGT6LjADyUWJUDyqpQerrourO7kQod4Wn1MJ1vm/R2aivF2pXiEv9Lt1AgJMkonx4j0T6GfYuRhagjhl3OtMbV6F6+DxfmhznrrtRNH7rCk9M6aT7SaU5VJeGYYHcgnqJ/QwxnF4Fw64p1PaPORQ6vCZO9ZlLML4p9hSoaFzg5IUn4BKHO4+LHQsK8kK4tM+NqR3SGpOu83xlqgFBg8LaYb1Jpxb8f6Rk7h5BIdAHisf+G0w8JjpPmiBief8+eIXLr+JmYKgS7dJTSjqaCbMCpCYMOiPC14/gEbPVgOyinZP0I2cHWPq7xsUXkA6wf1eoNfuMmNGCEZh84/XfYa6aIhLibe/Nt35A2xkNxnovoYxqLhcZONzBGqvb2/gjG74+zan9vJe3n7YWq6D3GMXqlxbyxa6VXx4sZCskONUqTla8mKa4ic+YVR7cv2w9caRRUBUA2/P3g1R6dpQBNE16Wl/A7iArlFx82vl6BOfL51NMJn6rMuJMBKstYYm8mZIjrM+EMMrhErFqpnNthd7XEzPNxPogt5LtAqFCriVjgNZNF/oxBJuxW2s/P3Gs447M5cL/3MxXawy1bhvQ8RmdjbGneYg55LzvP/v7RLChe0AQmUXTg53+RwwVsnk6lU9FxlFkZ6p+1dEGqsJXPM3/JD6K9Y5WVXWppi6mfPBULce6BmmJPW3zV5K7G4mriAJfudA5qSd6OXtHjnRLMmioQeK0GmDofNbQimoss2TdcZr8uqcSCewU3M8xjvzxo4AC/UCMDUfk96ojLxh+ODrRXKCyR1bHDQIwMxhzL+PXpzDlMVzt0vqPwPoL7FtHPbn2+6crFNoTcVHSJAYkOfPRRnMjuwOLs/BjUhmFDTOjaC4EnP6pk0MQOUCw+SqrYBkod1xUftBD7nSn6 gv/KMhDg KD8Gf0psChdauiqSMA+znntfxPZGfDEefgL7Skhcd1+HynA4xVu2o74nsLnaXtzTrjNsser7IvcxIhUEnfiHHNh56Xku4KL+nPH6Qf0lZvhfso0bFCiqD1ZhN6qJsMRtNaIh7aN86MyNC+rOPuifr17Vf8wYO8RYq2mJRjsIohkEoilcL6u5WpbNhrswD1NYn2EYrKlLRXXn56F5Wk8jGxrUIMb/5jzw5A6Uvlqmc5WYU1zx6ziANzSI7WYsiNjyjy32g6hlnw4BtMhh6G8Wfh48YobA+cIZ9Wz/pFGDrUBeBDX17hoXZaa5QCsAOvQX9tPPC9PrMVXJqZG7WgY0E4bd7DLkjgjh/YCn22dSCJOZC7t0/olXdCxPwt7Lz2nBSxBqQCV58bhrYjzJlYvkdbVzHlmCS3E+a9M0wi8t9rCsPxQIF7rddRHaRizkFMl5CNT7LMAl/YH4t6Db0wpKMEzNi8+ct5qeyrd5ViQQJXd7bklIXzQ+aluH/A23yBZhB5XjJC5/x4PjPs5sdbXoi+Fqz9gs2FrdcloiLVW//v3LzPFYDtXXsnREokpC3ANDJS2Qyh32JvtmkwbfsPJwpUOgSdcbTuMtSYdfI X-Bogosity: Ham, tests=bogofilter, spamicity=0.000000, version=1.2.4 Sender: owner-linux-mm@kvack.org Precedence: bulk X-Loop: owner-majordomo@kvack.org List-ID: List-Subscribe: List-Unsubscribe: --x4TvRmf7dRhYSYeH Content-Type: text/plain; charset=utf-8 Content-Disposition: inline Content-Transfer-Encoding: quoted-printable On Fri, Oct 18, 2024 at 06:53:50PM +0800, Yunsheng Lin wrote: > diff --git a/Documentation/mm/page_frags.rst b/Documentation/mm/page_frag= s.rst > index 503ca6cdb804..7fd9398aca4e 100644 > --- a/Documentation/mm/page_frags.rst > +++ b/Documentation/mm/page_frags.rst > @@ -1,3 +1,5 @@ > +.. SPDX-License-Identifier: GPL-2.0 > + > =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D > Page fragments > =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D > @@ -40,4 +42,176 @@ page via a single call. The advantage to doing this = is that it allows for > cleaning up the multiple references that were added to a page in order to > avoid calling get_page per allocation. > =20 > -Alexander Duyck, Nov 29, 2016. > + > +Architecture overview > +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D > + > +.. code-block:: none > + > + +----------------------+ > + | page_frag API caller | > + +----------------------+ > + | > + | > + v > + +------------------------------------------------------------------+ > + | request page fragment | > + +------------------------------------------------------------------+ > + | | | > + | | | > + | Cache not enough | > + | | | > + | +-----------------+ | > + | | reuse old cache |--Usable-->| > + | +-----------------+ | > + | | | > + | Not usable | > + | | | > + | v | > + Cache empty +-----------------+ | > + | | drain old cache | | > + | +-----------------+ | > + | | | > + v_________________________________v | > + | | > + | | > + _________________v_______________ | > + | | Cache is en= ough > + | | | > + PAGE_SIZE < PAGE_FRAG_CACHE_MAX_SIZE | | > + | | | > + | PAGE_SIZE >=3D PAGE_FRAG_CACHE_MAX_SIZE | > + v | | > + +----------------------------------+ | | > + | refill cache with order > 0 page | | | > + +----------------------------------+ | | > + | | | | > + | | | | > + | Refill failed | | > + | | | | > + | v v | > + | +------------------------------------+ | > + | | refill cache with order 0 page | | > + | +----------------------------------=3D-+ | > + | | | > + Refill succeed | | > + | Refill succeed | > + | | | > + v v v > + +------------------------------------------------------------------+ > + | allocate fragment from cache | > + +------------------------------------------------------------------+ > + > +API interface > +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D > +As the design and implementation of page_frag API implies, the allocatio= n side > +does not allow concurrent calling. Instead it is assumed that the caller= must > +ensure there is not concurrent alloc calling to the same page_frag_cache > +instance by using its own lock or rely on some lockless guarantee like N= API > +softirq. > + > +Depending on different aligning requirement, the page_frag API caller ma= y call > +page_frag_*_align*() to ensure the returned virtual address or offset of= the > +page is aligned according to the 'align/alignment' parameter. Note the s= ize of > +the allocated fragment is not aligned, the caller needs to provide an al= igned > +fragsz if there is an alignment requirement for the size of the fragment. > + > +Depending on different use cases, callers expecting to deal with va, pag= e or > +both va and page for them may call page_frag_alloc, page_frag_refill, or > +page_frag_alloc_refill API accordingly. > + > +There is also a use case that needs minimum memory in order for forward = progress, > +but more performant if more memory is available. Using page_frag_*_prepa= re() and > +page_frag_commit*() related API, the caller requests the minimum memory = it needs > +and the prepare API will return the maximum size of the fragment returne= d. The > +caller needs to either call the commit API to report how much memory it = actually > +uses, or not do so if deciding to not use any memory. > + > +.. kernel-doc:: include/linux/page_frag_cache.h > + :identifiers: page_frag_cache_init page_frag_cache_is_pfmemalloc > + __page_frag_alloc_align page_frag_alloc_align page_frag_alloc > + __page_frag_refill_align page_frag_refill_align > + page_frag_refill __page_frag_refill_prepare_align > + page_frag_refill_prepare_align page_frag_refill_prepare > + __page_frag_alloc_refill_prepare_align > + page_frag_alloc_refill_prepare_align > + page_frag_alloc_refill_prepare page_frag_alloc_refill_probe > + page_frag_refill_probe page_frag_commit > + page_frag_commit_noref page_frag_alloc_abort > + > +.. kernel-doc:: mm/page_frag_cache.c > + :identifiers: page_frag_cache_drain page_frag_free > + __page_frag_alloc_refill_probe_align > + > +Coding examples > +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D > + > +Initialization and draining API > +------------------------------- > + > +.. code-block:: c > + > + page_frag_cache_init(nc); > + ... > + page_frag_cache_drain(nc); > + > + > +Allocation & freeing API > +------------------------ > + > +.. code-block:: c > + > + void *va; > + > + va =3D page_frag_alloc_align(nc, size, gfp, align); > + if (!va) > + goto do_error; > + > + err =3D do_something(va, size); > + if (err) { > + page_frag_abort(nc, size); > + goto do_error; > + } > + > + ... > + > + page_frag_free(va); > + > + > +Preparation & committing API > +---------------------------- > + > +.. code-block:: c > + > + struct page_frag page_frag, *pfrag; > + bool merge =3D true; > + void *va; > + > + pfrag =3D &page_frag; > + va =3D page_frag_alloc_refill_prepare(nc, 32U, pfrag, GFP_KERNEL); > + if (!va) > + goto wait_for_space; > + > + copy =3D min_t(unsigned int, copy, pfrag->size); > + if (!skb_can_coalesce(skb, i, pfrag->page, pfrag->offset)) { > + if (i >=3D max_skb_frags) > + goto new_segment; > + > + merge =3D false; > + } > + > + copy =3D mem_schedule(copy); > + if (!copy) > + goto wait_for_space; > + > + err =3D copy_from_iter_full_nocache(va, copy, iter); > + if (err) > + goto do_error; > + > + if (merge) { > + skb_frag_size_add(&skb_shinfo(skb)->frags[i - 1], copy); > + page_frag_commit_noref(nc, pfrag, copy); > + } else { > + skb_fill_page_desc(skb, i, pfrag->page, pfrag->offset, copy); > + page_frag_commit(nc, pfrag, copy); > + } Looks good. > +/** > + * page_frag_cache_is_pfmemalloc() - Check for pfmemalloc. > + * @nc: page_frag cache from which to check > + * > + * Used to check if the current page in page_frag cache is allocated fro= m the "Check if ..." > + * pfmemalloc reserves. It has the same calling context expectation as t= he > + * allocation API. > + * > + * Return: > + * true if the current page in page_frag cache is allocated from the pfm= emalloc > + * reserves, otherwise return false. > + */ > ... > +/** > + * page_frag_alloc() - Allocate a page fragment. > + * @nc: page_frag cache from which to allocate > + * @fragsz: the requested fragment size > + * @gfp_mask: the allocation gfp to use when cache need to be refilled > + * > + * Alloc a page fragment from page_frag cache. "Allocate a page fragment ..." > + * > + * Return: > + * virtual address of the page fragment, otherwise return NULL. > + */ > static inline void *page_frag_alloc(struct page_frag_cache *nc, > ... > +/** > + * __page_frag_refill_prepare_align() - Prepare refilling a page_frag wi= th > + * aligning requirement. > + * @nc: page_frag cache from which to refill > + * @fragsz: the requested fragment size > + * @pfrag: the page_frag to be refilled. > + * @gfp_mask: the allocation gfp to use when cache need to be refilled > + * @align_mask: the requested aligning requirement for the fragment > + * > + * Prepare refill a page_frag from page_frag cache with aligning require= ment. "Prepare refilling ..." > + * > + * Return: > + * True if prepare refilling succeeds, otherwise return false. > + */ > ... > +/** > + * __page_frag_alloc_refill_probe_align() - Probe allocing a fragment and > + * refilling a page_frag with aligning requirement. > + * @nc: page_frag cache from which to allocate and refill > + * @fragsz: the requested fragment size > + * @pfrag: the page_frag to be refilled. > + * @align_mask: the requested aligning requirement for the fragment. > + * > + * Probe allocing a fragment and refilling a page_frag from page_frag ca= che with "Probe allocating..." > + * aligning requirement. > + * > + * Return: > + * virtual address of the page fragment, otherwise return NULL. > + */ Thanks. --=20 An old man doll... just what I always wanted! - Clara --x4TvRmf7dRhYSYeH Content-Type: application/pgp-signature; name="signature.asc" -----BEGIN PGP SIGNATURE----- iHUEABYKAB0WIQSSYQ6Cy7oyFNCHrUH2uYlJVVFOowUCZxTVQQAKCRD2uYlJVVFO o48dAP9w1/ikZVwkTZ7/6Z8gKCKSKyBXAc/aFC4yi/F/wg1m/gEAnZmKKYWDOFVX sWPxiPDgoXCZ5BkNapDzwPg3sMi+/Ak= =gYU5 -----END PGP SIGNATURE----- --x4TvRmf7dRhYSYeH--