| 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 | |