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