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