Documentation/filesystems/path-lookup.txt

22 Since 2.5.62 kernel, dcache has been using a new locking model that uses RCU to
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"
84 The hash lists are RCU protected, so list walking is not serialised with
85 concurrent updates (insertion, deletion from the hash). This is a standard RCU
100 Back to the rename case. In usual RCU protected lists, the only operations that
102 list. The object will not be reused until an RCU grace period is complete.
103 This ensures the RCU list traversal primitives can run over the object without
104 problems (see RCU documentation for how this works).
114 new list before waiting for a grace period, this can result in a concurrent RCU
143 This is a standard RCU-list deletion, which leaves the deleted object's
197 What this means is that a caller, provided they are holding RCU lock to
203 Inodes are also rcu freed, so the seqcount lookup dentry's inode may also be
209 RCU-walk path walking design
212 Path walking code now has two distinct modes, ref-walk and rcu-walk. ref-walk
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
222 [*] RCU is still used for the dentry hash lookup in ref-walk, but not the full
226 path string, rcu-walk uses a d_seq protected snapshot. When looking up a
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.
285 requires ref-walk, then instead of restarting the walk, we attempt to drop rcu
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.
307 * inode is also RCU protected so we can load d_inode and use the inode for
311 * When the destination dentry is reached, drop rcu there (ie. take d_lock,
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.
340 The following table gives rcu lookup statistics for a few simple workloads
342 drop rcu that fail due to d_seq failure and requiring the entire path lookup
343 again. Other cases are successful rcu-drops that are required before the final
345 routine requiring rcu drop, permission for permission check requiring drop,
348      rcu-lookups     restart  nodentry          link  revalidate  permission
355 What this shows is that failed rcu-walk lookups, ie. ones that are restarted
360 Dropping from rcu-walk to ref-walk mean that we have encountered a dentry where
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
378 1. Scaling dcache with RCU (https://linuxjournal.com/article.php?sid=7124).