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 168 struct bin_attribute { 169 struct attribute attr; 170 size_t size; 171 void *private; 172 ssize_t (*read)(struct file *, struct kobject *, struct bin_attribute *, 173 char *, loff_t, size_t); 174 ssize_t (*write)(struct file *, struct kobject *, struct bin_attribute *, 175 char *, loff_t, size_t); 176 int (*mmap)(struct file *, struct kobject *, struct bin_attribute *attr, 177 struct vm_area_struct *vma); 178 }; 179 180 /** 181 * sysfs_bin_attr_init - initialize a dynamically allocated bin_attribute 182 * @attr: struct bin_attribute to initialize 183 * 184 * Initialize a dynamically allocated struct bin_attribute so we 185 * can make lockdep happy. This is a new requirement for 186 * attributes and initially this is only needed when lockdep is 187 * enabled. Lockdep gives a nice error when your attribute is 188 * added to sysfs if you don't have this. 189 */ 190 #define sysfs_bin_attr_init(bin_attr) sysfs_attr_init(&(bin_attr)->attr) 191 192 /* macros to create static binary attributes easier */ 193 #define __BIN_ATTR(_name, _mode, _read, _write, _size) { \ 194 .attr = { .name = __stringify(_name), .mode = _mode }, \ 195 .read = _read, \ 196 .write = _write, \ 197 .size = _size, \ 198 } 199 200 #define __BIN_ATTR_RO(_name, _size) { \ 201 .attr = { .name = __stringify(_name), .mode = 0444 }, \ 202 .read = _name##_read, \ 203 .size = _size, \ 204 } 205 206 #define __BIN_ATTR_WO(_name, _size) { \ 207 .attr = { .name = __stringify(_name), .mode = 0200 }, \ 208 .write = _name##_write, \ 209 .size = _size, \ 210 } 211 212 #define __BIN_ATTR_RW(_name, _size) \ 213 __BIN_ATTR(_name, 0644, _name##_read, _name##_write, _size) 214 215 #define __BIN_ATTR_NULL __ATTR_NULL 216 217 #define BIN_ATTR(_name, _mode, _read, _write, _size) \ 218 struct bin_attribute bin_attr_##_name = __BIN_ATTR(_name, _mode, _read, \ 219 _write, _size) 220 221 #define BIN_ATTR_RO(_name, _size) \ 222 struct bin_attribute bin_attr_##_name = __BIN_ATTR_RO(_name, _size) 223 224 #define BIN_ATTR_WO(_name, _size) \ 225 struct bin_attribute bin_attr_##_name = __BIN_ATTR_WO(_name, _size) 226 227 #define BIN_ATTR_RW(_name, _size) \ 228 struct bin_attribute bin_attr_##_name = __BIN_ATTR_RW(_name, _size) 229 230 struct sysfs_ops { 231 ssize_t (*show)(struct kobject *, struct attribute *, char *); 232 ssize_t (*store)(struct kobject *, struct attribute *, const char *, size_t); 233 }; 234 235 #ifdef CONFIG_SYSFS 236 237 int __must_check sysfs_create_dir_ns(struct kobject *kobj, const void *ns); 238 void sysfs_remove_dir(struct kobject *kobj); 239 int __must_check sysfs_rename_dir_ns(struct kobject *kobj, const char *new_name, 240 const void *new_ns); 241 int __must_check sysfs_move_dir_ns(struct kobject *kobj, 242 struct kobject *new_parent_kobj, 243 const void *new_ns); 244 int __must_check sysfs_create_mount_point(struct kobject *parent_kobj, 245 const char *name); 246 void sysfs_remove_mount_point(struct kobject *parent_kobj, 247 const char *name); 248 249 int __must_check sysfs_create_file_ns(struct kobject *kobj, 250 const struct attribute *attr, 251 const void *ns); 252 int __must_check sysfs_create_files(struct kobject *kobj, 253 const struct attribute * const *attr); 254 int __must_check sysfs_chmod_file(struct kobject *kobj, 255 const struct attribute *attr, umode_t mode); 256 struct kernfs_node *sysfs_break_active_protection(struct kobject *kobj, 257 const struct attribute *attr); 258 void sysfs_unbreak_active_protection(struct kernfs_node *kn); 259 void sysfs_remove_file_ns(struct kobject *kobj, const struct attribute *attr, 260 const void *ns); 261 bool sysfs_remove_file_self(struct kobject *kobj, const struct attribute *attr); 262 void sysfs_remove_files(struct kobject *kobj, const struct attribute * const *attr); 263 264 int __must_check sysfs_create_bin_file(struct kobject *kobj, 265 const struct bin_attribute *attr); 266 void sysfs_remove_bin_file(struct kobject *kobj, 267 const struct bin_attribute *attr); 268 269 int __must_check sysfs_create_link(struct kobject *kobj, struct kobject *target, 270 const char *name); 271 int __must_check sysfs_create_link_nowarn(struct kobject *kobj, 272 struct kobject *target, 273 const char *name); 274 void sysfs_remove_link(struct kobject *kobj, const char *name); 275 276 int sysfs_rename_link_ns(struct kobject *kobj, struct kobject *target, 277 const char *old_name, const char *new_name, 278 const void *new_ns); 279 280 void sysfs_delete_link(struct kobject *dir, struct kobject *targ, 281 const char *name); 282 283 int __must_check sysfs_create_group(struct kobject *kobj, 284 const struct attribute_group *grp); 285 int __must_check sysfs_create_groups(struct kobject *kobj, 286 const struct attribute_group **groups); 287 int __must_check sysfs_update_groups(struct kobject *kobj, 288 const struct attribute_group **groups); 289 int sysfs_update_group(struct kobject *kobj, 290 const struct attribute_group *grp); 291 void sysfs_remove_group(struct kobject *kobj, 292 const struct attribute_group *grp); 293 void sysfs_remove_groups(struct kobject *kobj, 294 const struct attribute_group **groups); 295 int sysfs_add_file_to_group(struct kobject *kobj, 296 const struct attribute *attr, const char *group); 297 void sysfs_remove_file_from_group(struct kobject *kobj, 298 const struct attribute *attr, const char *group); 299 int sysfs_merge_group(struct kobject *kobj, 300 const struct attribute_group *grp); 301 void sysfs_unmerge_group(struct kobject *kobj, 302 const struct attribute_group *grp); 303 int sysfs_add_link_to_group(struct kobject *kobj, const char *group_name, 304 struct kobject *target, const char *link_name); 305 void sysfs_remove_link_from_group(struct kobject *kobj, const char *group_name, 306 const char *link_name); 307 int compat_only_sysfs_link_entry_to_kobj(struct kobject *kobj, 308 struct kobject *target_kobj, 309 const char *target_name, 310 const char *symlink_name); 311 312 void sysfs_notify(struct kobject *kobj, const char *dir, const char *attr); 313 314 int __must_check sysfs_init(void); 315 316 static inline void sysfs_enable_ns(struct kernfs_node *kn) 317 { 318 return kernfs_enable_ns(kn); 319 } 320 321 int sysfs_file_change_owner(struct kobject *kobj, const char *name, kuid_t kuid, 322 kgid_t kgid); 323 int sysfs_change_owner(struct kobject *kobj, kuid_t kuid, kgid_t kgid); 324 int sysfs_link_change_owner(struct kobject *kobj, struct kobject *targ, 325 const char *name, kuid_t kuid, kgid_t kgid); 326 int sysfs_groups_change_owner(struct kobject *kobj, 327 const struct attribute_group **groups, 328 kuid_t kuid, kgid_t kgid); 329 int sysfs_group_change_owner(struct kobject *kobj, 330 const struct attribute_group *groups, kuid_t kuid, 331 kgid_t kgid); 332 __printf(2, 3) 333 int sysfs_emit(char *buf, const char *fmt, ...); 334 __printf(3, 4) 335 int sysfs_emit_at(char *buf, int at, const char *fmt, ...); 336 337 #else /* CONFIG_SYSFS */ 338 339 static inline int sysfs_create_dir_ns(struct kobject *kobj, const void *ns) 340 { 341 return 0; 342 } 343 344 static inline void sysfs_remove_dir(struct kobject *kobj) 345 { 346 } 347 348 static inline int sysfs_rename_dir_ns(struct kobject *kobj, 349 const char *new_name, const void *new_ns) 350 { 351 return 0; 352 } 353 354 static inline int sysfs_move_dir_ns(struct kobject *kobj, 355 struct kobject *new_parent_kobj, 356 const void *new_ns) 357 { 358 return 0; 359 } 360 361 static inline int sysfs_create_mount_point(struct kobject *parent_kobj, 362 const char *name) 363 { 364 return 0; 365 } 366 367 static inline void sysfs_remove_mount_point(struct kobject *parent_kobj, 368 const char *name) 369 { 370 } 371 372 static inline int sysfs_create_file_ns(struct kobject *kobj, 373 const struct attribute *attr, 374 const void *ns) 375 { 376 return 0; 377 } 378 379 static inline int sysfs_create_files(struct kobject *kobj, 380 const struct attribute * const *attr) 381 { 382 return 0; 383 } 384 385 static inline int sysfs_chmod_file(struct kobject *kobj, 386 const struct attribute *attr, umode_t mode) 387 { 388 return 0; 389 } 390 391 static inline struct kernfs_node * 392 sysfs_break_active_protection(struct kobject *kobj, 393 const struct attribute *attr) 394 { 395 return NULL; 396 } 397 398 static inline void sysfs_unbreak_active_protection(struct kernfs_node *kn) 399 { 400 } 401 402 static inline void sysfs_remove_file_ns(struct kobject *kobj, 403 const struct attribute *attr, 404 const void *ns) 405 { 406 } 407 408 static inline bool sysfs_remove_file_self(struct kobject *kobj, 409 const struct attribute *attr) 410 { 411 return false; 412 } 413 414 static inline void sysfs_remove_files(struct kobject *kobj, 415 const struct attribute * const *attr) 416 { 417 } 418 419 static inline int sysfs_create_bin_file(struct kobject *kobj, 420 const struct bin_attribute *attr) 421 { 422 return 0; 423 } 424 425 static inline void sysfs_remove_bin_file(struct kobject *kobj, 426 const struct bin_attribute *attr) 427 { 428 } 429 430 static inline int sysfs_create_link(struct kobject *kobj, 431 struct kobject *target, const char *name) 432 { 433 return 0; 434 } 435 436 static inline int sysfs_create_link_nowarn(struct kobject *kobj, 437 struct kobject *target, 438 const char *name) 439 { 440 return 0; 441 } 442 443 static inline void sysfs_remove_link(struct kobject *kobj, const char *name) 444 { 445 } 446 447 static inline int sysfs_rename_link_ns(struct kobject *k, struct kobject *t, 448 const char *old_name, 449 const char *new_name, const void *ns) 450 { 451 return 0; 452 } 453 454 static inline void sysfs_delete_link(struct kobject *k, struct kobject *t, 455 const char *name) 456 { 457 } 458 459 static inline int sysfs_create_group(struct kobject *kobj, 460 const struct attribute_group *grp) 461 { 462 return 0; 463 } 464 465 static inline int sysfs_create_groups(struct kobject *kobj, 466 const struct attribute_group **groups) 467 { 468 return 0; 469 } 470 471 static inline int sysfs_update_groups(struct kobject *kobj, 472 const struct attribute_group **groups) 473 { 474 return 0; 475 } 476 477 static inline int sysfs_update_group(struct kobject *kobj, 478 const struct attribute_group *grp) 479 { 480 return 0; 481 } 482 483 static inline void sysfs_remove_group(struct kobject *kobj, 484 const struct attribute_group *grp) 485 { 486 } 487 488 static inline void sysfs_remove_groups(struct kobject *kobj, 489 const struct attribute_group **groups) 490 { 491 } 492 493 static inline int sysfs_add_file_to_group(struct kobject *kobj, 494 const struct attribute *attr, const char *group) 495 { 496 return 0; 497 } 498 499 static inline void sysfs_remove_file_from_group(struct kobject *kobj, 500 const struct attribute *attr, const char *group) 501 { 502 } 503 504 static inline int sysfs_merge_group(struct kobject *kobj, 505 const struct attribute_group *grp) 506 { 507 return 0; 508 } 509 510 static inline void sysfs_unmerge_group(struct kobject *kobj, 511 const struct attribute_group *grp) 512 { 513 } 514 515 static inline int sysfs_add_link_to_group(struct kobject *kobj, 516 const char *group_name, struct kobject *target, 517 const char *link_name) 518 { 519 return 0; 520 } 521 522 static inline void sysfs_remove_link_from_group(struct kobject *kobj, 523 const char *group_name, const char *link_name) 524 { 525 } 526 527 static inline int compat_only_sysfs_link_entry_to_kobj(struct kobject *kobj, 528 struct kobject *target_kobj, 529 const char *target_name, 530 const char *symlink_name) 531 { 532 return 0; 533 } 534 535 static inline void sysfs_notify(struct kobject *kobj, const char *dir, 536 const char *attr) 537 { 538 } 539 540 static inline int __must_check sysfs_init(void) 541 { 542 return 0; 543 } 544 545 static inline void sysfs_enable_ns(struct kernfs_node *kn) 546 { 547 } 548 549 static inline int sysfs_file_change_owner(struct kobject *kobj, 550 const char *name, kuid_t kuid, 551 kgid_t kgid) 552 { 553 return 0; 554 } 555 556 static inline int sysfs_link_change_owner(struct kobject *kobj, 557 struct kobject *targ, 558 const char *name, kuid_t kuid, 559 kgid_t kgid) 560 { 561 return 0; 562 } 563 564 static inline int sysfs_change_owner(struct kobject *kobj, kuid_t kuid, kgid_t kgid) 565 { 566 return 0; 567 } 568 569 static inline int sysfs_groups_change_owner(struct kobject *kobj, 570 const struct attribute_group **groups, 571 kuid_t kuid, kgid_t kgid) 572 { 573 return 0; 574 } 575 576 static inline int sysfs_group_change_owner(struct kobject *kobj, 577 const struct attribute_group *groups, 578 kuid_t kuid, kgid_t kgid) 579 { 580 return 0; 581 } 582 583 __printf(2, 3) 584 static inline int sysfs_emit(char *buf, const char *fmt, ...) 585 { 586 return 0; 587 } 588 589 __printf(3, 4) 590 static inline int sysfs_emit_at(char *buf, int at, const char *fmt, ...) 591 { 592 return 0; 593 } 594 #endif /* CONFIG_SYSFS */ 595 596 static inline int __must_check sysfs_create_file(struct kobject *kobj, 597 const struct attribute *attr) 598 { 599 return sysfs_create_file_ns(kobj, attr, NULL); 600 } 601 602 static inline void sysfs_remove_file(struct kobject *kobj, 603 const struct attribute *attr) 604 { 605 sysfs_remove_file_ns(kobj, attr, NULL); 606 } 607 608 static inline int sysfs_rename_link(struct kobject *kobj, struct kobject *target, 609 const char *old_name, const char *new_name) 610 { 611 return sysfs_rename_link_ns(kobj, target, old_name, new_name, NULL); 612 } 613 614 static inline void sysfs_notify_dirent(struct kernfs_node *kn) 615 { 616 kernfs_notify(kn); 617 } 618 619 static inline struct kernfs_node *sysfs_get_dirent(struct kernfs_node *parent, 620 const char *name) 621 { 622 return kernfs_find_and_get(parent, name); 623 } 624 625 static inline struct kernfs_node *sysfs_get(struct kernfs_node *kn) 626 { 627 kernfs_get(kn); 628 return kn; 629 } 630 631 static inline void sysfs_put(struct kernfs_node *kn) 632 { 633 kernfs_put(kn); 634 } 635 636 #endif /* _SYSFS_H_ */ 637