]>
Commit | Line | Data |
---|---|---|
1 | ================================= | |
2 | Linux Plug and Play Documentation | |
3 | ================================= | |
4 | ||
5 | :Author: Adam Belay <ambx1@neo.rr.com> | |
6 | :Last updated: Oct. 16, 2002 | |
7 | ||
8 | ||
9 | Overview | |
10 | -------- | |
11 | ||
12 | Plug and Play provides a means of detecting and setting resources for legacy or | |
13 | otherwise unconfigurable devices. The Linux Plug and Play Layer provides these | |
14 | services to compatible drivers. | |
15 | ||
16 | ||
17 | The User Interface | |
18 | ------------------ | |
19 | ||
20 | The Linux Plug and Play user interface provides a means to activate PnP devices | |
21 | for legacy and user level drivers that do not support Linux Plug and Play. The | |
22 | user interface is integrated into sysfs. | |
23 | ||
24 | In addition to the standard sysfs file the following are created in each | |
25 | device's directory: | |
26 | - id - displays a list of support EISA IDs | |
27 | - options - displays possible resource configurations | |
28 | - resources - displays currently allocated resources and allows resource changes | |
29 | ||
30 | activating a device | |
31 | ^^^^^^^^^^^^^^^^^^^ | |
32 | ||
33 | :: | |
34 | ||
35 | # echo "auto" > resources | |
36 | ||
37 | this will invoke the automatic resource config system to activate the device | |
38 | ||
39 | manually activating a device | |
40 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^ | |
41 | ||
42 | :: | |
43 | ||
44 | # echo "manual <depnum> <mode>" > resources | |
45 | ||
46 | <depnum> - the configuration number | |
47 | <mode> - static or dynamic | |
48 | static = for next boot | |
49 | dynamic = now | |
50 | ||
51 | disabling a device | |
52 | ^^^^^^^^^^^^^^^^^^ | |
53 | ||
54 | :: | |
55 | ||
56 | # echo "disable" > resources | |
57 | ||
58 | ||
59 | EXAMPLE: | |
60 | ||
61 | Suppose you need to activate the floppy disk controller. | |
62 | ||
63 | 1. change to the proper directory, in my case it is | |
64 | /driver/bus/pnp/devices/00:0f:: | |
65 | ||
66 | # cd /driver/bus/pnp/devices/00:0f | |
67 | # cat name | |
68 | PC standard floppy disk controller | |
69 | ||
70 | 2. check if the device is already active:: | |
71 | ||
72 | # cat resources | |
73 | DISABLED | |
74 | ||
75 | - Notice the string "DISABLED". This means the device is not active. | |
76 | ||
77 | 3. check the device's possible configurations (optional):: | |
78 | ||
79 | # cat options | |
80 | Dependent: 01 - Priority acceptable | |
81 | port 0x3f0-0x3f0, align 0x7, size 0x6, 16-bit address decoding | |
82 | port 0x3f7-0x3f7, align 0x0, size 0x1, 16-bit address decoding | |
83 | irq 6 | |
84 | dma 2 8-bit compatible | |
85 | Dependent: 02 - Priority acceptable | |
86 | port 0x370-0x370, align 0x7, size 0x6, 16-bit address decoding | |
87 | port 0x377-0x377, align 0x0, size 0x1, 16-bit address decoding | |
88 | irq 6 | |
89 | dma 2 8-bit compatible | |
90 | ||
91 | 4. now activate the device:: | |
92 | ||
93 | # echo "auto" > resources | |
94 | ||
95 | 5. finally check if the device is active:: | |
96 | ||
97 | # cat resources | |
98 | io 0x3f0-0x3f5 | |
99 | io 0x3f7-0x3f7 | |
100 | irq 6 | |
101 | dma 2 | |
102 | ||
103 | also there are a series of kernel parameters:: | |
104 | ||
105 | pnp_reserve_irq=irq1[,irq2] .... | |
106 | pnp_reserve_dma=dma1[,dma2] .... | |
107 | pnp_reserve_io=io1,size1[,io2,size2] .... | |
108 | pnp_reserve_mem=mem1,size1[,mem2,size2] .... | |
109 | ||
110 | ||
111 | ||
112 | The Unified Plug and Play Layer | |
113 | ------------------------------- | |
114 | ||
115 | All Plug and Play drivers, protocols, and services meet at a central location | |
116 | called the Plug and Play Layer. This layer is responsible for the exchange of | |
117 | information between PnP drivers and PnP protocols. Thus it automatically | |
118 | forwards commands to the proper protocol. This makes writing PnP drivers | |
119 | significantly easier. | |
120 | ||
121 | The following functions are available from the Plug and Play Layer: | |
122 | ||
123 | pnp_get_protocol | |
124 | increments the number of uses by one | |
125 | ||
126 | pnp_put_protocol | |
127 | deincrements the number of uses by one | |
128 | ||
129 | pnp_register_protocol | |
130 | use this to register a new PnP protocol | |
131 | ||
132 | pnp_unregister_protocol | |
133 | use this function to remove a PnP protocol from the Plug and Play Layer | |
134 | ||
135 | pnp_register_driver | |
136 | adds a PnP driver to the Plug and Play Layer | |
137 | ||
138 | this includes driver model integration | |
139 | returns zero for success or a negative error number for failure; count | |
140 | calls to the .add() method if you need to know how many devices bind to | |
141 | the driver | |
142 | ||
143 | pnp_unregister_driver | |
144 | removes a PnP driver from the Plug and Play Layer | |
145 | ||
146 | ||
147 | ||
148 | Plug and Play Protocols | |
149 | ----------------------- | |
150 | ||
151 | This section contains information for PnP protocol developers. | |
152 | ||
153 | The following Protocols are currently available in the computing world: | |
154 | ||
155 | - PNPBIOS: | |
156 | used for system devices such as serial and parallel ports. | |
157 | - ISAPNP: | |
158 | provides PnP support for the ISA bus | |
159 | - ACPI: | |
160 | among its many uses, ACPI provides information about system level | |
161 | devices. | |
162 | ||
163 | It is meant to replace the PNPBIOS. It is not currently supported by Linux | |
164 | Plug and Play but it is planned to be in the near future. | |
165 | ||
166 | ||
167 | Requirements for a Linux PnP protocol: | |
168 | 1. the protocol must use EISA IDs | |
169 | 2. the protocol must inform the PnP Layer of a device's current configuration | |
170 | ||
171 | - the ability to set resources is optional but preferred. | |
172 | ||
173 | The following are PnP protocol related functions: | |
174 | ||
175 | pnp_add_device | |
176 | use this function to add a PnP device to the PnP layer | |
177 | ||
178 | only call this function when all wanted values are set in the pnp_dev | |
179 | structure | |
180 | ||
181 | pnp_init_device | |
182 | call this to initialize the PnP structure | |
183 | ||
184 | pnp_remove_device | |
185 | call this to remove a device from the Plug and Play Layer. | |
186 | it will fail if the device is still in use. | |
187 | automatically will free mem used by the device and related structures | |
188 | ||
189 | pnp_add_id | |
190 | adds an EISA ID to the list of supported IDs for the specified device | |
191 | ||
192 | For more information consult the source of a protocol such as | |
193 | /drivers/pnp/pnpbios/core.c. | |
194 | ||
195 | ||
196 | ||
197 | Linux Plug and Play Drivers | |
198 | --------------------------- | |
199 | ||
200 | This section contains information for Linux PnP driver developers. | |
201 | ||
202 | The New Way | |
203 | ^^^^^^^^^^^ | |
204 | ||
205 | 1. first make a list of supported EISA IDS | |
206 | ||
207 | ex:: | |
208 | ||
209 | static const struct pnp_id pnp_dev_table[] = { | |
210 | /* Standard LPT Printer Port */ | |
211 | {.id = "PNP0400", .driver_data = 0}, | |
212 | /* ECP Printer Port */ | |
213 | {.id = "PNP0401", .driver_data = 0}, | |
214 | {.id = ""} | |
215 | }; | |
216 | ||
217 | Please note that the character 'X' can be used as a wild card in the function | |
218 | portion (last four characters). | |
219 | ||
220 | ex:: | |
221 | ||
222 | /* Unknown PnP modems */ | |
223 | { "PNPCXXX", UNKNOWN_DEV }, | |
224 | ||
225 | Supported PnP card IDs can optionally be defined. | |
226 | ex:: | |
227 | ||
228 | static const struct pnp_id pnp_card_table[] = { | |
229 | { "ANYDEVS", 0 }, | |
230 | { "", 0 } | |
231 | }; | |
232 | ||
233 | 2. Optionally define probe and remove functions. It may make sense not to | |
234 | define these functions if the driver already has a reliable method of detecting | |
235 | the resources, such as the parport_pc driver. | |
236 | ||
237 | ex:: | |
238 | ||
239 | static int | |
240 | serial_pnp_probe(struct pnp_dev * dev, const struct pnp_id *card_id, const | |
241 | struct pnp_id *dev_id) | |
242 | { | |
243 | . . . | |
244 | ||
245 | ex:: | |
246 | ||
247 | static void serial_pnp_remove(struct pnp_dev * dev) | |
248 | { | |
249 | . . . | |
250 | ||
251 | consult /drivers/serial/8250_pnp.c for more information. | |
252 | ||
253 | 3. create a driver structure | |
254 | ||
255 | ex:: | |
256 | ||
257 | static struct pnp_driver serial_pnp_driver = { | |
258 | .name = "serial", | |
259 | .card_id_table = pnp_card_table, | |
260 | .id_table = pnp_dev_table, | |
261 | .probe = serial_pnp_probe, | |
262 | .remove = serial_pnp_remove, | |
263 | }; | |
264 | ||
265 | * name and id_table cannot be NULL. | |
266 | ||
267 | 4. register the driver | |
268 | ||
269 | ex:: | |
270 | ||
271 | static int __init serial8250_pnp_init(void) | |
272 | { | |
273 | return pnp_register_driver(&serial_pnp_driver); | |
274 | } | |
275 | ||
276 | The Old Way | |
277 | ^^^^^^^^^^^ | |
278 | ||
279 | A series of compatibility functions have been created to make it easy to convert | |
280 | ISAPNP drivers. They should serve as a temporary solution only. | |
281 | ||
282 | They are as follows:: | |
283 | ||
284 | struct pnp_card *pnp_find_card(unsigned short vendor, | |
285 | unsigned short device, | |
286 | struct pnp_card *from) | |
287 | ||
288 | struct pnp_dev *pnp_find_dev(struct pnp_card *card, | |
289 | unsigned short vendor, | |
290 | unsigned short function, | |
291 | struct pnp_dev *from) | |
292 |