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