mirror of
https://github.com/edk2-porting/linux-next.git
synced 2024-12-24 13:13:57 +08:00
9a4aa7bfce
Each text file under Documentation follows a different format. Some doesn't even have titles! Change its representation to follow the adopted standard, using ReST markups for it to be parseable by Sphinx: - Use a markup for document title; - use :Author: and :Last updated: for authorship; - adjust whitespaces where needed; - mark literal blocks; - fix a few subtitle markups. Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
293 lines
7.0 KiB
Plaintext
293 lines
7.0 KiB
Plaintext
=================================
|
|
Linux Plug and Play Documentation
|
|
=================================
|
|
|
|
:Author: 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)
|
|
|