Turn buffer head documentation into its own document, and make many
general improvements to the docs. Obviously there is much more that
could be done. Tested with make htmldocs.
v2:
- Incorporate feedback from Randy & Pankaj
- Add docs for brelse() and bforget()
- Improve bdev_getblk() docs
Matthew Wilcox (Oracle) (8):
doc: Improve the description of __folio_mark_dirty
buffer: Add kernel-doc for block_dirty_folio()
buffer: Add kernel-doc for try_to_free_buffers()
buffer: Fix __bread and __bread_gfp kernel-doc
buffer: Add kernel-doc for brelse() and __brelse()
buffer: Add kernel-doc for bforget() and __bforget()
buffer: Improve bdev_getblk documentation
doc: Split buffer.rst out of api-summary.rst
Documentation/filesystems/api-summary.rst | 3 -
Documentation/filesystems/index.rst | 1 +
fs/buffer.c | 165 +++++++++++++---------
include/linux/buffer_head.h | 48 +++++--
mm/page-writeback.c | 14 +-
5 files changed, 145 insertions(+), 86 deletions(-)
--
2.43.0
Add some more information about the state of the buffer_head returned.
Signed-off-by: Matthew Wilcox (Oracle) <[email protected]>
---
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,
--
2.43.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) <[email protected]>
---
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);
-/*
- * 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..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);
}
+/**
+ * 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)
--
2.43.0
> + * If all buffers on a folio have zero reference count, are clean
> + * and unlocked, and if the folio is clean and unlocked then
IIUC from your [PATCH 3/8], folio only needs to be unlocked to free the
buffers as try_to_free_buffers() will remove the dirty flag and "clean"
the folio?
So:
s/if folio is clean and unlocked/if folio is unlocked
> + * 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)
> --
> 2.43.0
>
On Wed, Jan 10, 2024 at 03:30:54PM +0100, Pankaj Raghav (Samsung) wrote:
> > + * If all buffers on a folio have zero reference count, are clean
> > + * and unlocked, and if the folio is clean and unlocked then
>
> IIUC from your [PATCH 3/8], folio only needs to be unlocked to free the
> buffers as try_to_free_buffers() will remove the dirty flag and "clean"
> the folio?
> So:
> s/if folio is clean and unlocked/if folio is unlocked
That's a good point. Perhaps "unlocked and not under writeback"
would be better wording, since that would be true.
On Wed, Jan 10, 2024 at 05:26:55PM +0000, Matthew Wilcox wrote:
> On Wed, Jan 10, 2024 at 03:30:54PM +0100, Pankaj Raghav (Samsung) wrote:
> > > + * If all buffers on a folio have zero reference count, are clean
> > > + * and unlocked, and if the folio is clean and unlocked then
> >
> > IIUC from your [PATCH 3/8], folio only needs to be unlocked to free the
> > buffers as try_to_free_buffers() will remove the dirty flag and "clean"
> > the folio?
> > So:
> > s/if folio is clean and unlocked/if folio is unlocked
>
> That's a good point. Perhaps "unlocked and not under writeback"
> would be better wording, since that would be true.
Yeah. That sounds good to me!