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