linux/device/class.h

0001 // SPDX-License-Identifier: GPL-2.0
0002 /*
0003  * The class-specific portions of the driver model
0004  *
0005  * Copyright (c) 2001-2003 Patrick Mochel <mochel@osdl.org>
0006  * Copyright (c) 2004-2009 Greg Kroah-Hartman <gregkh@suse.de>
0007  * Copyright (c) 2008-2009 Novell Inc.
0008  * Copyright (c) 2012-2019 Greg Kroah-Hartman <gregkh@linuxfoundation.org>
0009  * Copyright (c) 2012-2019 Linux Foundation
0010  *
0011  * See Documentation/driver-api/driver-model/ for more information.
0012  */
0013
0014 #ifndef _DEVICE_CLASS_H_
0015 #define _DEVICE_CLASS_H_
0016
0017 #include <linux/kobject.h>
0018 #include <linux/klist.h>
0019 #include <linux/pm.h>
0020 #include <linux/device/bus.h>
0021
0022 struct device;
0023 struct fwnode_handle;
0024
0025 /**
0026  * struct class - device classes
0027  * @name:   Name of the class.
0028  * @owner:  The module owner.
0029  * @class_groups: Default attributes of this class.
0030  * @dev_groups: Default attributes of the devices that belong to the class.
0031  * @dev_kobj:   The kobject that represents this class and links it into the hierarchy.
0032  * @dev_uevent: Called when a device is added, removed from this class, or a
0033  *      few other things that generate uevents to add the environment
0034  *      variables.
0035  * @devnode:    Callback to provide the devtmpfs.
0036  * @class_release: Called to release this class.
0037  * @dev_release: Called to release the device.
0038  * @shutdown_pre: Called at shut-down time before driver shutdown.
0039  * @ns_type:    Callbacks so sysfs can detemine namespaces.
0040  * @namespace:  Namespace of the device belongs to this class.
0041  * @get_ownership: Allows class to specify uid/gid of the sysfs directories
0042  *      for the devices belonging to the class. Usually tied to
0043  *      device's namespace.
0044  * @pm:     The default device power management operations of this class.
0045  * @p:      The private data of the driver core, no one other than the
0046  *      driver core can touch this.
0047  *
0048  * A class is a higher-level view of a device that abstracts out low-level
0049  * implementation details. Drivers may see a SCSI disk or an ATA disk, but,
0050  * at the class level, they are all simply disks. Classes allow user space
0051  * to work with devices based on what they do, rather than how they are
0052  * connected or how they work.
0053  */
0054 struct class {
0055     const char      *name;
0056     struct module       *owner;
0057
0058     const struct attribute_group    **class_groups;
0059     const struct attribute_group    **dev_groups;
0060     struct kobject          *dev_kobj;
0061
0062     int (*dev_uevent)(struct device *dev, struct kobj_uevent_env *env);
0063     char *(*devnode)(struct device *dev, umode_t *mode);
0064
0065     void (*class_release)(struct class *class);
0066     void (*dev_release)(struct device *dev);
0067
0068     int (*shutdown_pre)(struct device *dev);
0069
0070     const struct kobj_ns_type_operations *ns_type;
0071     const void *(*namespace)(struct device *dev);
0072
0073     void (*get_ownership)(struct device *dev, kuid_t *uid, kgid_t *gid);
0074
0075     const struct dev_pm_ops *pm;
0076
0077     struct subsys_private *p;
0078 };
0079
0080 struct class_dev_iter {
0081     struct klist_iter       ki;
0082     const struct device_type    *type;
0083 };
0084
0085 extern struct kobject *sysfs_dev_block_kobj;
0086 extern struct kobject *sysfs_dev_char_kobj;
0087 extern int __must_check __class_register(struct class *class,
0088                      struct lock_class_key *key);
0089 extern void class_unregister(struct class *class);
0090
0091 /* This is a #define to keep the compiler from merging different
0092  * instances of the __key variable */
0093 #define class_register(class)           \
0094 ({                      \
0095     static struct lock_class_key __key; \
0096     __class_register(class, &__key);    \
0097 })
0098
0099 struct class_compat;
0100 struct class_compat *class_compat_register(const char *name);
0101 void class_compat_unregister(struct class_compat *cls);
0102 int class_compat_create_link(struct class_compat *cls, struct device *dev,
0103                  struct device *device_link);
0104 void class_compat_remove_link(struct class_compat *cls, struct device *dev,
0105                   struct device *device_link);
0106
0107 extern void class_dev_iter_init(struct class_dev_iter *iter,
0108                 struct class *class,
0109                 struct device *start,
0110                 const struct device_type *type);
0111 extern struct device *class_dev_iter_next(struct class_dev_iter *iter);
0112 extern void class_dev_iter_exit(struct class_dev_iter *iter);
0113
0114 extern int class_for_each_device(struct class *class, struct device *start,
0115                  void *data,
0116                  int (*fn)(struct device *dev, void *data));
0117 extern struct device *class_find_device(struct class *class,
0118                     struct device *start, const void *data,
0119                     int (*match)(struct device *, const void *));
0120
0121 /**
0122  * class_find_device_by_name - device iterator for locating a particular device
0123  * of a specific name.
0124  * @class: class type
0125  * @name: name of the device to match
0126  */
0127 static inline struct device *class_find_device_by_name(struct class *class,
0128                                const char *name)
0129 {
0130     return class_find_device(class, NULL, name, device_match_name);
0131 }
0132
0133 /**
0134  * class_find_device_by_of_node : device iterator for locating a particular device
0135  * matching the of_node.
0136  * @class: class type
0137  * @np: of_node of the device to match.
0138  */
0139 static inline struct device *
0140 class_find_device_by_of_node(struct class *class, const struct device_node *np)
0141 {
0142     return class_find_device(class, NULL, np, device_match_of_node);
0143 }
0144
0145 /**
0146  * class_find_device_by_fwnode : device iterator for locating a particular device
0147  * matching the fwnode.
0148  * @class: class type
0149  * @fwnode: fwnode of the device to match.
0150  */
0151 static inline struct device *
0152 class_find_device_by_fwnode(struct class *class,
0153                 const struct fwnode_handle *fwnode)
0154 {
0155     return class_find_device(class, NULL, fwnode, device_match_fwnode);
0156 }
0157
0158 /**
0159  * class_find_device_by_devt : device iterator for locating a particular device
0160  * matching the device type.
0161  * @class: class type
0162  * @devt: device type of the device to match.
0163  */
0164 static inline struct device *class_find_device_by_devt(struct class *class,
0165                                dev_t devt)
0166 {
0167     return class_find_device(class, NULL, &devt, device_match_devt);
0168 }
0169
0170 #ifdef CONFIG_ACPI
0171 struct acpi_device;
0172 /**
0173  * class_find_device_by_acpi_dev : device iterator for locating a particular
0174  * device matching the ACPI_COMPANION device.
0175  * @class: class type
0176  * @adev: ACPI_COMPANION device to match.
0177  */
0178 static inline struct device *
0179 class_find_device_by_acpi_dev(struct class *class, const struct acpi_device *adev)
0180 {
0181     return class_find_device(class, NULL, adev, device_match_acpi_dev);
0182 }
0183 #else
0184 static inline struct device *
0185 class_find_device_by_acpi_dev(struct class *class, const void *adev)
0186 {
0187     return NULL;
0188 }
0189 #endif
0190
0191 struct class_attribute {
0192     struct attribute attr;
0193     ssize_t (*show)(struct class *class, struct class_attribute *attr,
0194             char *buf);
0195     ssize_t (*store)(struct class *class, struct class_attribute *attr,
0196             const char *buf, size_t count);
0197 };
0198
0199 #define CLASS_ATTR_RW(_name) \
0200     struct class_attribute class_attr_##_name = __ATTR_RW(_name)
0201 #define CLASS_ATTR_RO(_name) \
0202     struct class_attribute class_attr_##_name = __ATTR_RO(_name)
0203 #define CLASS_ATTR_WO(_name) \
0204     struct class_attribute class_attr_##_name = __ATTR_WO(_name)
0205
0206 extern int __must_check class_create_file_ns(struct class *class,
0207                          const struct class_attribute *attr,
0208                          const void *ns);
0209 extern void class_remove_file_ns(struct class *class,
0210                  const struct class_attribute *attr,
0211                  const void *ns);
0212
0213 static inline int __must_check class_create_file(struct class *class,
0214                     const struct class_attribute *attr)
0215 {
0216     return class_create_file_ns(class, attr, NULL);
0217 }
0218
0219 static inline void class_remove_file(struct class *class,
0220                      const struct class_attribute *attr)
0221 {
0222     return class_remove_file_ns(class, attr, NULL);
0223 }
0224
0225 /* Simple class attribute that is just a static string */
0226 struct class_attribute_string {
0227     struct class_attribute attr;
0228     char *str;
0229 };
0230
0231 /* Currently read-only only */
0232 #define _CLASS_ATTR_STRING(_name, _mode, _str) \
0233     { __ATTR(_name, _mode, show_class_attr_string, NULL), _str }
0234 #define CLASS_ATTR_STRING(_name, _mode, _str) \
0235     struct class_attribute_string class_attr_##_name = \
0236         _CLASS_ATTR_STRING(_name, _mode, _str)
0237
0238 extern ssize_t show_class_attr_string(struct class *class, struct class_attribute *attr,
0239                         char *buf);
0240
0241 struct class_interface {
0242     struct list_head    node;
0243     struct class        *class;
0244
0245     int (*add_dev)      (struct device *, struct class_interface *);
0246     void (*remove_dev)  (struct device *, struct class_interface *);
0247 };
0248
0249 extern int __must_check class_interface_register(struct class_interface *);
0250 extern void class_interface_unregister(struct class_interface *);
0251
0252 extern struct class * __must_check __class_create(struct module *owner,
0253                           const char *name,
0254                           struct lock_class_key *key);
0255 extern void class_destroy(struct class *cls);
0256
0257 /* This is a #define to keep the compiler from merging different
0258  * instances of the __key variable */
0259
0260 /**
0261  * class_create - create a struct class structure
0262  * @owner: pointer to the module that is to "own" this struct class
0263  * @name: pointer to a string for the name of this class.
0264  *
0265  * This is used to create a struct class pointer that can then be used
0266  * in calls to device_create().
0267  *
0268  * Returns &struct class pointer on success, or ERR_PTR() on error.
0269  *
0270  * Note, the pointer created here is to be destroyed when finished by
0271  * making a call to class_destroy().
0272  */
0273 #define class_create(owner, name)       \
0274 ({                      \
0275     static struct lock_class_key __key; \
0276     __class_create(owner, name, &__key);    \
0277 })
0278
0279
0280 #endif  /* _DEVICE_CLASS_H_ */