annotate Documentation/eisa.txt @ 854:950b9eb27661

usbback: fix urb interval value for interrupt urbs.

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