1/* SPDX-License-Identifier: GPL-2.0 */
2#ifndef __LINUX_DCACHE_H
3#define __LINUX_DCACHE_H
4
5#include <linux/atomic.h>
6#include <linux/list.h>
7#include <linux/math.h>
8#include <linux/rculist.h>
9#include <linux/rculist_bl.h>
10#include <linux/spinlock.h>
11#include <linux/seqlock.h>
12#include <linux/cache.h>
13#include <linux/rcupdate.h>
14#include <linux/lockref.h>
15#include <linux/stringhash.h>
16#include <linux/wait.h>
17
18struct path;
19struct file;
20struct vfsmount;
21
22/*
23 * linux/include/linux/dcache.h
24 *
25 * Dirent cache data structures
26 *
27 * (C) Copyright 1997 Thomas Schoebel-Theuer,
28 * with heavy changes by Linus Torvalds
29 */
30
31#define IS_ROOT(x) ((x) == (x)->d_parent)
32
33/* The hash is always the low bits of hash_len */
34#ifdef __LITTLE_ENDIAN
35 #define HASH_LEN_DECLARE u32 hash; u32 len
36 #define bytemask_from_count(cnt) (~(~0ul << (cnt)*8))
37#else
38 #define HASH_LEN_DECLARE u32 len; u32 hash
39 #define bytemask_from_count(cnt) (~(~0ul >> (cnt)*8))
40#endif
41
42/*
43 * "quick string" -- eases parameter passing, but more importantly
44 * saves "metadata" about the string (ie length and the hash).
45 *
46 * hash comes first so it snuggles against d_parent in the
47 * dentry.
48 */
49struct qstr {
50 union {
51 struct {
52 HASH_LEN_DECLARE;
53 };
54 u64 hash_len;
55 };
56 const unsigned char *name;
57};
58
59#define QSTR_INIT(n,l) { { { .len = l } }, .name = n }
60#define QSTR_LEN(n,l) (struct qstr)QSTR_INIT(n,l)
61#define QSTR(n) QSTR_LEN(n, strlen(n))
62
63extern const struct qstr empty_name;
64extern const struct qstr slash_name;
65extern const struct qstr dotdot_name;
66
67/*
68 * Try to keep struct dentry aligned on 64 byte cachelines (this will
69 * give reasonable cacheline footprint with larger lines without the
70 * large memory footprint increase).
71 */
72#ifdef CONFIG_64BIT
73# define DNAME_INLINE_WORDS 5 /* 192 bytes */
74#else
75# ifdef CONFIG_SMP
76# define DNAME_INLINE_WORDS 9 /* 128 bytes */
77# else
78# define DNAME_INLINE_WORDS 11 /* 128 bytes */
79# endif
80#endif
81
82#define DNAME_INLINE_LEN (DNAME_INLINE_WORDS*sizeof(unsigned long))
83
84union shortname_store {
85 unsigned char string[DNAME_INLINE_LEN];
86 unsigned long words[DNAME_INLINE_WORDS];
87};
88
89#define d_lock d_lockref.lock
90#define d_iname d_shortname.string
91
92struct dentry {
93 /* RCU lookup touched fields */
94 unsigned int d_flags; /* protected by d_lock */
95 seqcount_spinlock_t d_seq; /* per dentry seqlock */
96 struct hlist_bl_node d_hash; /* lookup hash list */
97 struct dentry *d_parent; /* parent directory */
98 union {
99 struct qstr __d_name; /* for use ONLY in fs/dcache.c */
100 const struct qstr d_name;
101 };
102 struct inode *d_inode; /* Where the name belongs to - NULL is
103 * negative */
104 union shortname_store d_shortname;
105 /* --- cacheline 1 boundary (64 bytes) was 32 bytes ago --- */
106
107 /* Ref lookup also touches following */
108 const struct dentry_operations *d_op;
109 struct super_block *d_sb; /* The root of the dentry tree */
110 unsigned long d_time; /* used by d_revalidate */
111 void *d_fsdata; /* fs-specific data */
112 /* --- cacheline 2 boundary (128 bytes) --- */
113 struct lockref d_lockref; /* per-dentry lock and refcount
114 * keep separate from RCU lookup area if
115 * possible!
116 */
117
118 union {
119 struct list_head d_lru; /* LRU list */
120 wait_queue_head_t *d_wait; /* in-lookup ones only */
121 };
122 struct hlist_node d_sib; /* child of parent list */
123 struct hlist_head d_children; /* our children */
124 /*
125 * d_alias and d_rcu can share memory
126 */
127 union {
128 struct hlist_node d_alias; /* inode alias list */
129 struct hlist_bl_node d_in_lookup_hash; /* only for in-lookup ones */
130 struct rcu_head d_rcu;
131 } d_u;
132};
133
134/*
135 * dentry->d_lock spinlock nesting subclasses:
136 *
137 * 0: normal
138 * 1: nested
139 */
140enum dentry_d_lock_class
141{
142 DENTRY_D_LOCK_NORMAL, /* implicitly used by plain spin_lock() APIs. */
143 DENTRY_D_LOCK_NESTED
144};
145
146enum d_real_type {
147 D_REAL_DATA,
148 D_REAL_METADATA,
149};
150
151struct dentry_operations {
152 int (*d_revalidate)(struct inode *, const struct qstr *,
153 struct dentry *, unsigned int);
154 int (*d_weak_revalidate)(struct dentry *, unsigned int);
155 int (*d_hash)(const struct dentry *, struct qstr *);
156 int (*d_compare)(const struct dentry *,
157 unsigned int, const char *, const struct qstr *);
158 int (*d_delete)(const struct dentry *);
159 int (*d_init)(struct dentry *);
160 void (*d_release)(struct dentry *);
161 void (*d_prune)(struct dentry *);
162 void (*d_iput)(struct dentry *, struct inode *);
163 char *(*d_dname)(struct dentry *, char *, int);
164 struct vfsmount *(*d_automount)(struct path *);
165 int (*d_manage)(const struct path *, bool);
166 struct dentry *(*d_real)(struct dentry *, enum d_real_type type);
167 bool (*d_unalias_trylock)(const struct dentry *);
168 void (*d_unalias_unlock)(const struct dentry *);
169} ____cacheline_aligned;
170
171/*
172 * Locking rules for dentry_operations callbacks are to be found in
173 * Documentation/filesystems/locking.rst. Keep it updated!
174 *
175 * FUrther descriptions are found in Documentation/filesystems/vfs.rst.
176 * Keep it updated too!
177 */
178
179/* d_flags entries */
180enum dentry_flags {
181 DCACHE_OP_HASH = BIT(0),
182 DCACHE_OP_COMPARE = BIT(1),
183 DCACHE_OP_REVALIDATE = BIT(2),
184 DCACHE_OP_DELETE = BIT(3),
185 DCACHE_OP_PRUNE = BIT(4),
186 /*
187 * This dentry is possibly not currently connected to the dcache tree,
188 * in which case its parent will either be itself, or will have this
189 * flag as well. nfsd will not use a dentry with this bit set, but will
190 * first endeavour to clear the bit either by discovering that it is
191 * connected, or by performing lookup operations. Any filesystem which
192 * supports nfsd_operations MUST have a lookup function which, if it
193 * finds a directory inode with a DCACHE_DISCONNECTED dentry, will
194 * d_move that dentry into place and return that dentry rather than the
195 * passed one, typically using d_splice_alias.
196 */
197 DCACHE_DISCONNECTED = BIT(5),
198 DCACHE_REFERENCED = BIT(6), /* Recently used, don't discard. */
199 DCACHE_DONTCACHE = BIT(7), /* Purge from memory on final dput() */
200 DCACHE_CANT_MOUNT = BIT(8),
201 DCACHE_GENOCIDE = BIT(9),
202 DCACHE_SHRINK_LIST = BIT(10),
203 DCACHE_OP_WEAK_REVALIDATE = BIT(11),
204 /*
205 * this dentry has been "silly renamed" and has to be deleted on the
206 * last dput()
207 */
208 DCACHE_NFSFS_RENAMED = BIT(12),
209 DCACHE_FSNOTIFY_PARENT_WATCHED = BIT(13), /* Parent inode is watched by some fsnotify listener */
210 DCACHE_DENTRY_KILLED = BIT(14),
211 DCACHE_MOUNTED = BIT(15), /* is a mountpoint */
212 DCACHE_NEED_AUTOMOUNT = BIT(16), /* handle automount on this dir */
213 DCACHE_MANAGE_TRANSIT = BIT(17), /* manage transit from this dirent */
214 DCACHE_LRU_LIST = BIT(18),
215 DCACHE_ENTRY_TYPE = (7 << 19), /* bits 19..21 are for storing type: */
216 DCACHE_MISS_TYPE = (0 << 19), /* Negative dentry */
217 DCACHE_WHITEOUT_TYPE = (1 << 19), /* Whiteout dentry (stop pathwalk) */
218 DCACHE_DIRECTORY_TYPE = (2 << 19), /* Normal directory */
219 DCACHE_AUTODIR_TYPE = (3 << 19), /* Lookupless directory (presumed automount) */
220 DCACHE_REGULAR_TYPE = (4 << 19), /* Regular file type */
221 DCACHE_SPECIAL_TYPE = (5 << 19), /* Other file type */
222 DCACHE_SYMLINK_TYPE = (6 << 19), /* Symlink */
223 DCACHE_NOKEY_NAME = BIT(22), /* Encrypted name encoded without key */
224 DCACHE_OP_REAL = BIT(23),
225 DCACHE_PAR_LOOKUP = BIT(24), /* being looked up (with parent locked shared) */
226 DCACHE_DENTRY_CURSOR = BIT(25),
227 DCACHE_NORCU = BIT(26), /* No RCU delay for freeing */
228};
229
230#define DCACHE_MANAGED_DENTRY \
231 (DCACHE_MOUNTED|DCACHE_NEED_AUTOMOUNT|DCACHE_MANAGE_TRANSIT)
232
233extern seqlock_t rename_lock;
234
235/*
236 * These are the low-level FS interfaces to the dcache..
237 */
238extern void d_instantiate(struct dentry *, struct inode *);
239extern void d_instantiate_new(struct dentry *, struct inode *);
240extern void __d_drop(struct dentry *dentry);
241extern void d_drop(struct dentry *dentry);
242extern void d_delete(struct dentry *);
243
244/* allocate/de-allocate */
245extern struct dentry * d_alloc(struct dentry *, const struct qstr *);
246extern struct dentry * d_alloc_anon(struct super_block *);
247extern struct dentry * d_alloc_parallel(struct dentry *, const struct qstr *,
248 wait_queue_head_t *);
249extern struct dentry * d_splice_alias(struct inode *, struct dentry *);
250/* weird procfs mess; *NOT* exported */
251extern struct dentry * d_splice_alias_ops(struct inode *, struct dentry *,
252 const struct dentry_operations *);
253extern struct dentry * d_add_ci(struct dentry *, struct inode *, struct qstr *);
254extern bool d_same_name(const struct dentry *dentry, const struct dentry *parent,
255 const struct qstr *name);
256extern struct dentry *d_find_any_alias(struct inode *inode);
257extern struct dentry * d_obtain_alias(struct inode *);
258extern struct dentry * d_obtain_root(struct inode *);
259extern void shrink_dcache_sb(struct super_block *);
260extern void shrink_dcache_parent(struct dentry *);
261extern void d_invalidate(struct dentry *);
262
263/* only used at mount-time */
264extern struct dentry * d_make_root(struct inode *);
265
266extern void d_mark_tmpfile(struct file *, struct inode *);
267extern void d_tmpfile(struct file *, struct inode *);
268
269extern struct dentry *d_find_alias(struct inode *);
270extern void d_prune_aliases(struct inode *);
271
272extern struct dentry *d_find_alias_rcu(struct inode *);
273
274/* test whether we have any submounts in a subdir tree */
275extern int path_has_submounts(const struct path *);
276
277/*
278 * This adds the entry to the hash queues.
279 */
280extern void d_rehash(struct dentry *);
281
282extern void d_add(struct dentry *, struct inode *);
283
284/* used for rename() and baskets */
285extern void d_move(struct dentry *, struct dentry *);
286extern void d_exchange(struct dentry *, struct dentry *);
287extern struct dentry *d_ancestor(struct dentry *, struct dentry *);
288
289extern struct dentry *d_lookup(const struct dentry *, const struct qstr *);
290
291static inline unsigned d_count(const struct dentry *dentry)
292{
293 return dentry->d_lockref.count;
294}
295
296ino_t d_parent_ino(struct dentry *dentry);
297
298/*
299 * helper function for dentry_operations.d_dname() members
300 */
301extern __printf(3, 4)
302char *dynamic_dname(char *, int, const char *, ...);
303
304extern char *__d_path(const struct path *, const struct path *, char *, int);
305extern char *d_absolute_path(const struct path *, char *, int);
306extern char *d_path(const struct path *, char *, int);
307extern char *dentry_path_raw(const struct dentry *, char *, int);
308extern char *dentry_path(const struct dentry *, char *, int);
309
310/* Allocation counts.. */
311
312/**
313 * dget_dlock - get a reference to a dentry
314 * @dentry: dentry to get a reference to
315 *
316 * Given a live dentry, increment the reference count and return the dentry.
317 * Caller must hold @dentry->d_lock. Making sure that dentry is alive is
318 * caller's resonsibility. There are many conditions sufficient to guarantee
319 * that; e.g. anything with non-negative refcount is alive, so's anything
320 * hashed, anything positive, anyone's parent, etc.
321 */
322static inline struct dentry *dget_dlock(struct dentry *dentry)
323{
324 dentry->d_lockref.count++;
325 return dentry;
326}
327
328
329/**
330 * dget - get a reference to a dentry
331 * @dentry: dentry to get a reference to
332 *
333 * Given a dentry or %NULL pointer increment the reference count
334 * if appropriate and return the dentry. A dentry will not be
335 * destroyed when it has references. Conversely, a dentry with
336 * no references can disappear for any number of reasons, starting
337 * with memory pressure. In other words, that primitive is
338 * used to clone an existing reference; using it on something with
339 * zero refcount is a bug.
340 *
341 * NOTE: it will spin if @dentry->d_lock is held. From the deadlock
342 * avoidance point of view it is equivalent to spin_lock()/increment
343 * refcount/spin_unlock(), so calling it under @dentry->d_lock is
344 * always a bug; so's calling it under ->d_lock on any of its descendents.
345 *
346 */
347static inline struct dentry *dget(struct dentry *dentry)
348{
349 if (dentry)
350 lockref_get(lockref: &dentry->d_lockref);
351 return dentry;
352}
353
354extern struct dentry *dget_parent(struct dentry *dentry);
355
356/**
357 * d_unhashed - is dentry hashed
358 * @dentry: entry to check
359 *
360 * Returns true if the dentry passed is not currently hashed.
361 */
362static inline int d_unhashed(const struct dentry *dentry)
363{
364 return hlist_bl_unhashed(h: &dentry->d_hash);
365}
366
367static inline int d_unlinked(const struct dentry *dentry)
368{
369 return d_unhashed(dentry) && !IS_ROOT(dentry);
370}
371
372static inline int cant_mount(const struct dentry *dentry)
373{
374 return (dentry->d_flags & DCACHE_CANT_MOUNT);
375}
376
377static inline void dont_mount(struct dentry *dentry)
378{
379 spin_lock(lock: &dentry->d_lock);
380 dentry->d_flags |= DCACHE_CANT_MOUNT;
381 spin_unlock(lock: &dentry->d_lock);
382}
383
384extern void __d_lookup_unhash_wake(struct dentry *dentry);
385
386static inline int d_in_lookup(const struct dentry *dentry)
387{
388 return dentry->d_flags & DCACHE_PAR_LOOKUP;
389}
390
391static inline void d_lookup_done(struct dentry *dentry)
392{
393 if (unlikely(d_in_lookup(dentry)))
394 __d_lookup_unhash_wake(dentry);
395}
396
397extern void dput(struct dentry *);
398
399static inline bool d_managed(const struct dentry *dentry)
400{
401 return dentry->d_flags & DCACHE_MANAGED_DENTRY;
402}
403
404static inline bool d_mountpoint(const struct dentry *dentry)
405{
406 return dentry->d_flags & DCACHE_MOUNTED;
407}
408
409/*
410 * Directory cache entry type accessor functions.
411 */
412static inline unsigned __d_entry_type(const struct dentry *dentry)
413{
414 return dentry->d_flags & DCACHE_ENTRY_TYPE;
415}
416
417static inline bool d_is_miss(const struct dentry *dentry)
418{
419 return __d_entry_type(dentry) == DCACHE_MISS_TYPE;
420}
421
422static inline bool d_is_whiteout(const struct dentry *dentry)
423{
424 return __d_entry_type(dentry) == DCACHE_WHITEOUT_TYPE;
425}
426
427static inline bool d_can_lookup(const struct dentry *dentry)
428{
429 return __d_entry_type(dentry) == DCACHE_DIRECTORY_TYPE;
430}
431
432static inline bool d_is_autodir(const struct dentry *dentry)
433{
434 return __d_entry_type(dentry) == DCACHE_AUTODIR_TYPE;
435}
436
437static inline bool d_is_dir(const struct dentry *dentry)
438{
439 return d_can_lookup(dentry) || d_is_autodir(dentry);
440}
441
442static inline bool d_is_symlink(const struct dentry *dentry)
443{
444 return __d_entry_type(dentry) == DCACHE_SYMLINK_TYPE;
445}
446
447static inline bool d_is_reg(const struct dentry *dentry)
448{
449 return __d_entry_type(dentry) == DCACHE_REGULAR_TYPE;
450}
451
452static inline bool d_is_special(const struct dentry *dentry)
453{
454 return __d_entry_type(dentry) == DCACHE_SPECIAL_TYPE;
455}
456
457static inline bool d_is_file(const struct dentry *dentry)
458{
459 return d_is_reg(dentry) || d_is_special(dentry);
460}
461
462static inline bool d_is_negative(const struct dentry *dentry)
463{
464 // TODO: check d_is_whiteout(dentry) also.
465 return d_is_miss(dentry);
466}
467
468static inline bool d_flags_negative(unsigned flags)
469{
470 return (flags & DCACHE_ENTRY_TYPE) == DCACHE_MISS_TYPE;
471}
472
473static inline bool d_is_positive(const struct dentry *dentry)
474{
475 return !d_is_negative(dentry);
476}
477
478/**
479 * d_really_is_negative - Determine if a dentry is really negative (ignoring fallthroughs)
480 * @dentry: The dentry in question
481 *
482 * Returns true if the dentry represents either an absent name or a name that
483 * doesn't map to an inode (ie. ->d_inode is NULL). The dentry could represent
484 * a true miss, a whiteout that isn't represented by a 0,0 chardev or a
485 * fallthrough marker in an opaque directory.
486 *
487 * Note! (1) This should be used *only* by a filesystem to examine its own
488 * dentries. It should not be used to look at some other filesystem's
489 * dentries. (2) It should also be used in combination with d_inode() to get
490 * the inode. (3) The dentry may have something attached to ->d_lower and the
491 * type field of the flags may be set to something other than miss or whiteout.
492 */
493static inline bool d_really_is_negative(const struct dentry *dentry)
494{
495 return dentry->d_inode == NULL;
496}
497
498/**
499 * d_really_is_positive - Determine if a dentry is really positive (ignoring fallthroughs)
500 * @dentry: The dentry in question
501 *
502 * Returns true if the dentry represents a name that maps to an inode
503 * (ie. ->d_inode is not NULL). The dentry might still represent a whiteout if
504 * that is represented on medium as a 0,0 chardev.
505 *
506 * Note! (1) This should be used *only* by a filesystem to examine its own
507 * dentries. It should not be used to look at some other filesystem's
508 * dentries. (2) It should also be used in combination with d_inode() to get
509 * the inode.
510 */
511static inline bool d_really_is_positive(const struct dentry *dentry)
512{
513 return dentry->d_inode != NULL;
514}
515
516static inline int simple_positive(const struct dentry *dentry)
517{
518 return d_really_is_positive(dentry) && !d_unhashed(dentry);
519}
520
521unsigned long vfs_pressure_ratio(unsigned long val);
522
523/**
524 * d_inode - Get the actual inode of this dentry
525 * @dentry: The dentry to query
526 *
527 * This is the helper normal filesystems should use to get at their own inodes
528 * in their own dentries and ignore the layering superimposed upon them.
529 */
530static inline struct inode *d_inode(const struct dentry *dentry)
531{
532 return dentry->d_inode;
533}
534
535/**
536 * d_inode_rcu - Get the actual inode of this dentry with READ_ONCE()
537 * @dentry: The dentry to query
538 *
539 * This is the helper normal filesystems should use to get at their own inodes
540 * in their own dentries and ignore the layering superimposed upon them.
541 */
542static inline struct inode *d_inode_rcu(const struct dentry *dentry)
543{
544 return READ_ONCE(dentry->d_inode);
545}
546
547/**
548 * d_backing_inode - Get upper or lower inode we should be using
549 * @upper: The upper layer
550 *
551 * This is the helper that should be used to get at the inode that will be used
552 * if this dentry were to be opened as a file. The inode may be on the upper
553 * dentry or it may be on a lower dentry pinned by the upper.
554 *
555 * Normal filesystems should not use this to access their own inodes.
556 */
557static inline struct inode *d_backing_inode(const struct dentry *upper)
558{
559 struct inode *inode = upper->d_inode;
560
561 return inode;
562}
563
564/**
565 * d_real - Return the real dentry
566 * @dentry: the dentry to query
567 * @type: the type of real dentry (data or metadata)
568 *
569 * If dentry is on a union/overlay, then return the underlying, real dentry.
570 * Otherwise return the dentry itself.
571 *
572 * See also: Documentation/filesystems/vfs.rst
573 */
574static inline struct dentry *d_real(struct dentry *dentry, enum d_real_type type)
575{
576 if (unlikely(dentry->d_flags & DCACHE_OP_REAL))
577 return dentry->d_op->d_real(dentry, type);
578 else
579 return dentry;
580}
581
582/**
583 * d_real_inode - Return the real inode hosting the data
584 * @dentry: The dentry to query
585 *
586 * If dentry is on a union/overlay, then return the underlying, real inode.
587 * Otherwise return d_inode().
588 */
589static inline struct inode *d_real_inode(const struct dentry *dentry)
590{
591 /* This usage of d_real() results in const dentry */
592 return d_inode(dentry: d_real(dentry: (struct dentry *) dentry, type: D_REAL_DATA));
593}
594
595struct name_snapshot {
596 struct qstr name;
597 union shortname_store inline_name;
598};
599void take_dentry_name_snapshot(struct name_snapshot *, struct dentry *);
600void release_dentry_name_snapshot(struct name_snapshot *);
601
602static inline struct dentry *d_first_child(const struct dentry *dentry)
603{
604 return hlist_entry_safe(dentry->d_children.first, struct dentry, d_sib);
605}
606
607static inline struct dentry *d_next_sibling(const struct dentry *dentry)
608{
609 return hlist_entry_safe(dentry->d_sib.next, struct dentry, d_sib);
610}
611
612void set_default_d_op(struct super_block *, const struct dentry_operations *);
613
614#endif /* __LINUX_DCACHE_H */
615