About Kernel Documentation Linux Kernel Contact Linux Resources Linux Blog

Documentation / eisa.txt




Custom Search

Based on kernel version 3.13. Page generated on 2014-01-20 22:02 EST.

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 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 <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. 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-dependent 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). Defaults 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, 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.
Hide Line Numbers
About Kernel Documentation Linux Kernel Contact Linux Resources Linux Blog

Information is copyright its respective author. All material is available from the Linux Kernel Source distributed under a GPL License. This page is provided as a free service by mjmwired.net.