ia64/linux-2.6.18-xen.hg

annotate Documentation/pnp.txt @ 0:831230e53067

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