1================ 2EISA bus support 3================ 4 5:Author: Marc Zyngier <maz@wild-wind.fr.eu.org> 6 7This document groups random notes about porting EISA drivers to the 8new EISA/sysfs API. 9 10Starting from version 2.5.59, the EISA bus is almost given the same 11status as other much more mainstream busses such as PCI or USB. This 12has been possible through sysfs, which defines a nice enough set of 13abstractions to manage busses, devices and drivers. 14 15Although the new API is quite simple to use, converting existing 16drivers to the new infrastructure is not an easy task (mostly because 17detection code is generally also used to probe ISA cards). Moreover, 18most EISA drivers are among the oldest Linux drivers so, as you can 19imagine, some dust has settled here over the years. 20 21The EISA infrastructure is made up of three parts: 22 23 - The bus code implements most of the generic code. It is shared 24 among all the architectures that the EISA code runs on. It 25 implements bus probing (detecting EISA cards available on the bus), 26 allocates I/O resources, allows fancy naming through sysfs, and 27 offers interfaces for driver to register. 28 29 - The bus root driver implements the glue between the bus hardware 30 and the generic bus code. It is responsible for discovering the 31 device implementing the bus, and setting it up to be latter probed 32 by the bus code. This can go from something as simple as reserving 33 an I/O region on x86, to the rather more complex, like the hppa 34 EISA code. This is the part to implement in order to have EISA 35 running on an "new" platform. 36 37 - The driver offers the bus a list of devices that it manages, and 38 implements the necessary callbacks to probe and release devices 39 whenever told to. 40 41Every function/structure below lives in <linux/eisa.h>, which depends 42heavily on <linux/device.h>. 43 44Bus root driver 45=============== 46 47:: 48 49 int eisa_root_register (struct eisa_root_device *root); 50 51The eisa_root_register function is used to declare a device as the 52root of an EISA bus. The eisa_root_device structure holds a reference 53to this device, as well as some parameters for probing purposes:: 54 55 struct eisa_root_device { 56 struct device *dev; /* Pointer to bridge device */ 57 struct resource *res; 58 unsigned long bus_base_addr; 59 int slots; /* Max slot number */ 60 int force_probe; /* Probe even when no slot 0 */ 61 u64 dma_mask; /* from bridge device */ 62 int bus_nr; /* Set by eisa_root_register */ 63 struct resource eisa_root_res; /* ditto */ 64 }; 65 66============= ====================================================== 67node used for eisa_root_register internal purpose 68dev pointer to the root device 69res root device I/O resource 70bus_base_addr slot 0 address on this bus 71slots max slot number to probe 72force_probe Probe even when slot 0 is empty (no EISA mainboard) 73dma_mask Default DMA mask. Usually the bridge device dma_mask. 74bus_nr unique bus id, set by eisa_root_register 75============= ====================================================== 76 77Driver 78====== 79 80:: 81 82 int eisa_driver_register (struct eisa_driver *edrv); 83 void eisa_driver_unregister (struct eisa_driver *edrv); 84 85Clear enough ? 86 87:: 88 89 struct eisa_device_id { 90 char sig[EISA_SIG_LEN]; 91 unsigned long driver_data; 92 }; 93 94 struct eisa_driver { 95 const struct eisa_device_id *id_table; 96 struct device_driver driver; 97 }; 98 99=============== ==================================================== 100id_table an array of NULL terminated EISA id strings, 101 followed by an empty string. Each string can 102 optionally be paired with a driver-dependent value 103 (driver_data). 104 105driver a generic driver, such as described in 106 Documentation/driver-api/driver-model/driver.rst. Only .name, 107 .probe and .remove members are mandatory. 108=============== ==================================================== 109 110An example is the 3c59x driver:: 111 112 static struct eisa_device_id vortex_eisa_ids[] = { 113 { "TCM5920", EISA_3C592_OFFSET }, 114 { "TCM5970", EISA_3C597_OFFSET }, 115 { "" } 116 }; 117 118 static struct eisa_driver vortex_eisa_driver = { 119 .id_table = vortex_eisa_ids, 120 .driver = { 121 .name = "3c59x", 122 .probe = vortex_eisa_probe, 123 .remove = vortex_eisa_remove 124 } 125 }; 126 127Device 128====== 129 130The sysfs framework calls .probe and .remove functions upon device 131discovery and removal (note that the .remove function is only called 132when driver is built as a module). 133 134Both functions are passed a pointer to a 'struct device', which is 135encapsulated in a 'struct eisa_device' described as follows:: 136 137 struct eisa_device { 138 struct eisa_device_id id; 139 int slot; 140 int state; 141 unsigned long base_addr; 142 struct resource res[EISA_MAX_RESOURCES]; 143 u64 dma_mask; 144 struct device dev; /* generic device */ 145 }; 146 147======== ============================================================ 148id EISA id, as read from device. id.driver_data is set from the 149 matching driver EISA id. 150slot slot number which the device was detected on 151state set of flags indicating the state of the device. Current 152 flags are EISA_CONFIG_ENABLED and EISA_CONFIG_FORCED. 153res set of four 256 bytes I/O regions allocated to this device 154dma_mask DMA mask set from the parent device. 155dev generic device (see Documentation/driver-api/driver-model/device.rst) 156======== ============================================================ 157 158You can get the 'struct eisa_device' from 'struct device' using the 159'to_eisa_device' macro. 160 161Misc stuff 162========== 163 164:: 165 166 void eisa_set_drvdata (struct eisa_device *edev, void *data); 167 168Stores data into the device's driver_data area. 169 170:: 171 172 void *eisa_get_drvdata (struct eisa_device *edev): 173 174Gets the pointer previously stored into the device's driver_data area. 175 176:: 177 178 int eisa_get_region_index (void *addr); 179 180Returns the region number (0 <= x < EISA_MAX_RESOURCES) of a given 181address. 182 183Kernel parameters 184================= 185 186eisa_bus.enable_dev 187 A comma-separated list of slots to be enabled, even if the firmware 188 set the card as disabled. The driver must be able to properly 189 initialize the device in such conditions. 190 191eisa_bus.disable_dev 192 A comma-separated list of slots to be disabled, even if the firmware 193 set the card as enabled. The driver won't be called to handle this 194 device. 195 196virtual_root.force_probe 197 Force the probing code to probe EISA slots even when it cannot find an 198 EISA compliant mainboard (nothing appears on slot 0). Defaults to 0 199 (don't force), and set to 1 (force probing) when 200 CONFIG_EISA_VLB_PRIMING is set. 201 202Random notes 203============ 204 205Converting an EISA driver to the new API mostly involves *deleting* 206code (since probing is now in the core EISA code). Unfortunately, most 207drivers share their probing routine between ISA, and EISA. Special 208care must be taken when ripping out the EISA code, so other busses 209won't suffer from these surgical strikes... 210 211You *must not* expect any EISA device to be detected when returning 212from eisa_driver_register, since the chances are that the bus has not 213yet been probed. In fact, that's what happens most of the time (the 214bus root driver usually kicks in rather late in the boot process). 215Unfortunately, most drivers are doing the probing by themselves, and 216expect to have explored the whole machine when they exit their probe 217routine. 218 219For example, switching your favorite EISA SCSI card to the "hotplug" 220model is "the right thing"(tm). 221 222Thanks 223====== 224 225I'd like to thank the following people for their help: 226 227- Xavier Benigni for lending me a wonderful Alpha Jensen, 228- James Bottomley, Jeff Garzik for getting this stuff into the kernel, 229- Andries Brouwer for contributing numerous EISA ids, 230- Catrin Jones for coping with far too many machines at home. 231