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