Document the BA_CLRBUF flag used in ufs and ext2fs filesystems.

Suggested by: kib
MFC after:    3 days
Sponsored by: Netflix

1 files changed, 7 insertions, 0 deletions

diff --git a/sys/ufs/ufs/ufs_extern.h b/sys/ufs/ufs/ufs_extern.h
index cc6078065e7f..a28fcffabd2e 100644
--- a/sys/ufs/ufs/ufs_extern.h
+++ b/sys/ufs/ufs/ufs_extern.h
@@ -119,6 +119,13 @@ void	softdep_revert_rmdir(struct inode *, struct inode *);
  *
  * Note: The general vfs code typically limits the sequential heuristic
  * count to 127.  See sequential_heuristic() in kern/vfs_vnops.c
+ *
+ * The BA_CLRBUF flag specifies that the existing content of the block
+ * will not be completely overwritten by the caller, so buffers for new
+ * blocks must be cleared and buffers for existing blocks must be read.
+ * When BA_CLRBUF is not set the buffer will be completely overwritten
+ * and there is no reason to clear them or to spend I/O fetching existing
+ * data. The BA_CLRBUF flag is handled in the UFS_BALLOC() functions.
  */
 #define	BA_CLRBUF	0x00010000	/* Clear invalid areas of buffer. */
 #define	BA_METAONLY	0x00020000	/* Return indirect block buffer. */