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 6D6B8C433FE for ; Tue, 5 Apr 2022 05:48:47 +0000 (UTC) Received: by kanga.kvack.org (Postfix) id CB0056B0071; Tue, 5 Apr 2022 01:48:36 -0400 (EDT) Received: by kanga.kvack.org (Postfix, from userid 40) id C60E56B0073; Tue, 5 Apr 2022 01:48:36 -0400 (EDT) X-Delivered-To: int-list-linux-mm@kvack.org Received: by kanga.kvack.org (Postfix, from userid 63042) id B27756B0074; Tue, 5 Apr 2022 01:48:36 -0400 (EDT) X-Delivered-To: linux-mm@kvack.org Received: from forelay.hostedemail.com (smtprelay0067.hostedemail.com [216.40.44.67]) by kanga.kvack.org (Postfix) with ESMTP id 9FC856B0071 for ; Tue, 5 Apr 2022 01:48:36 -0400 (EDT) Received: from smtpin23.hostedemail.com (10.5.19.251.rfc1918.com [10.5.19.251]) by forelay02.hostedemail.com (Postfix) with ESMTP id 57F26AAAF9 for ; Tue, 5 Apr 2022 05:48:26 +0000 (UTC) X-FDA: 79321745412.23.FD65EA0 Received: from smtp-out2.suse.de (smtp-out2.suse.de [195.135.220.29]) by imf20.hostedemail.com (Postfix) with ESMTP id BA6951C0019 for ; Tue, 5 Apr 2022 05:48:25 +0000 (UTC) Received: from imap2.suse-dmz.suse.de (imap2.suse-dmz.suse.de [192.168.254.74]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature ECDSA (P-521) server-digest SHA512) (No client certificate requested) by smtp-out2.suse.de (Postfix) with ESMTPS id 59FF91F38C; Tue, 5 Apr 2022 05:48:24 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=suse.de; s=susede2_rsa; t=1649137704; h=from:from:reply-to:date:date:message-id:message-id:to:to:cc:cc: mime-version:mime-version:content-type:content-type: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references; bh=1r2orMrVQp/4ILk838S1tDzUbcjwXJeLpgvBNYW22Ck=; b=HC72URascQxUqzcuXkfB+sEZA54o97vGoK5spXM0ibpz+w23NT1NuCASZtgNDsN+6T6N03 9U3bPZKROCgLzp6OKRhIx1UlawtZRAafvcyaSqpXw+9GFLtimOiMLHbegz3+DD6fbHVB79 GsHVeMWiOkRmbt0uvvTXSXTZ7FwNd+A= DKIM-Signature: v=1; a=ed25519-sha256; c=relaxed/relaxed; d=suse.de; s=susede2_ed25519; t=1649137704; h=from:from:reply-to:date:date:message-id:message-id:to:to:cc:cc: mime-version:mime-version:content-type:content-type: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references; bh=1r2orMrVQp/4ILk838S1tDzUbcjwXJeLpgvBNYW22Ck=; b=5wcdIsL9plpl8ZiUGcInouKSsFfnwSu1Ty4HkDbJZLsVBGtcSmEWnrpY/GfvfwnzcHRXiv yy19/2oPrV+i7zBg== Received: from imap2.suse-dmz.suse.de (imap2.suse-dmz.suse.de [192.168.254.74]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature ECDSA (P-521) server-digest SHA512) (No client certificate requested) by imap2.suse-dmz.suse.de (Postfix) with ESMTPS id C070913216; Tue, 5 Apr 2022 05:48:22 +0000 (UTC) Received: from dovecot-director2.suse.de ([192.168.254.65]) by imap2.suse-dmz.suse.de with ESMTPSA id gqqVHybYS2KaSAAAMHmgww (envelope-from ); Tue, 05 Apr 2022 05:48:22 +0000 Content-Type: text/plain; charset="utf-8" Content-Transfer-Encoding: quoted-printable MIME-Version: 1.0 From: "NeilBrown" To: "Matthew Wilcox" Cc: linux-doc@vger.kernel.org, linux-mm@kvack.org, linux-fsdevel@vger.kernel.org, "Miaohe Lin" Subject: Re: [RFC] Documentation for folio_lock() and friends In-reply-to: References: Date: Tue, 05 Apr 2022 15:48:19 +1000 Message-id: <164913769939.10985.13675614818955421206@noble.neil.brown.name> X-Rspam-User: X-Stat-Signature: hiraazqieaibznhhhjnnymtjptp4mayb Authentication-Results: imf20.hostedemail.com; dkim=pass header.d=suse.de header.s=susede2_rsa header.b=HC72URas; dkim=pass header.d=suse.de header.s=susede2_ed25519 header.b=5wcdIsL9; spf=pass (imf20.hostedemail.com: domain of neilb@suse.de designates 195.135.220.29 as permitted sender) smtp.mailfrom=neilb@suse.de; dmarc=pass (policy=none) header.from=suse.de X-Rspamd-Server: rspam01 X-Rspamd-Queue-Id: BA6951C0019 X-HE-Tag: 1649137705-719492 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: On Tue, 05 Apr 2022, Matthew Wilcox wrote: > It's a shame to not have these functions documented. I'm sure I've > missed a few things that would be useful to document here. >=20 > diff --git a/include/linux/pagemap.h b/include/linux/pagemap.h > index ab47579af434..47b7851f1b64 100644 > --- a/include/linux/pagemap.h > +++ b/include/linux/pagemap.h > @@ -888,6 +888,18 @@ bool __folio_lock_or_retry(struct folio *folio, struct= mm_struct *mm, > void unlock_page(struct page *page); > void folio_unlock(struct folio *folio); > =20 > +/** > + * folio_trylock() - Attempt to lock a folio. > + * @folio: The folio to attempt to lock. > + * > + * Sometimes it is undesirable to wait for a folio to be unlocked (eg > + * when the locks are being taken in the wrong order, or if making > + * progress through a batch of folios is more important than processing > + * them in order). Usually folio_lock() is the correct function to call. Usually? I think a "see also" type reference to folio_lock() is useful, but I don't think "usually" is helpful. > + * > + * Context: Any context. > + * Return: Whether the lock was successfully acquired. > + */ > static inline bool folio_trylock(struct folio *folio) > { > return likely(!test_and_set_bit_lock(PG_locked, folio_flags(folio, 0))); > @@ -901,6 +913,26 @@ static inline int trylock_page(struct page *page) > return folio_trylock(page_folio(page)); > } > =20 > +/** > + * folio_lock() - Lock this folio. > + * @folio: The folio to lock. > + * > + * The folio lock protects against many things, probably more than it > + * should. It is primarily held while a folio is being read from storage, > + * either from its backing file or from swap. It is also held while a > + * folio is being truncated from its address_space. > + * > + * Holding the lock usually prevents the contents of the folio from being > + * modified by other kernel users, although it does not prevent userspace > + * from modifying data if it's mapped. The lock is not consistently held > + * while a folio is being modified by DMA. I don't think this paragraph is helpful... maybe if it listed which change *are* prevented by the lock, rather than a few which aren't? I think it is significant that the lock prevents removal from the page cache, and so ->mapping is only stable while the lock is held. It might be worth adding something about that. > + * > + * Context: May sleep. If you need to acquire the locks of two or > + * more folios, they must be in order of ascending index, if they are > + * in the same address_space. If they are in different address_spaces, > + * acquire the lock of the folio which belongs to the address_space which > + * has the lowest address in memory first. > + */ > static inline void folio_lock(struct folio *folio) > { > might_sleep(); > @@ -908,6 +940,17 @@ static inline void folio_lock(struct folio *folio) > __folio_lock(folio); > } > =20 > +/** > + * lock_page() - Lock the folio containing this page. > + * @page: The page to lock. > + * > + * See folio_lock() for a description of what the lock protects. > + * This is a legacy function and new code should probably use folio_lock() > + * instead. > + * > + * Context: May sleep. Pages in the same folio share a lock, so do not > + * attempt to lock two pages which share a folio. > + */ > static inline void lock_page(struct page *page) > { > struct folio *folio; > @@ -918,6 +961,16 @@ static inline void lock_page(struct page *page) > __folio_lock(folio); > } > =20 > +/** > + * folio_lock_killable() - Lock this folio, interruptible by a fatal signa= l. > + * @folio: The folio to lock. > + * > + * Attempts to lock the folio, like folio_lock(), except that the sleep > + * to acquire the lock is interruptible by a fatal signal. > + * > + * Context: May sleep; see folio_lock(). > + * Return: 0 if the lock was acquired; -EINTR if a fatal signal was receiv= ed. > + */ > static inline int folio_lock_killable(struct folio *folio) > { > might_sleep(); > @@ -964,8 +1017,8 @@ int folio_wait_bit_killable(struct folio *folio, int b= it_nr); > * Wait for a folio to be unlocked. > * > * This must be called with the caller "holding" the folio, > - * ie with increased "page->count" so that the folio won't > - * go away during the wait.. > + * ie with increased folio reference count so that the folio won't > + * go away during the wait. > */ > static inline void folio_wait_locked(struct folio *folio) > { >=20 >=20 Thanks, NeilBrown