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