include/linux/kernfs.h

   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 */