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