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 /* type-specific structures for kernfs_node union members */
  75 struct kernfs_elem_dir {
  76         unsigned long           subdirs;
  77         /* children rbtree starts here and goes through kn->rb */
  78         struct rb_root          children;
  79
  80         /*
  81          * The kernfs hierarchy this directory belongs to.  This fits
  82          * better directly in kernfs_node but is here to save space.
  83          */
  84         struct kernfs_root      *root;
  85 };
  86
  87 struct kernfs_elem_symlink {
  88         struct kernfs_node      *target_kn;
  89 };
  90
  91 struct kernfs_elem_attr {
  92         const struct kernfs_ops *ops;
  93         struct kernfs_open_node *open;
  94         loff_t                  size;
  95         struct kernfs_node      *notify_next;   /* for kernfs_notify() */
  96 };
  97
  98 /*
  99  * kernfs_node - the building block of kernfs hierarchy.  Each and every
 100  * kernfs node is represented by single kernfs_node.  Most fields are
 101  * private to kernfs and shouldn't be accessed directly by kernfs users.
 102  *
 103  * As long as s_count reference is held, the kernfs_node itself is
 104  * accessible.  Dereferencing elem or any other outer entity requires
 105  * active reference.
 106  */
 107 struct kernfs_node {
 108         atomic_t                count;
 109         atomic_t                active;
 110 #ifdef CONFIG_DEBUG_LOCK_ALLOC
 111         struct lockdep_map      dep_map;
 112 #endif
 113         /*
 114          * Use kernfs_get_parent() and kernfs_name/path() instead of
 115          * accessing the following two fields directly.  If the node is
 116          * never moved to a different parent, it is safe to access the
 117          * parent directly.
 118          */
 119         struct kernfs_node      *parent;
 120         const char              *name;
 121
 122         struct rb_node          rb;
 123
 124         const void              *ns;    /* namespace tag */
 125         unsigned int            hash;   /* ns + name hash */
 126         union {
 127                 struct kernfs_elem_dir          dir;
 128                 struct kernfs_elem_symlink      symlink;
 129                 struct kernfs_elem_attr         attr;
 130         };
 131
 132         void                    *priv;
 133
 134         unsigned short          flags;
 135         umode_t                 mode;
 136         unsigned int            ino;
 137         struct kernfs_iattrs    *iattr;
 138 };
 139
 140 /*
 141  * kernfs_syscall_ops may be specified on kernfs_create_root() to support
 142  * syscalls.  These optional callbacks are invoked on the matching syscalls
 143  * and can perform any kernfs operations which don't necessarily have to be
 144  * the exact operation requested.  An active reference is held for each
 145  * kernfs_node parameter.
 146  */
 147 struct kernfs_syscall_ops {
 148         int (*remount_fs)(struct kernfs_root *root, int *flags, char *data);
 149         int (*show_options)(struct seq_file *sf, struct kernfs_root *root);
 150
 151         int (*mkdir)(struct kernfs_node *parent, const char *name,
 152                      umode_t mode);
 153         int (*rmdir)(struct kernfs_node *kn);
 154         int (*rename)(struct kernfs_node *kn, struct kernfs_node *new_parent,
 155                       const char *new_name);
 156         int (*show_path)(struct seq_file *sf, struct kernfs_node *kn,
 157                          struct kernfs_root *root);
 158 };
 159
 160 struct kernfs_root {
 161         /* published fields */
 162         struct kernfs_node      *kn;
 163         unsigned int            flags;  /* KERNFS_ROOT_* flags */
 164
 165         /* private fields, do not use outside kernfs proper */
 166         struct ida              ino_ida;
 167         struct kernfs_syscall_ops *syscall_ops;
 168
 169         /* list of kernfs_super_info of this root, protected by kernfs_mutex */
 170         struct list_head        supers;
 171
 172         wait_queue_head_t       deactivate_waitq;
 173 };
 174
 175 struct kernfs_open_file {
 176         /* published fields */
 177         struct kernfs_node      *kn;
 178         struct file             *file;
 179         struct seq_file         *seq_file;
 180         void                    *priv;
 181
 182         /* private fields, do not use outside kernfs proper */
 183         struct mutex            mutex;
 184         struct mutex            prealloc_mutex;
 185         int                     event;
 186         struct list_head        list;
 187         char                    *prealloc_buf;
 188
 189         size_t                  atomic_write_len;
 190         bool                    mmapped:1;
 191         bool                    released:1;
 192         const struct vm_operations_struct *vm_ops;
 193 };
 194
 195 struct kernfs_ops {
 196         /*
 197          * Optional open/release methods.  Both are called with
 198          * @of->seq_file populated.
 199          */
 200         int (*open)(struct kernfs_open_file *of);
 201         void (*release)(struct kernfs_open_file *of);
 202
 203         /*
 204          * Read is handled by either seq_file or raw_read().
 205          *
 206          * If seq_show() is present, seq_file path is active.  Other seq
 207          * operations are optional and if not implemented, the behavior is
 208          * equivalent to single_open().  @sf->private points to the
 209          * associated kernfs_open_file.
 210          *
 211          * read() is bounced through kernel buffer and a read larger than
 212          * PAGE_SIZE results in partial operation of PAGE_SIZE.
 213          */
 214         int (*seq_show)(struct seq_file *sf, void *v);
 215
 216         void *(*seq_start)(struct seq_file *sf, loff_t *ppos);
 217         void *(*seq_next)(struct seq_file *sf, void *v, loff_t *ppos);
 218         void (*seq_stop)(struct seq_file *sf, void *v);
 219
 220         ssize_t (*read)(struct kernfs_open_file *of, char *buf, size_t bytes,
 221                         loff_t off);
 222
 223         /*
 224          * write() is bounced through kernel buffer.  If atomic_write_len
 225          * is not set, a write larger than PAGE_SIZE results in partial
 226          * operations of PAGE_SIZE chunks.  If atomic_write_len is set,
 227          * writes upto the specified size are executed atomically but
 228          * larger ones are rejected with -E2BIG.
 229          */
 230         size_t atomic_write_len;
 231         /*
 232          * "prealloc" causes a buffer to be allocated at open for
 233          * all read/write requests.  As ->seq_show uses seq_read()
 234          * which does its own allocation, it is incompatible with
 235          * ->prealloc.  Provide ->read and ->write with ->prealloc.
 236          */
 237         bool prealloc;
 238         ssize_t (*write)(struct kernfs_open_file *of, char *buf, size_t bytes,
 239                          loff_t off);
 240
 241         int (*mmap)(struct kernfs_open_file *of, struct vm_area_struct *vma);
 242
 243 #ifdef CONFIG_DEBUG_LOCK_ALLOC
 244         struct lock_class_key   lockdep_key;
 245 #endif
 246 };
 247
 248 #ifdef CONFIG_KERNFS
 249
 250 static inline enum kernfs_node_type kernfs_type(struct kernfs_node *kn)
 251 {
 252         return kn->flags & KERNFS_TYPE_MASK;
 253 }
 254
 255 /**
 256  * kernfs_enable_ns - enable namespace under a directory
 257  * @kn: directory of interest, should be empty
 258  *
 259  * This is to be called right after @kn is created to enable namespace
 260  * under it.  All children of @kn must have non-NULL namespace tags and
 261  * only the ones which match the super_block's tag will be visible.
 262  */
 263 static inline void kernfs_enable_ns(struct kernfs_node *kn)
 264 {
 265         WARN_ON_ONCE(kernfs_type(kn) != KERNFS_DIR);
 266         WARN_ON_ONCE(!RB_EMPTY_ROOT(&kn->dir.children));
 267         kn->flags |= KERNFS_NS;
 268 }
 269
 270 /**
 271  * kernfs_ns_enabled - test whether namespace is enabled
 272  * @kn: the node to test
 273  *
 274  * Test whether namespace filtering is enabled for the children of @ns.
 275  */
 276 static inline bool kernfs_ns_enabled(struct kernfs_node *kn)
 277 {
 278         return kn->flags & KERNFS_NS;
 279 }
 280
 281 int kernfs_name(struct kernfs_node *kn, char *buf, size_t buflen);
 282 int kernfs_path_from_node(struct kernfs_node *root_kn, struct kernfs_node *kn,
 283                           char *buf, size_t buflen);
 284 void pr_cont_kernfs_name(struct kernfs_node *kn);
 285 void pr_cont_kernfs_path(struct kernfs_node *kn);
 286 struct kernfs_node *kernfs_get_parent(struct kernfs_node *kn);
 287 struct kernfs_node *kernfs_find_and_get_ns(struct kernfs_node *parent,
 288                                            const char *name, const void *ns);
 289 struct kernfs_node *kernfs_walk_and_get_ns(struct kernfs_node *parent,
 290                                            const char *path, const void *ns);
 291 void kernfs_get(struct kernfs_node *kn);
 292 void kernfs_put(struct kernfs_node *kn);
 293
 294 struct kernfs_node *kernfs_node_from_dentry(struct dentry *dentry);
 295 struct kernfs_root *kernfs_root_from_sb(struct super_block *sb);
 296 struct inode *kernfs_get_inode(struct super_block *sb, struct kernfs_node *kn);
 297
 298 struct dentry *kernfs_node_dentry(struct kernfs_node *kn,
 299                                   struct super_block *sb);
 300 struct kernfs_root *kernfs_create_root(struct kernfs_syscall_ops *scops,
 301                                        unsigned int flags, void *priv);
 302 void kernfs_destroy_root(struct kernfs_root *root);
 303
 304 struct kernfs_node *kernfs_create_dir_ns(struct kernfs_node *parent,
 305                                          const char *name, umode_t mode,
 306                                          void *priv, const void *ns);
 307 struct kernfs_node *kernfs_create_empty_dir(struct kernfs_node *parent,
 308                                             const char *name);
 309 struct kernfs_node *__kernfs_create_file(struct kernfs_node *parent,
 310                                          const char *name,
 311                                          umode_t mode, loff_t size,
 312                                          const struct kernfs_ops *ops,
 313                                          void *priv, const void *ns,
 314                                          struct lock_class_key *key);
 315 struct kernfs_node *kernfs_create_link(struct kernfs_node *parent,
 316                                        const char *name,
 317                                        struct kernfs_node *target);
 318 void kernfs_activate(struct kernfs_node *kn);
 319 void kernfs_remove(struct kernfs_node *kn);
 320 void kernfs_break_active_protection(struct kernfs_node *kn);
 321 void kernfs_unbreak_active_protection(struct kernfs_node *kn);
 322 bool kernfs_remove_self(struct kernfs_node *kn);
 323 int kernfs_remove_by_name_ns(struct kernfs_node *parent, const char *name,
 324                              const void *ns);
 325 int kernfs_rename_ns(struct kernfs_node *kn, struct kernfs_node *new_parent,
 326                      const char *new_name, const void *new_ns);
 327 int kernfs_setattr(struct kernfs_node *kn, const struct iattr *iattr);
 328 void kernfs_notify(struct kernfs_node *kn);
 329
 330 const void *kernfs_super_ns(struct super_block *sb);
 331 struct dentry *kernfs_mount_ns(struct file_system_type *fs_type, int flags,
 332                                struct kernfs_root *root, unsigned long magic,
 333                                bool *new_sb_created, const void *ns);
 334 void kernfs_kill_sb(struct super_block *sb);
 335 struct super_block *kernfs_pin_sb(struct kernfs_root *root, const void *ns);
 336
 337 void kernfs_init(void);
 338
 339 #else   /* CONFIG_KERNFS */
 340
 341 static inline enum kernfs_node_type kernfs_type(struct kernfs_node *kn)
 342 { return 0; }   /* whatever */
 343
 344 static inline void kernfs_enable_ns(struct kernfs_node *kn) { }
 345
 346 static inline bool kernfs_ns_enabled(struct kernfs_node *kn)
 347 { return false; }
 348
 349 static inline int kernfs_name(struct kernfs_node *kn, char *buf, size_t buflen)
 350 { return -ENOSYS; }
 351
 352 static inline int kernfs_path_from_node(struct kernfs_node *root_kn,
 353                                         struct kernfs_node *kn,
 354                                         char *buf, size_t buflen)
 355 { return -ENOSYS; }
 356
 357 static inline void pr_cont_kernfs_name(struct kernfs_node *kn) { }
 358 static inline void pr_cont_kernfs_path(struct kernfs_node *kn) { }
 359
 360 static inline struct kernfs_node *kernfs_get_parent(struct kernfs_node *kn)
 361 { return NULL; }
 362
 363 static inline struct kernfs_node *
 364 kernfs_find_and_get_ns(struct kernfs_node *parent, const char *name,
 365                        const void *ns)
 366 { return NULL; }
 367 static inline struct kernfs_node *
 368 kernfs_walk_and_get_ns(struct kernfs_node *parent, const char *path,
 369                        const void *ns)
 370 { return NULL; }
 371
 372 static inline void kernfs_get(struct kernfs_node *kn) { }
 373 static inline void kernfs_put(struct kernfs_node *kn) { }
 374
 375 static inline struct kernfs_node *kernfs_node_from_dentry(struct dentry *dentry)
 376 { return NULL; }
 377
 378 static inline struct kernfs_root *kernfs_root_from_sb(struct super_block *sb)
 379 { return NULL; }
 380
 381 static inline struct inode *
 382 kernfs_get_inode(struct super_block *sb, struct kernfs_node *kn)
 383 { return NULL; }
 384
 385 static inline struct kernfs_root *
 386 kernfs_create_root(struct kernfs_syscall_ops *scops, unsigned int flags,
 387                    void *priv)
 388 { return ERR_PTR(-ENOSYS); }
 389
 390 static inline void kernfs_destroy_root(struct kernfs_root *root) { }
 391
 392 static inline struct kernfs_node *
 393 kernfs_create_dir_ns(struct kernfs_node *parent, const char *name,
 394                      umode_t mode, void *priv, const void *ns)
 395 { return ERR_PTR(-ENOSYS); }
 396
 397 static inline struct kernfs_node *
 398 __kernfs_create_file(struct kernfs_node *parent, const char *name,
 399                      umode_t mode, loff_t size, const struct kernfs_ops *ops,
 400                      void *priv, const void *ns, struct lock_class_key *key)
 401 { return ERR_PTR(-ENOSYS); }
 402
 403 static inline struct kernfs_node *
 404 kernfs_create_link(struct kernfs_node *parent, const char *name,
 405                    struct kernfs_node *target)
 406 { return ERR_PTR(-ENOSYS); }
 407
 408 static inline void kernfs_activate(struct kernfs_node *kn) { }
 409
 410 static inline void kernfs_remove(struct kernfs_node *kn) { }
 411
 412 static inline bool kernfs_remove_self(struct kernfs_node *kn)
 413 { return false; }
 414
 415 static inline int kernfs_remove_by_name_ns(struct kernfs_node *kn,
 416                                            const char *name, const void *ns)
 417 { return -ENOSYS; }
 418
 419 static inline int kernfs_rename_ns(struct kernfs_node *kn,
 420                                    struct kernfs_node *new_parent,
 421                                    const char *new_name, const void *new_ns)
 422 { return -ENOSYS; }
 423
 424 static inline int kernfs_setattr(struct kernfs_node *kn,
 425                                  const struct iattr *iattr)
 426 { return -ENOSYS; }
 427
 428 static inline void kernfs_notify(struct kernfs_node *kn) { }
 429
 430 static inline const void *kernfs_super_ns(struct super_block *sb)
 431 { return NULL; }
 432
 433 static inline struct dentry *
 434 kernfs_mount_ns(struct file_system_type *fs_type, int flags,
 435                 struct kernfs_root *root, unsigned long magic,
 436                 bool *new_sb_created, const void *ns)
 437 { return ERR_PTR(-ENOSYS); }
 438
 439 static inline void kernfs_kill_sb(struct super_block *sb) { }
 440
 441 static inline void kernfs_init(void) { }
 442
 443 #endif  /* CONFIG_KERNFS */
 444
 445 /**
 446  * kernfs_path - build full path of a given node
 447  * @kn: kernfs_node of interest
 448  * @buf: buffer to copy @kn's name into
 449  * @buflen: size of @buf
 450  *
 451  * Builds and returns the full path of @kn in @buf of @buflen bytes.  The
 452  * path is built from the end of @buf so the returned pointer usually
 453  * doesn't match @buf.  If @buf isn't long enough, @buf is nul terminated
 454  * and %NULL is returned.
 455  */
 456 static inline int kernfs_path(struct kernfs_node *kn, char *buf, size_t buflen)
 457 {
 458         return kernfs_path_from_node(kn, NULL, buf, buflen);
 459 }
 460
 461 static inline struct kernfs_node *
 462 kernfs_find_and_get(struct kernfs_node *kn, const char *name)
 463 {
 464         return kernfs_find_and_get_ns(kn, name, NULL);
 465 }
 466
 467 static inline struct kernfs_node *
 468 kernfs_walk_and_get(struct kernfs_node *kn, const char *path)
 469 {
 470         return kernfs_walk_and_get_ns(kn, path, NULL);
 471 }
 472
 473 static inline struct kernfs_node *
 474 kernfs_create_dir(struct kernfs_node *parent, const char *name, umode_t mode,
 475                   void *priv)
 476 {
 477         return kernfs_create_dir_ns(parent, name, mode, priv, NULL);
 478 }
 479
 480 static inline struct kernfs_node *
 481 kernfs_create_file_ns(struct kernfs_node *parent, const char *name,
 482                       umode_t mode, loff_t size, const struct kernfs_ops *ops,
 483                       void *priv, const void *ns)
 484 {
 485         struct lock_class_key *key = NULL;
 486
 487 #ifdef CONFIG_DEBUG_LOCK_ALLOC
 488         key = (struct lock_class_key *)&ops->lockdep_key;
 489 #endif
 490         return __kernfs_create_file(parent, name, mode, size, ops, priv, ns,
 491                                     key);
 492 }
 493
 494 static inline struct kernfs_node *
 495 kernfs_create_file(struct kernfs_node *parent, const char *name, umode_t mode,
 496                    loff_t size, const struct kernfs_ops *ops, void *priv)
 497 {
 498         return kernfs_create_file_ns(parent, name, mode, size, ops, priv, NULL);
 499 }
 500
 501 static inline int kernfs_remove_by_name(struct kernfs_node *parent,
 502                                         const char *name)
 503 {
 504         return kernfs_remove_by_name_ns(parent, name, NULL);
 505 }
 506
 507 static inline int kernfs_rename(struct kernfs_node *kn,
 508                                 struct kernfs_node *new_parent,
 509                                 const char *new_name)
 510 {
 511         return kernfs_rename_ns(kn, new_parent, new_name, NULL);
 512 }
 513
 514 static inline struct dentry *
 515 kernfs_mount(struct file_system_type *fs_type, int flags,
 516                 struct kernfs_root *root, unsigned long magic,
 517                 bool *new_sb_created)
 518 {
 519         return kernfs_mount_ns(fs_type, flags, root,
 520                                 magic, new_sb_created, NULL);
 521 }
 522
 523 #endif  /* __LINUX_KERNFS_H */