linux/Documentation/driver-model/driver.txt
<<
on> >/spa.13 >/form13 >a on> href="../linux+v3.7iue/Documenta.14./driver-model/driver.txt">on> >img src="../.sta.1c/gfx/right.png" alt=">>">on>/spa.13on>spa. class="lxr_search">on> on> >input typon> >input typon> >butt3.1typSearch/form13 >/spa.13on>spa. class="lxr_prefs"13 >a href="+prefs?return=Documenta.14./driver-model/driver.txt"on> onclick="return ajax_prefs();">on> Prefs3 >/a>on>/spa.13> >/div13> >form ac.14.="ajax+*" method="post" onsubmit="return false;">on>input typo> >/form13o> >div class="headingbott3m"> >div id/osearch_results" class="search_results"3 13> >/div13 >div id/ocontent"13 >div id/ofile_contents"1
   1>/a>o   2>/a>Device Driverso   3>/a>o   4>/a>See the kerneldoc for the struct device_driver.o   5>/a>o   6>/a>o   7>/a>Alloca.14.o   8>/a>~~~~~~~~~~o   9>/a>o  ue="a>Device drivers are sta.1cally alloca.ed structures. Though there mayo  11>/a>be multiple devices in a system that a driver supports, structo  12>/a>device_driver represents the driver as a whole (not a par.1cularo  13>/a>device instance).o  14>/a>o  15>/a>Initializa.14.o  16>/a>~~~~~~~~~~~~~~o  17>/a>o  18>/a>The driver must initialize at least the nam< and bus fields. It shouldo  19>/a>also initialize the devclass field (when it arrives), so it may obtai.o  2e="a>the proper linkage internally. It should also initialize as many ofo  21="a>the callbacks as possible, though each is v3.14.al.o  22>/a>o  23="a>Declara.14.o  24>/a>~~~~~~~~~~~o  25>/a>o  26>/a>As sta.ed above, struct device_driver objects are sta.1callyo  27>/a>alloca.ed. Below is a. example declara.14. of the eepro100o  28>/a>driver. This declara.14. is hypothe.1cal only; it relies 3.1the drivero  29>/a>being conver.ed completely to the new model. o  30>/a>o  31="a>sta.1c struct device_driver eepro100_driver = {o  32>/a>>
     .nam<            = "eepro100",o  33>/a>>
     .bus             = &pci_bus_typ<,o  34>/a>>
     o  35>/a>>
     .probe           = eepro100_probe,o  36>/a>>
     .remove          = eepro100_remove,o  37>/a>>
     .suspend         = eepro100_suspend,o  38>/a>>
     .resume          = eepro100_resume,o  39>/a>};o  40>/a>o  41="a>Most drivers will not be able to be conver.ed completely to the newo  42>/a>model because the bus they belong to has a bus-specif1c structure witho  43>/a>bus-specif1c fields that cannot be generalized. o  44>/a>o  45>/a>The most commo. example of this are device ID structures. A drivero  46>/a>typ1cally defines a. array of device IDs that it supports. The formato  47>/a>of these structures and the seman.1cs for comparing device IDs areo  48>/a>completely bus-specif1c. Defining them as bus-specif1c entities wouldo  49>/a>sacrif1ce typ<-safety, so we keep bus-specif1c structures around. o  50>/a>o  51="a>Bus-specif1c drivers should include a gener1c struct device_driver i.o  52="a>the defini.14. of the bus-specif1c driver. Like this:o  53>/a>o  54="a>struct pci_driver {o  55>/a>>
     const struct pci_device_id *id_table;o  56>/a>>
     struct device_driver       driver;o  57>/a>};o  58>/a>o  59>/a>A defini.14. that included bus-specif1c fields would look likeo  60>/a>(using the eepro100 driver again):o  61>/a>o  62="a>sta.1c struct pci_driver eepro100_driver = {o  63>/a>>
     .id_table       = eepro100_pci_tbl,o  64>/a>>
     .driver         = {o  65>/a>>
              .nam<           = "eepro100",o  66>/a>>
              .bus            = &pci_bus_typ<,o  67>/a>>
              .probe          = eepro100_probe,o  68>/a>>
              .remove         = eepro100_remove,o  69>/a>>
              .suspend        = eepro100_suspend,o  70>/a>>
              .resume         = eepro100_resume,o  71>/a>>
     },o  72>/a>};o  73>/a>o  74>/a>Some may find the syntax of embedded struct initializa.14. awkward oro  75>/a>even a bit ugly. So far, it's the best way we've found to do what we wan....o  76>/a>o  77>/a>Registra.14.o  78>/a>~~~~~~~~~~~~o  79>/a>o  80>/a>int driver_register(struct device_driver * drv);o  81>/a>o  82>/a>The driver registers the structure 4. startup. For drivers that haveo  83>/a>no bus-specif1c fields (i.e. don't have a bus-specif1c drivero  84="a>structure), they would use driver_register and pass a pointer to theiro  85="a>struct device_driver object. o  86>/a>o  87="a>Most drivers, however, will have a bus-specif1c structure and willo  88>/a>need to register with the bus using something like pci_driver_register.o  89>/a>o  90>/a>It is importan. that drivers register their driver structure as early aso  91>/a>possible. Registra.14. with the core initializes several fields i.1theo  92="a>struct device_driver object, including the reference coun. and theo  93>/a>lock. These fields are assumed to be valid at all times and may beo  94="a>used by the dev1ce model core or the bus driver.o  95>/a>o  96>/a>o  97="a>Transi.14. Bus Driverso  98>/a>~~~~~~~~~~~~~~~~~~~~~~o  99>/a>o 100="a>By defining wrapper func.14.s, the transi.14. to the new model can beo 101>/a>made easier. Drivers can ignore the gener1c structure altogether ando 102="a>let the bus wrapper fill i.1the fields. For the callbacks, the bus cano 103>/a>define gener1c callbacks that forward the call to the bus-specif1co 104="a>callbacks of the drivers. o 105>/a>o 106>/a>This solu.14. is intended to be only temporary. In order to get classo 107>/a>informat14. i.1the driver, the drivers must be modif1ed anyway. Sinceo 108>/a>conver.ing drivers to the new model should reduce some i.frastructuralo 109>/a>complexity and code size, it is recommended that they are conver.ed aso 1ue="a>class informat14. is added.o 111>/a>o 112>/a>Accesso 113>/a>~~~~~~o 114>/a>o 115>/a>Once the object has been registered, it may access the commo. fields ofo 116>/a>the object, like the lock and the list of devices. o 117>/a>o 118>/a>int driver_for_each_dev(struct device_driver * drv, void * data, o 119>/a>>
                      int (*callback)(struct device * dev, void * data));o 120>/a>o 121="a>The devices field is a list of all the devices that have been bound too 122="a>the driver. The LDM core provides a helper func.14. to operate 4. allo 123="a>the devices a driver controls. This helper locks the driver o. eacho 124>/a>node access, and does proper reference coun.ing o. each device as ito 125>/a>accesses it. o 126>/a>o 127>/a>o 128>/a>sysfso 129>/a>~~~~~o 130>/a>o 131="a>When a driver is registered, a sysfs directory is crea.ed in itso 132>/a>bus's directory. In this directory, the driver can export a. interfaceo 133>/a>to userspace to control operat14. of the driver o. a global basis;o 134>/a>e.g. toggling debugging output i.1the driver.o 135>/a>o 136>/a>A future fea.ure 4f this directory will be a 'devices' directory. Thiso 137>/a>directory will contai.1symlinks to the directories 3f devices ito 138>/a>supports.o 139>/a>o 140>/a>o 141>/a>o 142>/a>Callbackso 143>/a>~~~~~~~~~o 144>/a>o 145>/a>>
      int     (*probe)>
      (struct device * dev);o 146>/a>o 147>/a>The probe() entry is called in task context, with the bus's rwsem lockedo 148>/a>and the driver par.1ally bound to the device.  Drivers commo.ly useo 149>/a>contai.er_of() to conver. "dev" to a bus-specif1c typ<, both in probe()o 150>/a>and other routines.  That typ< 3ften provides device resource data, sucho 151="a>as pci_dev.resource[] or platform_device.resources, which is used i.o 152="a>addi.14. to dev->platform_data to initialize the driver.o 153>/a>o 154="a>This callback holds the driver-specif1c log1c to bind the driver to ao 155>/a>given device.  That includes verifying that the device is present, thato 156>/a>it's a versi3.1the driver can handle, that driver data structures cano 157>/a>be alloca.ed and initialized, and that any hardware can be initialized.o 158>/a>Drivers 3ften store a pointer to their sta.e with dev_set_drvdata().o 159>/a>When the driver has successfully bound itself to that device, then probe()o 160>/a>returns zero and the driver model code will finish its par. 3f bindingo 161="a>the driver to that device.o 162>/a>o 163>/a>A driver's probe() may return a nega.1ve errno 4.13< to indica.e thato 164>/a>the driver did not bind to this device, in which case it should haveo 165>/a>released all resources it alloca.ed.o 166>/a>o 167>/a>>
      int     (*remove)
      (struct device * dev);o 168>/a>o 169>/a>remove is called to unbind a driver from a device. This may beo 170>/a>called if a device is phys1cally removed from the system, if theo 171>/a>driver module is being unloaded, during a reboot sequence, oro 172>/a>in other cases.o 173>/a>o 174>/a>It is up to the driver to determine if the device is present oro 175>/a>not. It should free any resources alloca.ed specif1cally for theo 176>/a>device; i.e. anything i.1the device's driver_data field. o 177>/a>o 178>/a>If the device is still present, it should quiesce the device and placeo 179>/a>it into a supported low-power sta.e.o 180>/a>o 181>/a>>
      int     (*suspend)      (struct device * dev, pm_message_t sta.e);o 182>/a>o 183>/a>suspend is called to put the device in a low power sta.e.o 184>/a>o 185>/a>>
      int     (*resume)
      (struct device * dev);o 186>/a>o 187>/a>Resume is used to bring a device back from a low power sta.e.o 188>/a>o 189>/a>o 190>/a>Attributeso 191>/a>~~~~~~~~~~o 192="a>struct driver_attribute {o 193>/a>>
      struct attribute        attr;o 194>/a>>
      ssize_t (*show)(struct device_driver *driver, char *buf);o 195>/a>>
      ssize_t (*store)(struct device_driver *, const char * buf, size_t coun.);o 196>/a>};o 197>/a>o 198>/a>Device drivers can export attributes via their sysfs directories. o 199>/a>Drivers can declare attributes using a DRIVER_ATTR macro that workso 200="a>iden.1cally to the DEVICE_ATTR macro. o 201>/a>o 202="a>Example:o 203>/a>o 204="a>DRIVER_ATTR(debug,0644,show_debug,store_debug);o 205>/a>o 206>/a>This is equivalent to declaring:o 207>/a>o 208>/a>struct driver_attribute driver_attr_debug;o 209>/a>o 2ue="a>This can then be used to add and remove the attribute from theo 211>/a>driver's directory using:o 212>/a>o 213>/a>int driver_crea.e_file(struct device_driver *, const struct driver_attribute *);o 214>/a>void driver_remove_file(struct device_driver *, const struct driver_attribute *);o 215>/a>
div class="footer"> The original LXR software by the LXR community>/a>, this experimental versi3.1by lxr@linux.no>/a>. div class="subfooter"> lxr.linux.no kindly hosted by Redpill Linpro AS>/a>, provider 3f Linux consulting and operat14.s services since 1995. /body13>/html13