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