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