1 /* SPDX-License-Identifier: GPL-2.0 */ 2 /* 3 * sysfs.h - definitions for the device driver filesystem 4 * 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> 9 * 10 * Please see Documentation/filesystems/sysfs.rst for more information. 11 */ 12 13 #ifndef _SYSFS_H_ 14 #define _SYSFS_H_ 15 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> 24 25 struct kobject; 26 struct module; 27 struct bin_attribute; 28 enum kobj_ns_type; 29 30 struct attribute { 31 const char *name; 32 umode_t mode; 33 #ifdef CONFIG_DEBUG_LOCK_ALLOC 34 bool ignore_lockdep:1; 35 struct lock_class_key *key; 36 struct lock_class_key skey; 37 #endif 38 }; 39 40 /** 41 * sysfs_attr_init - initialize a dynamically allocated sysfs attribute 42 * @attr: struct attribute to initialize 43 * 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. 49 */ 50 #ifdef CONFIG_DEBUG_LOCK_ALLOC 51 #define sysfs_attr_init(attr) \ 52 do { \ 53 static struct lock_class_key __key; \ 54 \ 55 (attr)->key = &__key; \ 56 } while (0) 57 #else 58 #define sysfs_attr_init(attr) do {} while (0) 59 #endif 60 61 /** 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 65 * a new subdirectory with this name. 66 * @is_visible: Optional: Function to return permissions associated with an 67 * attribute of the group. Will be called repeatedly for each 68 * non-binary attribute in the group. Only read/write 69 * permissions as well as SYSFS_PREALLOC are accepted. Must 70 * return 0 if an attribute is not visible. The returned value 71 * will replace static permissions defined in struct attribute. 72 * @is_bin_visible: 73 * Optional: Function to return permissions associated with a 74 * binary attribute of the group. Will be called repeatedly 75 * for each binary attribute in the group. Only read/write 76 * permissions as well as SYSFS_PREALLOC are accepted. Must 77 * return 0 if a binary attribute is not visible. The returned 78 * value will replace static permissions defined in 79 * struct bin_attribute. 80 * @attrs: Pointer to NULL terminated list of attributes. 81 * @bin_attrs: Pointer to NULL terminated list of binary attributes. 82 * Either attrs or bin_attrs or both must be provided. 83 */ 84 struct attribute_group { 85 const char *name; 86 umode_t (*is_visible)(struct kobject *, 87 struct attribute *, int); 88 umode_t (*is_bin_visible)(struct kobject *, 89 struct bin_attribute *, int); 90 struct attribute **attrs; 91 struct bin_attribute **bin_attrs; 92 }; 93 94 /* 95 * Use these macros to make defining attributes easier. 96 * See include/linux/device.h for examples.. 97 */ 98 99 #define SYSFS_PREALLOC 010000 100 101 #define __ATTR(_name, _mode, _show, _store) { \ 102 .attr = {.name = __stringify(_name), \ 103 .mode = VERIFY_OCTAL_PERMISSIONS(_mode) }, \ 104 .show = _show, \ 105 .store = _store, \ 106 } 107 108 #define __ATTR_PREALLOC(_name, _mode, _show, _store) { \ 109 .attr = {.name = __stringify(_name), \ 110 .mode = SYSFS_PREALLOC | VERIFY_OCTAL_PERMISSIONS(_mode) },\ 111 .show = _show, \ 112 .store = _store, \ 113 } 114 115 #define __ATTR_RO(_name) { \ 116 .attr = { .name = __stringify(_name), .mode = 0444 }, \ 117 .show = _name##_show, \ 118 } 119 120 #define __ATTR_RO_MODE(_name, _mode) { \ 121 .attr = { .name = __stringify(_name), \ 122 .mode = VERIFY_OCTAL_PERMISSIONS(_mode) }, \ 123 .show = _name##_show, \ 124 } 125 126 #define __ATTR_RW_MODE(_name, _mode) { \ 127 .attr = { .name = __stringify(_name), \ 128 .mode = VERIFY_OCTAL_PERMISSIONS(_mode) }, \ 129 .show = _name##_show, \ 130 .store = _name##_store, \ 131 } 132 133 #define __ATTR_WO(_name) { \ 134 .attr = { .name = __stringify(_name), .mode = 0200 }, \ 135 .store = _name##_store, \ 136 } 137 138 #define __ATTR_RW(_name) __ATTR(_name, 0644, _name##_show, _name##_store) 139 140 #define __ATTR_NULL { .attr = { .name = NULL } } 141 142 #ifdef CONFIG_DEBUG_LOCK_ALLOC 143 #define __ATTR_IGNORE_LOCKDEP(_name, _mode, _show, _store) { \ 144 .attr = {.name = __stringify(_name), .mode = _mode, \ 145 .ignore_lockdep = true }, \ 146 .show = _show, \ 147 .store = _store, \ 148 } 149 #else 150 #define __ATTR_IGNORE_LOCKDEP __ATTR 151 #endif 152 153 #define __ATTRIBUTE_GROUPS(_name) \ 154 static const struct attribute_group *_name##_groups[] = { \ 155 &_name##_group, \ 156 NULL, \ 157 } 158 159 #define ATTRIBUTE_GROUPS(_name) \ 160 static const struct attribute_group _name##_group = { \ 161 .attrs = _name##_attrs, \ 162 }; \ 163 __ATTRIBUTE_GROUPS(_name) 164 165 struct file; 166 struct vm_area_struct; 167 struct address_space; 168 169 struct bin_attribute { 170 struct attribute attr; 171 size_t size; 172 void *private; 173 struct address_space *mapping; 174 ssize_t (*read)(struct file *, struct kobject *, struct bin_attribute *, 175 char *, loff_t, size_t); 176 ssize_t (*write)(struct file *, struct kobject *, struct bin_attribute *, 177 char *, loff_t, size_t); 178 int (*mmap)(struct file *, struct kobject *, struct bin_attribute *attr, 179 struct vm_area_struct *vma); 180 }; 181 182 /** 183 * sysfs_bin_attr_init - initialize a dynamically allocated bin_attribute 184 * @attr: struct bin_attribute to initialize 185 * 186 * Initialize a dynamically allocated struct bin_attribute so we 187 * can make lockdep happy. This is a new requirement for 188 * attributes and initially this is only needed when lockdep is 189 * enabled. Lockdep gives a nice error when your attribute is 190 * added to sysfs if you don't have this. 191 */ 192 #define sysfs_bin_attr_init(bin_attr) sysfs_attr_init(&(bin_attr)->attr) 193 194 /* macros to create static binary attributes easier */ 195 #define __BIN_ATTR(_name, _mode, _read, _write, _size) { \ 196 .attr = { .name = __stringify(_name), .mode = _mode }, \ 197 .read = _read, \ 198 .write = _write, \ 199 .size = _size, \ 200 } 201 202 #define __BIN_ATTR_RO(_name, _size) { \ 203 .attr = { .name = __stringify(_name), .mode = 0444 }, \ 204 .read = _name##_read, \ 205 .size = _size, \ 206 } 207 208 #define __BIN_ATTR_WO(_name, _size) { \ 209 .attr = { .name = __stringify(_name), .mode = 0200 }, \ 210 .write = _name##_write, \ 211 .size = _size, \ 212 } 213 214 #define __BIN_ATTR_RW(_name, _size) \ 215 __BIN_ATTR(_name, 0644, _name##_read, _name##_write, _size) 216 217 #define __BIN_ATTR_NULL __ATTR_NULL 218 219 #define BIN_ATTR(_name, _mode, _read, _write, _size) \ 220 struct bin_attribute bin_attr_##_name = __BIN_ATTR(_name, _mode, _read, \ 221 _write, _size) 222 223 #define BIN_ATTR_RO(_name, _size) \ 224 struct bin_attribute bin_attr_##_name = __BIN_ATTR_RO(_name, _size) 225 226 #define BIN_ATTR_WO(_name, _size) \ 227 struct bin_attribute bin_attr_##_name = __BIN_ATTR_WO(_name, _size) 228 229 #define BIN_ATTR_RW(_name, _size) \ 230 struct bin_attribute bin_attr_##_name = __BIN_ATTR_RW(_name, _size) 231 232 struct sysfs_ops { 233 ssize_t (*show)(struct kobject *, struct attribute *, char *); 234 ssize_t (*store)(struct kobject *, struct attribute *, const char *, size_t); 235 }; 236 237 #ifdef CONFIG_SYSFS 238 239 int __must_check sysfs_create_dir_ns(struct kobject *kobj, const void *ns); 240 void sysfs_remove_dir(struct kobject *kobj); 241 int __must_check sysfs_rename_dir_ns(struct kobject *kobj, const char *new_name, 242 const void *new_ns); 243 int __must_check sysfs_move_dir_ns(struct kobject *kobj, 244 struct kobject *new_parent_kobj, 245 const void *new_ns); 246 int __must_check sysfs_create_mount_point(struct kobject *parent_kobj, 247 const char *name); 248 void sysfs_remove_mount_point(struct kobject *parent_kobj, 249 const char *name); 250 251 int __must_check sysfs_create_file_ns(struct kobject *kobj, 252 const struct attribute *attr, 253 const void *ns); 254 int __must_check sysfs_create_files(struct kobject *kobj, 255 const struct attribute * const *attr); 256 int __must_check sysfs_chmod_file(struct kobject *kobj, 257 const struct attribute *attr, umode_t mode); 258 struct kernfs_node *sysfs_break_active_protection(struct kobject *kobj, 259 const struct attribute *attr); 260 void sysfs_unbreak_active_protection(struct kernfs_node *kn); 261 void sysfs_remove_file_ns(struct kobject *kobj, const struct attribute *attr, 262 const void *ns); 263 bool sysfs_remove_file_self(struct kobject *kobj, const struct attribute *attr); 264 void sysfs_remove_files(struct kobject *kobj, const struct attribute * const *attr); 265 266 int __must_check sysfs_create_bin_file(struct kobject *kobj, 267 const struct bin_attribute *attr); 268 void sysfs_remove_bin_file(struct kobject *kobj, 269 const struct bin_attribute *attr); 270 271 int __must_check sysfs_create_link(struct kobject *kobj, struct kobject *target, 272 const char *name); 273 int __must_check sysfs_create_link_nowarn(struct kobject *kobj, 274 struct kobject *target, 275 const char *name); 276 void sysfs_remove_link(struct kobject *kobj, const char *name); 277 278 int sysfs_rename_link_ns(struct kobject *kobj, struct kobject *target, 279 const char *old_name, const char *new_name, 280 const void *new_ns); 281 282 void sysfs_delete_link(struct kobject *dir, struct kobject *targ, 283 const char *name); 284 285 int __must_check sysfs_create_group(struct kobject *kobj, 286 const struct attribute_group *grp); 287 int __must_check sysfs_create_groups(struct kobject *kobj, 288 const struct attribute_group **groups); 289 int __must_check sysfs_update_groups(struct kobject *kobj, 290 const struct attribute_group **groups); 291 int sysfs_update_group(struct kobject *kobj, 292 const struct attribute_group *grp); 293 void sysfs_remove_group(struct kobject *kobj, 294 const struct attribute_group *grp); 295 void sysfs_remove_groups(struct kobject *kobj, 296 const struct attribute_group **groups); 297 int sysfs_add_file_to_group(struct kobject *kobj, 298 const struct attribute *attr, const char *group); 299 void sysfs_remove_file_from_group(struct kobject *kobj, 300 const struct attribute *attr, const char *group); 301 int sysfs_merge_group(struct kobject *kobj, 302 const struct attribute_group *grp); 303 void sysfs_unmerge_group(struct kobject *kobj, 304 const struct attribute_group *grp); 305 int sysfs_add_link_to_group(struct kobject *kobj, const char *group_name, 306 struct kobject *target, const char *link_name); 307 void sysfs_remove_link_from_group(struct kobject *kobj, const char *group_name, 308 const char *link_name); 309 int compat_only_sysfs_link_entry_to_kobj(struct kobject *kobj, 310 struct kobject *target_kobj, 311 const char *target_name, 312 const char *symlink_name); 313 314 void sysfs_notify(struct kobject *kobj, const char *dir, const char *attr); 315 316 int __must_check sysfs_init(void); 317 318 static inline void sysfs_enable_ns(struct kernfs_node *kn) 319 { 320 return kernfs_enable_ns(kn); 321 } 322 323 int sysfs_file_change_owner(struct kobject *kobj, const char *name, kuid_t kuid, 324 kgid_t kgid); 325 int sysfs_change_owner(struct kobject *kobj, kuid_t kuid, kgid_t kgid); 326 int sysfs_link_change_owner(struct kobject *kobj, struct kobject *targ, 327 const char *name, kuid_t kuid, kgid_t kgid); 328 int sysfs_groups_change_owner(struct kobject *kobj, 329 const struct attribute_group **groups, 330 kuid_t kuid, kgid_t kgid); 331 int sysfs_group_change_owner(struct kobject *kobj, 332 const struct attribute_group *groups, kuid_t kuid, 333 kgid_t kgid); 334 __printf(2, 3) 335 int sysfs_emit(char *buf, const char *fmt, ...); 336 __printf(3, 4) 337 int sysfs_emit_at(char *buf, int at, const char *fmt, ...); 338 339 #else /* CONFIG_SYSFS */ 340 341 static inline int sysfs_create_dir_ns(struct kobject *kobj, const void *ns) 342 { 343 return 0; 344 } 345 346 static inline void sysfs_remove_dir(struct kobject *kobj) 347 { 348 } 349 350 static inline int sysfs_rename_dir_ns(struct kobject *kobj, 351 const char *new_name, const void *new_ns) 352 { 353 return 0; 354 } 355 356 static inline int sysfs_move_dir_ns(struct kobject *kobj, 357 struct kobject *new_parent_kobj, 358 const void *new_ns) 359 { 360 return 0; 361 } 362 363 static inline int sysfs_create_mount_point(struct kobject *parent_kobj, 364 const char *name) 365 { 366 return 0; 367 } 368 369 static inline void sysfs_remove_mount_point(struct kobject *parent_kobj, 370 const char *name) 371 { 372 } 373 374 static inline int sysfs_create_file_ns(struct kobject *kobj, 375 const struct attribute *attr, 376 const void *ns) 377 { 378 return 0; 379 } 380 381 static inline int sysfs_create_files(struct kobject *kobj, 382 const struct attribute * const *attr) 383 { 384 return 0; 385 } 386 387 static inline int sysfs_chmod_file(struct kobject *kobj, 388 const struct attribute *attr, umode_t mode) 389 { 390 return 0; 391 } 392 393 static inline struct kernfs_node * 394 sysfs_break_active_protection(struct kobject *kobj, 395 const struct attribute *attr) 396 { 397 return NULL; 398 } 399 400 static inline void sysfs_unbreak_active_protection(struct kernfs_node *kn) 401 { 402 } 403 404 static inline void sysfs_remove_file_ns(struct kobject *kobj, 405 const struct attribute *attr, 406 const void *ns) 407 { 408 } 409 410 static inline bool sysfs_remove_file_self(struct kobject *kobj, 411 const struct attribute *attr) 412 { 413 return false; 414 } 415 416 static inline void sysfs_remove_files(struct kobject *kobj, 417 const struct attribute * const *attr) 418 { 419 } 420 421 static inline int sysfs_create_bin_file(struct kobject *kobj, 422 const struct bin_attribute *attr) 423 { 424 return 0; 425 } 426 427 static inline void sysfs_remove_bin_file(struct kobject *kobj, 428 const struct bin_attribute *attr) 429 { 430 } 431 432 static inline int sysfs_create_link(struct kobject *kobj, 433 struct kobject *target, const char *name) 434 { 435 return 0; 436 } 437 438 static inline int sysfs_create_link_nowarn(struct kobject *kobj, 439 struct kobject *target, 440 const char *name) 441 { 442 return 0; 443 } 444 445 static inline void sysfs_remove_link(struct kobject *kobj, const char *name) 446 { 447 } 448 449 static inline int sysfs_rename_link_ns(struct kobject *k, struct kobject *t, 450 const char *old_name, 451 const char *new_name, const void *ns) 452 { 453 return 0; 454 } 455 456 static inline void sysfs_delete_link(struct kobject *k, struct kobject *t, 457 const char *name) 458 { 459 } 460 461 static inline int sysfs_create_group(struct kobject *kobj, 462 const struct attribute_group *grp) 463 { 464 return 0; 465 } 466 467 static inline int sysfs_create_groups(struct kobject *kobj, 468 const struct attribute_group **groups) 469 { 470 return 0; 471 } 472 473 static inline int sysfs_update_groups(struct kobject *kobj, 474 const struct attribute_group **groups) 475 { 476 return 0; 477 } 478 479 static inline int sysfs_update_group(struct kobject *kobj, 480 const struct attribute_group *grp) 481 { 482 return 0; 483 } 484 485 static inline void sysfs_remove_group(struct kobject *kobj, 486 const struct attribute_group *grp) 487 { 488 } 489 490 static inline void sysfs_remove_groups(struct kobject *kobj, 491 const struct attribute_group **groups) 492 { 493 } 494 495 static inline int sysfs_add_file_to_group(struct kobject *kobj, 496 const struct attribute *attr, const char *group) 497 { 498 return 0; 499 } 500 501 static inline void sysfs_remove_file_from_group(struct kobject *kobj, 502 const struct attribute *attr, const char *group) 503 { 504 } 505 506 static inline int sysfs_merge_group(struct kobject *kobj, 507 const struct attribute_group *grp) 508 { 509 return 0; 510 } 511 512 static inline void sysfs_unmerge_group(struct kobject *kobj, 513 const struct attribute_group *grp) 514 { 515 } 516 517 static inline int sysfs_add_link_to_group(struct kobject *kobj, 518 const char *group_name, struct kobject *target, 519 const char *link_name) 520 { 521 return 0; 522 } 523 524 static inline void sysfs_remove_link_from_group(struct kobject *kobj, 525 const char *group_name, const char *link_name) 526 { 527 } 528 529 static inline int compat_only_sysfs_link_entry_to_kobj(struct kobject *kobj, 530 struct kobject *target_kobj, 531 const char *target_name, 532 const char *symlink_name) 533 { 534 return 0; 535 } 536 537 static inline void sysfs_notify(struct kobject *kobj, const char *dir, 538 const char *attr) 539 { 540 } 541 542 static inline int __must_check sysfs_init(void) 543 { 544 return 0; 545 } 546 547 static inline void sysfs_enable_ns(struct kernfs_node *kn) 548 { 549 } 550 551 static inline int sysfs_file_change_owner(struct kobject *kobj, 552 const char *name, kuid_t kuid, 553 kgid_t kgid) 554 { 555 return 0; 556 } 557 558 static inline int sysfs_link_change_owner(struct kobject *kobj, 559 struct kobject *targ, 560 const char *name, kuid_t kuid, 561 kgid_t kgid) 562 { 563 return 0; 564 } 565 566 static inline int sysfs_change_owner(struct kobject *kobj, kuid_t kuid, kgid_t kgid) 567 { 568 return 0; 569 } 570 571 static inline int sysfs_groups_change_owner(struct kobject *kobj, 572 const struct attribute_group **groups, 573 kuid_t kuid, kgid_t kgid) 574 { 575 return 0; 576 } 577 578 static inline int sysfs_group_change_owner(struct kobject *kobj, 579 const struct attribute_group *groups, 580 kuid_t kuid, kgid_t kgid) 581 { 582 return 0; 583 } 584 585 __printf(2, 3) 586 static inline int sysfs_emit(char *buf, const char *fmt, ...) 587 { 588 return 0; 589 } 590 591 __printf(3, 4) 592 static inline int sysfs_emit_at(char *buf, int at, const char *fmt, ...) 593 { 594 return 0; 595 } 596 #endif /* CONFIG_SYSFS */ 597 598 static inline int __must_check sysfs_create_file(struct kobject *kobj, 599 const struct attribute *attr) 600 { 601 return sysfs_create_file_ns(kobj, attr, NULL); 602 } 603 604 static inline void sysfs_remove_file(struct kobject *kobj, 605 const struct attribute *attr) 606 { 607 sysfs_remove_file_ns(kobj, attr, NULL); 608 } 609 610 static inline int sysfs_rename_link(struct kobject *kobj, struct kobject *target, 611 const char *old_name, const char *new_name) 612 { 613 return sysfs_rename_link_ns(kobj, target, old_name, new_name, NULL); 614 } 615 616 static inline void sysfs_notify_dirent(struct kernfs_node *kn) 617 { 618 kernfs_notify(kn); 619 } 620 621 static inline struct kernfs_node *sysfs_get_dirent(struct kernfs_node *parent, 622 const char *name) 623 { 624 return kernfs_find_and_get(parent, name); 625 } 626 627 static inline struct kernfs_node *sysfs_get(struct kernfs_node *kn) 628 { 629 kernfs_get(kn); 630 return kn; 631 } 632 633 static inline void sysfs_put(struct kernfs_node *kn) 634 { 635 kernfs_put(kn); 636 } 637 638 #endif /* _SYSFS_H_ */ 639