]> git.proxmox.com Git - mirror_ubuntu-zesty-kernel.git/blame - include/linux/kernfs.h
Documentation: start documenting driver design patterns
[mirror_ubuntu-zesty-kernel.git] / include / linux / kernfs.h
CommitLineData
b8441ed2
TH
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
879f40d1 10#include <linux/kernel.h>
5d0e26bb 11#include <linux/err.h>
dd8a5b03
TH
12#include <linux/list.h>
13#include <linux/mutex.h>
bc755553 14#include <linux/idr.h>
517e64f5 15#include <linux/lockdep.h>
cf9e5a73
TH
16#include <linux/rbtree.h>
17#include <linux/atomic.h>
18#include <linux/completion.h>
879f40d1 19
5d60418e
TH
20struct file;
21struct iattr;
dd8a5b03
TH
22struct seq_file;
23struct vm_area_struct;
4b93dc9b
TH
24struct super_block;
25struct file_system_type;
5d60418e 26
cf9e5a73
TH
27struct sysfs_open_dirent;
28struct sysfs_inode_attrs;
29
30enum kernfs_node_type {
31 SYSFS_DIR = 0x0001,
32 SYSFS_KOBJ_ATTR = 0x0002,
33 SYSFS_KOBJ_LINK = 0x0004,
34};
35
36#define SYSFS_TYPE_MASK 0x000f
37#define SYSFS_COPY_NAME (SYSFS_DIR | SYSFS_KOBJ_LINK)
38#define SYSFS_ACTIVE_REF SYSFS_KOBJ_ATTR
39#define SYSFS_FLAG_MASK ~SYSFS_TYPE_MASK
40
41enum kernfs_node_flag {
42 SYSFS_FLAG_REMOVED = 0x0010,
43 SYSFS_FLAG_NS = 0x0020,
44 SYSFS_FLAG_HAS_SEQ_SHOW = 0x0040,
45 SYSFS_FLAG_HAS_MMAP = 0x0080,
46 SYSFS_FLAG_LOCKDEP = 0x0100,
47};
48
49/* type-specific structures for sysfs_dirent->s_* union members */
50struct sysfs_elem_dir {
51 unsigned long subdirs;
52 /* children rbtree starts here and goes through sd->s_rb */
53 struct rb_root children;
54
55 /*
56 * The kernfs hierarchy this directory belongs to. This fits
57 * better directly in sysfs_dirent but is here to save space.
58 */
59 struct kernfs_root *root;
60};
61
62struct sysfs_elem_symlink {
63 struct sysfs_dirent *target_sd;
64};
65
66struct sysfs_elem_attr {
67 const struct kernfs_ops *ops;
68 struct sysfs_open_dirent *open;
69 loff_t size;
70};
71
72/*
73 * sysfs_dirent - the building block of sysfs hierarchy. Each and every
74 * sysfs node is represented by single sysfs_dirent. Most fields are
75 * private to kernfs and shouldn't be accessed directly by kernfs users.
76 *
77 * As long as s_count reference is held, the sysfs_dirent itself is
78 * accessible. Dereferencing s_elem or any other outer entity
79 * requires s_active reference.
80 */
81struct sysfs_dirent {
82 atomic_t s_count;
83 atomic_t s_active;
84#ifdef CONFIG_DEBUG_LOCK_ALLOC
85 struct lockdep_map dep_map;
86#endif
87 /* the following two fields are published */
88 struct sysfs_dirent *s_parent;
89 const char *s_name;
90
91 struct rb_node s_rb;
92
93 union {
94 struct completion *completion;
95 struct sysfs_dirent *removed_list;
96 } u;
97
98 const void *s_ns; /* namespace tag */
99 unsigned int s_hash; /* ns + name hash */
100 union {
101 struct sysfs_elem_dir s_dir;
102 struct sysfs_elem_symlink s_symlink;
103 struct sysfs_elem_attr s_attr;
104 };
105
106 void *priv;
107
108 unsigned short s_flags;
109 umode_t s_mode;
110 unsigned int s_ino;
111 struct sysfs_inode_attrs *s_iattr;
112};
b8441ed2 113
ba7443bc
TH
114struct kernfs_root {
115 /* published fields */
116 struct sysfs_dirent *sd;
bc755553
TH
117
118 /* private fields, do not use outside kernfs proper */
119 struct ida ino_ida;
ba7443bc
TH
120};
121
dd8a5b03
TH
122struct sysfs_open_file {
123 /* published fields */
124 struct sysfs_dirent *sd;
125 struct file *file;
126
127 /* private fields, do not use outside kernfs proper */
128 struct mutex mutex;
129 int event;
130 struct list_head list;
131
132 bool mmapped;
133 const struct vm_operations_struct *vm_ops;
134};
135
f6acf8bb
TH
136struct kernfs_ops {
137 /*
138 * Read is handled by either seq_file or raw_read().
139 *
d19b9846
TH
140 * If seq_show() is present, seq_file path is active. Other seq
141 * operations are optional and if not implemented, the behavior is
142 * equivalent to single_open(). @sf->private points to the
f6acf8bb
TH
143 * associated sysfs_open_file.
144 *
145 * read() is bounced through kernel buffer and a read larger than
146 * PAGE_SIZE results in partial operation of PAGE_SIZE.
147 */
148 int (*seq_show)(struct seq_file *sf, void *v);
d19b9846
TH
149
150 void *(*seq_start)(struct seq_file *sf, loff_t *ppos);
151 void *(*seq_next)(struct seq_file *sf, void *v, loff_t *ppos);
152 void (*seq_stop)(struct seq_file *sf, void *v);
f6acf8bb
TH
153
154 ssize_t (*read)(struct sysfs_open_file *of, char *buf, size_t bytes,
155 loff_t off);
156
157 /*
158 * write() is bounced through kernel buffer and a write larger than
159 * PAGE_SIZE results in partial operation of PAGE_SIZE.
160 */
161 ssize_t (*write)(struct sysfs_open_file *of, char *buf, size_t bytes,
162 loff_t off);
163
164 int (*mmap)(struct sysfs_open_file *of, struct vm_area_struct *vma);
517e64f5
TH
165
166#ifdef CONFIG_DEBUG_LOCK_ALLOC
167 struct lock_class_key lockdep_key;
168#endif
f6acf8bb
TH
169};
170
879f40d1
TH
171#ifdef CONFIG_SYSFS
172
cf9e5a73
TH
173static inline enum kernfs_node_type sysfs_type(struct sysfs_dirent *sd)
174{
175 return sd->s_flags & SYSFS_TYPE_MASK;
176}
177
178/**
179 * kernfs_enable_ns - enable namespace under a directory
180 * @sd: directory of interest, should be empty
181 *
182 * This is to be called right after @sd is created to enable namespace
183 * under it. All children of @sd must have non-NULL namespace tags and
184 * only the ones which match the super_block's tag will be visible.
185 */
186static inline void kernfs_enable_ns(struct sysfs_dirent *sd)
187{
188 WARN_ON_ONCE(sysfs_type(sd) != SYSFS_DIR);
189 WARN_ON_ONCE(!RB_EMPTY_ROOT(&sd->s_dir.children));
190 sd->s_flags |= SYSFS_FLAG_NS;
191}
192
ac9bba03
TH
193/**
194 * kernfs_ns_enabled - test whether namespace is enabled
195 * @sd: the node to test
196 *
197 * Test whether namespace filtering is enabled for the children of @ns.
198 */
199static inline bool kernfs_ns_enabled(struct sysfs_dirent *sd)
200{
201 return sd->s_flags & SYSFS_FLAG_NS;
202}
203
ccf73cf3
TH
204struct sysfs_dirent *kernfs_find_and_get_ns(struct sysfs_dirent *parent,
205 const char *name, const void *ns);
206void kernfs_get(struct sysfs_dirent *sd);
207void kernfs_put(struct sysfs_dirent *sd);
208
ba7443bc
TH
209struct kernfs_root *kernfs_create_root(void *priv);
210void kernfs_destroy_root(struct kernfs_root *root);
211
93b2b8e4
TH
212struct sysfs_dirent *kernfs_create_dir_ns(struct sysfs_dirent *parent,
213 const char *name, void *priv,
214 const void *ns);
517e64f5
TH
215struct sysfs_dirent *kernfs_create_file_ns_key(struct sysfs_dirent *parent,
216 const char *name,
217 umode_t mode, loff_t size,
218 const struct kernfs_ops *ops,
219 void *priv, const void *ns,
220 struct lock_class_key *key);
5d0e26bb
TH
221struct sysfs_dirent *kernfs_create_link(struct sysfs_dirent *parent,
222 const char *name,
223 struct sysfs_dirent *target);
879f40d1
TH
224void kernfs_remove(struct sysfs_dirent *sd);
225int kernfs_remove_by_name_ns(struct sysfs_dirent *parent, const char *name,
226 const void *ns);
890ece16
TH
227int kernfs_rename_ns(struct sysfs_dirent *sd, struct sysfs_dirent *new_parent,
228 const char *new_name, const void *new_ns);
5d60418e 229int kernfs_setattr(struct sysfs_dirent *sd, const struct iattr *iattr);
024f6471 230void kernfs_notify(struct sysfs_dirent *sd);
879f40d1 231
4b93dc9b
TH
232const void *kernfs_super_ns(struct super_block *sb);
233struct dentry *kernfs_mount_ns(struct file_system_type *fs_type, int flags,
234 struct kernfs_root *root, const void *ns);
235void kernfs_kill_sb(struct super_block *sb);
236
237void kernfs_init(void);
238
879f40d1
TH
239#else /* CONFIG_SYSFS */
240
cf9e5a73
TH
241static inline enum kernfs_node_type sysfs_type(struct sysfs_dirent *sd)
242{ return 0; } /* whatever */
243
244static inline void kernfs_enable_ns(struct sysfs_dirent *sd) { }
245
ac9bba03
TH
246static inline bool kernfs_ns_enabled(struct sysfs_dirent *sd)
247{ return false; }
248
ccf73cf3
TH
249static inline struct sysfs_dirent *
250kernfs_find_and_get_ns(struct sysfs_dirent *parent, const char *name,
251 const void *ns)
252{ return NULL; }
253
254static inline void kernfs_get(struct sysfs_dirent *sd) { }
255static inline void kernfs_put(struct sysfs_dirent *sd) { }
256
ba7443bc
TH
257static inline struct kernfs_root *kernfs_create_root(void *priv)
258{ return ERR_PTR(-ENOSYS); }
259
260static inline void kernfs_destroy_root(struct kernfs_root *root) { }
261
93b2b8e4
TH
262static inline struct sysfs_dirent *
263kernfs_create_dir_ns(struct sysfs_dirent *parent, const char *name, void *priv,
264 const void *ns)
265{ return ERR_PTR(-ENOSYS); }
266
496f7394 267static inline struct sysfs_dirent *
517e64f5
TH
268kernfs_create_file_ns_key(struct sysfs_dirent *parent, const char *name,
269 umode_t mode, loff_t size,
270 const struct kernfs_ops *ops, void *priv,
271 const void *ns, struct lock_class_key *key)
496f7394
TH
272{ return ERR_PTR(-ENOSYS); }
273
5d0e26bb
TH
274static inline struct sysfs_dirent *
275kernfs_create_link(struct sysfs_dirent *parent, const char *name,
276 struct sysfs_dirent *target)
277{ return ERR_PTR(-ENOSYS); }
278
879f40d1
TH
279static inline void kernfs_remove(struct sysfs_dirent *sd) { }
280
281static inline int kernfs_remove_by_name_ns(struct sysfs_dirent *parent,
282 const char *name, const void *ns)
283{ return -ENOSYS; }
284
890ece16
TH
285static inline int kernfs_rename_ns(struct sysfs_dirent *sd,
286 struct sysfs_dirent *new_parent,
287 const char *new_name, const void *new_ns)
288{ return -ENOSYS; }
289
5d60418e
TH
290static inline int kernfs_setattr(struct sysfs_dirent *sd,
291 const struct iattr *iattr)
292{ return -ENOSYS; }
293
024f6471
TH
294static inline void kernfs_notify(struct sysfs_dirent *sd) { }
295
4b93dc9b
TH
296static inline const void *kernfs_super_ns(struct super_block *sb)
297{ return NULL; }
298
299static inline struct dentry *
300kernfs_mount_ns(struct file_system_type *fs_type, int flags,
301 struct kernfs_root *root, const void *ns)
302{ return ERR_PTR(-ENOSYS); }
303
304static inline void kernfs_kill_sb(struct super_block *sb) { }
305
306static inline void kernfs_init(void) { }
307
879f40d1
TH
308#endif /* CONFIG_SYSFS */
309
93b2b8e4 310static inline struct sysfs_dirent *
ccf73cf3
TH
311kernfs_find_and_get(struct sysfs_dirent *sd, const char *name)
312{
313 return kernfs_find_and_get_ns(sd, name, NULL);
314}
315
316static inline struct sysfs_dirent *
93b2b8e4
TH
317kernfs_create_dir(struct sysfs_dirent *parent, const char *name, void *priv)
318{
319 return kernfs_create_dir_ns(parent, name, priv, NULL);
320}
321
517e64f5
TH
322static inline struct sysfs_dirent *
323kernfs_create_file_ns(struct sysfs_dirent *parent, const char *name,
324 umode_t mode, loff_t size, const struct kernfs_ops *ops,
325 void *priv, const void *ns)
326{
327 struct lock_class_key *key = NULL;
328
329#ifdef CONFIG_DEBUG_LOCK_ALLOC
330 key = (struct lock_class_key *)&ops->lockdep_key;
331#endif
332 return kernfs_create_file_ns_key(parent, name, mode, size, ops, priv,
333 ns, key);
334}
335
496f7394
TH
336static inline struct sysfs_dirent *
337kernfs_create_file(struct sysfs_dirent *parent, const char *name, umode_t mode,
338 loff_t size, const struct kernfs_ops *ops, void *priv)
339{
340 return kernfs_create_file_ns(parent, name, mode, size, ops, priv, NULL);
341}
342
879f40d1
TH
343static inline int kernfs_remove_by_name(struct sysfs_dirent *parent,
344 const char *name)
345{
346 return kernfs_remove_by_name_ns(parent, name, NULL);
347}
348
4b93dc9b
TH
349static inline struct dentry *
350kernfs_mount(struct file_system_type *fs_type, int flags,
351 struct kernfs_root *root)
352{
353 return kernfs_mount_ns(fs_type, flags, root, NULL);
354}
355
b8441ed2 356#endif /* __LINUX_KERNFS_H */