Contents of /alx-src/tags/kernel26-2.6.12-alx-r9/Documentation/eisa.txt
Parent Directory | Revision Log
Revision 630 -
(show annotations)
(download)
Wed Mar 4 11:03:09 2009 UTC (15 years, 6 months ago) by niro
File MIME type: text/plain
File size: 7290 byte(s)
Wed Mar 4 11:03:09 2009 UTC (15 years, 6 months ago) by niro
File MIME type: text/plain
File size: 7290 byte(s)
Tag kernel26-2.6.12-alx-r9
1 | EISA bus support (Marc Zyngier <maz@wild-wind.fr.eu.org>) |
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 avaible 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 <linux/eisa.h>, which depends |
38 | heavily on <linux/device.h>. |
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. Usualy 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 | optionnaly 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. |