From patchwork Fri Jun 2 22:24:39 2023 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: "Matthew Wilcox (Oracle)" X-Patchwork-Id: 13265924 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 3243DC77B7A for ; Fri, 2 Jun 2023 22:24:58 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S236140AbjFBWY4 (ORCPT ); Fri, 2 Jun 2023 18:24:56 -0400 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:33780 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S235469AbjFBWYz (ORCPT ); Fri, 2 Jun 2023 18:24:55 -0400 Received: from casper.infradead.org (casper.infradead.org [IPv6:2001:8b0:10b:1236::1]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id 271401BC; Fri, 2 Jun 2023 15:24:54 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=infradead.org; s=casper.20170209; h=Content-Transfer-Encoding:MIME-Version: References:In-Reply-To:Message-Id:Date:Subject:Cc:To:From:Sender:Reply-To: Content-Type:Content-ID:Content-Description; bh=Zh3vwPttBvras0W9xMfJik9g+4v5Ww/hZDI6n4H8e78=; b=pM5IUzBsEY/vQ/Nwzm+o5XiibG IOpgqcvsClLvAZJelssepb3n2OTF2AW+HrocgmfIPiDeyzGorPuH3Jr+56+KFiXs/OplCEkrjlYHd 9ZDQjtG9cG6C4B+/D77rKvCcXi7gZk/dSBWUn+Y5mBtsYyrX3qH1a3Z88bDDf4ntLVqrSnXGUQtly faF3JtRTar1aY9Ay2gT32DS+n8JHW0TybRVImNbzp1jSzm383SwBZ/Lz9ieycACTOXRtF3EqTci6s 32ZNZvVTVQWuW5BMR9dua0bAP8NaH6Tz0TCA2wAtLw2k8adz7h9+wQO1QbgfvoGSTliA1tMFmO5Rc 2lD87zRg==; Received: from willy by casper.infradead.org with local (Exim 4.94.2 #2 (Red Hat Linux)) id 1q5DCQ-009aPK-Pp; Fri, 02 Jun 2023 22:24:46 +0000 From: "Matthew Wilcox (Oracle)" To: linux-fsdevel@vger.kernel.org Cc: "Matthew Wilcox (Oracle)" , linux-xfs@vger.kernel.org, Wang Yugui , Dave Chinner , Christoph Hellwig , "Darrick J . Wong" Subject: [PATCH v2 2/7] doc: Correct the description of ->release_folio Date: Fri, 2 Jun 2023 23:24:39 +0100 Message-Id: <20230602222445.2284892-3-willy@infradead.org> X-Mailer: git-send-email 2.37.1 In-Reply-To: <20230602222445.2284892-1-willy@infradead.org> References: <20230602222445.2284892-1-willy@infradead.org> MIME-Version: 1.0 Precedence: bulk List-ID: X-Mailing-List: linux-xfs@vger.kernel.org The filesystem ->release_folio method is called under more circumstances now than when the documentation was written. The second sentence describing the interpretation of the return value is the wrong polarity (false indicates failure, not success). And the third sentence is also wrong (the kernel calls try_to_free_buffers() instead). So replace the entire paragraph with a detailed description of what the state of the folio may be, the meaning of the gfp parameter, why the method is being called and what the filesystem is expected to do. Signed-off-by: Matthew Wilcox (Oracle) Reviewed-by: Darrick J. Wong Reviewed-by: Christoph Hellwig Reviewed-by: Darrick J. Wong --- Documentation/filesystems/locking.rst | 14 ++++++++++---- 1 file changed, 10 insertions(+), 4 deletions(-) diff --git a/Documentation/filesystems/locking.rst b/Documentation/filesystems/locking.rst index aa1a233b0fa8..91dc9d5bc602 100644 --- a/Documentation/filesystems/locking.rst +++ b/Documentation/filesystems/locking.rst @@ -374,10 +374,16 @@ invalidate_lock before invalidating page cache in truncate / hole punch path (and thus calling into ->invalidate_folio) to block races between page cache invalidation and page cache filling functions (fault, read, ...). -->release_folio() is called when the kernel is about to try to drop the -buffers from the folio in preparation for freeing it. It returns false to -indicate that the buffers are (or may be) freeable. If ->release_folio is -NULL, the kernel assumes that the fs has no private interest in the buffers. +->release_folio() is called when the MM wants to make a change to the +folio that would invalidate the filesystem's private data. For example, +it may be about to be removed from the address_space or split. The folio +is locked and not under writeback. It may be dirty. The gfp parameter is +not usually used for allocation, but rather to indicate what the filesystem +may do to attempt to free the private data. The filesystem may +return false to indicate that the folio's private data cannot be freed. +If it returns true, it should have already removed the private data from +the folio. If a filesystem does not provide a ->release_folio method, +the kernel will call try_to_free_buffers(). ->free_folio() is called when the kernel has dropped the folio from the page cache.