Back to home page

LXR

 
 

    


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