aboutsummaryrefslogtreecommitdiffstats
path: root/Documentation/driver-model/platform.txt
diff options
context:
space:
mode:
authorLinus Torvalds <torvalds@ppc970.osdl.org>2005-04-16 18:20:36 -0400
committerLinus Torvalds <torvalds@ppc970.osdl.org>2005-04-16 18:20:36 -0400
commit1da177e4c3f41524e886b7f1b8a0c1fc7321cac2 (patch)
tree0bba044c4ce775e45a88a51686b5d9f90697ea9d /Documentation/driver-model/platform.txt
Linux-2.6.12-rc2v2.6.12-rc2
Initial git repository build. I'm not bothering with the full history, even though we have it. We can create a separate "historical" git archive of that later if we want to, and in the meantime it's about 3.2GB when imported into git - space that would just make the early git days unnecessarily complicated, when we don't have a lot of good infrastructure for it. Let it rip!
Diffstat (limited to 'Documentation/driver-model/platform.txt')
-rw-r--r--Documentation/driver-model/platform.txt99
1 files changed, 99 insertions, 0 deletions
diff --git a/Documentation/driver-model/platform.txt b/Documentation/driver-model/platform.txt
new file mode 100644
index 000000000000..5eee3e0bfc4c
--- /dev/null
+++ b/Documentation/driver-model/platform.txt
@@ -0,0 +1,99 @@
1Platform Devices and Drivers
2~~~~~~~~~~~~~~~~~~~~~~~~~~~~
3
4Platform devices
5~~~~~~~~~~~~~~~~
6Platform devices are devices that typically appear as autonomous
7entities in the system. This includes legacy port-based devices and
8host bridges to peripheral buses.
9
10
11Platform drivers
12~~~~~~~~~~~~~~~~
13Drivers for platform devices are typically very simple and
14unstructured. Either the device was present at a particular I/O port
15and the driver was loaded, or it was not. There was no possibility
16of hotplugging or alternative discovery besides probing at a specific
17I/O address and expecting a specific response.
18
19
20Other Architectures, Modern Firmware, and new Platforms
21~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
22These devices are not always at the legacy I/O ports. This is true on
23other architectures and on some modern architectures. In most cases,
24the drivers are modified to discover the devices at other well-known
25ports for the given platform. However, the firmware in these systems
26does usually know where exactly these devices reside, and in some
27cases, it's the only way of discovering them.
28
29
30The Platform Bus
31~~~~~~~~~~~~~~~~
32A platform bus has been created to deal with these issues. First and
33foremost, it groups all the legacy devices under a common bus, and
34gives them a common parent if they don't already have one.
35
36But, besides the organizational benefits, the platform bus can also
37accommodate firmware-based enumeration.
38
39
40Device Discovery
41~~~~~~~~~~~~~~~~
42The platform bus has no concept of probing for devices. Devices
43discovery is left up to either the legacy drivers or the
44firmware. These entities are expected to notify the platform of
45devices that it discovers via the bus's add() callback:
46
47 platform_bus.add(parent,bus_id).
48
49
50Bus IDs
51~~~~~~~
52Bus IDs are the canonical names for the devices. There is no globally
53standard addressing mechanism for legacy devices. In the IA-32 world,
54we have Pnp IDs to use, as well as the legacy I/O ports. However,
55neither tell what the device really is or have any meaning on other
56platforms.
57
58Since both PnP IDs and the legacy I/O ports (and other standard I/O
59ports for specific devices) have a 1:1 mapping, we map the
60platform-specific name or identifier to a generic name (at least
61within the scope of the kernel).
62
63For example, a serial driver might find a device at I/O 0x3f8. The
64ACPI firmware might also discover a device with PnP ID (_HID)
65PNP0501. Both correspond to the same device and should be mapped to the
66canonical name 'serial'.
67
68The bus_id field should be a concatenation of the canonical name and
69the instance of that type of device. For example, the device at I/O
70port 0x3f8 should have a bus_id of "serial0". This places the
71responsibility of enumerating devices of a particular type up to the
72discovery mechanism. But, they are the entity that should know best
73(as opposed to the platform bus driver).
74
75
76Drivers
77~~~~~~~
78Drivers for platform devices should have a name that is the same as
79the canonical name of the devices they support. This allows the
80platform bus driver to do simple matching with the basic data
81structures to determine if a driver supports a certain device.
82
83For example, a legacy serial driver should have a name of 'serial' and
84register itself with the platform bus.
85
86
87Driver Binding
88~~~~~~~~~~~~~~
89Legacy drivers assume they are bound to the device once they start up
90and probe an I/O port. Divorcing them from this will be a difficult
91process. However, that shouldn't prevent us from implementing
92firmware-based enumeration.
93
94The firmware should notify the platform bus about devices before the
95legacy drivers have had a chance to load. Once the drivers are loaded,
96they driver model core will attempt to bind the driver to any
97previously-discovered devices. Once that has happened, it will be free
98to discover any other devices it pleases.
99