From nobody Fri Dec 26 05:15:28 2025 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 6CE8539FDB; Tue, 9 Jan 2024 14:34:08 +0000 (UTC) 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="u05ju9U7" 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=LknggBhcXoqAVfUx/eiZL0v95VMCfMsJSCjCKH+cREY=; b=u05ju9U7gbnxlRQ/OUK1KvCOG8 cDqdbb7UoJdf6bcU61e4xanTqpFuFa8eBLVyqpqWoVDw2Ee8ePbipaTYhrSdsaXf695bsT5yo3Kpi nl3wgGNjxQSew2H7PJJSzxJslqcd7576lK65+Vr8PQGZCGajBx1ygvvf9MJEJu/h4z5SlHNIx5mCj sEC2o2K3jiNz++3agFJkIaLm8VQ4Gy9l6FMbdxcr1sm6fBXYfAHAR6QVeR6AOsC81bMbNfEuJnDZA slpSg+GSuBBm8/sCHAK//PIXO6trM1DRcIHXaM7S1EVsrz1zv35hk91oyK1P3JAYdtfHBK/e77o3V e9omKaig==; Received: from willy by casper.infradead.org with local (Exim 4.94.2 #2 (Red Hat Linux)) id 1rNDB0-009xrQ-RF; Tue, 09 Jan 2024 14:33:58 +0000 From: "Matthew Wilcox (Oracle)" To: Jonathan Corbet Cc: "Matthew Wilcox (Oracle)" , linux-doc@vger.kernel.org, linux-fsdevel@vger.kernel.org, linux-kernel@vger.kernel.org Subject: [PATCH v2 1/8] doc: Improve the description of __folio_mark_dirty Date: Tue, 9 Jan 2024 14:33:50 +0000 Message-Id: <20240109143357.2375046-2-willy@infradead.org> X-Mailer: git-send-email 2.37.1 In-Reply-To: <20240109143357.2375046-1-willy@infradead.org> References: <20240109143357.2375046-1-willy@infradead.org> Precedence: bulk X-Mailing-List: linux-kernel@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable Content-Type: text/plain; charset="utf-8" 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 cd4e4ae77c40..f09179fca2cf 100644 --- a/mm/page-writeback.c +++ b/mm/page-writeback.c @@ -2652,11 +2652,15 @@ void folio_account_cleaned(struct folio *folio, str= uct bdi_writeback *wb) * If warn is true, then emit a warning if the folio is not uptodate and h= as * 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) --=20 2.43.0 From nobody Fri Dec 26 05:15:28 2025 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 BD67739ACB; Tue, 9 Jan 2024 14:34:10 +0000 (UTC) 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="QprLpERe" 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=TCE+5KgYHDY4CxZU9Cz581t8brafbTwNpWCFcRWEPX0=; b=QprLpEReoXz9XO1qo8ivYWUljL WEpivWzbQ+yI6DWv13a4pSX7mHzEOA2ggrtVvmM0oT2Ekfgzx3bfl9+7MPsI1DOELJ3giHqy3UlvZ H/G92q+Ry9bCNQAf8wAJ8eCSEeOkIVPW3Y/F8cz1mINg3IyFMEAaznImZ57gdDcFaPJRcSwQ7IF7P B5q9WLoAdJj6+vQ2tsn0BkwJuCoA2iyZnYPWSbpBROBId7Iddi3eI/6JhYyP0SreMRTemcgzZfeIP k1eCKjqGZDUALWkdG1nYcQkSKPlFq5AtPe+JRaxmX5oc/SVvUOYUPMUUaI0dvPcLrwmNqY/tcOy+3 ZHPtf5JA==; Received: from willy by casper.infradead.org with local (Exim 4.94.2 #2 (Red Hat Linux)) id 1rNDB0-009xrS-Tw; Tue, 09 Jan 2024 14:33:58 +0000 From: "Matthew Wilcox (Oracle)" To: Jonathan Corbet Cc: "Matthew Wilcox (Oracle)" , linux-doc@vger.kernel.org, linux-fsdevel@vger.kernel.org, linux-kernel@vger.kernel.org Subject: [PATCH v2 2/8] buffer: Add kernel-doc for block_dirty_folio() Date: Tue, 9 Jan 2024 14:33:51 +0000 Message-Id: <20240109143357.2375046-3-willy@infradead.org> X-Mailer: git-send-email 2.37.1 In-Reply-To: <20240109143357.2375046-1-willy@infradead.org> References: <20240109143357.2375046-1-willy@infradead.org> Precedence: bulk X-Mailing-List: linux-kernel@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable Content-Type: text/plain; charset="utf-8" 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 --- fs/buffer.c | 55 ++++++++++++++++++++++++++++++----------------------- 1 file changed, 31 insertions(+), 24 deletions(-) diff --git a/fs/buffer.c b/fs/buffer.c index d3bcf601d3e5..071f01b28c90 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); =20 -/* - * Add a page to the dirty page list. - * - * It is a sad fact of life that this function is called from several plac= es - * 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 do= es - * 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 ra= ce - * window in which a writepage caller may see the page cleanness but not t= he - * 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/cl= ean - * page on the dirty page list. - * - * We use i_private_lock to lock against try_to_free_buffers while using t= he - * page's buffer list. Also use this to protect against clean buffers bei= ng - * added to the page after it was set dirty. - * - * FIXME: may need to call ->reservepage here as well. That's rather up t= o 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) { --=20 2.43.0 From nobody Fri Dec 26 05:15:28 2025 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 4F62E3A1BA; Tue, 9 Jan 2024 14:34:11 +0000 (UTC) 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="ToQx4GGb" 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=cca0/i33EOqMAkZgYIeSRXbVYWRM3R2G+zhbkmE3gJs=; b=ToQx4GGbYUyKYdHFRtG64tsI0E 6B1SLA7rgJoaFg6yV275YZFQodqDN4YazJdaRo6sLRwxzDy+THnFq1skLIjawWPpwu0hrC80kO/GT PWfsA1BBnWCOtaLvsiwJiOSxT6322c9oa9kxga1dOg6iPY9KxKXcoXNvM2rx3qltZuujcRUBee3cm WN8eN2/Em1DgWFgGc+JBEFB67pyM4zUNj/i1Pj2pFnRJ4zYGv1dANBmydKmytpTwYqbHxzOcbEBPt sXFER4VtTGWV3dXlqTRq8me73WxnozzI9kQzq82DU8D7t8UOsME8o4brJ1Sh/kqO9Thtxi132IRaS Rmjiyl6g==; Received: from willy by casper.infradead.org with local (Exim 4.94.2 #2 (Red Hat Linux)) id 1rNDB1-009xrU-0M; Tue, 09 Jan 2024 14:33:59 +0000 From: "Matthew Wilcox (Oracle)" To: Jonathan Corbet Cc: "Matthew Wilcox (Oracle)" , linux-doc@vger.kernel.org, linux-fsdevel@vger.kernel.org, linux-kernel@vger.kernel.org Subject: [PATCH v2 3/8] buffer: Add kernel-doc for try_to_free_buffers() Date: Tue, 9 Jan 2024 14:33:52 +0000 Message-Id: <20240109143357.2375046-4-willy@infradead.org> X-Mailer: git-send-email 2.37.1 In-Reply-To: <20240109143357.2375046-1-willy@infradead.org> References: <20240109143357.2375046-1-willy@infradead.org> Precedence: bulk X-Mailing-List: linux-kernel@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable Content-Type: text/plain; charset="utf-8" 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 --- fs/buffer.c | 44 ++++++++++++++++++++++++-------------------- 1 file changed, 24 insertions(+), 20 deletions(-) diff --git a/fs/buffer.c b/fs/buffer.c index 071f01b28c90..25861241657f 100644 --- a/fs/buffer.c +++ b/fs/buffer.c @@ -2864,26 +2864,6 @@ int sync_dirty_buffer(struct buffer_head *bh) } EXPORT_SYMBOL(sync_dirty_buffer); =20 -/* - * 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) | @@ -2917,6 +2897,30 @@ drop_buffers(struct folio *folio, struct buffer_head= **buffers_to_free) return false; } =20 +/** + * 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 =3D folio->mapping; --=20 2.43.0 From nobody Fri Dec 26 05:15:28 2025 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 CDA0B3B296; Tue, 9 Jan 2024 14:34:16 +0000 (UTC) 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="UjSgiwUM" 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=O7lis2itUlx9IU8kc9yc0wwrtDMZQuoZYKYmXgRl3Lw=; b=UjSgiwUMpvBrJVcDFbKwXeW/6A ozkYUjDTagYCXTCZls66gJHF5HQOysaAECLs0wvEeLz24S0H4G/37KPMqVF/qxNuLD0qSAGiEmtje UKqWNxG1EzUZcdip9yDkUz9k1kIOTffGElk8ggUYbJk/U+z/XNe2XJwNFa/mZ6qC/8FabQmMnFdMu 9WCpfVY60l6MySLYqRFvf75Erli+/NKwmSeYfk0fhin5l3FRQS95BxnINGfb2oOJPiILhpR8KyCYq 0vTPxLtYNVk5nLv0D3wYEQ3Q4NBbuZZkNmLONNmmXSZSF61a1toFzWC68wD55AaZ8M5L/7C+R8Msc /wyLFLiQ==; Received: from willy by casper.infradead.org with local (Exim 4.94.2 #2 (Red Hat Linux)) id 1rNDB1-009xrW-38; Tue, 09 Jan 2024 14:33:59 +0000 From: "Matthew Wilcox (Oracle)" To: Jonathan Corbet Cc: "Matthew Wilcox (Oracle)" , linux-doc@vger.kernel.org, linux-fsdevel@vger.kernel.org, linux-kernel@vger.kernel.org, Pankaj Raghav Subject: [PATCH v2 4/8] buffer: Fix __bread and __bread_gfp kernel-doc Date: Tue, 9 Jan 2024 14:33:53 +0000 Message-Id: <20240109143357.2375046-5-willy@infradead.org> X-Mailer: git-send-email 2.37.1 In-Reply-To: <20240109143357.2375046-1-willy@infradead.org> References: <20240109143357.2375046-1-willy@infradead.org> Precedence: bulk X-Mailing-List: linux-kernel@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable Content-Type: text/plain; charset="utf-8" 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) --- 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 25861241657f..160bbc1f929c 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); =20 /** - * __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; =20 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[], } =20 /** - * __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 migrat= ed. - * 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); } --=20 2.43.0 From nobody Fri Dec 26 05:15:28 2025 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 29A8D3C481; Tue, 9 Jan 2024 14:34:25 +0000 (UTC) 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="hGupIP86" 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=OxfIaVCptnL2Ku+19F0c3pEPzF3dZDzT7NBA3grsvvg=; b=hGupIP86Lcpom0DkHphtQajPbO HXwIe8TJDCYILaA1beUztFAWD5PDxrfHloqmSPK5Hoxm73HAhHDYQ9B1+qW96hj8q6JMiYv9CVxGC IVhPSbqGoKSFYEYj2eSb2EIiU3FY2WAxgbvrtEYho0pQ2pAwyW/jGFTQYMmYieceg+l9fcE+0Mpnt 7H/hZnvulSuk+A0tWgBNEZOgOTkXAY826yGrfGMQlI8kH4ZEPmPWHynnB4OWNzy2qVQutfhFCb9Y0 sXlH74lhDdYo/4lM2MwUx7IEpkwfgCF5FgkhPTHnutArNUL/XQ6FHEmggXFYTqicQiHgX4G1DNGXw R6Ppwo8w==; Received: from willy by casper.infradead.org with local (Exim 4.94.2 #2 (Red Hat Linux)) id 1rNDB1-009xrY-5o; Tue, 09 Jan 2024 14:33:59 +0000 From: "Matthew Wilcox (Oracle)" To: Jonathan Corbet Cc: "Matthew Wilcox (Oracle)" , linux-doc@vger.kernel.org, linux-fsdevel@vger.kernel.org, linux-kernel@vger.kernel.org Subject: [PATCH v2 5/8] buffer: Add kernel-doc for brelse() and __brelse() Date: Tue, 9 Jan 2024 14:33:54 +0000 Message-Id: <20240109143357.2375046-6-willy@infradead.org> X-Mailer: git-send-email 2.37.1 In-Reply-To: <20240109143357.2375046-1-willy@infradead.org> References: <20240109143357.2375046-1-willy@infradead.org> Precedence: bulk X-Mailing-List: linux-kernel@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable Content-Type: text/plain; charset="utf-8" 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) --- 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 160bbc1f929c..9a7b3649c872 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); =20 -/* - * Decrement a buffer_head's reference count. If all buffers against a pa= ge - * have zero reference count, are clean and unlocked, and if the page is c= lean - * and unlocked then try_to_free_buffers() may strip the buffers from the = page - * in preparation for freeing it (sometimes, rarely, buffers are removed f= rom - * a page but it ends up not being freed, and buffers may later be reattac= hed). +/** + * __brelse - Release a buffer. + * @bh: The buffer to release. + * + * This variant of brelse() can be called if @bh is guaranteed to not be N= ULL. */ -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..3cbc01bbc398 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); } =20 +/** + * 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 clean and unlocked 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) --=20 2.43.0 From nobody Fri Dec 26 05:15:28 2025 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 D531C39FD9; Tue, 9 Jan 2024 14:34:07 +0000 (UTC) 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="Lt2UkjDk" 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=vjZcjkW+p03n5C+wK7KGpaZp9bYGqoRJwYEYBxOudMc=; b=Lt2UkjDkT28/d0suB5S1yhWMov vEOp9Vd5ZNRxxNKaFg7GdXTopFh0JJf4jJEOFGHoPKIn838dLZMUDVxrV3wWgW2sOoG1Vx5dZufH3 lkBgApHwpQC2gQeJTNTrqUH3L2J6y+emSTGZV6DkFh6hsGpMfN9vv3VfnNW02r4SgnSVtA8xxvmky A/rIttBXUDzgh+PZG0V57SsWSRNlUh5tOhYx6QLOSwQVe7+SjYaSlaWScOt1jZZQ6x8z5SMwb2Mwl gqWNtgPaqCS71tNQXg9yzyCd6V67+KCBmvAqFrTmFbaatP+42QObd6TzF3KVw99BUa1y4mnclSNKR cyl7y2mw==; Received: from willy by casper.infradead.org with local (Exim 4.94.2 #2 (Red Hat Linux)) id 1rNDB1-009xra-8V; Tue, 09 Jan 2024 14:33:59 +0000 From: "Matthew Wilcox (Oracle)" To: Jonathan Corbet Cc: "Matthew Wilcox (Oracle)" , linux-doc@vger.kernel.org, linux-fsdevel@vger.kernel.org, linux-kernel@vger.kernel.org Subject: [PATCH v2 6/8] buffer: Add kernel-doc for bforget() and __bforget() Date: Tue, 9 Jan 2024 14:33:55 +0000 Message-Id: <20240109143357.2375046-7-willy@infradead.org> X-Mailer: git-send-email 2.37.1 In-Reply-To: <20240109143357.2375046-1-willy@infradead.org> References: <20240109143357.2375046-1-willy@infradead.org> Precedence: bulk X-Mailing-List: linux-kernel@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable Content-Type: text/plain; charset="utf-8" Distinguish these functions from brelse() and __brelse(). Signed-off-by: Matthew Wilcox (Oracle) --- 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 9a7b3649c872..05b68eccfdcc 100644 --- a/fs/buffer.c +++ b/fs/buffer.c @@ -1242,9 +1242,12 @@ void __brelse(struct buffer_head *bh) } EXPORT_SYMBOL(__brelse); =20 -/* - * 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 3cbc01bbc398..9dc5477f13c7 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); } =20 +/** + * 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) --=20 2.43.0 From nobody Fri Dec 26 05:15:28 2025 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 D3BA53C067; Tue, 9 Jan 2024 14:34:22 +0000 (UTC) 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="WOy8RXNK" 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=vQE4Vr9H4MhDEQ3ZsfKD//avXDRAF3tvXQ94yS9EaIc=; b=WOy8RXNKs6IkvVSwr390DH5rRe 0rst5N0FA/qgl8haZG3WWpgKA98XqBUTBrk6VO84tfKI2gUcXcpXwQNWdwLmkXJ4kLGdQS8yL6k1d YFFIVqft4rvEIVeyqvGjnFTqIiNrNifH3XoCAogibRgbU57ipvSoHdN8OqlAvtrdpZ/iP8zoEKcNl Wpc74Ie6cZstz0i54+BmqZSWqG7rIQ/fZflo7FfJ1OMCcHw1Ql97n2vKjI7g5sIPYm2NnKmVrZP+E uBbWWP25xLMR7PETFxYOVfR+g5nuWaU/y4y10cjIxhvfydceKgEMvwjELoP9fYWoFWYy1W4aa2AZC cUHHeFNQ==; Received: from willy by casper.infradead.org with local (Exim 4.94.2 #2 (Red Hat Linux)) id 1rNDB1-009xrc-BC; Tue, 09 Jan 2024 14:33:59 +0000 From: "Matthew Wilcox (Oracle)" To: Jonathan Corbet Cc: "Matthew Wilcox (Oracle)" , linux-doc@vger.kernel.org, linux-fsdevel@vger.kernel.org, linux-kernel@vger.kernel.org Subject: [PATCH v2 7/8] buffer: Improve bdev_getblk documentation Date: Tue, 9 Jan 2024 14:33:56 +0000 Message-Id: <20240109143357.2375046-8-willy@infradead.org> X-Mailer: git-send-email 2.37.1 In-Reply-To: <20240109143357.2375046-1-willy@infradead.org> References: <20240109143357.2375046-1-willy@infradead.org> Precedence: bulk X-Mailing-List: linux-kernel@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable Content-Type: text/plain; charset="utf-8" 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 05b68eccfdcc..562de7e013f7 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, --=20 2.43.0 From nobody Fri Dec 26 05:15:28 2025 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 3C2323A8E0; Tue, 9 Jan 2024 14:34:13 +0000 (UTC) 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="H1I0YeOE" 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=tjpzRGznwK55I7Q2n7VmfSXQNhK2++G4Xwmpa8nx6sg=; b=H1I0YeOEf67h7TTv7M7ugEzK7n 6P74J41Y4EwelsITPZRidtA8FiyzA45p3bNNFgAQLnCfIW63g9UrIxOiVt2dMZokstSZO4RiI4Z/u UD+6DBLOkbzB/s2/cc5/kDTluKrmHc/mZV3+uTyR0rzXtLUEO4FfHHRbYHk6fTmByOhEEI4iseZQs 3IZfD+gFQ9rGuhqHj1LL7oFXM5Mqip9JYAKDQfrt8x6+qs79wV8iA1Iu/ahmhowRWWc4wmN4EfCf8 zTBIxW08LjWoOj7dFKXwCy4lNfB9glwCBlhCv1jGZtviKXlLSo7f1csvw0MCT1lcYUr6x+oF2hdJF jJCikf9g==; Received: from willy by casper.infradead.org with local (Exim 4.94.2 #2 (Red Hat Linux)) id 1rNDB1-009xre-DN; Tue, 09 Jan 2024 14:33:59 +0000 From: "Matthew Wilcox (Oracle)" To: Jonathan Corbet Cc: "Matthew Wilcox (Oracle)" , linux-doc@vger.kernel.org, linux-fsdevel@vger.kernel.org, linux-kernel@vger.kernel.org Subject: [PATCH v2 8/8] doc: Split buffer.rst out of api-summary.rst Date: Tue, 9 Jan 2024 14:33:57 +0000 Message-Id: <20240109143357.2375046-9-willy@infradead.org> X-Mailer: git-send-email 2.37.1 In-Reply-To: <20240109143357.2375046-1-willy@infradead.org> References: <20240109143357.2375046-1-willy@infradead.org> Precedence: bulk X-Mailing-List: linux-kernel@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable Content-Type: text/plain; charset="utf-8" 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/file= systems/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: =20 -.. kernel-doc:: fs/buffer.c - :export: - .. kernel-doc:: block/bio.c :export: =20 diff --git a/Documentation/filesystems/index.rst b/Documentation/filesystem= s/index.rst index e18bc5ae3b35..5fc9b19b8d8e 100644 --- a/Documentation/filesystems/index.rst +++ b/Documentation/filesystems/index.rst @@ -50,6 +50,7 @@ filesystem implementations. .. toctree:: :maxdepth: 2 =20 + buffer journalling fscrypt fsverity --=20 2.43.0