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