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