1ISA Plug & Play support by Jaroslav Kysela <perex@suse.cz>
2==========================================================
3
4Interface /proc/isapnp
5======================
6
7Read commands:
8--------------
9
10No comment.
11
12Write commands:
13---------------
14
15With the write interface you can activate or modify the configuration of
16ISA Plug & Play devices.  It is mainly useful for drivers which have not
17been rewritten to use the ISA Plug & Play kernel support yet.
18
19card <idx> <vendor>	- select PnP device by vendor identification
20csn <CSN>		- select PnP device by CSN
21dev <idx> <logdev>	- select logical device
22auto			- run autoconfigure
23activate		- activate logical device
24deactivate		- deactivate logical device
25port <idx> <value>	- set port 0-7 to value
26irq <idx> <value>	- set IRQ 0-1 to value
27dma <idx> <value>	- set DMA 0-1 to value
28memory <idx> <value>	- set memory 0-3 to value
29poke <reg> <value>	- poke configuration byte to selected register
30pokew <reg> <value>	- poke configuration word to selected register
31poked <reg> <value>	- poke configuration dword to selected register
32allow_dma0 <value>	- allow dma channel 0 during auto activation: 0=off, 1=on
33
34Explanation:
35	- variable <idx> begins with zero
36	- variable <CSN> begins with one
37	- <vendor> is in the standard format 'ABC1234'
38	- <logdev> is in the standard format 'ABC1234'
39
40Example:
41
42cat > /proc/isapnp <<EOF
43card 0 CSC7537
44dev 0 CSC0000
45port 0 0x534
46port 1 0x388
47port 2 0x220
48irq 0 5
49dma 0 1
50dma 1 3
51poke 0x70 9
52activate
53logdev 0 CSC0001
54port 0 0x240
55activate
56EOF
57
58
59Information for developers
60==========================
61
62Finding a device
63----------------
64
65extern struct pci_bus *isapnp_find_card(unsigned short vendor,
66                                        unsigned short device,
67                                        struct pci_bus *from);
68
69This function finds an ISA PnP card.  For the vendor argument, the
70ISAPNP_VENDOR(a,b,c) macro should be used, where a,b,c are characters or
71integers.  For the device argument the ISAPNP_DEVICE(x) macro should be
72used, where x is an integer value.  Both vendor and device arguments
73can be taken from contents of the /proc/isapnp file.
74
75extern struct pci_dev *isapnp_find_dev(struct pci_bus *card,
76                                       unsigned short vendor,
77                                       unsigned short function,
78                                       struct pci_dev *from);
79
80This function finds an ISA PnP device. If card is NULL, then the global
81search mode is used (all devices are used for the searching).  Otherwise
82only devices which belong to the specified card are checked.  For the
83function number the ISAPNP_FUNCTION(x) macro can be used; it works
84similarly to the ISAPNP_DEVICE(x) macro.
85
86extern int isapnp_probe_cards(const struct isapnp_card_id *ids,
87                              int (*probe)(struct pci_bus *card,
88                              const struct isapnp_card_id *id));
89
90
91This function is a helper for drivers which need to use more than
92one device from an ISA PnP card.  The probe callback is called with
93appropriate arguments for each card.
94
95Example for ids parameter initialization:
96
97static struct isapnp_card_id card_ids[] __devinitdata = {
98	{
99        	ISAPNP_CARD_ID('A','D','V', 0x550a),
100                devs: {
101			ISAPNP_DEVICE_ID('A', 'D', 'V', 0x0010),
102			ISAPNP_DEVICE_ID('A', 'D', 'V', 0x0011)
103		},
104		driver_data: 0x1234,
105	},
106	{
107		ISAPNP_CARD_END,
108	}
109};
110ISAPNP_CARD_TABLE(card_ids);
111
112extern int isapnp_probe_devs(const struct isapnp_device_id *ids,
113                             int (*probe)(struct pci_bus *card,
114                             const struct isapnp_device_id *id));
115
116
117This function is a helper for drivers which need to use one
118device from an ISA PnP card.  The probe callback is called with
119appropriate arguments for each matched device.
120
121Example for ids parameter initialization:
122
123static struct isapnp_device_id device_ids[] __devinitdata = {
124	{ ISAPNP_DEVICE_SINGLE('E','S','S', 0x0968, 'E','S','S', 0x0968), },
125	{ ISAPNP_DEVICE_SINGLE_END, }
126};
127MODULE_DEVICE_TABLE(isapnp, device_ids);
128
129
130ISA PnP configuration
131=====================
132
133There are two ways in which the ISA PnP interface can be used.
134
135First way: low-level
136--------------------
137
138All ISA PNP configuration registers are accessible via the low-level
139isapnp_(read|write)_(byte|word|dword) functions.
140
141The function isapnp_cfg_begin() must be called before any lowlevel function.
142The function isapnp_cfg_end() must be always called after configuration
143otherwise the access to the ISA PnP configuration functions will be blocked.
144
145Second way: auto-configuration
146------------------------------
147
148This feature gives to the driver the real power of the ISA PnP driver.
149The function dev->prepare() initializes the resource members in the device
150structure.  This structure contains all resources set to auto configuration
151values after the initialization.  The device driver may modify some resources
152to skip the auto configuration for a given resource.
153
154Once the device structure contains all requested resource values, the function
155dev->activate() must be called to assign free resources to resource members
156with the auto configuration value.
157
158Function dev->activate() does:
159   - resources with the auto configuration value are configured
160   - the auto configuration is created using ISA PnP resource map
161   - the function writes configuration to ISA PnP configuration registers
162   - the function returns to the caller actual used resources
163
164When the device driver is removed, function dev->deactivate() has to be
165called to free all assigned resources.
166
167Example (game port initialization)
168==================================
169
170/*** initialization ***/
171
172	struct pci_dev *dev;
173
174	/* find the first game port, use standard PnP IDs */
175	dev = isapnp_find_dev(NULL,
176			      ISAPNP_VENDOR('P','N','P'),
177			      ISAPNP_FUNCTION(0xb02f),
178			      NULL);
179	if (!dev)
180		return -ENODEV;
181	if (dev->active)
182		return -EBUSY;
183	if (dev->prepare(dev)<0)
184		return -EAGAIN;
185	if (!(dev->resource[0].flags & IORESOURCE_IO))
186		return -ENODEV;
187	if (!dev->ro) {
188		/* override resource */
189		if (user_port != USER_PORT_AUTO_VALUE)
190			isapnp_resource_change(&dev->resource[0], user_port, 1);
191	}
192	if (dev->activate(dev)<0) {
193		printk("isapnp configure failed (out of resources?)\n");
194		return -ENOMEM;
195	}
196	user_port = dev->resource[0].start;		/* get real port */
197
198/*** deactivation ***/
199
200	/* to deactivate use: */
201 	if (dev)
202 		dev->deactivate(dev);
203