0001 =================================
0002 Linux Plug and Play Documentation
0003 =================================
0004
0005 :Author: Adam Belay <ambx1@neo.rr.com>
0006 :Last updated: Oct. 16, 2002
0007
0008
0009 Overview
0010 --------
0011
0012 Plug and Play provides a means of detecting and setting resources for legacy or
0013 otherwise unconfigurable devices. The Linux Plug and Play Layer provides these
0014 services to compatible drivers.
0015
0016
0017 The User Interface
0018 ------------------
0019
0020 The Linux Plug and Play user interface provides a means to activate PnP devices
0021 for legacy and user level drivers that do not support Linux Plug and Play. The
0022 user interface is integrated into sysfs.
0023
0024 In addition to the standard sysfs file the following are created in each
0025 device's directory:
0026 - id - displays a list of support EISA IDs
0027 - options - displays possible resource configurations
0028 - resources - displays currently allocated resources and allows resource changes
0029
0030 activating a device
0031 ^^^^^^^^^^^^^^^^^^^
0032
0033 ::
0034
0035 # echo "auto" > resources
0036
0037 this will invoke the automatic resource config system to activate the device
0038
0039 manually activating a device
0040 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
0041
0042 ::
0043
0044 # echo "manual <depnum> <mode>" > resources
0045
0046 <depnum> - the configuration number
0047 <mode> - static or dynamic
0048 static = for next boot
0049 dynamic = now
0050
0051 disabling a device
0052 ^^^^^^^^^^^^^^^^^^
0053
0054 ::
0055
0056 # echo "disable" > resources
0057
0058
0059 EXAMPLE:
0060
0061 Suppose you need to activate the floppy disk controller.
0062
0063 1. change to the proper directory, in my case it is
0064 /driver/bus/pnp/devices/00:0f::
0065
0066 # cd /driver/bus/pnp/devices/00:0f
0067 # cat name
0068 PC standard floppy disk controller
0069
0070 2. check if the device is already active::
0071
0072 # cat resources
0073 DISABLED
0074
0075 - Notice the string "DISABLED". This means the device is not active.
0076
0077 3. check the device's possible configurations (optional)::
0078
0079 # cat options
0080 Dependent: 01 - Priority acceptable
0081 port 0x3f0-0x3f0, align 0x7, size 0x6, 16-bit address decoding
0082 port 0x3f7-0x3f7, align 0x0, size 0x1, 16-bit address decoding
0083 irq 6
0084 dma 2 8-bit compatible
0085 Dependent: 02 - Priority acceptable
0086 port 0x370-0x370, align 0x7, size 0x6, 16-bit address decoding
0087 port 0x377-0x377, align 0x0, size 0x1, 16-bit address decoding
0088 irq 6
0089 dma 2 8-bit compatible
0090
0091 4. now activate the device::
0092
0093 # echo "auto" > resources
0094
0095 5. finally check if the device is active::
0096
0097 # cat resources
0098 io 0x3f0-0x3f5
0099 io 0x3f7-0x3f7
0100 irq 6
0101 dma 2
0102
0103 also there are a series of kernel parameters::
0104
0105 pnp_reserve_irq=irq1[,irq2] ....
0106 pnp_reserve_dma=dma1[,dma2] ....
0107 pnp_reserve_io=io1,size1[,io2,size2] ....
0108 pnp_reserve_mem=mem1,size1[,mem2,size2] ....
0109
0110
0111
0112 The Unified Plug and Play Layer
0113 -------------------------------
0114
0115 All Plug and Play drivers, protocols, and services meet at a central location
0116 called the Plug and Play Layer. This layer is responsible for the exchange of
0117 information between PnP drivers and PnP protocols. Thus it automatically
0118 forwards commands to the proper protocol. This makes writing PnP drivers
0119 significantly easier.
0120
0121 The following functions are available from the Plug and Play Layer:
0122
0123 pnp_get_protocol
0124 increments the number of uses by one
0125
0126 pnp_put_protocol
0127 deincrements the number of uses by one
0128
0129 pnp_register_protocol
0130 use this to register a new PnP protocol
0131
0132 pnp_unregister_protocol
0133 use this function to remove a PnP protocol from the Plug and Play Layer
0134
0135 pnp_register_driver
0136 adds a PnP driver to the Plug and Play Layer
0137
0138 this includes driver model integration
0139 returns zero for success or a negative error number for failure; count
0140 calls to the .add() method if you need to know how many devices bind to
0141 the driver
0142
0143 pnp_unregister_driver
0144 removes a PnP driver from the Plug and Play Layer
0145
0146
0147
0148 Plug and Play Protocols
0149 -----------------------
0150
0151 This section contains information for PnP protocol developers.
0152
0153 The following Protocols are currently available in the computing world:
0154
0155 - PNPBIOS:
0156 used for system devices such as serial and parallel ports.
0157 - ISAPNP:
0158 provides PnP support for the ISA bus
0159 - ACPI:
0160 among its many uses, ACPI provides information about system level
0161 devices.
0162
0163 It is meant to replace the PNPBIOS. It is not currently supported by Linux
0164 Plug and Play but it is planned to be in the near future.
0165
0166
0167 Requirements for a Linux PnP protocol:
0168 1. the protocol must use EISA IDs
0169 2. the protocol must inform the PnP Layer of a device's current configuration
0170
0171 - the ability to set resources is optional but preferred.
0172
0173 The following are PnP protocol related functions:
0174
0175 pnp_add_device
0176 use this function to add a PnP device to the PnP layer
0177
0178 only call this function when all wanted values are set in the pnp_dev
0179 structure
0180
0181 pnp_init_device
0182 call this to initialize the PnP structure
0183
0184 pnp_remove_device
0185 call this to remove a device from the Plug and Play Layer.
0186 it will fail if the device is still in use.
0187 automatically will free mem used by the device and related structures
0188
0189 pnp_add_id
0190 adds an EISA ID to the list of supported IDs for the specified device
0191
0192 For more information consult the source of a protocol such as
0193 /drivers/pnp/pnpbios/core.c.
0194
0195
0196
0197 Linux Plug and Play Drivers
0198 ---------------------------
0199
0200 This section contains information for Linux PnP driver developers.
0201
0202 The New Way
0203 ^^^^^^^^^^^
0204
0205 1. first make a list of supported EISA IDS
0206
0207 ex::
0208
0209 static const struct pnp_id pnp_dev_table[] = {
0210 /* Standard LPT Printer Port */
0211 {.id = "PNP0400", .driver_data = 0},
0212 /* ECP Printer Port */
0213 {.id = "PNP0401", .driver_data = 0},
0214 {.id = ""}
0215 };
0216
0217 Please note that the character 'X' can be used as a wild card in the function
0218 portion (last four characters).
0219
0220 ex::
0221
0222 /* Unknown PnP modems */
0223 { "PNPCXXX", UNKNOWN_DEV },
0224
0225 Supported PnP card IDs can optionally be defined.
0226 ex::
0227
0228 static const struct pnp_id pnp_card_table[] = {
0229 { "ANYDEVS", 0 },
0230 { "", 0 }
0231 };
0232
0233 2. Optionally define probe and remove functions. It may make sense not to
0234 define these functions if the driver already has a reliable method of detecting
0235 the resources, such as the parport_pc driver.
0236
0237 ex::
0238
0239 static int
0240 serial_pnp_probe(struct pnp_dev * dev, const struct pnp_id *card_id, const
0241 struct pnp_id *dev_id)
0242 {
0243 . . .
0244
0245 ex::
0246
0247 static void serial_pnp_remove(struct pnp_dev * dev)
0248 {
0249 . . .
0250
0251 consult /drivers/serial/8250_pnp.c for more information.
0252
0253 3. create a driver structure
0254
0255 ex::
0256
0257 static struct pnp_driver serial_pnp_driver = {
0258 .name = "serial",
0259 .card_id_table = pnp_card_table,
0260 .id_table = pnp_dev_table,
0261 .probe = serial_pnp_probe,
0262 .remove = serial_pnp_remove,
0263 };
0264
0265 * name and id_table cannot be NULL.
0266
0267 4. register the driver
0268
0269 ex::
0270
0271 static int __init serial8250_pnp_init(void)
0272 {
0273 return pnp_register_driver(&serial_pnp_driver);
0274 }
0275
0276 The Old Way
0277 ^^^^^^^^^^^
0278
0279 A series of compatibility functions have been created to make it easy to convert
0280 ISAPNP drivers. They should serve as a temporary solution only.
0281
0282 They are as follows::
0283
0284 struct pnp_dev *pnp_find_dev(struct pnp_card *card,
0285 unsigned short vendor,
0286 unsigned short function,
0287 struct pnp_dev *from)
0288
