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