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