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