include/linux/kernfs.h

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