Documentation/filesystems/path-lookup.txt

5 performing a path walk. Typically, for every open(), stat() etc., the path name
17 thus in every component during path look-up. Since 2.5.10 onwards, fast-walk
30 are path-walk intensive tend to do path lookups starting from a common dentry
34 Since 2.6.38, RCU is used to make a significant part of the entire path walk
36 even stores into cachelines of common dentries). This is known as "rcu-walk"
56 permissions on the parent inode to be able to walk into it.
67 - find the start point of the walk;
92 point to perform the next step of our path walk against.
162 still at 2. Now when it follows 2's 'next' pointer, it will walk off into
180 start the next part of the path walk from).
186 the next part of the path walk. When loading the coherent snapshot under d_seq,
209 RCU-walk path walking design
212 Path walking code now has two distinct modes, ref-walk and rcu-walk. ref-walk
215 it. ref-walk is simple and obvious, and may sleep, take locks, etc while path
216 walking is operating on each dentry. rcu-walk uses seqcount based dentry
218 shared data in the dentry or inode. rcu-walk can not be applied to all cases,
219 eg. if the filesystem must sleep or perform non trivial operations, rcu-walk
220 must be switched to ref-walk mode.
222 [*] RCU is still used for the dentry hash lookup in ref-walk, but not the full
223     path walk.
225 Where ref-walk uses a stable, refcounted ``parent'' to walk the remaining
226 path string, rcu-walk uses a d_seq protected snapshot. When looking up a
229 ladder of snapshots to walk down.
246     +---------------------+   rcu-walk begins here, we note d_seq, check the
273 Taking a refcount on a dentry from rcu-walk mode, by taking its d_lock,
275 "dropping rcu" or dropping from rcu-walk into ref-walk mode.
280 the path walk must be fully restarted (which we do in ref-walk mode, to avoid
285 requires ref-walk, then instead of restarting the walk, we attempt to drop rcu
286 at the last known good dentry we have. Avoiding a full restart in ref-walk in
290 The detailed design for rcu-walk is like this:
291 * LOOKUP_RCU is set in nd->flags, which distinguishes rcu-walk from ref-walk.
292 * Take the RCU lock for the entire path walk, starting with the acquiring
296   access d_ops and i_ops during rcu-walk.
297 * Similarly take the vfsmount lock for the entire path walk. So now mnt
306   during the path walk.
309 * i_mode, i_uid, i_gid can be tested for exec permissions during path walk.
314   of the path lookup in ref-walk mode. -ECHILD tends to be used (for want of
315   a better errno) to signal an rcu-walk failure.
317 The cases where rcu-walk cannot continue are:
321 It may be possible eventually to make following links rcu-walk aware.
323 Uncached path elements will always require dropping to ref-walk mode, at the
355 What this shows is that failed rcu-walk lookups, ie. ones that are restarted
356 entirely with ref-walk, are quite rare. Even the "vfstest" case which
360 Dropping from rcu-walk to ref-walk mean that we have encountered a dentry where
362 we have reached the target of the path walk, or because we have encountered a
363 condition that can't be resolved in rcu-walk mode.  Ideally, we drop rcu-walk
367 Note that a graceful drop from rcu-walk mode due to something such as the
369 rcu-walk scheme, because some elements of the path may have been walked in
370 rcu-walk mode. The further we get from common path elements (such as cwd or