0001 ================
0002 EISA bus support
0003 ================
0004
0005 :Author: Marc Zyngier <maz@wild-wind.fr.eu.org>
0006
0007 This document groups random notes about porting EISA drivers to the
0008 new EISA/sysfs API.
0009
0010 Starting from version 2.5.59, the EISA bus is almost given the same
0011 status as other much more mainstream busses such as PCI or USB. This
0012 has been possible through sysfs, which defines a nice enough set of
0013 abstractions to manage busses, devices and drivers.
0014
0015 Although the new API is quite simple to use, converting existing
0016 drivers to the new infrastructure is not an easy task (mostly because
0017 detection code is generally also used to probe ISA cards). Moreover,
0018 most EISA drivers are among the oldest Linux drivers so, as you can
0019 imagine, some dust has settled here over the years.
0020
0021 The EISA infrastructure is made up of three parts:
0022
0023 - The bus code implements most of the generic code. It is shared
0024 among all the architectures that the EISA code runs on. It
0025 implements bus probing (detecting EISA cards available on the bus),
0026 allocates I/O resources, allows fancy naming through sysfs, and
0027 offers interfaces for driver to register.
0028
0029 - The bus root driver implements the glue between the bus hardware
0030 and the generic bus code. It is responsible for discovering the
0031 device implementing the bus, and setting it up to be latter probed
0032 by the bus code. This can go from something as simple as reserving
0033 an I/O region on x86, to the rather more complex, like the hppa
0034 EISA code. This is the part to implement in order to have EISA
0035 running on an "new" platform.
0036
0037 - The driver offers the bus a list of devices that it manages, and
0038 implements the necessary callbacks to probe and release devices
0039 whenever told to.
0040
0041 Every function/structure below lives in <linux/eisa.h>, which depends
0042 heavily on <linux/device.h>.
0043
0044 Bus root driver
0045 ===============
0046
0047 ::
0048
0049 int eisa_root_register (struct eisa_root_device *root);
0050
0051 The eisa_root_register function is used to declare a device as the
0052 root of an EISA bus. The eisa_root_device structure holds a reference
0053 to this device, as well as some parameters for probing purposes::
0054
0055 struct eisa_root_device {
0056 struct device *dev; /* Pointer to bridge device */
0057 struct resource *res;
0058 unsigned long bus_base_addr;
0059 int slots; /* Max slot number */
0060 int force_probe; /* Probe even when no slot 0 */
0061 u64 dma_mask; /* from bridge device */
0062 int bus_nr; /* Set by eisa_root_register */
0063 struct resource eisa_root_res; /* ditto */
0064 };
0065
0066 ============= ======================================================
0067 node used for eisa_root_register internal purpose
0068 dev pointer to the root device
0069 res root device I/O resource
0070 bus_base_addr slot 0 address on this bus
0071 slots max slot number to probe
0072 force_probe Probe even when slot 0 is empty (no EISA mainboard)
0073 dma_mask Default DMA mask. Usually the bridge device dma_mask.
0074 bus_nr unique bus id, set by eisa_root_register
0075 ============= ======================================================
0076
0077 Driver
0078 ======
0079
0080 ::
0081
0082 int eisa_driver_register (struct eisa_driver *edrv);
0083 void eisa_driver_unregister (struct eisa_driver *edrv);
0084
0085 Clear enough ?
0086
0087 ::
0088
0089 struct eisa_device_id {
0090 char sig[EISA_SIG_LEN];
0091 unsigned long driver_data;
0092 };
0093
0094 struct eisa_driver {
0095 const struct eisa_device_id *id_table;
0096 struct device_driver driver;
0097 };
0098
0099 =============== ====================================================
0100 id_table an array of NULL terminated EISA id strings,
0101 followed by an empty string. Each string can
0102 optionally be paired with a driver-dependent value
0103 (driver_data).
0104
0105 driver a generic driver, such as described in
0106 Documentation/driver-api/driver-model/driver.rst. Only .name,
0107 .probe and .remove members are mandatory.
0108 =============== ====================================================
0109
0110 An example is the 3c59x driver::
0111
0112 static struct eisa_device_id vortex_eisa_ids[] = {
0113 { "TCM5920", EISA_3C592_OFFSET },
0114 { "TCM5970", EISA_3C597_OFFSET },
0115 { "" }
0116 };
0117
0118 static struct eisa_driver vortex_eisa_driver = {
0119 .id_table = vortex_eisa_ids,
0120 .driver = {
0121 .name = "3c59x",
0122 .probe = vortex_eisa_probe,
0123 .remove = vortex_eisa_remove
0124 }
0125 };
0126
0127 Device
0128 ======
0129
0130 The sysfs framework calls .probe and .remove functions upon device
0131 discovery and removal (note that the .remove function is only called
0132 when driver is built as a module).
0133
0134 Both functions are passed a pointer to a 'struct device', which is
0135 encapsulated in a 'struct eisa_device' described as follows::
0136
0137 struct eisa_device {
0138 struct eisa_device_id id;
0139 int slot;
0140 int state;
0141 unsigned long base_addr;
0142 struct resource res[EISA_MAX_RESOURCES];
0143 u64 dma_mask;
0144 struct device dev; /* generic device */
0145 };
0146
0147 ======== ============================================================
0148 id EISA id, as read from device. id.driver_data is set from the
0149 matching driver EISA id.
0150 slot slot number which the device was detected on
0151 state set of flags indicating the state of the device. Current
0152 flags are EISA_CONFIG_ENABLED and EISA_CONFIG_FORCED.
0153 res set of four 256 bytes I/O regions allocated to this device
0154 dma_mask DMA mask set from the parent device.
0155 dev generic device (see Documentation/driver-api/driver-model/device.rst)
0156 ======== ============================================================
0157
0158 You can get the 'struct eisa_device' from 'struct device' using the
0159 'to_eisa_device' macro.
0160
0161 Misc stuff
0162 ==========
0163
0164 ::
0165
0166 void eisa_set_drvdata (struct eisa_device *edev, void *data);
0167
0168 Stores data into the device's driver_data area.
0169
0170 ::
0171
0172 void *eisa_get_drvdata (struct eisa_device *edev):
0173
0174 Gets the pointer previously stored into the device's driver_data area.
0175
0176 ::
0177
0178 int eisa_get_region_index (void *addr);
0179
0180 Returns the region number (0 <= x < EISA_MAX_RESOURCES) of a given
0181 address.
0182
0183 Kernel parameters
0184 =================
0185
0186 eisa_bus.enable_dev
0187 A comma-separated list of slots to be enabled, even if the firmware
0188 set the card as disabled. The driver must be able to properly
0189 initialize the device in such conditions.
0190
0191 eisa_bus.disable_dev
0192 A comma-separated list of slots to be enabled, even if the firmware
0193 set the card as enabled. The driver won't be called to handle this
0194 device.
0195
0196 virtual_root.force_probe
0197 Force the probing code to probe EISA slots even when it cannot find an
0198 EISA compliant mainboard (nothing appears on slot 0). Defaults to 0
0199 (don't force), and set to 1 (force probing) when either
0200 CONFIG_ALPHA_JENSEN or CONFIG_EISA_VLB_PRIMING are set.
0201
0202 Random notes
0203 ============
0204
0205 Converting an EISA driver to the new API mostly involves *deleting*
0206 code (since probing is now in the core EISA code). Unfortunately, most
0207 drivers share their probing routine between ISA, and EISA. Special
0208 care must be taken when ripping out the EISA code, so other busses
0209 won't suffer from these surgical strikes...
0210
0211 You *must not* expect any EISA device to be detected when returning
0212 from eisa_driver_register, since the chances are that the bus has not
0213 yet been probed. In fact, that's what happens most of the time (the
0214 bus root driver usually kicks in rather late in the boot process).
0215 Unfortunately, most drivers are doing the probing by themselves, and
0216 expect to have explored the whole machine when they exit their probe
0217 routine.
0218
0219 For example, switching your favorite EISA SCSI card to the "hotplug"
0220 model is "the right thing"(tm).
0221
0222 Thanks
0223 ======
0224
0225 I'd like to thank the following people for their help:
0226
0227 - Xavier Benigni for lending me a wonderful Alpha Jensen,
0228 - James Bottomley, Jeff Garzik for getting this stuff into the kernel,
0229 - Andries Brouwer for contributing numerous EISA ids,
0230 - Catrin Jones for coping with far too many machines at home.
