drivers/base/class.c

   1 // SPDX-License-Identifier: GPL-2.0
   2 /*
   3  * class.c - basic device class management
   4  *
   5  * Copyright (c) 2002-3 Patrick Mochel
   6  * Copyright (c) 2002-3 Open Source Development Labs
   7  * Copyright (c) 2003-2004 Greg Kroah-Hartman
   8  * Copyright (c) 2003-2004 IBM Corp.
   9  *
  10  * This file is released under the GPLv2
  11  *
  12  */
  13
  14 #include <linux/device.h>
  15 #include <linux/module.h>
  16 #include <linux/init.h>
  17 #include <linux/string.h>
  18 #include <linux/kdev_t.h>
  19 #include <linux/err.h>
  20 #include <linux/slab.h>
  21 #include <linux/genhd.h>
  22 #include <linux/mutex.h>
  23 #include "base.h"
  24
  25 #define to_class_attr(_attr) container_of(_attr, struct class_attribute, attr)
  26
  27 static ssize_t class_attr_show(struct kobject *kobj, struct attribute *attr,
  28                                char *buf)
  29 {
  30         struct class_attribute *class_attr = to_class_attr(attr);
  31         struct subsys_private *cp = to_subsys_private(kobj);
  32         ssize_t ret = -EIO;
  33
  34         if (class_attr->show)
  35                 ret = class_attr->show(cp->class, class_attr, buf);
  36         return ret;
  37 }
  38
  39 static ssize_t class_attr_store(struct kobject *kobj, struct attribute *attr,
  40                                 const char *buf, size_t count)
  41 {
  42         struct class_attribute *class_attr = to_class_attr(attr);
  43         struct subsys_private *cp = to_subsys_private(kobj);
  44         ssize_t ret = -EIO;
  45
  46         if (class_attr->store)
  47                 ret = class_attr->store(cp->class, class_attr, buf, count);
  48         return ret;
  49 }
  50
  51 static void class_release(struct kobject *kobj)
  52 {
  53         struct subsys_private *cp = to_subsys_private(kobj);
  54         struct class *class = cp->class;
  55
  56         pr_debug("class '%s': release.\n", class->name);
  57
  58         if (class->class_release)
  59                 class->class_release(class);
  60         else
  61                 pr_debug("class '%s' does not have a release() function, "
  62                          "be careful\n", class->name);
  63
  64         kfree(cp);
  65 }
  66
  67 static const struct kobj_ns_type_operations *class_child_ns_type(struct kobject *kobj)
  68 {
  69         struct subsys_private *cp = to_subsys_private(kobj);
  70         struct class *class = cp->class;
  71
  72         return class->ns_type;
  73 }
  74
  75 static const struct sysfs_ops class_sysfs_ops = {
  76         .show      = class_attr_show,
  77         .store     = class_attr_store,
  78 };
  79
  80 static struct kobj_type class_ktype = {
  81         .sysfs_ops      = &class_sysfs_ops,
  82         .release        = class_release,
  83         .child_ns_type  = class_child_ns_type,
  84 };
  85
  86 /* Hotplug events for classes go to the class subsys */
  87 static struct kset *class_kset;
  88
  89
  90 int class_create_file_ns(struct class *cls, const struct class_attribute *attr,
  91                          const void *ns)
  92 {
  93         int error;
  94
  95         if (cls)
  96                 error = sysfs_create_file_ns(&cls->p->subsys.kobj,
  97                                              &attr->attr, ns);
  98         else
  99                 error = -EINVAL;
 100         return error;
 101 }
 102
 103 void class_remove_file_ns(struct class *cls, const struct class_attribute *attr,
 104                           const void *ns)
 105 {
 106         if (cls)
 107                 sysfs_remove_file_ns(&cls->p->subsys.kobj, &attr->attr, ns);
 108 }
 109
 110 static struct class *class_get(struct class *cls)
 111 {
 112         if (cls)
 113                 kset_get(&cls->p->subsys);
 114         return cls;
 115 }
 116
 117 static void class_put(struct class *cls)
 118 {
 119         if (cls)
 120                 kset_put(&cls->p->subsys);
 121 }
 122
 123 static void klist_class_dev_get(struct klist_node *n)
 124 {
 125         struct device *dev = container_of(n, struct device, knode_class);
 126
 127         get_device(dev);
 128 }
 129
 130 static void klist_class_dev_put(struct klist_node *n)
 131 {
 132         struct device *dev = container_of(n, struct device, knode_class);
 133
 134         put_device(dev);
 135 }
 136
 137 static int class_add_groups(struct class *cls,
 138                             const struct attribute_group **groups)
 139 {
 140         return sysfs_create_groups(&cls->p->subsys.kobj, groups);
 141 }
 142
 143 static void class_remove_groups(struct class *cls,
 144                                 const struct attribute_group **groups)
 145 {
 146         return sysfs_remove_groups(&cls->p->subsys.kobj, groups);
 147 }
 148
 149 int __class_register(struct class *cls, struct lock_class_key *key)
 150 {
 151         struct subsys_private *cp;
 152         int error;
 153
 154         pr_debug("device class '%s': registering\n", cls->name);
 155
 156         cp = kzalloc(sizeof(*cp), GFP_KERNEL);
 157         if (!cp)
 158                 return -ENOMEM;
 159         klist_init(&cp->klist_devices, klist_class_dev_get, klist_class_dev_put);
 160         INIT_LIST_HEAD(&cp->interfaces);
 161         kset_init(&cp->glue_dirs);
 162         __mutex_init(&cp->mutex, "subsys mutex", key);
 163         error = kobject_set_name(&cp->subsys.kobj, "%s", cls->name);
 164         if (error) {
 165                 kfree(cp);
 166                 return error;
 167         }
 168
 169         /* set the default /sys/dev directory for devices of this class */
 170         if (!cls->dev_kobj)
 171                 cls->dev_kobj = sysfs_dev_char_kobj;
 172
 173 #if defined(CONFIG_BLOCK)
 174         /* let the block class directory show up in the root of sysfs */
 175         if (!sysfs_deprecated || cls != &block_class)
 176                 cp->subsys.kobj.kset = class_kset;
 177 #else
 178         cp->subsys.kobj.kset = class_kset;
 179 #endif
 180         cp->subsys.kobj.ktype = &class_ktype;
 181         cp->class = cls;
 182         cls->p = cp;
 183
 184         error = kset_register(&cp->subsys);
 185         if (error) {
 186                 kfree(cp);
 187                 return error;
 188         }
 189         error = class_add_groups(class_get(cls), cls->class_groups);
 190         class_put(cls);
 191         return error;
 192 }
 193 EXPORT_SYMBOL_GPL(__class_register);
 194
 195 void class_unregister(struct class *cls)
 196 {
 197         pr_debug("device class '%s': unregistering\n", cls->name);
 198         class_remove_groups(cls, cls->class_groups);
 199         kset_unregister(&cls->p->subsys);
 200 }
 201
 202 static void class_create_release(struct class *cls)
 203 {
 204         pr_debug("%s called for %s\n", __func__, cls->name);
 205         kfree(cls);
 206 }
 207
 208 /**
 209  * class_create - create a struct class structure
 210  * @owner: pointer to the module that is to "own" this struct class
 211  * @name: pointer to a string for the name of this class.
 212  * @key: the lock_class_key for this class; used by mutex lock debugging
 213  *
 214  * This is used to create a struct class pointer that can then be used
 215  * in calls to device_create().
 216  *
 217  * Returns &struct class pointer on success, or ERR_PTR() on error.
 218  *
 219  * Note, the pointer created here is to be destroyed when finished by
 220  * making a call to class_destroy().
 221  */
 222 struct class *__class_create(struct module *owner, const char *name,
 223                              struct lock_class_key *key)
 224 {
 225         struct class *cls;
 226         int retval;
 227
 228         cls = kzalloc(sizeof(*cls), GFP_KERNEL);
 229         if (!cls) {
 230                 retval = -ENOMEM;
 231                 goto error;
 232         }
 233
 234         cls->name = name;
 235         cls->owner = owner;
 236         cls->class_release = class_create_release;
 237
 238         retval = __class_register(cls, key);
 239         if (retval)
 240                 goto error;
 241
 242         return cls;
 243
 244 error:
 245         kfree(cls);
 246         return ERR_PTR(retval);
 247 }
 248 EXPORT_SYMBOL_GPL(__class_create);
 249
 250 /**
 251  * class_destroy - destroys a struct class structure
 252  * @cls: pointer to the struct class that is to be destroyed
 253  *
 254  * Note, the pointer to be destroyed must have been created with a call
 255  * to class_create().
 256  */
 257 void class_destroy(struct class *cls)
 258 {
 259         if ((cls == NULL) || (IS_ERR(cls)))
 260                 return;
 261
 262         class_unregister(cls);
 263 }
 264
 265 /**
 266  * class_dev_iter_init - initialize class device iterator
 267  * @iter: class iterator to initialize
 268  * @class: the class we wanna iterate over
 269  * @start: the device to start iterating from, if any
 270  * @type: device_type of the devices to iterate over, NULL for all
 271  *
 272  * Initialize class iterator @iter such that it iterates over devices
 273  * of @class.  If @start is set, the list iteration will start there,
 274  * otherwise if it is NULL, the iteration starts at the beginning of
 275  * the list.
 276  */
 277 void class_dev_iter_init(struct class_dev_iter *iter, struct class *class,
 278                          struct device *start, const struct device_type *type)
 279 {
 280         struct klist_node *start_knode = NULL;
 281
 282         if (start)
 283                 start_knode = &start->knode_class;
 284         klist_iter_init_node(&class->p->klist_devices, &iter->ki, start_knode);
 285         iter->type = type;
 286 }
 287 EXPORT_SYMBOL_GPL(class_dev_iter_init);
 288
 289 /**
 290  * class_dev_iter_next - iterate to the next device
 291  * @iter: class iterator to proceed
 292  *
 293  * Proceed @iter to the next device and return it.  Returns NULL if
 294  * iteration is complete.
 295  *
 296  * The returned device is referenced and won't be released till
 297  * iterator is proceed to the next device or exited.  The caller is
 298  * free to do whatever it wants to do with the device including
 299  * calling back into class code.
 300  */
 301 struct device *class_dev_iter_next(struct class_dev_iter *iter)
 302 {
 303         struct klist_node *knode;
 304         struct device *dev;
 305
 306         while (1) {
 307                 knode = klist_next(&iter->ki);
 308                 if (!knode)
 309                         return NULL;
 310                 dev = container_of(knode, struct device, knode_class);
 311                 if (!iter->type || iter->type == dev->type)
 312                         return dev;
 313         }
 314 }
 315 EXPORT_SYMBOL_GPL(class_dev_iter_next);
 316
 317 /**
 318  * class_dev_iter_exit - finish iteration
 319  * @iter: class iterator to finish
 320  *
 321  * Finish an iteration.  Always call this function after iteration is
 322  * complete whether the iteration ran till the end or not.
 323  */
 324 void class_dev_iter_exit(struct class_dev_iter *iter)
 325 {
 326         klist_iter_exit(&iter->ki);
 327 }
 328 EXPORT_SYMBOL_GPL(class_dev_iter_exit);
 329
 330 /**
 331  * class_for_each_device - device iterator
 332  * @class: the class we're iterating
 333  * @start: the device to start with in the list, if any.
 334  * @data: data for the callback
 335  * @fn: function to be called for each device
 336  *
 337  * Iterate over @class's list of devices, and call @fn for each,
 338  * passing it @data.  If @start is set, the list iteration will start
 339  * there, otherwise if it is NULL, the iteration starts at the
 340  * beginning of the list.
 341  *
 342  * We check the return of @fn each time. If it returns anything
 343  * other than 0, we break out and return that value.
 344  *
 345  * @fn is allowed to do anything including calling back into class
 346  * code.  There's no locking restriction.
 347  */
 348 int class_for_each_device(struct class *class, struct device *start,
 349                           void *data, int (*fn)(struct device *, void *))
 350 {
 351         struct class_dev_iter iter;
 352         struct device *dev;
 353         int error = 0;
 354
 355         if (!class)
 356                 return -EINVAL;
 357         if (!class->p) {
 358                 WARN(1, "%s called for class '%s' before it was initialized",
 359                      __func__, class->name);
 360                 return -EINVAL;
 361         }
 362
 363         class_dev_iter_init(&iter, class, start, NULL);
 364         while ((dev = class_dev_iter_next(&iter))) {
 365                 error = fn(dev, data);
 366                 if (error)
 367                         break;
 368         }
 369         class_dev_iter_exit(&iter);
 370
 371         return error;
 372 }
 373 EXPORT_SYMBOL_GPL(class_for_each_device);
 374
 375 /**
 376  * class_find_device - device iterator for locating a particular device
 377  * @class: the class we're iterating
 378  * @start: Device to begin with
 379  * @data: data for the match function
 380  * @match: function to check device
 381  *
 382  * This is similar to the class_for_each_dev() function above, but it
 383  * returns a reference to a device that is 'found' for later use, as
 384  * determined by the @match callback.
 385  *
 386  * The callback should return 0 if the device doesn't match and non-zero
 387  * if it does.  If the callback returns non-zero, this function will
 388  * return to the caller and not iterate over any more devices.
 389  *
 390  * Note, you will need to drop the reference with put_device() after use.
 391  *
 392  * @match is allowed to do anything including calling back into class
 393  * code.  There's no locking restriction.
 394  */
 395 struct device *class_find_device(struct class *class, struct device *start,
 396                                  const void *data,
 397                                  int (*match)(struct device *, const void *))
 398 {
 399         struct class_dev_iter iter;
 400         struct device *dev;
 401
 402         if (!class)
 403                 return NULL;
 404         if (!class->p) {
 405                 WARN(1, "%s called for class '%s' before it was initialized",
 406                      __func__, class->name);
 407                 return NULL;
 408         }
 409
 410         class_dev_iter_init(&iter, class, start, NULL);
 411         while ((dev = class_dev_iter_next(&iter))) {
 412                 if (match(dev, data)) {
 413                         get_device(dev);
 414                         break;
 415                 }
 416         }
 417         class_dev_iter_exit(&iter);
 418
 419         return dev;
 420 }
 421 EXPORT_SYMBOL_GPL(class_find_device);
 422
 423 int class_interface_register(struct class_interface *class_intf)
 424 {
 425         struct class *parent;
 426         struct class_dev_iter iter;
 427         struct device *dev;
 428
 429         if (!class_intf || !class_intf->class)
 430                 return -ENODEV;
 431
 432         parent = class_get(class_intf->class);
 433         if (!parent)
 434                 return -EINVAL;
 435
 436         mutex_lock(&parent->p->mutex);
 437         list_add_tail(&class_intf->node, &parent->p->interfaces);
 438         if (class_intf->add_dev) {
 439                 class_dev_iter_init(&iter, parent, NULL, NULL);
 440                 while ((dev = class_dev_iter_next(&iter)))
 441                         class_intf->add_dev(dev, class_intf);
 442                 class_dev_iter_exit(&iter);
 443         }
 444         mutex_unlock(&parent->p->mutex);
 445
 446         return 0;
 447 }
 448
 449 void class_interface_unregister(struct class_interface *class_intf)
 450 {
 451         struct class *parent = class_intf->class;
 452         struct class_dev_iter iter;
 453         struct device *dev;
 454
 455         if (!parent)
 456                 return;
 457
 458         mutex_lock(&parent->p->mutex);
 459         list_del_init(&class_intf->node);
 460         if (class_intf->remove_dev) {
 461                 class_dev_iter_init(&iter, parent, NULL, NULL);
 462                 while ((dev = class_dev_iter_next(&iter)))
 463                         class_intf->remove_dev(dev, class_intf);
 464                 class_dev_iter_exit(&iter);
 465         }
 466         mutex_unlock(&parent->p->mutex);
 467
 468         class_put(parent);
 469 }
 470
 471 ssize_t show_class_attr_string(struct class *class,
 472                                struct class_attribute *attr, char *buf)
 473 {
 474         struct class_attribute_string *cs;
 475
 476         cs = container_of(attr, struct class_attribute_string, attr);
 477         return snprintf(buf, PAGE_SIZE, "%s\n", cs->str);
 478 }
 479
 480 EXPORT_SYMBOL_GPL(show_class_attr_string);
 481
 482 struct class_compat {
 483         struct kobject *kobj;
 484 };
 485
 486 /**
 487  * class_compat_register - register a compatibility class
 488  * @name: the name of the class
 489  *
 490  * Compatibility class are meant as a temporary user-space compatibility
 491  * workaround when converting a family of class devices to a bus devices.
 492  */
 493 struct class_compat *class_compat_register(const char *name)
 494 {
 495         struct class_compat *cls;
 496
 497         cls = kmalloc(sizeof(struct class_compat), GFP_KERNEL);
 498         if (!cls)
 499                 return NULL;
 500         cls->kobj = kobject_create_and_add(name, &class_kset->kobj);
 501         if (!cls->kobj) {
 502                 kfree(cls);
 503                 return NULL;
 504         }
 505         return cls;
 506 }
 507 EXPORT_SYMBOL_GPL(class_compat_register);
 508
 509 /**
 510  * class_compat_unregister - unregister a compatibility class
 511  * @cls: the class to unregister
 512  */
 513 void class_compat_unregister(struct class_compat *cls)
 514 {
 515         kobject_put(cls->kobj);
 516         kfree(cls);
 517 }
 518 EXPORT_SYMBOL_GPL(class_compat_unregister);
 519
 520 /**
 521  * class_compat_create_link - create a compatibility class device link to
 522  *                            a bus device
 523  * @cls: the compatibility class
 524  * @dev: the target bus device
 525  * @device_link: an optional device to which a "device" link should be created
 526  */
 527 int class_compat_create_link(struct class_compat *cls, struct device *dev,
 528                              struct device *device_link)
 529 {
 530         int error;
 531
 532         error = sysfs_create_link(cls->kobj, &dev->kobj, dev_name(dev));
 533         if (error)
 534                 return error;
 535
 536         /*
 537          * Optionally add a "device" link (typically to the parent), as a
 538          * class device would have one and we want to provide as much
 539          * backwards compatibility as possible.
 540          */
 541         if (device_link) {
 542                 error = sysfs_create_link(&dev->kobj, &device_link->kobj,
 543                                           "device");
 544                 if (error)
 545                         sysfs_remove_link(cls->kobj, dev_name(dev));
 546         }
 547
 548         return error;
 549 }
 550 EXPORT_SYMBOL_GPL(class_compat_create_link);
 551
 552 /**
 553  * class_compat_remove_link - remove a compatibility class device link to
 554  *                            a bus device
 555  * @cls: the compatibility class
 556  * @dev: the target bus device
 557  * @device_link: an optional device to which a "device" link was previously
 558  *               created
 559  */
 560 void class_compat_remove_link(struct class_compat *cls, struct device *dev,
 561                               struct device *device_link)
 562 {
 563         if (device_link)
 564                 sysfs_remove_link(&dev->kobj, "device");
 565         sysfs_remove_link(cls->kobj, dev_name(dev));
 566 }
 567 EXPORT_SYMBOL_GPL(class_compat_remove_link);
 568
 569 int __init classes_init(void)
 570 {
 571         class_kset = kset_create_and_add("class", NULL, NULL);
 572         if (!class_kset)
 573                 return -ENOMEM;
 574         return 0;
 575 }
 576
 577 EXPORT_SYMBOL_GPL(class_create_file_ns);
 578 EXPORT_SYMBOL_GPL(class_remove_file_ns);
 579 EXPORT_SYMBOL_GPL(class_unregister);
 580 EXPORT_SYMBOL_GPL(class_destroy);
 581
 582 EXPORT_SYMBOL_GPL(class_interface_register);
 583 EXPORT_SYMBOL_GPL(class_interface_unregister);