[PATCH RFC 3/5] fs: fix __lookup_mnt() documentation

From: Christian Brauner <brauner@kernel.org>
To: Al Viro <viro@zeniv.linux.org.uk>, Seth Forshee <sforshee@kernel.org>
Cc: linux-fsdevel@vger.kernel.org,
	"Christian Brauner (Microsoft)" <brauner@kernel.org>
Subject: [PATCH RFC 3/5] fs: fix __lookup_mnt() documentation
Date: Sat, 18 Mar 2023 16:51:59 +0100	[thread overview]
Message-ID: <20230202-fs-move-mount-replace-v1-3-9b73026d5f10@kernel.org> (raw)
In-Reply-To: <20230202-fs-move-mount-replace-v1-0-9b73026d5f10@kernel.org>

The comment on top of __lookup_mnt() states that it finds the first
mount implying that there could be multiple mounts mounted at the same
dentry with the same parent.

This was true on old kernels where __lookup_mnt() could encounter a
stack of child mounts such that each child had the same parent mount and
was mounted at the same dentry. These were called "shadow mounts" and
were created during mount propagation. So back then if a mount @m in the
destination propagation tree already had a child mount @p mounted at
@mp then any mount @n we propagated to @m at the same @mp would be
appended after the preexisting mount @p in @mount_hashtable.

This hasn't been the case for quite a while now and I don't see an
obvious way how such mount stacks could be created in another way. And
if that's possible it would invalidate assumptions made in other parts
of the code.

So for a long time on all relevant kernels the child-parent relationship
is unique per dentry. So given a child mount @c mounted at its parent
mount @p on dentry @mp means that @c is the only child mounted on
@p at @mp. Should a mount @m be propagated to @p on @mp then @m will be
mounted on @p at @mp and the preexisting child @c will be remounted on
top of @m at @m->mnt_root.

Signed-off-by: Christian Brauner (Microsoft) <brauner@kernel.org>
---
 fs/namespace.c | 13 ++++++++++---
 1 file changed, 10 insertions(+), 3 deletions(-)

diff --git a/fs/namespace.c b/fs/namespace.c
index 154569fd7343..42dc87f86f34 100644
--- a/fs/namespace.c
+++ b/fs/namespace.c
@@ -658,9 +658,16 @@ static bool legitimize_mnt(struct vfsmount *bastard, unsigned seq)
 	return false;
 }
 
-/*
- * find the first mount at @dentry on vfsmount @mnt.
- * call under rcu_read_lock()
+/**
+ * __lookup_mnt - find child mount
+ * @mnt:	parent mount
+ * @dentry:	mountpoint
+ *
+ * If @mnt has a child mount mounted @dentry find and return it. If a
+ * mount is found it is unique, i.e., there are no shadow child mounts
+ * with @mnt as parent and mounted at @dentry.
+ *
+ * Return: The child of @mnt mounted @dentry or NULL if there is none.
  */
 struct mount *__lookup_mnt(struct vfsmount *mnt, struct dentry *dentry)
 {

-- 
2.34.1

