From patchwork Tue Apr 16 03:17:45 2024 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Matthew Wilcox X-Patchwork-Id: 13631137 Received: from casper.infradead.org (casper.infradead.org [90.155.50.34]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by smtp.subspace.kernel.org (Postfix) with ESMTPS id D40931C6A8; Tue, 16 Apr 2024 03:18:00 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=90.155.50.34 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1713237482; cv=none; b=nvEhLBLbBVm6qGD0/DMRthO4DptJmFVNmDzZxukS4CVMKh49IWLgo72xgMCK+wa/LI4NRnsG1HWBAfDNNMuRigI/IbX3ZG886LbwCm10vgPNDqF7kwWlmTVHLaCyv9FoJW25WnbJDvk8tyTCbAhiomm3NkgUG9Nn3TyLzR0DZ9U= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1713237482; c=relaxed/simple; bh=PETw0eDtqxHmcHBtZCsfJPMLTBLDTPyLoOaXeSy7CdM=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=CKrmOriUClgTGdUs/tNpvChHIS1abKsmJV2Kbc1bZZkoFpxTdBQCS1TRyR+jgNsu3iyKOr210m7K0G01eFJI2srumPt7Cx7tcOYb1efIPUGZFnO3YCYNiiKyRK8owJIhpn7WLBYtsejuWVhf6VZaOV2zU7w9Vezh4Dw9ylz0kPw= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dmarc=none (p=none dis=none) header.from=infradead.org; spf=none smtp.mailfrom=infradead.org; dkim=pass (2048-bit key) header.d=infradead.org header.i=@infradead.org header.b=AaZld52W; arc=none smtp.client-ip=90.155.50.34 Authentication-Results: smtp.subspace.kernel.org; dmarc=none (p=none dis=none) header.from=infradead.org Authentication-Results: smtp.subspace.kernel.org; spf=none smtp.mailfrom=infradead.org Authentication-Results: smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=infradead.org header.i=@infradead.org header.b="AaZld52W" 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=frJu9FO9nwWcCqa63oYNqDsCSg+xZY7bhlunSAGmIxk=; b=AaZld52WYWilUb4dfckZ0N3fZx W+7cQ5V6++2YRA+//80KybGlwsBYXfYYhyjUdjC9qWP3iiWn6lBHAlcgwlxpvy/FY2mLGPElaJbih babVqBvhQiZQ93I1K1H9d4yr53b8RrcbzaY4Hei2s5pq496hbe85W5vBqaFX6mXlD2GpD0USO+Vic kmshZuRNhM78CBlyejCyoSd0oHIRoEjNJSx3XvibSAAIFeYutSeRUIx6KoMYQvc0NnUn7iT5IEFT9 PXvCjKacaYzH0bNo2I9ZJohYCf4ga/3fLGDW7E7pHIbUPjWRjsPz04kOTlYkrD2jbdZ1Nw17o+wGi 6VOIavcQ==; Received: from willy by casper.infradead.org with local (Exim 4.97.1 #2 (Red Hat Linux)) id 1rwZKV-0000000H6au-3oL8; Tue, 16 Apr 2024 03:17:55 +0000 From: "Matthew Wilcox (Oracle)" To: Andrew Morton Cc: "Matthew Wilcox (Oracle)" , linux-fsdevel@vger.kernel.org, linux-doc@vger.kernel.org Subject: [PATCH v3 1/8] doc: Improve the description of __folio_mark_dirty Date: Tue, 16 Apr 2024 04:17:45 +0100 Message-ID: <20240416031754.4076917-2-willy@infradead.org> X-Mailer: git-send-email 2.44.0 In-Reply-To: <20240416031754.4076917-1-willy@infradead.org> References: <20240416031754.4076917-1-willy@infradead.org> Precedence: bulk X-Mailing-List: linux-fsdevel@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 I've learned why it's safe to call __folio_mark_dirty() from mark_buffer_dirty() without holding the folio lock, so update the description to explain why. Signed-off-by: Matthew Wilcox (Oracle) --- mm/page-writeback.c | 14 +++++++++----- 1 file changed, 9 insertions(+), 5 deletions(-) diff --git a/mm/page-writeback.c b/mm/page-writeback.c index 62f28fe26511..bd91d5761e39 100644 --- a/mm/page-writeback.c +++ b/mm/page-writeback.c @@ -2706,11 +2706,15 @@ void folio_account_cleaned(struct folio *folio, struct bdi_writeback *wb) * If warn is true, then emit a warning if the folio is not uptodate and has * not been truncated. * - * The caller must hold folio_memcg_lock(). Most callers have the folio - * locked. A few have the folio blocked from truncation through other - * means (eg zap_vma_pages() has it mapped and is holding the page table - * lock). This can also be called from mark_buffer_dirty(), which I - * cannot prove is always protected against truncate. + * The caller must hold folio_memcg_lock(). It is the caller's + * responsibility to prevent the folio from being truncated while + * this function is in progress, although it may have been truncated + * before this function is called. Most callers have the folio locked. + * A few have the folio blocked from truncation through other means (e.g. + * zap_vma_pages() has it mapped and is holding the page table lock). + * When called from mark_buffer_dirty(), the filesystem should hold a + * reference to the buffer_head that is being marked dirty, which causes + * try_to_free_buffers() to fail. */ void __folio_mark_dirty(struct folio *folio, struct address_space *mapping, int warn) From patchwork Tue Apr 16 03:17:46 2024 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Matthew Wilcox X-Patchwork-Id: 13631140 Received: from casper.infradead.org (casper.infradead.org [90.155.50.34]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by smtp.subspace.kernel.org (Postfix) with ESMTPS id F41EE17550; Tue, 16 Apr 2024 03:18:03 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=90.155.50.34 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1713237485; cv=none; b=oq2E/CgmTP0syFydbS92Qqk7aePBYtichgbYUTHdW2mOyasaSNQ4/ZErSeb1X9lpFe4U5aNf7apvRt5OlIBzpCN6JO44LomOgOwUOBdDBxZQ5AXuFbAf1cMP3DMQMSNfboELfXjO9QmDqkOby1L7UAOWcQEvvu3OvmBVWEkUbPw= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1713237485; c=relaxed/simple; bh=nqkpEUdbg/EMVD3A1w81m+jCUYlbzdILtMgTK3K6UhY=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=AEYLBFq5xv7GtUSg0nlDe4favWoCTKJN71pbDG7KfWv7btCCc43K1iqIbWq/aQkDafq5YNI/4a5ki0P/kI3hc2qZLfmCpAnoXUy1OTP0Ry9DGwICIjdh3xDroAnhKgYgTO4pFk4pI1o+q/5T8vS8mUUaTorXQ5jccRaJDzdeHms= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dmarc=none (p=none dis=none) header.from=infradead.org; spf=none smtp.mailfrom=infradead.org; dkim=pass (2048-bit key) header.d=infradead.org header.i=@infradead.org header.b=WWGZ5zPx; arc=none smtp.client-ip=90.155.50.34 Authentication-Results: smtp.subspace.kernel.org; dmarc=none (p=none dis=none) header.from=infradead.org Authentication-Results: smtp.subspace.kernel.org; spf=none smtp.mailfrom=infradead.org Authentication-Results: smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=infradead.org header.i=@infradead.org header.b="WWGZ5zPx" 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=GOZyBLWge7qyAz30yvc9tiHbIMnsiWg9t4KEJ/+nXC4=; b=WWGZ5zPxAnL0RNs2k93S9gQ2qz FQxUJIOGwQcnZ2tutDutooQ3fBX2ZBHTauGFCLmjtnXT/N/nckX//d5N4D+rpKiOwvcfQvXpRZkpi izppwNkjbmUCycM5sZHa6p5qF/NWYKcFjuaBXJEnSucfZtkJCnfMdC27uNMcsxt9RqbxjZcXDFr96 +f9lR87GqkKJ/PyH8MG4aAF9UvUBILcLC1OHACV0vPt0v8LA7nN6a5hhE3ydSKcb1OeserZ/BVnXt xGCwQcK7zjVVxXsSNTijpWPlGjzvNYf51N04GVKfso4jsnxRg0uz9NlSlf6DdAFwaZlsFHrxqn4lH Aj00ipVA==; Received: from willy by casper.infradead.org with local (Exim 4.97.1 #2 (Red Hat Linux)) id 1rwZKV-0000000H6aw-4AGj; Tue, 16 Apr 2024 03:17:56 +0000 From: "Matthew Wilcox (Oracle)" To: Andrew Morton Cc: "Matthew Wilcox (Oracle)" , linux-fsdevel@vger.kernel.org, linux-doc@vger.kernel.org, Pankaj Raghav Subject: [PATCH v3 2/8] buffer: Add kernel-doc for block_dirty_folio() Date: Tue, 16 Apr 2024 04:17:46 +0100 Message-ID: <20240416031754.4076917-3-willy@infradead.org> X-Mailer: git-send-email 2.44.0 In-Reply-To: <20240416031754.4076917-1-willy@infradead.org> References: <20240416031754.4076917-1-willy@infradead.org> Precedence: bulk X-Mailing-List: linux-fsdevel@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Turn the excellent documentation for this function into kernel-doc. Replace 'page' with 'folio' and make a few other minor updates. Signed-off-by: Matthew Wilcox (Oracle) Reviewed-by: Pankaj Raghav Tested-by: Randy Dunlap --- fs/buffer.c | 55 ++++++++++++++++++++++++++++++----------------------- 1 file changed, 31 insertions(+), 24 deletions(-) diff --git a/fs/buffer.c b/fs/buffer.c index 4f73d23c2c46..b08526bdcb54 100644 --- a/fs/buffer.c +++ b/fs/buffer.c @@ -687,30 +687,37 @@ void mark_buffer_dirty_inode(struct buffer_head *bh, struct inode *inode) } EXPORT_SYMBOL(mark_buffer_dirty_inode); -/* - * Add a page to the dirty page list. - * - * It is a sad fact of life that this function is called from several places - * deeply under spinlocking. It may not sleep. - * - * If the page has buffers, the uptodate buffers are set dirty, to preserve - * dirty-state coherency between the page and the buffers. It the page does - * not have buffers then when they are later attached they will all be set - * dirty. - * - * The buffers are dirtied before the page is dirtied. There's a small race - * window in which a writepage caller may see the page cleanness but not the - * buffer dirtiness. That's fine. If this code were to set the page dirty - * before the buffers, a concurrent writepage caller could clear the page dirty - * bit, see a bunch of clean buffers and we'd end up with dirty buffers/clean - * page on the dirty page list. - * - * We use i_private_lock to lock against try_to_free_buffers while using the - * page's buffer list. Also use this to protect against clean buffers being - * added to the page after it was set dirty. - * - * FIXME: may need to call ->reservepage here as well. That's rather up to the - * address_space though. +/** + * block_dirty_folio - Mark a folio as dirty. + * @mapping: The address space containing this folio. + * @folio: The folio to mark dirty. + * + * Filesystems which use buffer_heads can use this function as their + * ->dirty_folio implementation. Some filesystems need to do a little + * work before calling this function. Filesystems which do not use + * buffer_heads should call filemap_dirty_folio() instead. + * + * If the folio has buffers, the uptodate buffers are set dirty, to + * preserve dirty-state coherency between the folio and the buffers. + * Buffers added to a dirty folio are created dirty. + * + * The buffers are dirtied before the folio is dirtied. There's a small + * race window in which writeback may see the folio cleanness but not the + * buffer dirtiness. That's fine. If this code were to set the folio + * dirty before the buffers, writeback could clear the folio dirty flag, + * see a bunch of clean buffers and we'd end up with dirty buffers/clean + * folio on the dirty folio list. + * + * We use i_private_lock to lock against try_to_free_buffers() while + * using the folio's buffer list. This also prevents clean buffers + * being added to the folio after it was set dirty. + * + * Context: May only be called from process context. Does not sleep. + * Caller must ensure that @folio cannot be truncated during this call, + * typically by holding the folio lock or having a page in the folio + * mapped and holding the page table lock. + * + * Return: True if the folio was dirtied; false if it was already dirtied. */ bool block_dirty_folio(struct address_space *mapping, struct folio *folio) { From patchwork Tue Apr 16 03:17:47 2024 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Matthew Wilcox X-Patchwork-Id: 13631138 Received: from casper.infradead.org (casper.infradead.org [90.155.50.34]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by smtp.subspace.kernel.org (Postfix) with ESMTPS id 45FF82110F; Tue, 16 Apr 2024 03:18:00 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=90.155.50.34 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1713237482; cv=none; b=CEFe/k2vcXjAviSx41dsDuqTWUWNrmKVDLZOSl7rgi408YxJqjsmDe1AX0SDTz9IynwuYUwmf5Q1SrFRGWS+bIqbpS2gR0E6cyJQzczNE6InKj9WpU4/oX5vonys9PnA8JmfRUhlXNWCarcxanpyCwQaC3tsm8iItOxidVBhNaY= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1713237482; c=relaxed/simple; bh=9NvoCCyUkA9ND3Xcd1/YQvCMqfALf0ZYmG86TlVkXvo=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=RXHiJG7SL6J2YVudajMWTF/wmGl7Xto7jY7hv1RuyrTiK4X2KXxc9MVqHCdzTcAtIoqFoflLyrrY6BmwOtpFNKjKf7GB3fw4Dx6v/7lONxytCU+lY5DrqUOAXYh2pVtXRG2cf/Jz6vuvFq+CyUIYYoaaVnbkwFmK2pBX8DijVPI= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dmarc=none (p=none dis=none) header.from=infradead.org; spf=none smtp.mailfrom=infradead.org; dkim=pass (2048-bit key) header.d=infradead.org header.i=@infradead.org header.b=UVdWMa7d; arc=none smtp.client-ip=90.155.50.34 Authentication-Results: smtp.subspace.kernel.org; dmarc=none (p=none dis=none) header.from=infradead.org Authentication-Results: smtp.subspace.kernel.org; spf=none smtp.mailfrom=infradead.org Authentication-Results: smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=infradead.org header.i=@infradead.org header.b="UVdWMa7d" 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=lpOFS2AKUdDWSXV132Y4ki1FMs3P3eJdhkcMjclknoI=; b=UVdWMa7d6K7PyViC4z6/BC4Ofe H99ytGmyycFiro8CSRxhP0RxrPHJSZhzWDLPOeIT3Pt5QtfZOVpF/JiKKqp2XCo6N/wvSOWVs9Awt u3xV+h+p4bHhoNCaWycEtRdhvYQG9TZTvKFoAmt5CdH+qLRDS9CKTrcttbA4pcx9qwZx0iwqV7iYH 3mYKWA8dM0Ct+8i/vmwCf+DSnVNKUQr9a+Am7uWyCRqg74DYYBJDvNGLHAw9GAJZtB42Bp7e0QIZA M1+utYnL/5nlMX/jOrFOsOOoSgtOqsBJxVSp4oaot9JZgl0PhZxGZVJTVH4+WAXLrqPeXcVHmOb8w tLp0jdyQ==; Received: from willy by casper.infradead.org with local (Exim 4.97.1 #2 (Red Hat Linux)) id 1rwZKW-0000000H6ay-0Jp5; Tue, 16 Apr 2024 03:17:56 +0000 From: "Matthew Wilcox (Oracle)" To: Andrew Morton Cc: "Matthew Wilcox (Oracle)" , linux-fsdevel@vger.kernel.org, linux-doc@vger.kernel.org, Pankaj Raghav Subject: [PATCH v3 3/8] buffer: Add kernel-doc for try_to_free_buffers() Date: Tue, 16 Apr 2024 04:17:47 +0100 Message-ID: <20240416031754.4076917-4-willy@infradead.org> X-Mailer: git-send-email 2.44.0 In-Reply-To: <20240416031754.4076917-1-willy@infradead.org> References: <20240416031754.4076917-1-willy@infradead.org> Precedence: bulk X-Mailing-List: linux-fsdevel@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 The documentation for this function has become separated from it over time; move it to the right place and turn it into kernel-doc. Mild editing of the content to make it more about what the function does, and less about how it does it. Signed-off-by: Matthew Wilcox (Oracle) Reviewed-by: Pankaj Raghav Tested-by: Randy Dunlap --- fs/buffer.c | 44 ++++++++++++++++++++++++-------------------- 1 file changed, 24 insertions(+), 20 deletions(-) diff --git a/fs/buffer.c b/fs/buffer.c index b08526bdcb54..0466ed7ed95a 100644 --- a/fs/buffer.c +++ b/fs/buffer.c @@ -2868,26 +2868,6 @@ int sync_dirty_buffer(struct buffer_head *bh) } EXPORT_SYMBOL(sync_dirty_buffer); -/* - * try_to_free_buffers() checks if all the buffers on this particular folio - * are unused, and releases them if so. - * - * Exclusion against try_to_free_buffers may be obtained by either - * locking the folio or by holding its mapping's i_private_lock. - * - * If the folio is dirty but all the buffers are clean then we need to - * be sure to mark the folio clean as well. This is because the folio - * may be against a block device, and a later reattachment of buffers - * to a dirty folio will set *all* buffers dirty. Which would corrupt - * filesystem data on the same device. - * - * The same applies to regular filesystem folios: if all the buffers are - * clean then we set the folio clean and proceed. To do that, we require - * total exclusion from block_dirty_folio(). That is obtained with - * i_private_lock. - * - * try_to_free_buffers() is non-blocking. - */ static inline int buffer_busy(struct buffer_head *bh) { return atomic_read(&bh->b_count) | @@ -2921,6 +2901,30 @@ drop_buffers(struct folio *folio, struct buffer_head **buffers_to_free) return false; } +/** + * try_to_free_buffers - Release buffers attached to this folio. + * @folio: The folio. + * + * If any buffers are in use (dirty, under writeback, elevated refcount), + * no buffers will be freed. + * + * If the folio is dirty but all the buffers are clean then we need to + * be sure to mark the folio clean as well. This is because the folio + * may be against a block device, and a later reattachment of buffers + * to a dirty folio will set *all* buffers dirty. Which would corrupt + * filesystem data on the same device. + * + * The same applies to regular filesystem folios: if all the buffers are + * clean then we set the folio clean and proceed. To do that, we require + * total exclusion from block_dirty_folio(). That is obtained with + * i_private_lock. + * + * Exclusion against try_to_free_buffers may be obtained by either + * locking the folio or by holding its mapping's i_private_lock. + * + * Context: Process context. @folio must be locked. Will not sleep. + * Return: true if all buffers attached to this folio were freed. + */ bool try_to_free_buffers(struct folio *folio) { struct address_space * const mapping = folio->mapping; From patchwork Tue Apr 16 03:17:48 2024 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Matthew Wilcox X-Patchwork-Id: 13631134 Received: from casper.infradead.org (casper.infradead.org [90.155.50.34]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by smtp.subspace.kernel.org (Postfix) with ESMTPS id 1D6D41799B; Tue, 16 Apr 2024 03:17:57 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=90.155.50.34 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1713237480; cv=none; b=olFr5AshL0Ef/LOjIPv1/foSfQwbCBUbaarKaNecP0xyBhmgykzgnDTqocY66MY5satH22xDXZ/FRhdZZt+7nLZl3M6Y/XPhQzZCW/FviLsAA6GOazEnoH15D0WVtxB/NqH+6RWXkTiwUO8vZwkhVcPA+WzvkCT9vxZ6SrEzYZQ= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1713237480; c=relaxed/simple; bh=lAPa08IhPQtMbTxyecDDdGadkBQWe/L12G3eEq8lCKM=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=VJN8d7LLr6cTzBonu6/tcdOVwaPxsedWy9tka7pQ45xTebxJtg1FarBn5EhnuNQkeSFcnRQ6WsEYCFze8nGi+cf86LQSE0LXrdAjmL0IOspBb9a5pnOjpXQBUyT4orFfSyutEHJG86iPjyZUSFUHlujuGPv37/hYJoeGlHwi4Jk= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dmarc=none (p=none dis=none) header.from=infradead.org; spf=none smtp.mailfrom=infradead.org; dkim=pass (2048-bit key) header.d=infradead.org header.i=@infradead.org header.b=ZvvSnld2; arc=none smtp.client-ip=90.155.50.34 Authentication-Results: smtp.subspace.kernel.org; dmarc=none (p=none dis=none) header.from=infradead.org Authentication-Results: smtp.subspace.kernel.org; spf=none smtp.mailfrom=infradead.org Authentication-Results: smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=infradead.org header.i=@infradead.org header.b="ZvvSnld2" 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=FGpNu8aZPJ0EzAtAE/YF4YBptN/FSxJxoVRcCRnwFCE=; b=ZvvSnld2uxIIEqpK6cpCdU8Iup z79SIS3mE7t0WrcTNa7v2owUoVlchXnMhxsCOYkAVjHmqwQAHVN8NJOJusEzLtVQojbE3AkMPLKIk nOEqP1JOof33SWzMHFyYbIDOgCLdYnllDZrA78jvNi5ARZqDm4xV+arkzVH+WlDC0KTNIvp6RfBH8 c/8zBVVpIWmweFmZKDMZ0I3fOt+XG0kIiKvQb1t+uvJCQoNSidNlnkzTJCfIjCG2jS+hYYB0JOvzM emDdkms2DLNFo9+cTsxI88nt8fANyHwt0X72O4ryyP7uio4t6He1CKWbEqjzKHUXVqCbfFs4HuPW/ nwirn9yA==; Received: from willy by casper.infradead.org with local (Exim 4.97.1 #2 (Red Hat Linux)) id 1rwZKW-0000000H6b0-0gC8; Tue, 16 Apr 2024 03:17:56 +0000 From: "Matthew Wilcox (Oracle)" To: Andrew Morton Cc: "Matthew Wilcox (Oracle)" , linux-fsdevel@vger.kernel.org, linux-doc@vger.kernel.org, Pankaj Raghav Subject: [PATCH v3 4/8] buffer: Fix __bread and __bread_gfp kernel-doc Date: Tue, 16 Apr 2024 04:17:48 +0100 Message-ID: <20240416031754.4076917-5-willy@infradead.org> X-Mailer: git-send-email 2.44.0 In-Reply-To: <20240416031754.4076917-1-willy@infradead.org> References: <20240416031754.4076917-1-willy@infradead.org> Precedence: bulk X-Mailing-List: linux-fsdevel@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 The extra indentation confused the kernel-doc parser, so remove it. Fix some other wording while I'm here, and advise the user they need to call brelse() on this buffer. __bread_gfp() isn't used directly by filesystems, but the other wrappers for it don't have documentation, so document it accordingly. Co-developed-by: Pankaj Raghav Signed-off-by: Pankaj Raghav Signed-off-by: Matthew Wilcox (Oracle) Tested-by: Randy Dunlap --- fs/buffer.c | 35 ++++++++++++++++++++++------------- include/linux/buffer_head.h | 22 +++++++++++++--------- 2 files changed, 35 insertions(+), 22 deletions(-) diff --git a/fs/buffer.c b/fs/buffer.c index 0466ed7ed95a..32ab3eddc44f 100644 --- a/fs/buffer.c +++ b/fs/buffer.c @@ -1453,20 +1453,29 @@ void __breadahead(struct block_device *bdev, sector_t block, unsigned size) EXPORT_SYMBOL(__breadahead); /** - * __bread_gfp() - reads a specified block and returns the bh - * @bdev: the block_device to read from - * @block: number of block - * @size: size (in bytes) to read - * @gfp: page allocation flag - * - * Reads a specified block, and returns buffer head that contains it. - * The page cache can be allocated from non-movable area - * not to prevent page migration if you set gfp to zero. - * It returns NULL if the block was unreadable. + * __bread_gfp() - Read a block. + * @bdev: The block device to read from. + * @block: Block number in units of block size. + * @size: The block size of this device in bytes. + * @gfp: Not page allocation flags; see below. + * + * You are not expected to call this function. You should use one of + * sb_bread(), sb_bread_unmovable() or __bread(). + * + * Read a specified block, and return the buffer head that refers to it. + * If @gfp is 0, the memory will be allocated using the block device's + * default GFP flags. If @gfp is __GFP_MOVABLE, the memory may be + * allocated from a movable area. Do not pass in a complete set of + * GFP flags. + * + * The returned buffer head has its refcount increased. The caller should + * call brelse() when it has finished with the buffer. + * + * Context: May sleep waiting for I/O. + * Return: NULL if the block was unreadable. */ -struct buffer_head * -__bread_gfp(struct block_device *bdev, sector_t block, - unsigned size, gfp_t gfp) +struct buffer_head *__bread_gfp(struct block_device *bdev, sector_t block, + unsigned size, gfp_t gfp) { struct buffer_head *bh; diff --git a/include/linux/buffer_head.h b/include/linux/buffer_head.h index d78454a4dd1f..56a1e9c1e71e 100644 --- a/include/linux/buffer_head.h +++ b/include/linux/buffer_head.h @@ -437,17 +437,21 @@ static inline void bh_readahead_batch(int nr, struct buffer_head *bhs[], } /** - * __bread() - reads a specified block and returns the bh - * @bdev: the block_device to read from - * @block: number of block - * @size: size (in bytes) to read + * __bread() - Read a block. + * @bdev: The block device to read from. + * @block: Block number in units of block size. + * @size: The block size of this device in bytes. * - * Reads a specified block, and returns buffer head that contains it. - * The page cache is allocated from movable area so that it can be migrated. - * It returns NULL if the block was unreadable. + * Read a specified block, and return the buffer head that refers + * to it. The memory is allocated from the movable area so that it can + * be migrated. The returned buffer head has its refcount increased. + * The caller should call brelse() when it has finished with the buffer. + * + * Context: May sleep waiting for I/O. + * Return: NULL if the block was unreadable. */ -static inline struct buffer_head * -__bread(struct block_device *bdev, sector_t block, unsigned size) +static inline struct buffer_head *__bread(struct block_device *bdev, + sector_t block, unsigned size) { return __bread_gfp(bdev, block, size, __GFP_MOVABLE); } From patchwork Tue Apr 16 03:17:49 2024 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Matthew Wilcox X-Patchwork-Id: 13631139 Received: from casper.infradead.org (casper.infradead.org [90.155.50.34]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by smtp.subspace.kernel.org (Postfix) with ESMTPS id 055E82110F; Tue, 16 Apr 2024 03:18:03 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=90.155.50.34 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1713237485; cv=none; b=lGHULYtPTT/zH6465a7TB4DbNlVHrUs28eCjfurpgggMXVGoIYOpqbBYAs5w/D94+63Af8PmRR2M5F0SAItHCfTw3emqQJYLLfLG3asEMwLNQrWCI9f/6pgHxp8/jVJJml9SgsLhYLZSGIE7oAH42dWE1gqK1ztw2i2pZzGjgAE= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1713237485; c=relaxed/simple; bh=DbC+Tn185R2Zx2iSvqPYl8LWUAlvno1KmLJ8dcxgaVs=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=dHm+tHx7eTeNjTHXyFquf5UW+/wa5hUCOJzcst08iwwaeJoWANDL9qa8o9lOaKvH8EMBmPKadgLy+PinfqQx7BwTzii7+T0TfaZkxw3PAJqsPYjZHlQs0ripCbWz5CAhOXA/q+INqEftBN0kePhyAsH4PxDazv7bdgoB4su2StU= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dmarc=none (p=none dis=none) header.from=infradead.org; spf=none smtp.mailfrom=infradead.org; dkim=pass (2048-bit key) header.d=infradead.org header.i=@infradead.org header.b=havkGGcL; arc=none smtp.client-ip=90.155.50.34 Authentication-Results: smtp.subspace.kernel.org; dmarc=none (p=none dis=none) header.from=infradead.org Authentication-Results: smtp.subspace.kernel.org; spf=none smtp.mailfrom=infradead.org Authentication-Results: smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=infradead.org header.i=@infradead.org header.b="havkGGcL" 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=5/IxEJ6lq78GgJjoEkwt0LTdkDq6FNAtO1rS999rOAk=; b=havkGGcLEGDZABeim5heL7u4SJ 70uwilsM6mgfa1v87jI1mC2lNqz+8wYbhu2a1GDsvwxuWCDDdQTZvDfepy+5AqlFmN1+w1JtzgRiD Pb2Smw2Ku/gUDe+PcNsZGA1AZASc1c0k5HmPwjyPkw9mHniToHObl3VRFJpwkSmVbKMfVGxpO4YVe QarpP4ZXrU5+/nmKL15BH5aq1Ns4S0mgyAOgcVKYG55GMWrbndoQxmWuuOSr2kxMw81MEr8/RgAei i34N2Gk8mr4W3dxDQgJnCX3W2TT4Nex0yYBIR8e/HUwZ/NrP5/7gXaEinpsf3bqSBKTYr3lkhxue3 eYAoZ+dw==; Received: from willy by casper.infradead.org with local (Exim 4.97.1 #2 (Red Hat Linux)) id 1rwZKW-0000000H6b2-0zlb; Tue, 16 Apr 2024 03:17:56 +0000 From: "Matthew Wilcox (Oracle)" To: Andrew Morton Cc: "Matthew Wilcox (Oracle)" , linux-fsdevel@vger.kernel.org, linux-doc@vger.kernel.org Subject: [PATCH v3 5/8] buffer: Add kernel-doc for brelse() and __brelse() Date: Tue, 16 Apr 2024 04:17:49 +0100 Message-ID: <20240416031754.4076917-6-willy@infradead.org> X-Mailer: git-send-email 2.44.0 In-Reply-To: <20240416031754.4076917-1-willy@infradead.org> References: <20240416031754.4076917-1-willy@infradead.org> Precedence: bulk X-Mailing-List: linux-fsdevel@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Move the documentation for __brelse() to brelse(), format it as kernel-doc and update it from talking about pages to folios. Signed-off-by: Matthew Wilcox (Oracle) Tested-by: Randy Dunlap --- fs/buffer.c | 17 ++++++++--------- include/linux/buffer_head.h | 16 ++++++++++++++++ 2 files changed, 24 insertions(+), 9 deletions(-) diff --git a/fs/buffer.c b/fs/buffer.c index 32ab3eddc44f..e5beca3868a7 100644 --- a/fs/buffer.c +++ b/fs/buffer.c @@ -1226,17 +1226,16 @@ void mark_buffer_write_io_error(struct buffer_head *bh) } EXPORT_SYMBOL(mark_buffer_write_io_error); -/* - * Decrement a buffer_head's reference count. If all buffers against a page - * have zero reference count, are clean and unlocked, and if the page is clean - * and unlocked then try_to_free_buffers() may strip the buffers from the page - * in preparation for freeing it (sometimes, rarely, buffers are removed from - * a page but it ends up not being freed, and buffers may later be reattached). +/** + * __brelse - Release a buffer. + * @bh: The buffer to release. + * + * This variant of brelse() can be called if @bh is guaranteed to not be NULL. */ -void __brelse(struct buffer_head * buf) +void __brelse(struct buffer_head *bh) { - if (atomic_read(&buf->b_count)) { - put_bh(buf); + if (atomic_read(&bh->b_count)) { + put_bh(bh); return; } WARN(1, KERN_ERR "VFS: brelse: Trying to free free buffer\n"); diff --git a/include/linux/buffer_head.h b/include/linux/buffer_head.h index 56a1e9c1e71e..c145817c6ca0 100644 --- a/include/linux/buffer_head.h +++ b/include/linux/buffer_head.h @@ -303,6 +303,22 @@ static inline void put_bh(struct buffer_head *bh) atomic_dec(&bh->b_count); } +/** + * brelse - Release a buffer. + * @bh: The buffer to release. + * + * Decrement a buffer_head's reference count. If @bh is NULL, this + * function is a no-op. + * + * If all buffers on a folio have zero reference count, are clean + * and unlocked, and if the folio is unlocked and not under writeback + * then try_to_free_buffers() may strip the buffers from the folio in + * preparation for freeing it (sometimes, rarely, buffers are removed + * from a folio but it ends up not being freed, and buffers may later + * be reattached). + * + * Context: Any context. + */ static inline void brelse(struct buffer_head *bh) { if (bh) From patchwork Tue Apr 16 03:17:50 2024 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Matthew Wilcox X-Patchwork-Id: 13631133 Received: from casper.infradead.org (casper.infradead.org [90.155.50.34]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by smtp.subspace.kernel.org (Postfix) with ESMTPS id 0330617999; Tue, 16 Apr 2024 03:17:57 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=90.155.50.34 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1713237480; cv=none; b=dvNhR85Q3tO+bk6zqw576DYqPRjSwopPAH338jXXHbhdQflk8qSg/cQDyF1xyHuYQ7Z680eRpcmiVm/IYAtio3WxH7aThn8ZOpoUZlB1+TZzsMFC8f29ZpXD9SNmPEY83BjndeurNZPna1O+CV7hJDKhIK+qjIwdqOfQo6kFc0k= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1713237480; c=relaxed/simple; bh=E95jUP9ti1BS2kxBZYtw3uLF7lT3S+o1aLhs5Rmn4Qo=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=Y5ZKpXBbQaLKE+Q2rg76Zxqdl0rXqiJubOLT2aEgbS7Rj8AlJjgD4oGHFOAX6375KXj4zb9Jp4RQOP8heJyp1C6DvDAgNWZo3hqdzgUnz974Z7NOziEAazcIQU3YgttT4ReJFUJCi2UiHm7W6B97foEvnR6LRlKBupBjg8cEdfI= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dmarc=none (p=none dis=none) header.from=infradead.org; spf=none smtp.mailfrom=infradead.org; dkim=pass (2048-bit key) header.d=infradead.org header.i=@infradead.org header.b=dagUszmL; arc=none smtp.client-ip=90.155.50.34 Authentication-Results: smtp.subspace.kernel.org; dmarc=none (p=none dis=none) header.from=infradead.org Authentication-Results: smtp.subspace.kernel.org; spf=none smtp.mailfrom=infradead.org Authentication-Results: smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=infradead.org header.i=@infradead.org header.b="dagUszmL" 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=pk9BBryg92so+HGLLXF/V590GSRkQSChFQr6bBQemN0=; b=dagUszmLGKgFnvSZCKCQjufSTU geaiXPZExHmlwI6cmL8f4YeBnxVf+t5S0B2ek3wVY74g/C3XRkXjWfvGBJxH8veEajEZq8S+DQPjW EJ28R7PXN+Ez5NZ5erZS2xj9ozG8N4h6/Ae158fP3/b5YI++9RQHYXsU/d3Awof6GEO/y6E40VSgG WZJVOOKTZSj2qugx+iHc9fWty2citR62r2YcHla04xF8KFbgPcG6Ig49TsW1GQVZMYu4glmPbLS2V RoRMYSJ5+4zoUWf7K5OmhbyfHikT8RMi/8CmC6m5t6e13s6C+kOFf4aNMUA2k7eZHDhVEjK73JiHf UsLUsypg==; Received: from willy by casper.infradead.org with local (Exim 4.97.1 #2 (Red Hat Linux)) id 1rwZKW-0000000H6b4-1IqZ; Tue, 16 Apr 2024 03:17:56 +0000 From: "Matthew Wilcox (Oracle)" To: Andrew Morton Cc: "Matthew Wilcox (Oracle)" , linux-fsdevel@vger.kernel.org, linux-doc@vger.kernel.org Subject: [PATCH v3 6/8] buffer: Add kernel-doc for bforget() and __bforget() Date: Tue, 16 Apr 2024 04:17:50 +0100 Message-ID: <20240416031754.4076917-7-willy@infradead.org> X-Mailer: git-send-email 2.44.0 In-Reply-To: <20240416031754.4076917-1-willy@infradead.org> References: <20240416031754.4076917-1-willy@infradead.org> Precedence: bulk X-Mailing-List: linux-fsdevel@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Distinguish these functions from brelse() and __brelse(). Signed-off-by: Matthew Wilcox (Oracle) Tested-by: Randy Dunlap --- fs/buffer.c | 9 ++++++--- include/linux/buffer_head.h | 10 ++++++++++ 2 files changed, 16 insertions(+), 3 deletions(-) diff --git a/fs/buffer.c b/fs/buffer.c index e5beca3868a7..60829312787a 100644 --- a/fs/buffer.c +++ b/fs/buffer.c @@ -1242,9 +1242,12 @@ void __brelse(struct buffer_head *bh) } EXPORT_SYMBOL(__brelse); -/* - * bforget() is like brelse(), except it discards any - * potentially dirty data. +/** + * __bforget - Discard any dirty data in a buffer. + * @bh: The buffer to forget. + * + * This variant of bforget() can be called if @bh is guaranteed to not + * be NULL. */ void __bforget(struct buffer_head *bh) { diff --git a/include/linux/buffer_head.h b/include/linux/buffer_head.h index c145817c6ca0..a1c0bdd0cca6 100644 --- a/include/linux/buffer_head.h +++ b/include/linux/buffer_head.h @@ -325,6 +325,16 @@ static inline void brelse(struct buffer_head *bh) __brelse(bh); } +/** + * bforget - Discard any dirty data in a buffer. + * @bh: The buffer to forget. + * + * Call this function instead of brelse() if the data written to a buffer + * no longer needs to be written back. It will clear the buffer's dirty + * flag so writeback of this buffer will be skipped. + * + * Context: Any context. + */ static inline void bforget(struct buffer_head *bh) { if (bh) From patchwork Tue Apr 16 03:17:51 2024 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Matthew Wilcox X-Patchwork-Id: 13631135 Received: from casper.infradead.org (casper.infradead.org [90.155.50.34]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by smtp.subspace.kernel.org (Postfix) with ESMTPS id 0329612B7F; Tue, 16 Apr 2024 03:17:57 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=90.155.50.34 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1713237480; cv=none; b=Wem3sBzY41RLQZhJQSl4Nqw5avvIFwf9wuDUBiky24s135QybIy9JahCzBqag4AMqwUIehFSsOUcSv7dEbG6Ne/Hv53k6jM9Vs4sZUS941aBmxsAjOzHK6QxpK4vmy0ggNy6Ndy0FwvEbxyedroMWJgVHWlHnJsmpWhAflOu5N0= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1713237480; c=relaxed/simple; bh=gfmKDcd9YWE/Cir+i8fsK+4kZ7g8NKRJF3hQTcwcF2I=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=DN3m3iHlIis8/Ud7lxx/pkhc7659YG4arv8UzQWeWC+3iFGQdftPEPzCRaMB4vEUzAuFxskAwFHp6WBK/OrQp6JwGemZ6ijTkBjkOGxjgKzBdC/pmJqH+4EUgfSYQaQ3Bv6tzD01onI0t5Ls3Nb4SCCx1bnGt2f9VmRhIa/DJLo= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dmarc=none (p=none dis=none) header.from=infradead.org; spf=none smtp.mailfrom=infradead.org; dkim=pass (2048-bit key) header.d=infradead.org header.i=@infradead.org header.b=Ne7/6EiI; arc=none smtp.client-ip=90.155.50.34 Authentication-Results: smtp.subspace.kernel.org; dmarc=none (p=none dis=none) header.from=infradead.org Authentication-Results: smtp.subspace.kernel.org; spf=none smtp.mailfrom=infradead.org Authentication-Results: smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=infradead.org header.i=@infradead.org header.b="Ne7/6EiI" 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=DjzRuP73q58spUrrIonqOCGah9N8XwVh2uAGIuI3AVE=; b=Ne7/6EiIYH3cUo0cIyllU/Vgm7 VKkO0zh2mLQy61Y2Ne/j89FWd7Cljqj6Us6C1LN67NKmC6cEzHfXKJAIt9r5jpuBiCRS+asbXUGMB 2T8Zi6F2aHHwMI760ZySpyOVe/Jsr9f4rvlL50Ynfv9dFfjwkndE2Lnz+OU1paEVXqvLf7YpENQey pMeX2oDTsjtlpoO9cBNS/NWpf2YuNW1g24C6GCOXnaKgZByhK4fsJpoyfP8oCUg48iOAH8GF8+f0J Lusvhl5OL7FRJLrSYMJ8imO40JlUt3T6W4an3FCihYYvVbEL26P4EM1yf4Ja3uh2Z+reo0inFIbVI BJSLGGlQ==; Received: from willy by casper.infradead.org with local (Exim 4.97.1 #2 (Red Hat Linux)) id 1rwZKW-0000000H6b9-1c63; Tue, 16 Apr 2024 03:17:56 +0000 From: "Matthew Wilcox (Oracle)" To: Andrew Morton Cc: "Matthew Wilcox (Oracle)" , linux-fsdevel@vger.kernel.org, linux-doc@vger.kernel.org Subject: [PATCH v3 7/8] buffer: Improve bdev_getblk documentation Date: Tue, 16 Apr 2024 04:17:51 +0100 Message-ID: <20240416031754.4076917-8-willy@infradead.org> X-Mailer: git-send-email 2.44.0 In-Reply-To: <20240416031754.4076917-1-willy@infradead.org> References: <20240416031754.4076917-1-willy@infradead.org> Precedence: bulk X-Mailing-List: linux-fsdevel@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Add some more information about the state of the buffer_head returned. Signed-off-by: Matthew Wilcox (Oracle) --- fs/buffer.c | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/fs/buffer.c b/fs/buffer.c index 60829312787a..ed698caa8834 100644 --- a/fs/buffer.c +++ b/fs/buffer.c @@ -1424,6 +1424,11 @@ EXPORT_SYMBOL(__find_get_block); * @size: The size of buffer_heads for this @bdev. * @gfp: The memory allocation flags to use. * + * The returned buffer head has its reference count incremented, but is + * not locked. The caller should call brelse() when it has finished + * with the buffer. The buffer may not be uptodate. If needed, the + * caller can bring it uptodate either by reading it or overwriting it. + * * Return: The buffer head, or NULL if memory could not be allocated. */ struct buffer_head *bdev_getblk(struct block_device *bdev, sector_t block, From patchwork Tue Apr 16 03:17:52 2024 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Matthew Wilcox X-Patchwork-Id: 13631136 Received: from casper.infradead.org (casper.infradead.org [90.155.50.34]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by smtp.subspace.kernel.org (Postfix) with ESMTPS id 1D703179B7; Tue, 16 Apr 2024 03:17:57 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=90.155.50.34 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1713237481; cv=none; b=U3w58IHWgZw9qM1FQFQEDfsInBygeHCDycxgmprhibU5r34CGM9lDmDyFdRqMmQfirgGzP2CLPUoZq6kZEPU6HOjCnpYmN13pxhI2kFdfObMNIjUNMv5cY5sU8p+m7dkeN4c0sPZgzrh2HEIBXRUlQtAvuBikokvpXHmF6mwcnY= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1713237481; c=relaxed/simple; bh=R4zR/ggMbwsDDsz3YLFyJdFeeu1DsOVGY8QCJ7KprCE=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=ANXuuGl1CzWjJbv7R92SGn9H6oj6hTsp+9WM6SaOaZcgzbuG4xMzuhHtXvlerJ2d5xZkfMzNw5wlJRWTXhmXfYyo6RMYCmPW0biJ0T7kiCP27UrwZFe19KYj+8EohWMpx5Xi3/fqWT3p2AiptuHLbcpUZsEMDSkueOmOnCDnP7M= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dmarc=none (p=none dis=none) header.from=infradead.org; spf=none smtp.mailfrom=infradead.org; dkim=pass (2048-bit key) header.d=infradead.org header.i=@infradead.org header.b=nGYV5Bl6; arc=none smtp.client-ip=90.155.50.34 Authentication-Results: smtp.subspace.kernel.org; dmarc=none (p=none dis=none) header.from=infradead.org Authentication-Results: smtp.subspace.kernel.org; spf=none smtp.mailfrom=infradead.org Authentication-Results: smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=infradead.org header.i=@infradead.org header.b="nGYV5Bl6" 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=rmgDp3RNfkN3sPWJ9s/SxWrF46fF3oO8saAb/9v0RQU=; b=nGYV5Bl6OTUcQaFxNJ8Qd5UDRD rAZf93AsDmTmmnsbAF7QNxF4QaDilQLQfZXDXuuUiaQB/EnzJP3bEY2Vg0JbuQIwoaGL5S5muyyVk yi7iuAsew9HdGeZIU8JCyd5l6s3HnRcPVXBPM0+Xky88JGsPwPl5W584FM2EEg6eQLF90UI7w4cdn XCG0B9WZoaNSvxeaMr28h4z5EZ0Htcg2yWkP+xlAkssYi9W/VgfW4yEPyg5tgxJfChOI3VLSjzW4I V5z6y/B6NB7TnvZ7UKzRs2OVIOiqojSuU/iPAl9H5zGeuHWXzmzXCHYwX3M7Yxg1WmWrHa1cTLOMe NGkFXbaQ==; Received: from willy by casper.infradead.org with local (Exim 4.97.1 #2 (Red Hat Linux)) id 1rwZKW-0000000H6bI-25ds; Tue, 16 Apr 2024 03:17:56 +0000 From: "Matthew Wilcox (Oracle)" To: Andrew Morton Cc: "Matthew Wilcox (Oracle)" , linux-fsdevel@vger.kernel.org, linux-doc@vger.kernel.org Subject: [PATCH v3 8/8] doc: Split buffer.rst out of api-summary.rst Date: Tue, 16 Apr 2024 04:17:52 +0100 Message-ID: <20240416031754.4076917-9-willy@infradead.org> X-Mailer: git-send-email 2.44.0 In-Reply-To: <20240416031754.4076917-1-willy@infradead.org> References: <20240416031754.4076917-1-willy@infradead.org> Precedence: bulk X-Mailing-List: linux-fsdevel@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Buffer heads are no longer a generic filesystem API but an optional filesystem support library. Make the documentation structure reflect that, and include the fine documentation kept in buffer_head.h. We could give a better overview of what buffer heads are all about, but my enthusiasm for documenting it is limited. Signed-off-by: Matthew Wilcox (Oracle) --- Documentation/filesystems/api-summary.rst | 3 --- Documentation/filesystems/index.rst | 1 + 2 files changed, 1 insertion(+), 3 deletions(-) diff --git a/Documentation/filesystems/api-summary.rst b/Documentation/filesystems/api-summary.rst index 98db2ea5fa12..cc5cc7f3fbd8 100644 --- a/Documentation/filesystems/api-summary.rst +++ b/Documentation/filesystems/api-summary.rst @@ -56,9 +56,6 @@ Other Functions .. kernel-doc:: fs/namei.c :export: -.. kernel-doc:: fs/buffer.c - :export: - .. kernel-doc:: block/bio.c :export: diff --git a/Documentation/filesystems/index.rst b/Documentation/filesystems/index.rst index 1f9b4c905a6a..8f5c1ee02e2f 100644 --- a/Documentation/filesystems/index.rst +++ b/Documentation/filesystems/index.rst @@ -50,6 +50,7 @@ filesystem implementations. .. toctree:: :maxdepth: 2 + buffer journalling fscrypt fsverity