xref: /openbmc/linux/include/linux/kernfs.h (revision 86bee12f)
1 /*
2  * kernfs.h - pseudo filesystem decoupled from vfs locking
3  *
4  * This file is released under the GPLv2.
5  */
6 
7 #ifndef __LINUX_KERNFS_H
8 #define __LINUX_KERNFS_H
9 
10 #include <linux/kernel.h>
11 #include <linux/err.h>
12 #include <linux/list.h>
13 #include <linux/mutex.h>
14 #include <linux/idr.h>
15 #include <linux/lockdep.h>
16 #include <linux/rbtree.h>
17 #include <linux/atomic.h>
18 #include <linux/wait.h>
19 
20 struct file;
21 struct dentry;
22 struct iattr;
23 struct seq_file;
24 struct vm_area_struct;
25 struct super_block;
26 struct file_system_type;
27 
28 struct kernfs_open_node;
29 struct kernfs_iattrs;
30 
31 enum kernfs_node_type {
32 	KERNFS_DIR		= 0x0001,
33 	KERNFS_FILE		= 0x0002,
34 	KERNFS_LINK		= 0x0004,
35 };
36 
37 #define KERNFS_TYPE_MASK	0x000f
38 #define KERNFS_FLAG_MASK	~KERNFS_TYPE_MASK
39 
40 enum kernfs_node_flag {
41 	KERNFS_ACTIVATED	= 0x0010,
42 	KERNFS_NS		= 0x0020,
43 	KERNFS_HAS_SEQ_SHOW	= 0x0040,
44 	KERNFS_HAS_MMAP		= 0x0080,
45 	KERNFS_LOCKDEP		= 0x0100,
46 	KERNFS_SUICIDAL		= 0x0400,
47 	KERNFS_SUICIDED		= 0x0800,
48 	KERNFS_EMPTY_DIR	= 0x1000,
49 };
50 
51 /* @flags for kernfs_create_root() */
52 enum kernfs_root_flag {
53 	/*
54 	 * kernfs_nodes are created in the deactivated state and invisible.
55 	 * They require explicit kernfs_activate() to become visible.  This
56 	 * can be used to make related nodes become visible atomically
57 	 * after all nodes are created successfully.
58 	 */
59 	KERNFS_ROOT_CREATE_DEACTIVATED		= 0x0001,
60 
61 	/*
62 	 * For regular flies, if the opener has CAP_DAC_OVERRIDE, open(2)
63 	 * succeeds regardless of the RW permissions.  sysfs had an extra
64 	 * layer of enforcement where open(2) fails with -EACCES regardless
65 	 * of CAP_DAC_OVERRIDE if the permission doesn't have the
66 	 * respective read or write access at all (none of S_IRUGO or
67 	 * S_IWUGO) or the respective operation isn't implemented.  The
68 	 * following flag enables that behavior.
69 	 */
70 	KERNFS_ROOT_EXTRA_OPEN_PERM_CHECK	= 0x0002,
71 };
72 
73 /* type-specific structures for kernfs_node union members */
74 struct kernfs_elem_dir {
75 	unsigned long		subdirs;
76 	/* children rbtree starts here and goes through kn->rb */
77 	struct rb_root		children;
78 
79 	/*
80 	 * The kernfs hierarchy this directory belongs to.  This fits
81 	 * better directly in kernfs_node but is here to save space.
82 	 */
83 	struct kernfs_root	*root;
84 };
85 
86 struct kernfs_elem_symlink {
87 	struct kernfs_node	*target_kn;
88 };
89 
90 struct kernfs_elem_attr {
91 	const struct kernfs_ops	*ops;
92 	struct kernfs_open_node	*open;
93 	loff_t			size;
94 	struct kernfs_node	*notify_next;	/* for kernfs_notify() */
95 };
96 
97 /*
98  * kernfs_node - the building block of kernfs hierarchy.  Each and every
99  * kernfs node is represented by single kernfs_node.  Most fields are
100  * private to kernfs and shouldn't be accessed directly by kernfs users.
101  *
102  * As long as s_count reference is held, the kernfs_node itself is
103  * accessible.  Dereferencing elem or any other outer entity requires
104  * active reference.
105  */
106 struct kernfs_node {
107 	atomic_t		count;
108 	atomic_t		active;
109 #ifdef CONFIG_DEBUG_LOCK_ALLOC
110 	struct lockdep_map	dep_map;
111 #endif
112 	/*
113 	 * Use kernfs_get_parent() and kernfs_name/path() instead of
114 	 * accessing the following two fields directly.  If the node is
115 	 * never moved to a different parent, it is safe to access the
116 	 * parent directly.
117 	 */
118 	struct kernfs_node	*parent;
119 	const char		*name;
120 
121 	struct rb_node		rb;
122 
123 	const void		*ns;	/* namespace tag */
124 	unsigned int		hash;	/* ns + name hash */
125 	union {
126 		struct kernfs_elem_dir		dir;
127 		struct kernfs_elem_symlink	symlink;
128 		struct kernfs_elem_attr		attr;
129 	};
130 
131 	void			*priv;
132 
133 	unsigned short		flags;
134 	umode_t			mode;
135 	unsigned int		ino;
136 	struct kernfs_iattrs	*iattr;
137 };
138 
139 /*
140  * kernfs_syscall_ops may be specified on kernfs_create_root() to support
141  * syscalls.  These optional callbacks are invoked on the matching syscalls
142  * and can perform any kernfs operations which don't necessarily have to be
143  * the exact operation requested.  An active reference is held for each
144  * kernfs_node parameter.
145  */
146 struct kernfs_syscall_ops {
147 	int (*remount_fs)(struct kernfs_root *root, int *flags, char *data);
148 	int (*show_options)(struct seq_file *sf, struct kernfs_root *root);
149 
150 	int (*mkdir)(struct kernfs_node *parent, const char *name,
151 		     umode_t mode);
152 	int (*rmdir)(struct kernfs_node *kn);
153 	int (*rename)(struct kernfs_node *kn, struct kernfs_node *new_parent,
154 		      const char *new_name);
155 	int (*show_path)(struct seq_file *sf, struct kernfs_node *kn,
156 			 struct kernfs_root *root);
157 };
158 
159 struct kernfs_root {
160 	/* published fields */
161 	struct kernfs_node	*kn;
162 	unsigned int		flags;	/* KERNFS_ROOT_* flags */
163 
164 	/* private fields, do not use outside kernfs proper */
165 	struct ida		ino_ida;
166 	struct kernfs_syscall_ops *syscall_ops;
167 
168 	/* list of kernfs_super_info of this root, protected by kernfs_mutex */
169 	struct list_head	supers;
170 
171 	wait_queue_head_t	deactivate_waitq;
172 };
173 
174 struct kernfs_open_file {
175 	/* published fields */
176 	struct kernfs_node	*kn;
177 	struct file		*file;
178 	void			*priv;
179 
180 	/* private fields, do not use outside kernfs proper */
181 	struct mutex		mutex;
182 	struct mutex		prealloc_mutex;
183 	int			event;
184 	struct list_head	list;
185 	char			*prealloc_buf;
186 
187 	size_t			atomic_write_len;
188 	bool			mmapped;
189 	const struct vm_operations_struct *vm_ops;
190 };
191 
192 struct kernfs_ops {
193 	/*
194 	 * Read is handled by either seq_file or raw_read().
195 	 *
196 	 * If seq_show() is present, seq_file path is active.  Other seq
197 	 * operations are optional and if not implemented, the behavior is
198 	 * equivalent to single_open().  @sf->private points to the
199 	 * associated kernfs_open_file.
200 	 *
201 	 * read() is bounced through kernel buffer and a read larger than
202 	 * PAGE_SIZE results in partial operation of PAGE_SIZE.
203 	 */
204 	int (*seq_show)(struct seq_file *sf, void *v);
205 
206 	void *(*seq_start)(struct seq_file *sf, loff_t *ppos);
207 	void *(*seq_next)(struct seq_file *sf, void *v, loff_t *ppos);
208 	void (*seq_stop)(struct seq_file *sf, void *v);
209 
210 	ssize_t (*read)(struct kernfs_open_file *of, char *buf, size_t bytes,
211 			loff_t off);
212 
213 	/*
214 	 * write() is bounced through kernel buffer.  If atomic_write_len
215 	 * is not set, a write larger than PAGE_SIZE results in partial
216 	 * operations of PAGE_SIZE chunks.  If atomic_write_len is set,
217 	 * writes upto the specified size are executed atomically but
218 	 * larger ones are rejected with -E2BIG.
219 	 */
220 	size_t atomic_write_len;
221 	/*
222 	 * "prealloc" causes a buffer to be allocated at open for
223 	 * all read/write requests.  As ->seq_show uses seq_read()
224 	 * which does its own allocation, it is incompatible with
225 	 * ->prealloc.  Provide ->read and ->write with ->prealloc.
226 	 */
227 	bool prealloc;
228 	ssize_t (*write)(struct kernfs_open_file *of, char *buf, size_t bytes,
229 			 loff_t off);
230 
231 	int (*mmap)(struct kernfs_open_file *of, struct vm_area_struct *vma);
232 
233 #ifdef CONFIG_DEBUG_LOCK_ALLOC
234 	struct lock_class_key	lockdep_key;
235 #endif
236 };
237 
238 #ifdef CONFIG_KERNFS
239 
240 static inline enum kernfs_node_type kernfs_type(struct kernfs_node *kn)
241 {
242 	return kn->flags & KERNFS_TYPE_MASK;
243 }
244 
245 /**
246  * kernfs_enable_ns - enable namespace under a directory
247  * @kn: directory of interest, should be empty
248  *
249  * This is to be called right after @kn is created to enable namespace
250  * under it.  All children of @kn must have non-NULL namespace tags and
251  * only the ones which match the super_block's tag will be visible.
252  */
253 static inline void kernfs_enable_ns(struct kernfs_node *kn)
254 {
255 	WARN_ON_ONCE(kernfs_type(kn) != KERNFS_DIR);
256 	WARN_ON_ONCE(!RB_EMPTY_ROOT(&kn->dir.children));
257 	kn->flags |= KERNFS_NS;
258 }
259 
260 /**
261  * kernfs_ns_enabled - test whether namespace is enabled
262  * @kn: the node to test
263  *
264  * Test whether namespace filtering is enabled for the children of @ns.
265  */
266 static inline bool kernfs_ns_enabled(struct kernfs_node *kn)
267 {
268 	return kn->flags & KERNFS_NS;
269 }
270 
271 int kernfs_name(struct kernfs_node *kn, char *buf, size_t buflen);
272 size_t kernfs_path_len(struct kernfs_node *kn);
273 int kernfs_path_from_node(struct kernfs_node *root_kn, struct kernfs_node *kn,
274 			  char *buf, size_t buflen);
275 char *kernfs_path(struct kernfs_node *kn, char *buf, size_t buflen);
276 void pr_cont_kernfs_name(struct kernfs_node *kn);
277 void pr_cont_kernfs_path(struct kernfs_node *kn);
278 struct kernfs_node *kernfs_get_parent(struct kernfs_node *kn);
279 struct kernfs_node *kernfs_find_and_get_ns(struct kernfs_node *parent,
280 					   const char *name, const void *ns);
281 struct kernfs_node *kernfs_walk_and_get_ns(struct kernfs_node *parent,
282 					   const char *path, const void *ns);
283 void kernfs_get(struct kernfs_node *kn);
284 void kernfs_put(struct kernfs_node *kn);
285 
286 struct kernfs_node *kernfs_node_from_dentry(struct dentry *dentry);
287 struct kernfs_root *kernfs_root_from_sb(struct super_block *sb);
288 struct inode *kernfs_get_inode(struct super_block *sb, struct kernfs_node *kn);
289 
290 struct dentry *kernfs_node_dentry(struct kernfs_node *kn,
291 				  struct super_block *sb);
292 struct kernfs_root *kernfs_create_root(struct kernfs_syscall_ops *scops,
293 				       unsigned int flags, void *priv);
294 void kernfs_destroy_root(struct kernfs_root *root);
295 
296 struct kernfs_node *kernfs_create_dir_ns(struct kernfs_node *parent,
297 					 const char *name, umode_t mode,
298 					 void *priv, const void *ns);
299 struct kernfs_node *kernfs_create_empty_dir(struct kernfs_node *parent,
300 					    const char *name);
301 struct kernfs_node *__kernfs_create_file(struct kernfs_node *parent,
302 					 const char *name,
303 					 umode_t mode, loff_t size,
304 					 const struct kernfs_ops *ops,
305 					 void *priv, const void *ns,
306 					 struct lock_class_key *key);
307 struct kernfs_node *kernfs_create_link(struct kernfs_node *parent,
308 				       const char *name,
309 				       struct kernfs_node *target);
310 void kernfs_activate(struct kernfs_node *kn);
311 void kernfs_remove(struct kernfs_node *kn);
312 void kernfs_break_active_protection(struct kernfs_node *kn);
313 void kernfs_unbreak_active_protection(struct kernfs_node *kn);
314 bool kernfs_remove_self(struct kernfs_node *kn);
315 int kernfs_remove_by_name_ns(struct kernfs_node *parent, const char *name,
316 			     const void *ns);
317 int kernfs_rename_ns(struct kernfs_node *kn, struct kernfs_node *new_parent,
318 		     const char *new_name, const void *new_ns);
319 int kernfs_setattr(struct kernfs_node *kn, const struct iattr *iattr);
320 void kernfs_notify(struct kernfs_node *kn);
321 
322 const void *kernfs_super_ns(struct super_block *sb);
323 struct dentry *kernfs_mount_ns(struct file_system_type *fs_type, int flags,
324 			       struct kernfs_root *root, unsigned long magic,
325 			       bool *new_sb_created, const void *ns);
326 void kernfs_kill_sb(struct super_block *sb);
327 struct super_block *kernfs_pin_sb(struct kernfs_root *root, const void *ns);
328 
329 void kernfs_init(void);
330 
331 #else	/* CONFIG_KERNFS */
332 
333 static inline enum kernfs_node_type kernfs_type(struct kernfs_node *kn)
334 { return 0; }	/* whatever */
335 
336 static inline void kernfs_enable_ns(struct kernfs_node *kn) { }
337 
338 static inline bool kernfs_ns_enabled(struct kernfs_node *kn)
339 { return false; }
340 
341 static inline int kernfs_name(struct kernfs_node *kn, char *buf, size_t buflen)
342 { return -ENOSYS; }
343 
344 static inline size_t kernfs_path_len(struct kernfs_node *kn)
345 { return 0; }
346 
347 static inline char *kernfs_path(struct kernfs_node *kn, char *buf,
348 				size_t buflen)
349 { return NULL; }
350 
351 static inline void pr_cont_kernfs_name(struct kernfs_node *kn) { }
352 static inline void pr_cont_kernfs_path(struct kernfs_node *kn) { }
353 
354 static inline struct kernfs_node *kernfs_get_parent(struct kernfs_node *kn)
355 { return NULL; }
356 
357 static inline struct kernfs_node *
358 kernfs_find_and_get_ns(struct kernfs_node *parent, const char *name,
359 		       const void *ns)
360 { return NULL; }
361 static inline struct kernfs_node *
362 kernfs_walk_and_get_ns(struct kernfs_node *parent, const char *path,
363 		       const void *ns)
364 { return NULL; }
365 
366 static inline void kernfs_get(struct kernfs_node *kn) { }
367 static inline void kernfs_put(struct kernfs_node *kn) { }
368 
369 static inline struct kernfs_node *kernfs_node_from_dentry(struct dentry *dentry)
370 { return NULL; }
371 
372 static inline struct kernfs_root *kernfs_root_from_sb(struct super_block *sb)
373 { return NULL; }
374 
375 static inline struct inode *
376 kernfs_get_inode(struct super_block *sb, struct kernfs_node *kn)
377 { return NULL; }
378 
379 static inline struct kernfs_root *
380 kernfs_create_root(struct kernfs_syscall_ops *scops, unsigned int flags,
381 		   void *priv)
382 { return ERR_PTR(-ENOSYS); }
383 
384 static inline void kernfs_destroy_root(struct kernfs_root *root) { }
385 
386 static inline struct kernfs_node *
387 kernfs_create_dir_ns(struct kernfs_node *parent, const char *name,
388 		     umode_t mode, void *priv, const void *ns)
389 { return ERR_PTR(-ENOSYS); }
390 
391 static inline struct kernfs_node *
392 __kernfs_create_file(struct kernfs_node *parent, const char *name,
393 		     umode_t mode, loff_t size, const struct kernfs_ops *ops,
394 		     void *priv, const void *ns, struct lock_class_key *key)
395 { return ERR_PTR(-ENOSYS); }
396 
397 static inline struct kernfs_node *
398 kernfs_create_link(struct kernfs_node *parent, const char *name,
399 		   struct kernfs_node *target)
400 { return ERR_PTR(-ENOSYS); }
401 
402 static inline void kernfs_activate(struct kernfs_node *kn) { }
403 
404 static inline void kernfs_remove(struct kernfs_node *kn) { }
405 
406 static inline bool kernfs_remove_self(struct kernfs_node *kn)
407 { return false; }
408 
409 static inline int kernfs_remove_by_name_ns(struct kernfs_node *kn,
410 					   const char *name, const void *ns)
411 { return -ENOSYS; }
412 
413 static inline int kernfs_rename_ns(struct kernfs_node *kn,
414 				   struct kernfs_node *new_parent,
415 				   const char *new_name, const void *new_ns)
416 { return -ENOSYS; }
417 
418 static inline int kernfs_setattr(struct kernfs_node *kn,
419 				 const struct iattr *iattr)
420 { return -ENOSYS; }
421 
422 static inline void kernfs_notify(struct kernfs_node *kn) { }
423 
424 static inline const void *kernfs_super_ns(struct super_block *sb)
425 { return NULL; }
426 
427 static inline struct dentry *
428 kernfs_mount_ns(struct file_system_type *fs_type, int flags,
429 		struct kernfs_root *root, unsigned long magic,
430 		bool *new_sb_created, const void *ns)
431 { return ERR_PTR(-ENOSYS); }
432 
433 static inline void kernfs_kill_sb(struct super_block *sb) { }
434 
435 static inline void kernfs_init(void) { }
436 
437 #endif	/* CONFIG_KERNFS */
438 
439 static inline struct kernfs_node *
440 kernfs_find_and_get(struct kernfs_node *kn, const char *name)
441 {
442 	return kernfs_find_and_get_ns(kn, name, NULL);
443 }
444 
445 static inline struct kernfs_node *
446 kernfs_walk_and_get(struct kernfs_node *kn, const char *path)
447 {
448 	return kernfs_walk_and_get_ns(kn, path, NULL);
449 }
450 
451 static inline struct kernfs_node *
452 kernfs_create_dir(struct kernfs_node *parent, const char *name, umode_t mode,
453 		  void *priv)
454 {
455 	return kernfs_create_dir_ns(parent, name, mode, priv, NULL);
456 }
457 
458 static inline struct kernfs_node *
459 kernfs_create_file_ns(struct kernfs_node *parent, const char *name,
460 		      umode_t mode, loff_t size, const struct kernfs_ops *ops,
461 		      void *priv, const void *ns)
462 {
463 	struct lock_class_key *key = NULL;
464 
465 #ifdef CONFIG_DEBUG_LOCK_ALLOC
466 	key = (struct lock_class_key *)&ops->lockdep_key;
467 #endif
468 	return __kernfs_create_file(parent, name, mode, size, ops, priv, ns,
469 				    key);
470 }
471 
472 static inline struct kernfs_node *
473 kernfs_create_file(struct kernfs_node *parent, const char *name, umode_t mode,
474 		   loff_t size, const struct kernfs_ops *ops, void *priv)
475 {
476 	return kernfs_create_file_ns(parent, name, mode, size, ops, priv, NULL);
477 }
478 
479 static inline int kernfs_remove_by_name(struct kernfs_node *parent,
480 					const char *name)
481 {
482 	return kernfs_remove_by_name_ns(parent, name, NULL);
483 }
484 
485 static inline int kernfs_rename(struct kernfs_node *kn,
486 				struct kernfs_node *new_parent,
487 				const char *new_name)
488 {
489 	return kernfs_rename_ns(kn, new_parent, new_name, NULL);
490 }
491 
492 static inline struct dentry *
493 kernfs_mount(struct file_system_type *fs_type, int flags,
494 		struct kernfs_root *root, unsigned long magic,
495 		bool *new_sb_created)
496 {
497 	return kernfs_mount_ns(fs_type, flags, root,
498 				magic, new_sb_created, NULL);
499 }
500 
501 #endif	/* __LINUX_KERNFS_H */
502