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 23struct file; 24struct dentry; 25struct iattr; 26struct seq_file; 27struct vm_area_struct; 28struct vm_operations_struct; 29struct super_block; 30struct file_system_type; 31struct poll_table_struct; 32struct fs_context; 33 34struct kernfs_fs_context; 35struct kernfs_open_node; 36struct 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 */ 90struct kernfs_global_locks { 91 struct mutex open_file_mutex[NR_KERNFS_LOCKS]; 92}; 93 94enum 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 105enum 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() */ 120enum 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 */ 153struct 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 170struct kernfs_elem_symlink { 171 struct kernfs_node *target_kn; 172}; 173 174struct 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 */ 190struct 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 unsigned short flags; 210 umode_t mode; 211 212 union { 213 struct kernfs_elem_dir dir; 214 struct kernfs_elem_symlink symlink; 215 struct kernfs_elem_attr attr; 216 }; 217 218 /* 219 * 64bit unique ID. On 64bit ino setups, id is the ino. On 32bit, 220 * the low 32bits are ino and upper generation. 221 */ 222 u64 id; 223 224 void *priv; 225 struct kernfs_iattrs *iattr; 226 227 struct rcu_head rcu; 228}; 229 230/* 231 * kernfs_syscall_ops may be specified on kernfs_create_root() to support 232 * syscalls. These optional callbacks are invoked on the matching syscalls 233 * and can perform any kernfs operations which don't necessarily have to be 234 * the exact operation requested. An active reference is held for each 235 * kernfs_node parameter. 236 */ 237struct kernfs_syscall_ops { 238 int (*show_options)(struct seq_file *sf, struct kernfs_root *root); 239 240 int (*mkdir)(struct kernfs_node *parent, const char *name, 241 umode_t mode); 242 int (*rmdir)(struct kernfs_node *kn); 243 int (*rename)(struct kernfs_node *kn, struct kernfs_node *new_parent, 244 const char *new_name); 245 int (*show_path)(struct seq_file *sf, struct kernfs_node *kn, 246 struct kernfs_root *root); 247}; 248 249struct kernfs_node *kernfs_root_to_node(struct kernfs_root *root); 250 251struct kernfs_open_file { 252 /* published fields */ 253 struct kernfs_node *kn; 254 struct file *file; 255 struct seq_file *seq_file; 256 void *priv; 257 258 /* private fields, do not use outside kernfs proper */ 259 struct mutex mutex; 260 struct mutex prealloc_mutex; 261 int event; 262 struct list_head list; 263 char *prealloc_buf; 264 265 size_t atomic_write_len; 266 bool mmapped:1; 267 bool released:1; 268 const struct vm_operations_struct *vm_ops; 269}; 270 271struct kernfs_ops { 272 /* 273 * Optional open/release methods. Both are called with 274 * @of->seq_file populated. 275 */ 276 int (*open)(struct kernfs_open_file *of); 277 void (*release)(struct kernfs_open_file *of); 278 279 /* 280 * Read is handled by either seq_file or raw_read(). 281 * 282 * If seq_show() is present, seq_file path is active. Other seq 283 * operations are optional and if not implemented, the behavior is 284 * equivalent to single_open(). @sf->private points to the 285 * associated kernfs_open_file. 286 * 287 * read() is bounced through kernel buffer and a read larger than 288 * PAGE_SIZE results in partial operation of PAGE_SIZE. 289 */ 290 int (*seq_show)(struct seq_file *sf, void *v); 291 292 void *(*seq_start)(struct seq_file *sf, loff_t *ppos); 293 void *(*seq_next)(struct seq_file *sf, void *v, loff_t *ppos); 294 void (*seq_stop)(struct seq_file *sf, void *v); 295 296 ssize_t (*read)(struct kernfs_open_file *of, char *buf, size_t bytes, 297 loff_t off); 298 299 /* 300 * write() is bounced through kernel buffer. If atomic_write_len 301 * is not set, a write larger than PAGE_SIZE results in partial 302 * operations of PAGE_SIZE chunks. If atomic_write_len is set, 303 * writes upto the specified size are executed atomically but 304 * larger ones are rejected with -E2BIG. 305 */ 306 size_t atomic_write_len; 307 /* 308 * "prealloc" causes a buffer to be allocated at open for 309 * all read/write requests. As ->seq_show uses seq_read() 310 * which does its own allocation, it is incompatible with 311 * ->prealloc. Provide ->read and ->write with ->prealloc. 312 */ 313 bool prealloc; 314 ssize_t (*write)(struct kernfs_open_file *of, char *buf, size_t bytes, 315 loff_t off); 316 317 __poll_t (*poll)(struct kernfs_open_file *of, 318 struct poll_table_struct *pt); 319 320 int (*mmap)(struct kernfs_open_file *of, struct vm_area_struct *vma); 321 loff_t (*llseek)(struct kernfs_open_file *of, loff_t offset, int whence); 322}; 323 324/* 325 * The kernfs superblock creation/mount parameter context. 326 */ 327struct kernfs_fs_context { 328 struct kernfs_root *root; /* Root of the hierarchy being mounted */ 329 void *ns_tag; /* Namespace tag of the mount (or NULL) */ 330 unsigned long magic; /* File system specific magic number */ 331 332 /* The following are set/used by kernfs_mount() */ 333 bool new_sb_created; /* Set to T if we allocated a new sb */ 334}; 335 336#ifdef CONFIG_KERNFS 337 338static inline enum kernfs_node_type kernfs_type(struct kernfs_node *kn) 339{ 340 return kn->flags & KERNFS_TYPE_MASK; 341} 342 343static inline ino_t kernfs_id_ino(u64 id) 344{ 345 /* id is ino if ino_t is 64bit; otherwise, low 32bits */ 346 if (sizeof(ino_t) >= sizeof(u64)) 347 return id; 348 else 349 return (u32)id; 350} 351 352static inline u32 kernfs_id_gen(u64 id) 353{ 354 /* gen is fixed at 1 if ino_t is 64bit; otherwise, high 32bits */ 355 if (sizeof(ino_t) >= sizeof(u64)) 356 return 1; 357 else 358 return id >> 32; 359} 360 361static inline ino_t kernfs_ino(struct kernfs_node *kn) 362{ 363 return kernfs_id_ino(kn->id); 364} 365 366static inline ino_t kernfs_gen(struct kernfs_node *kn) 367{ 368 return kernfs_id_gen(kn->id); 369} 370 371/** 372 * kernfs_enable_ns - enable namespace under a directory 373 * @kn: directory of interest, should be empty 374 * 375 * This is to be called right after @kn is created to enable namespace 376 * under it. All children of @kn must have non-NULL namespace tags and 377 * only the ones which match the super_block's tag will be visible. 378 */ 379static inline void kernfs_enable_ns(struct kernfs_node *kn) 380{ 381 WARN_ON_ONCE(kernfs_type(kn) != KERNFS_DIR); 382 WARN_ON_ONCE(!RB_EMPTY_ROOT(&kn->dir.children)); 383 kn->flags |= KERNFS_NS; 384} 385 386/** 387 * kernfs_ns_enabled - test whether namespace is enabled 388 * @kn: the node to test 389 * 390 * Test whether namespace filtering is enabled for the children of @ns. 391 */ 392static inline bool kernfs_ns_enabled(struct kernfs_node *kn) 393{ 394 return kn->flags & KERNFS_NS; 395} 396 397int kernfs_name(struct kernfs_node *kn, char *buf, size_t buflen); 398int kernfs_path_from_node(struct kernfs_node *root_kn, struct kernfs_node *kn, 399 char *buf, size_t buflen); 400void pr_cont_kernfs_name(struct kernfs_node *kn); 401void pr_cont_kernfs_path(struct kernfs_node *kn); 402struct kernfs_node *kernfs_get_parent(struct kernfs_node *kn); 403struct kernfs_node *kernfs_find_and_get_ns(struct kernfs_node *parent, 404 const char *name, const void *ns); 405struct kernfs_node *kernfs_walk_and_get_ns(struct kernfs_node *parent, 406 const char *path, const void *ns); 407void kernfs_get(struct kernfs_node *kn); 408void kernfs_put(struct kernfs_node *kn); 409 410struct kernfs_node *kernfs_node_from_dentry(struct dentry *dentry); 411struct kernfs_root *kernfs_root_from_sb(struct super_block *sb); 412struct inode *kernfs_get_inode(struct super_block *sb, struct kernfs_node *kn); 413 414struct dentry *kernfs_node_dentry(struct kernfs_node *kn, 415 struct super_block *sb); 416struct kernfs_root *kernfs_create_root(struct kernfs_syscall_ops *scops, 417 unsigned int flags, void *priv); 418void kernfs_destroy_root(struct kernfs_root *root); 419 420struct kernfs_node *kernfs_create_dir_ns(struct kernfs_node *parent, 421 const char *name, umode_t mode, 422 kuid_t uid, kgid_t gid, 423 void *priv, const void *ns); 424struct kernfs_node *kernfs_create_empty_dir(struct kernfs_node *parent, 425 const char *name); 426struct kernfs_node *__kernfs_create_file(struct kernfs_node *parent, 427 const char *name, umode_t mode, 428 kuid_t uid, kgid_t gid, 429 loff_t size, 430 const struct kernfs_ops *ops, 431 void *priv, const void *ns, 432 struct lock_class_key *key); 433struct kernfs_node *kernfs_create_link(struct kernfs_node *parent, 434 const char *name, 435 struct kernfs_node *target); 436void kernfs_activate(struct kernfs_node *kn); 437void kernfs_show(struct kernfs_node *kn, bool show); 438void kernfs_remove(struct kernfs_node *kn); 439void kernfs_break_active_protection(struct kernfs_node *kn); 440void kernfs_unbreak_active_protection(struct kernfs_node *kn); 441bool kernfs_remove_self(struct kernfs_node *kn); 442int kernfs_remove_by_name_ns(struct kernfs_node *parent, const char *name, 443 const void *ns); 444int kernfs_rename_ns(struct kernfs_node *kn, struct kernfs_node *new_parent, 445 const char *new_name, const void *new_ns); 446int kernfs_setattr(struct kernfs_node *kn, const struct iattr *iattr); 447__poll_t kernfs_generic_poll(struct kernfs_open_file *of, 448 struct poll_table_struct *pt); 449void kernfs_notify(struct kernfs_node *kn); 450 451int kernfs_xattr_get(struct kernfs_node *kn, const char *name, 452 void *value, size_t size); 453int kernfs_xattr_set(struct kernfs_node *kn, const char *name, 454 const void *value, size_t size, int flags); 455 456const void *kernfs_super_ns(struct super_block *sb); 457int kernfs_get_tree(struct fs_context *fc); 458void kernfs_free_fs_context(struct fs_context *fc); 459void kernfs_kill_sb(struct super_block *sb); 460 461void kernfs_init(void); 462 463struct kernfs_node *kernfs_find_and_get_node_by_id(struct kernfs_root *root, 464 u64 id); 465#else /* CONFIG_KERNFS */ 466 467static inline enum kernfs_node_type kernfs_type(struct kernfs_node *kn) 468{ return 0; } /* whatever */ 469 470static inline void kernfs_enable_ns(struct kernfs_node *kn) { } 471 472static inline bool kernfs_ns_enabled(struct kernfs_node *kn) 473{ return false; } 474 475static inline int kernfs_name(struct kernfs_node *kn, char *buf, size_t buflen) 476{ return -ENOSYS; } 477 478static inline int kernfs_path_from_node(struct kernfs_node *root_kn, 479 struct kernfs_node *kn, 480 char *buf, size_t buflen) 481{ return -ENOSYS; } 482 483static inline void pr_cont_kernfs_name(struct kernfs_node *kn) { } 484static inline void pr_cont_kernfs_path(struct kernfs_node *kn) { } 485 486static inline struct kernfs_node *kernfs_get_parent(struct kernfs_node *kn) 487{ return NULL; } 488 489static inline struct kernfs_node * 490kernfs_find_and_get_ns(struct kernfs_node *parent, const char *name, 491 const void *ns) 492{ return NULL; } 493static inline struct kernfs_node * 494kernfs_walk_and_get_ns(struct kernfs_node *parent, const char *path, 495 const void *ns) 496{ return NULL; } 497 498static inline void kernfs_get(struct kernfs_node *kn) { } 499static inline void kernfs_put(struct kernfs_node *kn) { } 500 501static inline struct kernfs_node *kernfs_node_from_dentry(struct dentry *dentry) 502{ return NULL; } 503 504static inline struct kernfs_root *kernfs_root_from_sb(struct super_block *sb) 505{ return NULL; } 506 507static inline struct inode * 508kernfs_get_inode(struct super_block *sb, struct kernfs_node *kn) 509{ return NULL; } 510 511static inline struct kernfs_root * 512kernfs_create_root(struct kernfs_syscall_ops *scops, unsigned int flags, 513 void *priv) 514{ return ERR_PTR(-ENOSYS); } 515 516static inline void kernfs_destroy_root(struct kernfs_root *root) { } 517 518static inline struct kernfs_node * 519kernfs_create_dir_ns(struct kernfs_node *parent, const char *name, 520 umode_t mode, kuid_t uid, kgid_t gid, 521 void *priv, const void *ns) 522{ return ERR_PTR(-ENOSYS); } 523 524static inline struct kernfs_node * 525__kernfs_create_file(struct kernfs_node *parent, const char *name, 526 umode_t mode, kuid_t uid, kgid_t gid, 527 loff_t size, const struct kernfs_ops *ops, 528 void *priv, const void *ns, struct lock_class_key *key) 529{ return ERR_PTR(-ENOSYS); } 530 531static inline struct kernfs_node * 532kernfs_create_link(struct kernfs_node *parent, const char *name, 533 struct kernfs_node *target) 534{ return ERR_PTR(-ENOSYS); } 535 536static inline void kernfs_activate(struct kernfs_node *kn) { } 537 538static inline void kernfs_remove(struct kernfs_node *kn) { } 539 540static inline bool kernfs_remove_self(struct kernfs_node *kn) 541{ return false; } 542 543static inline int kernfs_remove_by_name_ns(struct kernfs_node *kn, 544 const char *name, const void *ns) 545{ return -ENOSYS; } 546 547static inline int kernfs_rename_ns(struct kernfs_node *kn, 548 struct kernfs_node *new_parent, 549 const char *new_name, const void *new_ns) 550{ return -ENOSYS; } 551 552static inline int kernfs_setattr(struct kernfs_node *kn, 553 const struct iattr *iattr) 554{ return -ENOSYS; } 555 556static inline __poll_t kernfs_generic_poll(struct kernfs_open_file *of, 557 struct poll_table_struct *pt) 558{ return -ENOSYS; } 559 560static inline void kernfs_notify(struct kernfs_node *kn) { } 561 562static inline int kernfs_xattr_get(struct kernfs_node *kn, const char *name, 563 void *value, size_t size) 564{ return -ENOSYS; } 565 566static inline int kernfs_xattr_set(struct kernfs_node *kn, const char *name, 567 const void *value, size_t size, int flags) 568{ return -ENOSYS; } 569 570static inline const void *kernfs_super_ns(struct super_block *sb) 571{ return NULL; } 572 573static inline int kernfs_get_tree(struct fs_context *fc) 574{ return -ENOSYS; } 575 576static inline void kernfs_free_fs_context(struct fs_context *fc) { } 577 578static inline void kernfs_kill_sb(struct super_block *sb) { } 579 580static inline void kernfs_init(void) { } 581 582#endif /* CONFIG_KERNFS */ 583 584/** 585 * kernfs_path - build full path of a given node 586 * @kn: kernfs_node of interest 587 * @buf: buffer to copy @kn's name into 588 * @buflen: size of @buf 589 * 590 * If @kn is NULL result will be "(null)". 591 * 592 * Returns the length of the full path. If the full length is equal to or 593 * greater than @buflen, @buf contains the truncated path with the trailing 594 * '\0'. On error, -errno is returned. 595 */ 596static inline int kernfs_path(struct kernfs_node *kn, char *buf, size_t buflen) 597{ 598 return kernfs_path_from_node(kn, NULL, buf, buflen); 599} 600 601static inline struct kernfs_node * 602kernfs_find_and_get(struct kernfs_node *kn, const char *name) 603{ 604 return kernfs_find_and_get_ns(kn, name, NULL); 605} 606 607static inline struct kernfs_node * 608kernfs_walk_and_get(struct kernfs_node *kn, const char *path) 609{ 610 return kernfs_walk_and_get_ns(kn, path, NULL); 611} 612 613static inline struct kernfs_node * 614kernfs_create_dir(struct kernfs_node *parent, const char *name, umode_t mode, 615 void *priv) 616{ 617 return kernfs_create_dir_ns(parent, name, mode, 618 GLOBAL_ROOT_UID, GLOBAL_ROOT_GID, 619 priv, NULL); 620} 621 622static inline int kernfs_remove_by_name(struct kernfs_node *parent, 623 const char *name) 624{ 625 return kernfs_remove_by_name_ns(parent, name, NULL); 626} 627 628static inline int kernfs_rename(struct kernfs_node *kn, 629 struct kernfs_node *new_parent, 630 const char *new_name) 631{ 632 return kernfs_rename_ns(kn, new_parent, new_name, NULL); 633} 634 635#endif /* __LINUX_KERNFS_H */ 636