drivers/base/driver.c

0001 // SPDX-License-Identifier: GPL-2.0
0002 /*
0003  * driver.c - centralized device driver management
0004  *
0005  * Copyright (c) 2002-3 Patrick Mochel
0006  * Copyright (c) 2002-3 Open Source Development Labs
0007  * Copyright (c) 2007 Greg Kroah-Hartman <gregkh@suse.de>
0008  * Copyright (c) 2007 Novell Inc.
0009  */
0010
0011 #include <linux/device/driver.h>
0012 #include <linux/device.h>
0013 #include <linux/module.h>
0014 #include <linux/errno.h>
0015 #include <linux/slab.h>
0016 #include <linux/string.h>
0017 #include <linux/sysfs.h>
0018 #include "base.h"
0019
0020 static struct device *next_device(struct klist_iter *i)
0021 {
0022     struct klist_node *n = klist_next(i);
0023     struct device *dev = NULL;
0024     struct device_private *dev_prv;
0025
0026     if (n) {
0027         dev_prv = to_device_private_driver(n);
0028         dev = dev_prv->device;
0029     }
0030     return dev;
0031 }
0032
0033 /**
0034  * driver_set_override() - Helper to set or clear driver override.
0035  * @dev: Device to change
0036  * @override: Address of string to change (e.g. &device->driver_override);
0037  *            The contents will be freed and hold newly allocated override.
0038  * @s: NUL-terminated string, new driver name to force a match, pass empty
0039  *     string to clear it ("" or "\n", where the latter is only for sysfs
0040  *     interface).
0041  * @len: length of @s
0042  *
0043  * Helper to set or clear driver override in a device, intended for the cases
0044  * when the driver_override field is allocated by driver/bus code.
0045  *
0046  * Returns: 0 on success or a negative error code on failure.
0047  */
0048 int driver_set_override(struct device *dev, const char **override,
0049             const char *s, size_t len)
0050 {
0051     const char *new, *old;
0052     char *cp;
0053
0054     if (!override || !s)
0055         return -EINVAL;
0056
0057     /*
0058      * The stored value will be used in sysfs show callback (sysfs_emit()),
0059      * which has a length limit of PAGE_SIZE and adds a trailing newline.
0060      * Thus we can store one character less to avoid truncation during sysfs
0061      * show.
0062      */
0063     if (len >= (PAGE_SIZE - 1))
0064         return -EINVAL;
0065
0066     /*
0067      * Compute the real length of the string in case userspace sends us a
0068      * bunch of \0 characters like python likes to do.
0069      */
0070     len = strlen(s);
0071
0072     if (!len) {
0073         /* Empty string passed - clear override */
0074         device_lock(dev);
0075         old = *override;
0076         *override = NULL;
0077         device_unlock(dev);
0078         kfree(old);
0079
0080         return 0;
0081     }
0082
0083     cp = strnchr(s, len, '\n');
0084     if (cp)
0085         len = cp - s;
0086
0087     new = kstrndup(s, len, GFP_KERNEL);
0088     if (!new)
0089         return -ENOMEM;
0090
0091     device_lock(dev);
0092     old = *override;
0093     if (cp != s) {
0094         *override = new;
0095     } else {
0096         /* "\n" passed - clear override */
0097         kfree(new);
0098         *override = NULL;
0099     }
0100     device_unlock(dev);
0101
0102     kfree(old);
0103
0104     return 0;
0105 }
0106 EXPORT_SYMBOL_GPL(driver_set_override);
0107
0108 /**
0109  * driver_for_each_device - Iterator for devices bound to a driver.
0110  * @drv: Driver we're iterating.
0111  * @start: Device to begin with
0112  * @data: Data to pass to the callback.
0113  * @fn: Function to call for each device.
0114  *
0115  * Iterate over the @drv's list of devices calling @fn for each one.
0116  */
0117 int driver_for_each_device(struct device_driver *drv, struct device *start,
0118                void *data, int (*fn)(struct device *, void *))
0119 {
0120     struct klist_iter i;
0121     struct device *dev;
0122     int error = 0;
0123
0124     if (!drv)
0125         return -EINVAL;
0126
0127     klist_iter_init_node(&drv->p->klist_devices, &i,
0128                  start ? &start->p->knode_driver : NULL);
0129     while (!error && (dev = next_device(&i)))
0130         error = fn(dev, data);
0131     klist_iter_exit(&i);
0132     return error;
0133 }
0134 EXPORT_SYMBOL_GPL(driver_for_each_device);
0135
0136 /**
0137  * driver_find_device - device iterator for locating a particular device.
0138  * @drv: The device's driver
0139  * @start: Device to begin with
0140  * @data: Data to pass to match function
0141  * @match: Callback function to check device
0142  *
0143  * This is similar to the driver_for_each_device() function above, but
0144  * it returns a reference to a device that is 'found' for later use, as
0145  * determined by the @match callback.
0146  *
0147  * The callback should return 0 if the device doesn't match and non-zero
0148  * if it does.  If the callback returns non-zero, this function will
0149  * return to the caller and not iterate over any more devices.
0150  */
0151 struct device *driver_find_device(struct device_driver *drv,
0152                   struct device *start, const void *data,
0153                   int (*match)(struct device *dev, const void *data))
0154 {
0155     struct klist_iter i;
0156     struct device *dev;
0157
0158     if (!drv || !drv->p)
0159         return NULL;
0160
0161     klist_iter_init_node(&drv->p->klist_devices, &i,
0162                  (start ? &start->p->knode_driver : NULL));
0163     while ((dev = next_device(&i)))
0164         if (match(dev, data) && get_device(dev))
0165             break;
0166     klist_iter_exit(&i);
0167     return dev;
0168 }
0169 EXPORT_SYMBOL_GPL(driver_find_device);
0170
0171 /**
0172  * driver_create_file - create sysfs file for driver.
0173  * @drv: driver.
0174  * @attr: driver attribute descriptor.
0175  */
0176 int driver_create_file(struct device_driver *drv,
0177                const struct driver_attribute *attr)
0178 {
0179     int error;
0180
0181     if (drv)
0182         error = sysfs_create_file(&drv->p->kobj, &attr->attr);
0183     else
0184         error = -EINVAL;
0185     return error;
0186 }
0187 EXPORT_SYMBOL_GPL(driver_create_file);
0188
0189 /**
0190  * driver_remove_file - remove sysfs file for driver.
0191  * @drv: driver.
0192  * @attr: driver attribute descriptor.
0193  */
0194 void driver_remove_file(struct device_driver *drv,
0195             const struct driver_attribute *attr)
0196 {
0197     if (drv)
0198         sysfs_remove_file(&drv->p->kobj, &attr->attr);
0199 }
0200 EXPORT_SYMBOL_GPL(driver_remove_file);
0201
0202 int driver_add_groups(struct device_driver *drv,
0203               const struct attribute_group **groups)
0204 {
0205     return sysfs_create_groups(&drv->p->kobj, groups);
0206 }
0207
0208 void driver_remove_groups(struct device_driver *drv,
0209               const struct attribute_group **groups)
0210 {
0211     sysfs_remove_groups(&drv->p->kobj, groups);
0212 }
0213
0214 /**
0215  * driver_register - register driver with bus
0216  * @drv: driver to register
0217  *
0218  * We pass off most of the work to the bus_add_driver() call,
0219  * since most of the things we have to do deal with the bus
0220  * structures.
0221  */
0222 int driver_register(struct device_driver *drv)
0223 {
0224     int ret;
0225     struct device_driver *other;
0226
0227     if (!drv->bus->p) {
0228         pr_err("Driver '%s' was unable to register with bus_type '%s' because the bus was not initialized.\n",
0229                drv->name, drv->bus->name);
0230         return -EINVAL;
0231     }
0232
0233     if ((drv->bus->probe && drv->probe) ||
0234         (drv->bus->remove && drv->remove) ||
0235         (drv->bus->shutdown && drv->shutdown))
0236         pr_warn("Driver '%s' needs updating - please use "
0237             "bus_type methods\n", drv->name);
0238
0239     other = driver_find(drv->name, drv->bus);
0240     if (other) {
0241         pr_err("Error: Driver '%s' is already registered, "
0242             "aborting...\n", drv->name);
0243         return -EBUSY;
0244     }
0245
0246     ret = bus_add_driver(drv);
0247     if (ret)
0248         return ret;
0249     ret = driver_add_groups(drv, drv->groups);
0250     if (ret) {
0251         bus_remove_driver(drv);
0252         return ret;
0253     }
0254     kobject_uevent(&drv->p->kobj, KOBJ_ADD);
0255     deferred_probe_extend_timeout();
0256
0257     return ret;
0258 }
0259 EXPORT_SYMBOL_GPL(driver_register);
0260
0261 /**
0262  * driver_unregister - remove driver from system.
0263  * @drv: driver.
0264  *
0265  * Again, we pass off most of the work to the bus-level call.
0266  */
0267 void driver_unregister(struct device_driver *drv)
0268 {
0269     if (!drv || !drv->p) {
0270         WARN(1, "Unexpected driver unregister!\n");
0271         return;
0272     }
0273     driver_remove_groups(drv, drv->groups);
0274     bus_remove_driver(drv);
0275 }
0276 EXPORT_SYMBOL_GPL(driver_unregister);
0277
0278 /**
0279  * driver_find - locate driver on a bus by its name.
0280  * @name: name of the driver.
0281  * @bus: bus to scan for the driver.
0282  *
0283  * Call kset_find_obj() to iterate over list of drivers on
0284  * a bus to find driver by name. Return driver if found.
0285  *
0286  * This routine provides no locking to prevent the driver it returns
0287  * from being unregistered or unloaded while the caller is using it.
0288  * The caller is responsible for preventing this.
0289  */
0290 struct device_driver *driver_find(const char *name, struct bus_type *bus)
0291 {
0292     struct kobject *k = kset_find_obj(bus->p->drivers_kset, name);
0293     struct driver_private *priv;
0294
0295     if (k) {
0296         /* Drop reference added by kset_find_obj() */
0297         kobject_put(k);
0298         priv = to_driver(k);
0299         return priv->driver;
0300     }
0301     return NULL;
0302 }
0303 EXPORT_SYMBOL_GPL(driver_find);