diff options
Diffstat (limited to 'kernel/Documentation/pnp.txt')
| -rw-r--r-- | kernel/Documentation/pnp.txt | 251 |
1 files changed, 251 insertions, 0 deletions
diff --git a/kernel/Documentation/pnp.txt b/kernel/Documentation/pnp.txt new file mode 100644 index 000000000..763e4659b --- /dev/null +++ b/kernel/Documentation/pnp.txt @@ -0,0 +1,251 @@ +Linux Plug and Play Documentation +by Adam Belay <ambx1@neo.rr.com> +last updated: Oct. 16, 2002 +--------------------------------------------------------------------------------------- + + + +Overview +-------- + Plug and Play provides a means of detecting and setting resources for legacy or +otherwise unconfigurable devices. The Linux Plug and Play Layer provides these +services to compatible drivers. + + + +The User Interface +------------------ + The Linux Plug and Play user interface provides a means to activate PnP devices +for legacy and user level drivers that do not support Linux Plug and Play. The +user interface is integrated into sysfs. + +In addition to the standard sysfs file the following are created in each +device's directory: +id - displays a list of support EISA IDs +options - displays possible resource configurations +resources - displays currently allocated resources and allows resource changes + +-activating a device + +#echo "auto" > resources + +this will invoke the automatic resource config system to activate the device + +-manually activating a device + +#echo "manual <depnum> <mode>" > resources +<depnum> - the configuration number +<mode> - static or dynamic + static = for next boot + dynamic = now + +-disabling a device + +#echo "disable" > resources + + +EXAMPLE: + +Suppose you need to activate the floppy disk controller. +1.) change to the proper directory, in my case it is +/driver/bus/pnp/devices/00:0f +# cd /driver/bus/pnp/devices/00:0f +# cat name +PC standard floppy disk controller + +2.) check if the device is already active +# cat resources +DISABLED + +- Notice the string "DISABLED". This means the device is not active. + +3.) check the device's possible configurations (optional) +# cat options +Dependent: 01 - Priority acceptable + port 0x3f0-0x3f0, align 0x7, size 0x6, 16-bit address decoding + port 0x3f7-0x3f7, align 0x0, size 0x1, 16-bit address decoding + irq 6 + dma 2 8-bit compatible +Dependent: 02 - Priority acceptable + port 0x370-0x370, align 0x7, size 0x6, 16-bit address decoding + port 0x377-0x377, align 0x0, size 0x1, 16-bit address decoding + irq 6 + dma 2 8-bit compatible + +4.) now activate the device +# echo "auto" > resources + +5.) finally check if the device is active +# cat resources +io 0x3f0-0x3f5 +io 0x3f7-0x3f7 +irq 6 +dma 2 + +also there are a series of kernel parameters: +pnp_reserve_irq=irq1[,irq2] .... +pnp_reserve_dma=dma1[,dma2] .... +pnp_reserve_io=io1,size1[,io2,size2] .... +pnp_reserve_mem=mem1,size1[,mem2,size2] .... + + + +The Unified Plug and Play Layer +------------------------------- + All Plug and Play drivers, protocols, and services meet at a central location +called the Plug and Play Layer. This layer is responsible for the exchange of +information between PnP drivers and PnP protocols. Thus it automatically +forwards commands to the proper protocol. This makes writing PnP drivers +significantly easier. + +The following functions are available from the Plug and Play Layer: + +pnp_get_protocol +- increments the number of uses by one + +pnp_put_protocol +- deincrements the number of uses by one + +pnp_register_protocol +- use this to register a new PnP protocol + +pnp_unregister_protocol +- use this function to remove a PnP protocol from the Plug and Play Layer + +pnp_register_driver +- adds a PnP driver to the Plug and Play Layer +- this includes driver model integration +- returns zero for success or a negative error number for failure; count + calls to the .add() method if you need to know how many devices bind to + the driver + +pnp_unregister_driver +- removes a PnP driver from the Plug and Play Layer + + + +Plug and Play Protocols +----------------------- + This section contains information for PnP protocol developers. + +The following Protocols are currently available in the computing world: +- PNPBIOS: used for system devices such as serial and parallel ports. +- ISAPNP: provides PnP support for the ISA bus +- ACPI: among its many uses, ACPI provides information about system level +devices. +It is meant to replace the PNPBIOS. It is not currently supported by Linux +Plug and Play but it is planned to be in the near future. + + +Requirements for a Linux PnP protocol: +1.) the protocol must use EISA IDs +2.) the protocol must inform the PnP Layer of a device's current configuration +- the ability to set resources is optional but preferred. + +The following are PnP protocol related functions: + +pnp_add_device +- use this function to add a PnP device to the PnP layer +- only call this function when all wanted values are set in the pnp_dev +structure + +pnp_init_device +- call this to initialize the PnP structure + +pnp_remove_device +- call this to remove a device from the Plug and Play Layer. +- it will fail if the device is still in use. +- automatically will free mem used by the device and related structures + +pnp_add_id +- adds an EISA ID to the list of supported IDs for the specified device + +For more information consult the source of a protocol such as +/drivers/pnp/pnpbios/core.c. + + + +Linux Plug and Play Drivers +--------------------------- + This section contains information for Linux PnP driver developers. + +The New Way +........... +1.) first make a list of supported EISA IDS +ex: +static const struct pnp_id pnp_dev_table[] = { + /* Standard LPT Printer Port */ + {.id = "PNP0400", .driver_data = 0}, + /* ECP Printer Port */ + {.id = "PNP0401", .driver_data = 0}, + {.id = ""} +}; + +Please note that the character 'X' can be used as a wild card in the function +portion (last four characters). +ex: + /* Unknown PnP modems */ + { "PNPCXXX", UNKNOWN_DEV }, + +Supported PnP card IDs can optionally be defined. +ex: +static const struct pnp_id pnp_card_table[] = { + { "ANYDEVS", 0 }, + { "", 0 } +}; + +2.) Optionally define probe and remove functions. It may make sense not to +define these functions if the driver already has a reliable method of detecting +the resources, such as the parport_pc driver. +ex: +static int +serial_pnp_probe(struct pnp_dev * dev, const struct pnp_id *card_id, const + struct pnp_id *dev_id) +{ +. . . + +ex: +static void serial_pnp_remove(struct pnp_dev * dev) +{ +. . . + +consult /drivers/serial/8250_pnp.c for more information. + +3.) create a driver structure +ex: + +static struct pnp_driver serial_pnp_driver = { + .name = "serial", + .card_id_table = pnp_card_table, + .id_table = pnp_dev_table, + .probe = serial_pnp_probe, + .remove = serial_pnp_remove, +}; + +* name and id_table cannot be NULL. + +4.) register the driver +ex: + +static int __init serial8250_pnp_init(void) +{ + return pnp_register_driver(&serial_pnp_driver); +} + +The Old Way +........... + +A series of compatibility functions have been created to make it easy to convert +ISAPNP drivers. They should serve as a temporary solution only. + +They are as follows: + +struct pnp_card *pnp_find_card(unsigned short vendor, + unsigned short device, + struct pnp_card *from) + +struct pnp_dev *pnp_find_dev(struct pnp_card *card, + unsigned short vendor, + unsigned short function, + struct pnp_dev *from) + |