| 1 | ==============
|
| 2 | Driver Binding
|
| 3 | ==============
|
| 4 |
|
| 5 | Driver binding is the process of associating a device with a device
|
| 6 | driver that can control it. Bus drivers have typically handled this
|
| 7 | because there have been bus-specific structures to represent the
|
| 8 | devices and the drivers. With generic device and device driver
|
| 9 | structures, most of the binding can take place using common code.
|
| 10 |
|
| 11 |
|
| 12 | Bus
|
| 13 | ~~~
|
| 14 |
|
| 15 | The bus type structure contains a list of all devices that are on that bus
|
| 16 | type in the system. When device_register is called for a device, it is
|
| 17 | inserted into the end of this list. The bus object also contains a
|
| 18 | list of all drivers of that bus type. When driver_register is called
|
| 19 | for a driver, it is inserted at the end of this list. These are the
|
| 20 | two events which trigger driver binding.
|
| 21 |
|
| 22 |
|
| 23 | device_register
|
| 24 | ~~~~~~~~~~~~~~~
|
| 25 |
|
| 26 | When a new device is added, the bus's list of drivers is iterated over
|
| 27 | to find one that supports it. In order to determine that, the device
|
| 28 | ID of the device must match one of the device IDs that the driver
|
| 29 | supports. The format and semantics for comparing IDs is bus-specific.
|
| 30 | Instead of trying to derive a complex state machine and matching
|
| 31 | algorithm, it is up to the bus driver to provide a callback to compare
|
| 32 | a device against the IDs of a driver. The bus returns 1 if a match was
|
| 33 | found; 0 otherwise.
|
| 34 |
|
| 35 | int match(struct device * dev, struct device_driver * drv);
|
| 36 |
|
| 37 | If a match is found, the device's driver field is set to the driver
|
| 38 | and the driver's probe callback is called. This gives the driver a
|
| 39 | chance to verify that it really does support the hardware, and that
|
| 40 | it's in a working state.
|
| 41 |
|
| 42 | Device Class
|
| 43 | ~~~~~~~~~~~~
|
| 44 |
|
| 45 | Upon the successful completion of probe, the device is registered with
|
| 46 | the class to which it belongs. Device drivers belong to one and only one
|
| 47 | class, and that is set in the driver's devclass field.
|
| 48 | devclass_add_device is called to enumerate the device within the class
|
| 49 | and actually register it with the class, which happens with the
|
| 50 | class's register_dev callback.
|
| 51 |
|
| 52 |
|
| 53 | Driver
|
| 54 | ~~~~~~
|
| 55 |
|
| 56 | When a driver is attached to a device, the driver's probe() function is
|
| 57 | called. Within probe(), the driver initializes the device and allocates
|
| 58 | and initializes per-device data structures. This per-device state is
|
| 59 | associated with the device object for as long as the driver remains bound
|
| 60 | to it. Conceptually, this per-device data together with the binding to
|
| 61 | the device can be thought of as an instance of the driver.
|
| 62 |
|
| 63 | sysfs
|
| 64 | ~~~~~
|
| 65 |
|
| 66 | A symlink is created in the bus's 'devices' directory that points to
|
| 67 | the device's directory in the physical hierarchy.
|
| 68 |
|
| 69 | A symlink is created in the driver's 'devices' directory that points
|
| 70 | to the device's directory in the physical hierarchy.
|
| 71 |
|
| 72 | A directory for the device is created in the class's directory. A
|
| 73 | symlink is created in that directory that points to the device's
|
| 74 | physical location in the sysfs tree.
|
| 75 |
|
| 76 | A symlink can be created (though this isn't done yet) in the device's
|
| 77 | physical directory to either its class directory, or the class's
|
| 78 | top-level directory. One can also be created to point to its driver's
|
| 79 | directory also.
|
| 80 |
|
| 81 |
|
| 82 | driver_register
|
| 83 | ~~~~~~~~~~~~~~~
|
| 84 |
|
| 85 | The process is almost identical for when a new driver is added.
|
| 86 | The bus's list of devices is iterated over to find a match. Devices
|
| 87 | that already have a driver are skipped. All the devices are iterated
|
| 88 | over, to bind as many devices as possible to the driver.
|
| 89 |
|
| 90 |
|
| 91 | Removal
|
| 92 | ~~~~~~~
|
| 93 |
|
| 94 | When a device is removed, the reference count for it will eventually
|
| 95 | go to 0. When it does, the remove callback of the driver is called. It
|
| 96 | is removed from the driver's list of devices and the reference count
|
| 97 | of the driver is decremented. All symlinks between the two are removed.
|
| 98 |
|
| 99 | When a driver is removed, the list of devices that it supports is
|
| 100 | iterated over, and the driver's remove callback is called for each
|
| 101 | one. The device is removed from that list and the symlinks removed.
|
| 102 |
|
| 103 |
|
| 104 | Driver Override
|
| 105 | ~~~~~~~~~~~~~~~
|
| 106 |
|
| 107 | Userspace may override the standard matching by writing a driver name to
|
| 108 | a device's ``driver_override`` sysfs attribute. When set, only a driver
|
| 109 | whose name matches the override will be considered during binding. This
|
| 110 | bypasses all bus-specific matching (OF, ACPI, ID tables, etc.).
|
| 111 |
|
| 112 | The override may be cleared by writing an empty string, which returns
|
| 113 | the device to standard matching rules. Writing to ``driver_override``
|
| 114 | does not automatically unbind the device from its current driver or
|
| 115 | make any attempt to load the specified driver.
|
| 116 |
|
| 117 | Buses opt into this mechanism by setting the ``driver_override`` flag in
|
| 118 | their ``struct bus_type``::
|
| 119 |
|
| 120 | const struct bus_type example_bus_type = {
|
| 121 | ...
|
| 122 | .driver_override = true,
|
| 123 | };
|
| 124 |
|
| 125 | When the flag is set, the driver core automatically creates the
|
| 126 | ``driver_override`` sysfs attribute for every device on that bus.
|
| 127 |
|
| 128 | The bus's ``match()`` callback should check the override before performing
|
| 129 | its own matching, using ``device_match_driver_override()``::
|
| 130 |
|
| 131 | static int example_match(struct device *dev, const struct device_driver *drv)
|
| 132 | {
|
| 133 | int ret;
|
| 134 |
|
| 135 | ret = device_match_driver_override(dev, drv);
|
| 136 | if (ret >= 0)
|
| 137 | return ret;
|
| 138 |
|
| 139 | /* Fall through to bus-specific matching... */
|
| 140 | }
|
| 141 |
|
| 142 | ``device_match_driver_override()`` returns > 0 if the override matches
|
| 143 | the given driver, 0 if the override is set but does not match, or < 0 if
|
| 144 | no override is set at all.
|
| 145 |
|
| 146 | Additional helpers are available:
|
| 147 |
|
| 148 | - ``device_set_driver_override()`` - set or clear the override from kernel code.
|
| 149 | - ``device_has_driver_override()`` - check whether an override is set.
|