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