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 971F4CFC266 for ; Tue, 15 Oct 2024 05:20:37 +0000 (UTC) Received: by kanga.kvack.org (Postfix) id 085436B0082; Tue, 15 Oct 2024 01:20:37 -0400 (EDT) Received: by kanga.kvack.org (Postfix, from userid 40) id 0355B6B008A; Tue, 15 Oct 2024 01:20:36 -0400 (EDT) X-Delivered-To: int-list-linux-mm@kvack.org Received: by kanga.kvack.org (Postfix, from userid 63042) id E3ED06B0093; Tue, 15 Oct 2024 01:20:36 -0400 (EDT) X-Delivered-To: linux-mm@kvack.org Received: from relay.hostedemail.com (smtprelay0015.hostedemail.com [216.40.44.15]) by kanga.kvack.org (Postfix) with ESMTP id C05876B0082 for ; Tue, 15 Oct 2024 01:20:36 -0400 (EDT) Received: from smtpin16.hostedemail.com (a10.router.float.18 [10.200.18.1]) by unirelay03.hostedemail.com (Postfix) with ESMTP id A93A6A138C for ; Tue, 15 Oct 2024 05:20:20 +0000 (UTC) X-FDA: 82674686304.16.DD45BCF Received: from mail-pg1-f178.google.com (mail-pg1-f178.google.com [209.85.215.178]) by imf06.hostedemail.com (Postfix) with ESMTP id 2BF3F180011 for ; Tue, 15 Oct 2024 05:20:28 +0000 (UTC) Authentication-Results: imf06.hostedemail.com; dkim=pass header.d=gmail.com header.s=20230601 header.b=dEgcT6bl; spf=pass (imf06.hostedemail.com: domain of bagasdotme@gmail.com designates 209.85.215.178 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=1728969492; 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=Z2IhkJXPFLzz+hPR/kWflHimnMzSkOTzvQDFAvHBhxY=; b=aVqGlMh3hUahQLMFcoubrQ7cnEzTpLbOZzZw3qgVc6fA+YF+HlqiI8E9KnDwjpDG6NWzcQ amaKIkZzWR0+8owgxbLTZPndDU/w0hVKjwHKqGEjflKzMVvLJ5kJNoOZaW05G6zNFshrAg fqWkZ9WMa0LBgHCx3ns5KA3US3zcPC0= ARC-Seal: i=1; s=arc-20220608; d=hostedemail.com; t=1728969492; a=rsa-sha256; cv=none; b=tAjIz4hjqSD6tsUeJchGDgHaakG2fl934NFa4BM+3LbAIaUnpInhtYYD0mQKNDmncFoWy9 qW/W+oQrduGbNFEMDylo29F3o7wNwdiGTi5tg/VUWRSw878D9neyykq82WZIYwSI53Arwd tNNk9FEYqEwvZG/DyACPxSrVfugRuM8= ARC-Authentication-Results: i=1; imf06.hostedemail.com; dkim=pass header.d=gmail.com header.s=20230601 header.b=dEgcT6bl; spf=pass (imf06.hostedemail.com: domain of bagasdotme@gmail.com designates 209.85.215.178 as permitted sender) smtp.mailfrom=bagasdotme@gmail.com; dmarc=pass (policy=none) header.from=gmail.com Received: by mail-pg1-f178.google.com with SMTP id 41be03b00d2f7-7ea7d509e61so750817a12.1 for ; Mon, 14 Oct 2024 22:20:33 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20230601; t=1728969633; x=1729574433; 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=Z2IhkJXPFLzz+hPR/kWflHimnMzSkOTzvQDFAvHBhxY=; b=dEgcT6bl1S2VtSsAkWslibhhr8xRjuN9PJ7ZAaVjPQ2/c/x0I/re/2HYq4ei0YDgbO dRF90lh8r3WueQd4Ybdf5USfMaWYmk97SKcPKzZAXQGfGl3QdJScFAcnF9SieMwpzwJA McSjJmHiOyrkHAcwy5hlKhZJShW+RLdnmM90Coow5XFMlniq465xZRab7gzsZ2tmbnH7 UOWJOr9/rk8d3tv0Y7QkUjRKdz/2CSoNvcXesiu+8c8Pf6QNesMOL3gXTPS9rlbBgqsx gwY8R2toIWBHifUl6SiuY9sCrB1Qa4AdUv6kvg8bddEIkI6x8WZIociMUTrEY/KJIuW1 pdqQ== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1728969633; x=1729574433; 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=Z2IhkJXPFLzz+hPR/kWflHimnMzSkOTzvQDFAvHBhxY=; b=qPRNOGRySqwsQMmZMEOp/73wLBrF6ECFWsq11oAZJd8rLzJBnrZNvPKxRLAZspzHEe EOp2pPkuZgCR9na7QFR3tW0m5frusdCAT/b9l0Bh2n02JEFrsZVFJUw5hDIRy/Md4JHH tnfsK98LjhVDdjSYZnjb6yybfrsFtoxddVi4vCTxflSS1iuHBA1XcUL4sCI04Ekrr2dG HXPKvQja+fImFX9dw87P0cOaOT7QmIlSseHqvbidWSHauEngSmnshNDRikKxWdFAKS/r TrZIcl1vHW+JLGcQMXbYAdfHWP7+j1G8d0rchbCkaAjYH2MA8oOSt719OzHGcSFPO2Oa xdUg== X-Forwarded-Encrypted: i=1; AJvYcCV8OHkKen033guDcwofFNAF+aLYRtr/E3YoIhTj/bKuhV3P3ulbEKMBvVchXkyEG/LuUkNJc+qvFw==@kvack.org X-Gm-Message-State: AOJu0Yy6BVUa6zfIiSsi46XpqtLWSo2tG/WlFeZvbmQMMSAecng66Oa3 4lMJNEteXvysDlLG1Iljw+41XDm1urd30hTFyHAm21epnZWIvo8k X-Google-Smtp-Source: AGHT+IH3MzNOvexbhwEGTN4Lxk5gpsONFsFijM346VGqnxk5o8siCWx9cs7S/tdiu2/LDwkXCQUQpQ== X-Received: by 2002:a05:6a21:6b0b:b0:1d2:e78d:214a with SMTP id adf61e73a8af0-1d8bcfbae38mr21602493637.44.1728969632596; Mon, 14 Oct 2024 22:20:32 -0700 (PDT) Received: from archie.me ([103.124.138.155]) by smtp.gmail.com with ESMTPSA id 98e67ed59e1d1-2e392ed3b5esm577391a91.18.2024.10.14.22.20.30 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Mon, 14 Oct 2024 22:20:31 -0700 (PDT) Received: by archie.me (Postfix, from userid 1000) id 520064250F47; Tue, 15 Oct 2024 12:20:28 +0700 (WIB) Date: Tue, 15 Oct 2024 12:20:28 +0700 From: Bagas Sanjaya To: Yunsheng Lin , davem@davemloft.net, kuba@kernel.org, pabeni@redhat.com Cc: Linux Networking , Linux Kernel Mailing List , Alexander Duyck , Jonathan Corbet , Andrew Morton , Linux Memory Management List , Linux Documentation Subject: Re: [PATCH net-next v21 13/14] mm: page_frag: update documentation for page_frag Message-ID: References: <20241012112320.2503906-1-linyunsheng@huawei.com> <20241012112320.2503906-14-linyunsheng@huawei.com> MIME-Version: 1.0 Content-Type: multipart/signed; micalg=pgp-sha512; protocol="application/pgp-signature"; boundary="uausBQGM1VviM0gB" Content-Disposition: inline In-Reply-To: <20241012112320.2503906-14-linyunsheng@huawei.com> X-Rspamd-Queue-Id: 2BF3F180011 X-Stat-Signature: sgxhewjg4dpdrndunt5jqsabdws47ado X-Rspamd-Server: rspam09 X-Rspam-User: X-HE-Tag: 1728969628-85221 X-HE-Meta: U2FsdGVkX1+i99vkBPBulIJKb4EsgliNGop5uD3hPsjRr76jT1MOD+qlIzYwZq+x+UJ4lFKTra/felL0hJ89+BdvTgvP4mBCuscfcP6UTUrPIQbaJH5G9UNERbHiVI4J5pciufwBliQF8K+aRyUuliXZKj36wG9Xm2WUZt+WkDoiKGs2eY0FQo9JcinkE0y5eIQi13D0p0jNLZUSqmFHNNOVJNDtRkusfaSR4rL2CbL+VXewv9dTVmZIDGpDSwmo91LuzYffXDsB7cqk2mgeLCyffbYuoXEJaxwqikW9DbyjT5+WPcyKKd5QaV/RXFS3hJMxuXT9/oZdIpR2MxHoqFDOslh3rcZwCC1zPEeo51E5KZx2CajNnlPYWRHxCCugWUtVwqtZIe2d23tDteCtsHNIrNDv7RGk7UL38KxVf4f94v+wYkmgAEZwafuWGnfcif2pAF0zfMUyUE11sw3gYzmxOVGEshC5j4LiZx0Y46EzYPdaJ+UI29VhoPhdF6Mmo6a8UxNsqNyyT0DJwWXmbyR/gf4A6xB2kjcfmxg4luHUiHRt+NCqojGG3X0fyjcfIZmHKG2tA60R0+1hmug8s4lE0u+ibXtxole4+1YVWTzSB4N1c/vImI7Nx+AMH6C17eQVFySQOrKG7lv+2H6SywvC8cumE5qz74epZ648Z8t1DHmgic/iSJ9hgsjVwf90TuLtcRoW5u+LUpS+k8/ujLwzs01uWeHfBjhjZLCS2uYF9Z7T9Zrpcu9ByV7ABTxipFvsOBtb19AelkCRnp0rBoH10NPb2ag+3wTDT28FuHPurwtjMvwOx/wpfZLaL53NV0NnDFp6/HVN87wu+ujXWob0HcRRU6tzXjHR4kcl/DCZquHJm6gfRZ8kE/sk8P0qQrH7zTYURSFPm3GVdNz53SyOsEPk6oAw9N+yQOmAIga2Wav/bh7HRmtmyWtXrLW67VTm0tUcmFgv6rM7p/v yZ2UMrLk Fho7NH+2+BzlrcF0XxF+0LYgU0AFHXDK7APZdGSmaYTO/fqRQtqsJEaM9Z8ROA5ImwKWaBo3RpAD3XWNi8NnVo4gOTBNM6xq2Y8sBO5v2P+ZGGmOsxgOA0m0SLeuFPFBpPY5NbCLLiADLsSD64clyEYV4ffsAVv3IQ9HeTm/meNMn1Zj1ENNtPElv588wJi8k/L91kY0lUy3BH17Z/Vfb3/cF/vivwS7HuqNkzpZWKWqxHHoSsS/nerRUCHYCtvWg0OuVNO7uVuEo8yLs7cPnJv94KB+LkuEe/8FBm8VR6juz/NJlfiIYteqmoLezYANi/5nYUpehPTKxnCq8MpNdrI2yURX1GrNzwQR2Tt81nF3K89GU5n9RjCeMOsGVvlfF+zotpzyp+SiPcWJe+in7+hjfgEXyICe9s6sYy+8O4iGT/mqdlZKQYERUfda5eaKQLE24lbh/KdwX18AcmLXCRVPmTc5pid9scNYxGv9dgMYCkBp50eiWZmZZfPhBOQKrjd4bYiL1DLWA1bkx2jSIAtB9zN4hZPj5peWaTjnC9iLd4YHcQTdeqLSERe6usz9m4lHnYKA3eOSQ0xfEwUKDufin9ocW8JErbRJq 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: --uausBQGM1VviM0gB Content-Type: text/plain; charset=utf-8 Content-Disposition: inline Content-Transfer-Encoding: quoted-printable On Sat, Oct 12, 2024 at 07:23:19PM +0800, Yunsheng Lin wrote: > +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. Looks OK. > +Coding examples > +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D > + > +Init & Drain API > +---------------- Initialization and draining API? > +Alloc & Free API > +---------------- Shouldn't it be called allocation API? > +Prepare & Commit API > +-------------------- This one looks OK. > +/** > + * page_frag_cache_init() - Init page_frag cache. > + * @nc: page_frag cache from which to init > + * > + * Inline helper to init the page_frag cache. > + */ s/Init/Initialize/ > static inline void page_frag_cache_init(struct page_frag_cache *nc) > { > nc->encoded_page =3D 0; > } > =20 > +/** > + * 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 pfmemalloc'ed. is allocated by = pfmemalloc()? > + * It has the same calling context expectation as the alloc API. > + * > + * Return: > + * true if the current page in page_frag cache is pfmemalloc'ed, otherwi= se > + * return false. > + */ > static inline bool page_frag_cache_is_pfmemalloc(struct page_frag_cache = *nc) > { > return encoded_page_decode_pfmemalloc(nc->encoded_page); > } > =20 > +/** > + * page_frag_cache_page_offset() - Return the current page fragment's of= fset. > + * @nc: page_frag cache from which to check > + * > + * The API is only used in net/sched/em_meta.c for historical reason, do= not use > + * it for new caller unless there is a strong reason. Then what does page_frag_cache_page_offset() do then? > + * > + * Return: > + * the offset of the current page fragment in the page_frag cache. > + */ > static inline unsigned int page_frag_cache_page_offset(const struct page= _frag_cache *nc) > { > return nc->offset; > @@ -66,6 +93,19 @@ static inline unsigned int __page_frag_cache_commit(st= ruct page_frag_cache *nc, > return __page_frag_cache_commit_noref(nc, pfrag, used_sz); > } > =20 > +/** > + * __page_frag_alloc_align() - Alloc a page fragment with aligning > + * requirement. > + * @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 > + * @align_mask: the requested aligning requirement for the 'va' > + * > + * Alloc a page fragment from page_frag cache with aligning requirement. Allocate > + * > + * Return: > + * Virtual address of the page fragment, otherwise return NULL. > + */ > static inline void *__page_frag_alloc_align(struct page_frag_cache *nc, > unsigned int fragsz, gfp_t gfp_mask, > unsigned int align_mask) > @@ -83,6 +123,19 @@ static inline void *__page_frag_alloc_align(struct pa= ge_frag_cache *nc, > return va; > } > =20 > +/** > + * page_frag_alloc_align() - Alloc a page fragment with aligning require= ment. > + * @nc: page_frag cache from which to allocate > + * @fragsz: the requested fragment size > + * @gfp_mask: the allocation gfp to use when cache needs to be refilled > + * @align: the requested aligning requirement for the fragment > + * > + * WARN_ON_ONCE() checking for @align before allocing a page fragment fr= om allocating > + * page_frag cache with aligning requirement. > + * > + * Return: > + * virtual address of the page fragment, otherwise return NULL. > + */ > static inline void *page_frag_alloc_align(struct page_frag_cache *nc, > unsigned int fragsz, gfp_t gfp_mask, > unsigned int align) > @@ -91,12 +144,36 @@ static inline void *page_frag_alloc_align(struct pag= e_frag_cache *nc, > return __page_frag_alloc_align(nc, fragsz, gfp_mask, -align); > } > =20 > +/** > + * page_frag_alloc() - Alloc 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 > + * > + * Return: > + * virtual address of the page fragment, otherwise return NULL. > + */ > static inline void *page_frag_alloc(struct page_frag_cache *nc, > unsigned int fragsz, gfp_t gfp_mask) > { > return __page_frag_alloc_align(nc, fragsz, gfp_mask, ~0u); > } > =20 > +/** > + * __page_frag_alloc_refill_prepare_align() - Prepare allocing a fragmen= t 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. > + * @gfp_mask: the allocation gfp to use when cache need to be refilled > + * @align_mask: the requested aligning requirement for the fragment. > + * > + * Prepare allocing a fragment and refilling a page_frag from page_frag = cache. Prepare allocating? > + * > + * Return: > + * virtual address of the page fragment, otherwise return NULL. > + */ > static inline void *__page_frag_alloc_refill_prepare_align(struct page_f= rag_cache *nc, > unsigned int fragsz, > struct page_frag *pfrag, > @@ -166,6 +324,21 @@ static inline void *__page_frag_alloc_refill_prepare= _align(struct page_frag_cach > return __page_frag_cache_prepare(nc, fragsz, pfrag, gfp_mask, align_mas= k); > } Thanks. --=20 An old man doll... just what I always wanted! - Clara --uausBQGM1VviM0gB Content-Type: application/pgp-signature; name="signature.asc" -----BEGIN PGP SIGNATURE----- iHUEABYKAB0WIQSSYQ6Cy7oyFNCHrUH2uYlJVVFOowUCZw37lwAKCRD2uYlJVVFO ozsyAQD/vI8ZDKqg1/mPx9QCFewRQlcaTj1hUmavIjvE6eMZIwD+MJo+IyfxYIMz Vejvd38012SypK8hEnXwGWhvPMavcwU= =GCX2 -----END PGP SIGNATURE----- --uausBQGM1VviM0gB--