[v3,6/8] buffer: Add kernel-doc for bforget() and __bforget()

Commit Message

Matthew Wilcox April 16, 2024, 3:17 a.m. UTC

Distinguish these functions from brelse() and __brelse().

Signed-off-by: Matthew Wilcox (Oracle) <[e-mail]>
---
 fs/buffer.c                 |  9 ++++++---
 include/linux/buffer_head.h | 10 ++++++++++
 2 files changed, 16 insertions(+), 3 deletions(-)

Comments

Randy Dunlap April 17, 2024, 2:13 a.m. UTC | #1

On 4/15/24 8:17 PM, Matthew Wilcox (Oracle) wrote:
> Distinguish these functions from brelse() and __brelse().
> 
> Signed-off-by: Matthew Wilcox (Oracle) <[e-mail]>

Tested-by: Randy Dunlap <[e-mail]>
Thanks.

> ---
>  fs/buffer.c                 |  9 ++++++---
>  include/linux/buffer_head.h | 10 ++++++++++
>  2 files changed, 16 insertions(+), 3 deletions(-)
>

Patch

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)