1 /* SPDX-License-Identifier: GPL-2.0 */
3 * sysfs.h - definitions for the device driver filesystem
5 * Copyright (c) 2001,2002 Patrick Mochel
6 * Copyright (c) 2004 Silicon Graphics, Inc.
7 * Copyright (c) 2007 SUSE Linux Products GmbH
8 * Copyright (c) 2007 Tejun Heo <teheo@suse.de>
10 * Please see Documentation/filesystems/sysfs.rst for more information.
16 #include <linux/kernfs.h>
17 #include <linux/compiler.h>
18 #include <linux/errno.h>
19 #include <linux/list.h>
20 #include <linux/lockdep.h>
21 #include <linux/kobject_ns.h>
22 #include <linux/stat.h>
23 #include <linux/atomic.h>
33 #ifdef CONFIG_DEBUG_LOCK_ALLOC
34 bool ignore_lockdep:1;
35 struct lock_class_key *key;
36 struct lock_class_key skey;
41 * sysfs_attr_init - initialize a dynamically allocated sysfs attribute
42 * @attr: struct attribute to initialize
44 * Initialize a dynamically allocated struct attribute so we can
45 * make lockdep happy. This is a new requirement for attributes
46 * and initially this is only needed when lockdep is enabled.
47 * Lockdep gives a nice error when your attribute is added to
48 * sysfs if you don't have this.
50 #ifdef CONFIG_DEBUG_LOCK_ALLOC
51 #define sysfs_attr_init(attr) \
53 static struct lock_class_key __key; \
55 (attr)->key = &__key; \
58 #define sysfs_attr_init(attr) do {} while (0)
62 * struct attribute_group - data structure used to declare an attribute group.
63 * @name: Optional: Attribute group name
64 * If specified, the attribute group will be created in a
65 * new subdirectory with this name. Additionally when a
66 * group is named, @is_visible and @is_bin_visible may
67 * return SYSFS_GROUP_INVISIBLE to control visibility of
68 * the directory itself.
69 * @is_visible: Optional: Function to return permissions associated with an
70 * attribute of the group. Will be called repeatedly for
71 * each non-binary attribute in the group. Only read/write
72 * permissions as well as SYSFS_PREALLOC are accepted. Must
73 * return 0 if an attribute is not visible. The returned
74 * value will replace static permissions defined in struct
75 * attribute. Use SYSFS_GROUP_VISIBLE() when assigning this
76 * callback to specify separate _group_visible() and
77 * _attr_visible() handlers.
79 * Optional: Function to return permissions associated with a
80 * binary attribute of the group. Will be called repeatedly
81 * for each binary attribute in the group. Only read/write
82 * permissions as well as SYSFS_PREALLOC (and the
83 * visibility flags for named groups) are accepted. Must
84 * return 0 if a binary attribute is not visible. The
85 * returned value will replace static permissions defined
86 * in struct bin_attribute. If @is_visible is not set, Use
87 * SYSFS_GROUP_VISIBLE() when assigning this callback to
88 * specify separate _group_visible() and _attr_visible()
90 * @attrs: Pointer to NULL terminated list of attributes.
91 * @bin_attrs: Pointer to NULL terminated list of binary attributes.
92 * Either attrs or bin_attrs or both must be provided.
94 struct attribute_group {
96 umode_t (*is_visible)(struct kobject *,
97 struct attribute *, int);
98 umode_t (*is_bin_visible)(struct kobject *,
99 struct bin_attribute *, int);
100 struct attribute **attrs;
101 struct bin_attribute **bin_attrs;
104 #define SYSFS_PREALLOC 010000
105 #define SYSFS_GROUP_INVISIBLE 020000
108 * DEFINE_SYSFS_GROUP_VISIBLE(name):
109 * A helper macro to pair with the assignment of ".is_visible =
110 * SYSFS_GROUP_VISIBLE(name)", that arranges for the directory
111 * associated with a named attribute_group to optionally be hidden.
112 * This allows for static declaration of attribute_groups, and the
113 * simplification of attribute visibility lifetime that implies,
114 * without polluting sysfs with empty attribute directories.
117 * static umode_t example_attr_visible(struct kobject *kobj,
118 * struct attribute *attr, int n)
120 * if (example_attr_condition)
122 * else if (ro_attr_condition)
127 * static bool example_group_visible(struct kobject *kobj)
129 * if (example_group_condition)
134 * DEFINE_SYSFS_GROUP_VISIBLE(example);
136 * static struct attribute_group example_group = {
138 * .is_visible = SYSFS_GROUP_VISIBLE(example),
139 * .attrs = &example_attrs,
142 * Note that it expects <name>_attr_visible and <name>_group_visible to
143 * be defined. For cases where individual attributes do not need
144 * separate visibility consideration, only entire group visibility at
145 * once, see DEFINE_SIMPLE_SYSFS_GROUP_VISIBLE().
147 #define DEFINE_SYSFS_GROUP_VISIBLE(name) \
148 static inline umode_t sysfs_group_visible_##name( \
149 struct kobject *kobj, struct attribute *attr, int n) \
151 if (n == 0 && !name##_group_visible(kobj)) \
152 return SYSFS_GROUP_INVISIBLE; \
153 return name##_attr_visible(kobj, attr, n); \
157 * DEFINE_SIMPLE_SYSFS_GROUP_VISIBLE(name):
158 * A helper macro to pair with SYSFS_GROUP_VISIBLE() that like
159 * DEFINE_SYSFS_GROUP_VISIBLE() controls group visibility, but does
160 * not require the implementation of a per-attribute visibility
164 * static bool example_group_visible(struct kobject *kobj)
166 * if (example_group_condition)
171 * DEFINE_SIMPLE_SYSFS_GROUP_VISIBLE(example);
173 * static struct attribute_group example_group = {
175 * .is_visible = SYSFS_GROUP_VISIBLE(example),
176 * .attrs = &example_attrs,
179 #define DEFINE_SIMPLE_SYSFS_GROUP_VISIBLE(name) \
180 static inline umode_t sysfs_group_visible_##name( \
181 struct kobject *kobj, struct attribute *a, int n) \
183 if (n == 0 && !name##_group_visible(kobj)) \
184 return SYSFS_GROUP_INVISIBLE; \
189 * Same as DEFINE_SYSFS_GROUP_VISIBLE, but for groups with only binary
190 * attributes. If an attribute_group defines both text and binary
191 * attributes, the group visibility is determined by the function
192 * specified to is_visible() not is_bin_visible()
194 #define DEFINE_SYSFS_BIN_GROUP_VISIBLE(name) \
195 static inline umode_t sysfs_group_visible_##name( \
196 struct kobject *kobj, struct bin_attribute *attr, int n) \
198 if (n == 0 && !name##_group_visible(kobj)) \
199 return SYSFS_GROUP_INVISIBLE; \
200 return name##_attr_visible(kobj, attr, n); \
203 #define DEFINE_SIMPLE_SYSFS_BIN_GROUP_VISIBLE(name) \
204 static inline umode_t sysfs_group_visible_##name( \
205 struct kobject *kobj, struct bin_attribute *a, int n) \
207 if (n == 0 && !name##_group_visible(kobj)) \
208 return SYSFS_GROUP_INVISIBLE; \
212 #define SYSFS_GROUP_VISIBLE(fn) sysfs_group_visible_##fn
215 * Use these macros to make defining attributes easier.
216 * See include/linux/device.h for examples..
219 #define __ATTR(_name, _mode, _show, _store) { \
220 .attr = {.name = __stringify(_name), \
221 .mode = VERIFY_OCTAL_PERMISSIONS(_mode) }, \
226 #define __ATTR_PREALLOC(_name, _mode, _show, _store) { \
227 .attr = {.name = __stringify(_name), \
228 .mode = SYSFS_PREALLOC | VERIFY_OCTAL_PERMISSIONS(_mode) },\
233 #define __ATTR_RO(_name) { \
234 .attr = { .name = __stringify(_name), .mode = 0444 }, \
235 .show = _name##_show, \
238 #define __ATTR_RO_MODE(_name, _mode) { \
239 .attr = { .name = __stringify(_name), \
240 .mode = VERIFY_OCTAL_PERMISSIONS(_mode) }, \
241 .show = _name##_show, \
244 #define __ATTR_RW_MODE(_name, _mode) { \
245 .attr = { .name = __stringify(_name), \
246 .mode = VERIFY_OCTAL_PERMISSIONS(_mode) }, \
247 .show = _name##_show, \
248 .store = _name##_store, \
251 #define __ATTR_WO(_name) { \
252 .attr = { .name = __stringify(_name), .mode = 0200 }, \
253 .store = _name##_store, \
256 #define __ATTR_RW(_name) __ATTR(_name, 0644, _name##_show, _name##_store)
258 #define __ATTR_NULL { .attr = { .name = NULL } }
260 #ifdef CONFIG_DEBUG_LOCK_ALLOC
261 #define __ATTR_IGNORE_LOCKDEP(_name, _mode, _show, _store) { \
262 .attr = {.name = __stringify(_name), .mode = _mode, \
263 .ignore_lockdep = true }, \
268 #define __ATTR_IGNORE_LOCKDEP __ATTR
271 #define __ATTRIBUTE_GROUPS(_name) \
272 static const struct attribute_group *_name##_groups[] = { \
277 #define ATTRIBUTE_GROUPS(_name) \
278 static const struct attribute_group _name##_group = { \
279 .attrs = _name##_attrs, \
281 __ATTRIBUTE_GROUPS(_name)
283 #define BIN_ATTRIBUTE_GROUPS(_name) \
284 static const struct attribute_group _name##_group = { \
285 .bin_attrs = _name##_attrs, \
287 __ATTRIBUTE_GROUPS(_name)
290 struct vm_area_struct;
291 struct address_space;
293 struct bin_attribute {
294 struct attribute attr;
297 struct address_space *(*f_mapping)(void);
298 ssize_t (*read)(struct file *, struct kobject *, struct bin_attribute *,
299 char *, loff_t, size_t);
300 ssize_t (*write)(struct file *, struct kobject *, struct bin_attribute *,
301 char *, loff_t, size_t);
302 loff_t (*llseek)(struct file *, struct kobject *, struct bin_attribute *,
304 int (*mmap)(struct file *, struct kobject *, struct bin_attribute *attr,
305 struct vm_area_struct *vma);
309 * sysfs_bin_attr_init - initialize a dynamically allocated bin_attribute
310 * @attr: struct bin_attribute to initialize
312 * Initialize a dynamically allocated struct bin_attribute so we
313 * can make lockdep happy. This is a new requirement for
314 * attributes and initially this is only needed when lockdep is
315 * enabled. Lockdep gives a nice error when your attribute is
316 * added to sysfs if you don't have this.
318 #define sysfs_bin_attr_init(bin_attr) sysfs_attr_init(&(bin_attr)->attr)
320 /* macros to create static binary attributes easier */
321 #define __BIN_ATTR(_name, _mode, _read, _write, _size) { \
322 .attr = { .name = __stringify(_name), .mode = _mode }, \
328 #define __BIN_ATTR_RO(_name, _size) { \
329 .attr = { .name = __stringify(_name), .mode = 0444 }, \
330 .read = _name##_read, \
334 #define __BIN_ATTR_WO(_name, _size) { \
335 .attr = { .name = __stringify(_name), .mode = 0200 }, \
336 .write = _name##_write, \
340 #define __BIN_ATTR_RW(_name, _size) \
341 __BIN_ATTR(_name, 0644, _name##_read, _name##_write, _size)
343 #define __BIN_ATTR_NULL __ATTR_NULL
345 #define BIN_ATTR(_name, _mode, _read, _write, _size) \
346 struct bin_attribute bin_attr_##_name = __BIN_ATTR(_name, _mode, _read, \
349 #define BIN_ATTR_RO(_name, _size) \
350 struct bin_attribute bin_attr_##_name = __BIN_ATTR_RO(_name, _size)
352 #define BIN_ATTR_WO(_name, _size) \
353 struct bin_attribute bin_attr_##_name = __BIN_ATTR_WO(_name, _size)
355 #define BIN_ATTR_RW(_name, _size) \
356 struct bin_attribute bin_attr_##_name = __BIN_ATTR_RW(_name, _size)
359 #define __BIN_ATTR_ADMIN_RO(_name, _size) { \
360 .attr = { .name = __stringify(_name), .mode = 0400 }, \
361 .read = _name##_read, \
365 #define __BIN_ATTR_ADMIN_RW(_name, _size) \
366 __BIN_ATTR(_name, 0600, _name##_read, _name##_write, _size)
368 #define BIN_ATTR_ADMIN_RO(_name, _size) \
369 struct bin_attribute bin_attr_##_name = __BIN_ATTR_ADMIN_RO(_name, _size)
371 #define BIN_ATTR_ADMIN_RW(_name, _size) \
372 struct bin_attribute bin_attr_##_name = __BIN_ATTR_ADMIN_RW(_name, _size)
375 ssize_t (*show)(struct kobject *, struct attribute *, char *);
376 ssize_t (*store)(struct kobject *, struct attribute *, const char *, size_t);
381 int __must_check sysfs_create_dir_ns(struct kobject *kobj, const void *ns);
382 void sysfs_remove_dir(struct kobject *kobj);
383 int __must_check sysfs_rename_dir_ns(struct kobject *kobj, const char *new_name,
385 int __must_check sysfs_move_dir_ns(struct kobject *kobj,
386 struct kobject *new_parent_kobj,
388 int __must_check sysfs_create_mount_point(struct kobject *parent_kobj,
390 void sysfs_remove_mount_point(struct kobject *parent_kobj,
393 int __must_check sysfs_create_file_ns(struct kobject *kobj,
394 const struct attribute *attr,
396 int __must_check sysfs_create_files(struct kobject *kobj,
397 const struct attribute * const *attr);
398 int __must_check sysfs_chmod_file(struct kobject *kobj,
399 const struct attribute *attr, umode_t mode);
400 struct kernfs_node *sysfs_break_active_protection(struct kobject *kobj,
401 const struct attribute *attr);
402 void sysfs_unbreak_active_protection(struct kernfs_node *kn);
403 void sysfs_remove_file_ns(struct kobject *kobj, const struct attribute *attr,
405 bool sysfs_remove_file_self(struct kobject *kobj, const struct attribute *attr);
406 void sysfs_remove_files(struct kobject *kobj, const struct attribute * const *attr);
408 int __must_check sysfs_create_bin_file(struct kobject *kobj,
409 const struct bin_attribute *attr);
410 void sysfs_remove_bin_file(struct kobject *kobj,
411 const struct bin_attribute *attr);
413 int __must_check sysfs_create_link(struct kobject *kobj, struct kobject *target,
415 int __must_check sysfs_create_link_nowarn(struct kobject *kobj,
416 struct kobject *target,
418 void sysfs_remove_link(struct kobject *kobj, const char *name);
420 int sysfs_rename_link_ns(struct kobject *kobj, struct kobject *target,
421 const char *old_name, const char *new_name,
424 void sysfs_delete_link(struct kobject *dir, struct kobject *targ,
427 int __must_check sysfs_create_group(struct kobject *kobj,
428 const struct attribute_group *grp);
429 int __must_check sysfs_create_groups(struct kobject *kobj,
430 const struct attribute_group **groups);
431 int __must_check sysfs_update_groups(struct kobject *kobj,
432 const struct attribute_group **groups);
433 int sysfs_update_group(struct kobject *kobj,
434 const struct attribute_group *grp);
435 void sysfs_remove_group(struct kobject *kobj,
436 const struct attribute_group *grp);
437 void sysfs_remove_groups(struct kobject *kobj,
438 const struct attribute_group **groups);
439 int sysfs_add_file_to_group(struct kobject *kobj,
440 const struct attribute *attr, const char *group);
441 void sysfs_remove_file_from_group(struct kobject *kobj,
442 const struct attribute *attr, const char *group);
443 int sysfs_merge_group(struct kobject *kobj,
444 const struct attribute_group *grp);
445 void sysfs_unmerge_group(struct kobject *kobj,
446 const struct attribute_group *grp);
447 int sysfs_add_link_to_group(struct kobject *kobj, const char *group_name,
448 struct kobject *target, const char *link_name);
449 void sysfs_remove_link_from_group(struct kobject *kobj, const char *group_name,
450 const char *link_name);
451 int compat_only_sysfs_link_entry_to_kobj(struct kobject *kobj,
452 struct kobject *target_kobj,
453 const char *target_name,
454 const char *symlink_name);
456 void sysfs_notify(struct kobject *kobj, const char *dir, const char *attr);
458 int __must_check sysfs_init(void);
460 static inline void sysfs_enable_ns(struct kernfs_node *kn)
462 return kernfs_enable_ns(kn);
465 int sysfs_file_change_owner(struct kobject *kobj, const char *name, kuid_t kuid,
467 int sysfs_change_owner(struct kobject *kobj, kuid_t kuid, kgid_t kgid);
468 int sysfs_link_change_owner(struct kobject *kobj, struct kobject *targ,
469 const char *name, kuid_t kuid, kgid_t kgid);
470 int sysfs_groups_change_owner(struct kobject *kobj,
471 const struct attribute_group **groups,
472 kuid_t kuid, kgid_t kgid);
473 int sysfs_group_change_owner(struct kobject *kobj,
474 const struct attribute_group *groups, kuid_t kuid,
477 int sysfs_emit(char *buf, const char *fmt, ...);
479 int sysfs_emit_at(char *buf, int at, const char *fmt, ...);
481 #else /* CONFIG_SYSFS */
483 static inline int sysfs_create_dir_ns(struct kobject *kobj, const void *ns)
488 static inline void sysfs_remove_dir(struct kobject *kobj)
492 static inline int sysfs_rename_dir_ns(struct kobject *kobj,
493 const char *new_name, const void *new_ns)
498 static inline int sysfs_move_dir_ns(struct kobject *kobj,
499 struct kobject *new_parent_kobj,
505 static inline int sysfs_create_mount_point(struct kobject *parent_kobj,
511 static inline void sysfs_remove_mount_point(struct kobject *parent_kobj,
516 static inline int sysfs_create_file_ns(struct kobject *kobj,
517 const struct attribute *attr,
523 static inline int sysfs_create_files(struct kobject *kobj,
524 const struct attribute * const *attr)
529 static inline int sysfs_chmod_file(struct kobject *kobj,
530 const struct attribute *attr, umode_t mode)
535 static inline struct kernfs_node *
536 sysfs_break_active_protection(struct kobject *kobj,
537 const struct attribute *attr)
542 static inline void sysfs_unbreak_active_protection(struct kernfs_node *kn)
546 static inline void sysfs_remove_file_ns(struct kobject *kobj,
547 const struct attribute *attr,
552 static inline bool sysfs_remove_file_self(struct kobject *kobj,
553 const struct attribute *attr)
558 static inline void sysfs_remove_files(struct kobject *kobj,
559 const struct attribute * const *attr)
563 static inline int sysfs_create_bin_file(struct kobject *kobj,
564 const struct bin_attribute *attr)
569 static inline void sysfs_remove_bin_file(struct kobject *kobj,
570 const struct bin_attribute *attr)
574 static inline int sysfs_create_link(struct kobject *kobj,
575 struct kobject *target, const char *name)
580 static inline int sysfs_create_link_nowarn(struct kobject *kobj,
581 struct kobject *target,
587 static inline void sysfs_remove_link(struct kobject *kobj, const char *name)
591 static inline int sysfs_rename_link_ns(struct kobject *k, struct kobject *t,
592 const char *old_name,
593 const char *new_name, const void *ns)
598 static inline void sysfs_delete_link(struct kobject *k, struct kobject *t,
603 static inline int sysfs_create_group(struct kobject *kobj,
604 const struct attribute_group *grp)
609 static inline int sysfs_create_groups(struct kobject *kobj,
610 const struct attribute_group **groups)
615 static inline int sysfs_update_groups(struct kobject *kobj,
616 const struct attribute_group **groups)
621 static inline int sysfs_update_group(struct kobject *kobj,
622 const struct attribute_group *grp)
627 static inline void sysfs_remove_group(struct kobject *kobj,
628 const struct attribute_group *grp)
632 static inline void sysfs_remove_groups(struct kobject *kobj,
633 const struct attribute_group **groups)
637 static inline int sysfs_add_file_to_group(struct kobject *kobj,
638 const struct attribute *attr, const char *group)
643 static inline void sysfs_remove_file_from_group(struct kobject *kobj,
644 const struct attribute *attr, const char *group)
648 static inline int sysfs_merge_group(struct kobject *kobj,
649 const struct attribute_group *grp)
654 static inline void sysfs_unmerge_group(struct kobject *kobj,
655 const struct attribute_group *grp)
659 static inline int sysfs_add_link_to_group(struct kobject *kobj,
660 const char *group_name, struct kobject *target,
661 const char *link_name)
666 static inline void sysfs_remove_link_from_group(struct kobject *kobj,
667 const char *group_name, const char *link_name)
671 static inline int compat_only_sysfs_link_entry_to_kobj(struct kobject *kobj,
672 struct kobject *target_kobj,
673 const char *target_name,
674 const char *symlink_name)
679 static inline void sysfs_notify(struct kobject *kobj, const char *dir,
684 static inline int __must_check sysfs_init(void)
689 static inline void sysfs_enable_ns(struct kernfs_node *kn)
693 static inline int sysfs_file_change_owner(struct kobject *kobj,
694 const char *name, kuid_t kuid,
700 static inline int sysfs_link_change_owner(struct kobject *kobj,
701 struct kobject *targ,
702 const char *name, kuid_t kuid,
708 static inline int sysfs_change_owner(struct kobject *kobj, kuid_t kuid, kgid_t kgid)
713 static inline int sysfs_groups_change_owner(struct kobject *kobj,
714 const struct attribute_group **groups,
715 kuid_t kuid, kgid_t kgid)
720 static inline int sysfs_group_change_owner(struct kobject *kobj,
721 const struct attribute_group *groups,
722 kuid_t kuid, kgid_t kgid)
728 static inline int sysfs_emit(char *buf, const char *fmt, ...)
734 static inline int sysfs_emit_at(char *buf, int at, const char *fmt, ...)
738 #endif /* CONFIG_SYSFS */
740 static inline int __must_check sysfs_create_file(struct kobject *kobj,
741 const struct attribute *attr)
743 return sysfs_create_file_ns(kobj, attr, NULL);
746 static inline void sysfs_remove_file(struct kobject *kobj,
747 const struct attribute *attr)
749 sysfs_remove_file_ns(kobj, attr, NULL);
752 static inline int sysfs_rename_link(struct kobject *kobj, struct kobject *target,
753 const char *old_name, const char *new_name)
755 return sysfs_rename_link_ns(kobj, target, old_name, new_name, NULL);
758 static inline void sysfs_notify_dirent(struct kernfs_node *kn)
763 static inline struct kernfs_node *sysfs_get_dirent(struct kernfs_node *parent,
766 return kernfs_find_and_get(parent, name);
769 static inline struct kernfs_node *sysfs_get(struct kernfs_node *kn)
775 static inline void sysfs_put(struct kernfs_node *kn)
780 #endif /* _SYSFS_H_ */