[PATCH 2/4] fs: document seqlock usage in pwd pool APIs

[Christian Brauner]

Document why get_fs_pwd_pool() and put_fs_pwd_pool() use
read_seqlock_excl() rather than write_seqlock() to modify pwd_refs.

read_seqlock_excl() acquires the writer spinlock without bumping the
sequence counter. This is correct because pwd_refs changes don't affect
the path values that lockless seq readers care about. Using
write_seqlock() would needlessly force retries in concurrent
get_fs_pwd()/get_fs_root() callers.

Signed-off-by: Christian Brauner <brauner@xxxxxxxxxx>
---
 include/linux/fs_struct.h | 12 ++++++++++--
 1 file changed, 10 insertions(+), 2 deletions(-)

diff --git a/include/linux/fs_struct.h b/include/linux/fs_struct.h
index 9414a572d8f2..b88437f04672 100644
--- a/include/linux/fs_struct.h
+++ b/include/linux/fs_struct.h
@@ -41,7 +41,15 @@ static inline void get_fs_pwd(struct fs_struct *fs, struct path *pwd)
 	read_sequnlock_excl(&fs->seq);
 }
 
-/* Acquire a pwd reference from the pwd_refs pool, if available */
+/*
+ * Acquire a pwd reference from the pwd_refs pool, if available.
+ *
+ * Uses read_seqlock_excl() (writer spinlock without sequence bump) rather
+ * than write_seqlock() because modifying pwd_refs does not change the path
+ * values that lockless seq readers care about. Bumping the sequence counter
+ * would force unnecessary retries in concurrent get_fs_pwd()/get_fs_root()
+ * callers.
+ */
 static inline void get_fs_pwd_pool(struct fs_struct *fs, struct path *pwd)
 {
 	read_seqlock_excl(&fs->seq);
@@ -53,7 +61,7 @@ static inline void get_fs_pwd_pool(struct fs_struct *fs, struct path *pwd)
 	read_sequnlock_excl(&fs->seq);
 }
 
-/* Release a pwd reference back to the pwd_refs pool, if appropriate */
+/* Release a pwd reference back to the pwd_refs pool, if appropriate. */
 static inline void put_fs_pwd_pool(struct fs_struct *fs, struct path *pwd)
 {
 	read_seqlock_excl(&fs->seq);
-- 
2.47.3


--jqlkhartfnby3ev3
Content-Type: text/x-diff; charset=utf-8
Content-Disposition: attachment;
	filename="0003-fs-add-drain_fs_pwd_pool-helper.patch"