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