dcache.h

  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_SHRINK_LIST		= BIT(10),
202	DCACHE_OP_WEAK_REVALIDATE	= BIT(11),
203	/*
204	 * this dentry has been "silly renamed" and has to be deleted on the
205	 * last dput()
206	 */
207	DCACHE_NFSFS_RENAMED		= BIT(12),
208	DCACHE_FSNOTIFY_PARENT_WATCHED	= BIT(13),	/* Parent inode is watched by some fsnotify listener */
209	DCACHE_DENTRY_KILLED		= BIT(14),
210	DCACHE_MOUNTED			= BIT(15),	/* is a mountpoint */
211	DCACHE_NEED_AUTOMOUNT		= BIT(16),	/* handle automount on this dir */
212	DCACHE_MANAGE_TRANSIT		= BIT(17),	/* manage transit from this dirent */
213	DCACHE_LRU_LIST			= BIT(18),
214	DCACHE_ENTRY_TYPE		= (7 << 19),	/* bits 19..21 are for storing type: */
215	DCACHE_MISS_TYPE		= (0 << 19),	/* Negative dentry */
216	DCACHE_WHITEOUT_TYPE		= (1 << 19),	/* Whiteout dentry (stop pathwalk) */
217	DCACHE_DIRECTORY_TYPE		= (2 << 19),	/* Normal directory */
218	DCACHE_AUTODIR_TYPE		= (3 << 19),	/* Lookupless directory (presumed automount) */
219	DCACHE_REGULAR_TYPE		= (4 << 19),	/* Regular file type */
220	DCACHE_SPECIAL_TYPE		= (5 << 19),	/* Other file type */
221	DCACHE_SYMLINK_TYPE		= (6 << 19),	/* Symlink */
222	DCACHE_NOKEY_NAME		= BIT(22),	/* Encrypted name encoded without key */
223	DCACHE_OP_REAL			= BIT(23),
224	DCACHE_PAR_LOOKUP		= BIT(24),	/* being looked up (with parent locked shared) */
225	DCACHE_DENTRY_CURSOR		= BIT(25),
226	DCACHE_NORCU			= BIT(26),	/* No RCU delay for freeing */
227	DCACHE_PERSISTENT		= BIT(27)
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 *);
271extern void d_dispose_if_unused(struct dentry *, struct list_head *);
272extern void shrink_dentry_list(struct list_head *);
273
274extern struct dentry *d_find_alias_rcu(struct inode *);
275
276/* test whether we have any submounts in a subdir tree */
277extern int path_has_submounts(const struct path *);
278
279/*
280 * This adds the entry to the hash queues.
281 */
282extern void d_rehash(struct dentry *);
283 
284extern void d_add(struct dentry *, struct inode *);
285
286/* used for rename() and baskets */
287extern void d_move(struct dentry *, struct dentry *);
288extern void d_exchange(struct dentry *, struct dentry *);
289extern struct dentry *d_ancestor(struct dentry *, struct dentry *);
290
291extern struct dentry *d_lookup(const struct dentry *, const struct qstr *);
292
293static inline unsigned d_count(const struct dentry *dentry)
294{
295	return dentry->d_lockref.count;
296}
297
298ino_t d_parent_ino(struct dentry *dentry);
299
300/*
301 * helper function for dentry_operations.d_dname() members
302 */
303extern __printf(3, 4)
304char *dynamic_dname(char *, int, const char *, ...);
305
306extern char *__d_path(const struct path *, const struct path *, char *, int);
307extern char *d_absolute_path(const struct path *, char *, int);
308extern char *d_path(const struct path *, char *, int);
309extern char *dentry_path_raw(const struct dentry *, char *, int);
310extern char *dentry_path(const struct dentry *, char *, int);
311
312/* Allocation counts.. */
313
314/**
315 * dget_dlock -	get a reference to a dentry
316 * @dentry: dentry to get a reference to
317 *
318 * Given a live dentry, increment the reference count and return the dentry.
319 * Caller must hold @dentry->d_lock.  Making sure that dentry is alive is
320 * caller's resonsibility.  There are many conditions sufficient to guarantee
321 * that; e.g. anything with non-negative refcount is alive, so's anything
322 * hashed, anything positive, anyone's parent, etc.
323 */
324static inline struct dentry *dget_dlock(struct dentry *dentry)
325{
326	dentry->d_lockref.count++;
327	return dentry;
328}
329
330
331/**
332 * dget - get a reference to a dentry
333 * @dentry: dentry to get a reference to
334 *
335 * Given a dentry or %NULL pointer increment the reference count
336 * if appropriate and return the dentry.  A dentry will not be
337 * destroyed when it has references.  Conversely, a dentry with
338 * no references can disappear for any number of reasons, starting
339 * with memory pressure.  In other words, that primitive is
340 * used to clone an existing reference; using it on something with
341 * zero refcount is a bug.
342 *
343 * NOTE: it will spin if @dentry->d_lock is held.  From the deadlock
344 * avoidance point of view it is equivalent to spin_lock()/increment
345 * refcount/spin_unlock(), so calling it under @dentry->d_lock is
346 * always a bug; so's calling it under ->d_lock on any of its descendents.
347 *
348 */
349static inline struct dentry *dget(struct dentry *dentry)
350{
351	if (dentry)
352		lockref_get(&dentry->d_lockref);
353	return dentry;
354}
355
356extern struct dentry *dget_parent(struct dentry *dentry);
357
358/**
359 * d_unhashed - is dentry hashed
360 * @dentry: entry to check
361 *
362 * Returns true if the dentry passed is not currently hashed.
363 */
364static inline int d_unhashed(const struct dentry *dentry)
365{
366	return hlist_bl_unhashed(&dentry->d_hash);
367}
368
369static inline int d_unlinked(const struct dentry *dentry)
370{
371	return d_unhashed(dentry) && !IS_ROOT(dentry);
372}
373
374static inline int cant_mount(const struct dentry *dentry)
375{
376	return (dentry->d_flags & DCACHE_CANT_MOUNT);
377}
378
379static inline void dont_mount(struct dentry *dentry)
380{
381	spin_lock(&dentry->d_lock);
382	dentry->d_flags |= DCACHE_CANT_MOUNT;
383	spin_unlock(&dentry->d_lock);
384}
385
386extern void __d_lookup_unhash_wake(struct dentry *dentry);
387
388static inline int d_in_lookup(const struct dentry *dentry)
389{
390	return dentry->d_flags & DCACHE_PAR_LOOKUP;
391}
392
393static inline void d_lookup_done(struct dentry *dentry)
394{
395	if (unlikely(d_in_lookup(dentry)))
396		__d_lookup_unhash_wake(dentry);
397}
398
399extern void dput(struct dentry *);
400
401static inline bool d_managed(const struct dentry *dentry)
402{
403	return dentry->d_flags & DCACHE_MANAGED_DENTRY;
404}
405
406static inline bool d_mountpoint(const struct dentry *dentry)
407{
408	return dentry->d_flags & DCACHE_MOUNTED;
409}
410
411/*
412 * Directory cache entry type accessor functions.
413 */
414static inline unsigned __d_entry_type(const struct dentry *dentry)
415{
416	return dentry->d_flags & DCACHE_ENTRY_TYPE;
417}
418
419static inline bool d_is_miss(const struct dentry *dentry)
420{
421	return __d_entry_type(dentry) == DCACHE_MISS_TYPE;
422}
423
424static inline bool d_is_whiteout(const struct dentry *dentry)
425{
426	return __d_entry_type(dentry) == DCACHE_WHITEOUT_TYPE;
427}
428
429static inline bool d_can_lookup(const struct dentry *dentry)
430{
431	return __d_entry_type(dentry) == DCACHE_DIRECTORY_TYPE;
432}
433
434static inline bool d_is_autodir(const struct dentry *dentry)
435{
436	return __d_entry_type(dentry) == DCACHE_AUTODIR_TYPE;
437}
438
439static inline bool d_is_dir(const struct dentry *dentry)
440{
441	return d_can_lookup(dentry) || d_is_autodir(dentry);
442}
443
444static inline bool d_is_symlink(const struct dentry *dentry)
445{
446	return __d_entry_type(dentry) == DCACHE_SYMLINK_TYPE;
447}
448
449static inline bool d_is_reg(const struct dentry *dentry)
450{
451	return __d_entry_type(dentry) == DCACHE_REGULAR_TYPE;
452}
453
454static inline bool d_is_special(const struct dentry *dentry)
455{
456	return __d_entry_type(dentry) == DCACHE_SPECIAL_TYPE;
457}
458
459static inline bool d_is_file(const struct dentry *dentry)
460{
461	return d_is_reg(dentry) || d_is_special(dentry);
462}
463
464static inline bool d_is_negative(const struct dentry *dentry)
465{
466	// TODO: check d_is_whiteout(dentry) also.
467	return d_is_miss(dentry);
468}
469
470static inline bool d_flags_negative(unsigned flags)
471{
472	return (flags & DCACHE_ENTRY_TYPE) == DCACHE_MISS_TYPE;
473}
474
475static inline bool d_is_positive(const struct dentry *dentry)
476{
477	return !d_is_negative(dentry);
478}
479
480/**
481 * d_really_is_negative - Determine if a dentry is really negative (ignoring fallthroughs)
482 * @dentry: The dentry in question
483 *
484 * Returns true if the dentry represents either an absent name or a name that
485 * doesn't map to an inode (ie. ->d_inode is NULL).  The dentry could represent
486 * a true miss, a whiteout that isn't represented by a 0,0 chardev or a
487 * fallthrough marker in an opaque directory.
488 *
489 * Note!  (1) This should be used *only* by a filesystem to examine its own
490 * dentries.  It should not be used to look at some other filesystem's
491 * dentries.  (2) It should also be used in combination with d_inode() to get
492 * the inode.  (3) The dentry may have something attached to ->d_lower and the
493 * type field of the flags may be set to something other than miss or whiteout.
494 */
495static inline bool d_really_is_negative(const struct dentry *dentry)
496{
497	return dentry->d_inode == NULL;
498}
499
500/**
501 * d_really_is_positive - Determine if a dentry is really positive (ignoring fallthroughs)
502 * @dentry: The dentry in question
503 *
504 * Returns true if the dentry represents a name that maps to an inode
505 * (ie. ->d_inode is not NULL).  The dentry might still represent a whiteout if
506 * that is represented on medium as a 0,0 chardev.
507 *
508 * Note!  (1) This should be used *only* by a filesystem to examine its own
509 * dentries.  It should not be used to look at some other filesystem's
510 * dentries.  (2) It should also be used in combination with d_inode() to get
511 * the inode.
512 */
513static inline bool d_really_is_positive(const struct dentry *dentry)
514{
515	return dentry->d_inode != NULL;
516}
517
518static inline int simple_positive(const struct dentry *dentry)
519{
520	return d_really_is_positive(dentry) && !d_unhashed(dentry);
521}
522
523unsigned long vfs_pressure_ratio(unsigned long val);
524
525/**
526 * d_inode - Get the actual inode of this dentry
527 * @dentry: The dentry to query
528 *
529 * This is the helper normal filesystems should use to get at their own inodes
530 * in their own dentries and ignore the layering superimposed upon them.
531 */
532static inline struct inode *d_inode(const struct dentry *dentry)
533{
534	return dentry->d_inode;
535}
536
537/**
538 * d_inode_rcu - Get the actual inode of this dentry with READ_ONCE()
539 * @dentry: The dentry to query
540 *
541 * This is the helper normal filesystems should use to get at their own inodes
542 * in their own dentries and ignore the layering superimposed upon them.
543 */
544static inline struct inode *d_inode_rcu(const struct dentry *dentry)
545{
546	return READ_ONCE(dentry->d_inode);
547}
548
549/**
550 * d_backing_inode - Get upper or lower inode we should be using
551 * @upper: The upper layer
552 *
553 * This is the helper that should be used to get at the inode that will be used
554 * if this dentry were to be opened as a file.  The inode may be on the upper
555 * dentry or it may be on a lower dentry pinned by the upper.
556 *
557 * Normal filesystems should not use this to access their own inodes.
558 */
559static inline struct inode *d_backing_inode(const struct dentry *upper)
560{
561	struct inode *inode = upper->d_inode;
562
563	return inode;
564}
565
566/**
567 * d_real - Return the real dentry
568 * @dentry: the dentry to query
569 * @type: the type of real dentry (data or metadata)
570 *
571 * If dentry is on a union/overlay, then return the underlying, real dentry.
572 * Otherwise return the dentry itself.
573 *
574 * See also: Documentation/filesystems/vfs.rst
575 */
576static inline struct dentry *d_real(struct dentry *dentry, enum d_real_type type)
577{
578	if (unlikely(dentry->d_flags & DCACHE_OP_REAL))
579		return dentry->d_op->d_real(dentry, type);
580	else
581		return dentry;
582}
583
584/**
585 * d_real_inode - Return the real inode hosting the data
586 * @dentry: The dentry to query
587 *
588 * If dentry is on a union/overlay, then return the underlying, real inode.
589 * Otherwise return d_inode().
590 */
591static inline struct inode *d_real_inode(const struct dentry *dentry)
592{
593	/* This usage of d_real() results in const dentry */
594	return d_inode(d_real((struct dentry *) dentry, D_REAL_DATA));
595}
596
597struct name_snapshot {
598	struct qstr name;
599	union shortname_store inline_name;
600};
601void take_dentry_name_snapshot(struct name_snapshot *, struct dentry *);
602void release_dentry_name_snapshot(struct name_snapshot *);
603
604static inline struct dentry *d_first_child(const struct dentry *dentry)
605{
606	return hlist_entry_safe(dentry->d_children.first, struct dentry, d_sib);
607}
608
609static inline struct dentry *d_next_sibling(const struct dentry *dentry)
610{
611	return hlist_entry_safe(dentry->d_sib.next, struct dentry, d_sib);
612}
613
614void set_default_d_op(struct super_block *, const struct dentry_operations *);
615struct dentry *d_make_persistent(struct dentry *, struct inode *);
616void d_make_discardable(struct dentry *dentry);
617
618#endif	/* __LINUX_DCACHE_H */