aboutsummaryrefslogtreecommitdiffstats
path: root/Documentation
diff options
context:
space:
mode:
authorDavid Brownell <david-b@pacbell.net>2006-11-17 02:30:14 -0500
committerGreg Kroah-Hartman <gregkh@suse.de>2006-12-01 17:52:02 -0500
commitc957b32406b73ed66d0f20ebab0cab25c848105d (patch)
treea90a76afe8096d071a7819ad91810019c410acc5 /Documentation
parentc67334fbdfbba533af767610cf3fde8a49710e62 (diff)
Documentation/driver-model/platform.txt update/rewrite
This is almost a rewrite of the driver-model/platform.txt documentation; the previous text was obsolete (for several years), evidently it never got updated to match the change from being a PC "legacy_bus" to the more widely used core bus for most embedded systems. Signed-off-by: David Brownell <dbrownell@users.sourceforge.net> Signed-off-by: Greg Kroah-Hartman <gregkh@suse.de>
Diffstat (limited to 'Documentation')
-rw-r--r--Documentation/driver-model/platform.txt204
1 files changed, 118 insertions, 86 deletions
diff --git a/Documentation/driver-model/platform.txt b/Documentation/driver-model/platform.txt
index 5eee3e0bfc4c..9f0bc3bfd776 100644
--- a/Documentation/driver-model/platform.txt
+++ b/Documentation/driver-model/platform.txt
@@ -1,99 +1,131 @@
1Platform Devices and Drivers 1Platform Devices and Drivers
2~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 2~~~~~~~~~~~~~~~~~~~~~~~~~~~~
3See <linux/platform_device.h> for the driver model interface to the
4platform bus: platform_device, and platform_driver. This pseudo-bus
5is used to connect devices on busses with minimal infrastructure,
6like those used to integrate peripherals on many system-on-chip
7processors, or some "legacy" PC interconnects; as opposed to large
8formally specified ones like PCI or USB.
9
3 10
4Platform devices 11Platform devices
5~~~~~~~~~~~~~~~~ 12~~~~~~~~~~~~~~~~
6Platform devices are devices that typically appear as autonomous 13Platform devices are devices that typically appear as autonomous
7entities in the system. This includes legacy port-based devices and 14entities in the system. This includes legacy port-based devices and
8host bridges to peripheral buses. 15host bridges to peripheral buses, and most controllers integrated
9 16into system-on-chip platforms. What they usually have in common
10 17is direct addressing from a CPU bus. Rarely, a platform_device will
11Platform drivers 18be connected through a segment of some other kind of bus; but its
12~~~~~~~~~~~~~~~~ 19registers will still be directly addressible.
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 20
21Platform devices are given a name, used in driver binding, and a
22list of resources such as addresses and IRQs.
19 23
20Other Architectures, Modern Firmware, and new Platforms 24struct platform_device {
21~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 25 const char *name;
22These devices are not always at the legacy I/O ports. This is true on 26 u32 id;
23other architectures and on some modern architectures. In most cases, 27 struct device dev;
24the drivers are modified to discover the devices at other well-known 28 u32 num_resources;
25ports for the given platform. However, the firmware in these systems 29 struct resource *resource;
26does usually know where exactly these devices reside, and in some 30};
27cases, it's the only way of discovering them.
28 31
29 32
30The Platform Bus 33Platform drivers
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~~~~~~~~~~~~~~~~ 34~~~~~~~~~~~~~~~~
42The platform bus has no concept of probing for devices. Devices 35Platform drivers follow the standard driver model convention, where
43discovery is left up to either the legacy drivers or the 36discovery/enumeration is handled outside the drivers, and drivers
44firmware. These entities are expected to notify the platform of 37provide probe() and remove() methods. They support power management
45devices that it discovers via the bus's add() callback: 38and shutdown notifications using the standard conventions.
46 39
47 platform_bus.add(parent,bus_id). 40struct platform_driver {
48 41 int (*probe)(struct platform_device *);
49 42 int (*remove)(struct platform_device *);
50Bus IDs 43 void (*shutdown)(struct platform_device *);
51~~~~~~~ 44 int (*suspend)(struct platform_device *, pm_message_t state);
52Bus IDs are the canonical names for the devices. There is no globally 45 int (*suspend_late)(struct platform_device *, pm_message_t state);
53standard addressing mechanism for legacy devices. In the IA-32 world, 46 int (*resume_early)(struct platform_device *);
54we have Pnp IDs to use, as well as the legacy I/O ports. However, 47 int (*resume)(struct platform_device *);
55neither tell what the device really is or have any meaning on other 48 struct device_driver driver;
56platforms. 49};
57 50
58Since both PnP IDs and the legacy I/O ports (and other standard I/O 51Note that probe() should general verify that the specified device hardware
59ports for specific devices) have a 1:1 mapping, we map the 52actually exists; sometimes platform setup code can't be sure. The probing
60platform-specific name or identifier to a generic name (at least 53can use device resources, including clocks, and device platform_data.
61within the scope of the kernel). 54
62 55Platform drivers register themselves the normal way:
63For example, a serial driver might find a device at I/O 0x3f8. The 56
64ACPI firmware might also discover a device with PnP ID (_HID) 57 int platform_driver_register(struct platform_driver *drv);
65PNP0501. Both correspond to the same device and should be mapped to the 58
66canonical name 'serial'. 59Or, in common situations where the device is known not to be hot-pluggable,
67 60the probe() routine can live in an init section to reduce the driver's
68The bus_id field should be a concatenation of the canonical name and 61runtime memory footprint:
69the instance of that type of device. For example, the device at I/O 62
70port 0x3f8 should have a bus_id of "serial0". This places the 63 int platform_driver_probe(struct platform_driver *drv,
71responsibility of enumerating devices of a particular type up to the 64 int (*probe)(struct platform_device *))
72discovery mechanism. But, they are the entity that should know best 65
73(as opposed to the platform bus driver). 66
74 67Device Enumeration
75 68~~~~~~~~~~~~~~~~~~
76Drivers 69As a rule, platform specific (and often board-specific) setup code wil
77~~~~~~~ 70register platform devices:
78Drivers for platform devices should have a name that is the same as 71
79the canonical name of the devices they support. This allows the 72 int platform_device_register(struct platform_device *pdev);
80platform bus driver to do simple matching with the basic data 73
81structures to determine if a driver supports a certain device. 74 int platform_add_devices(struct platform_device **pdevs, int ndev);
82 75
83For example, a legacy serial driver should have a name of 'serial' and 76The general rule is to register only those devices that actually exist,
84register itself with the platform bus. 77but in some cases extra devices might be registered. For example, a kernel
85 78might be configured to work with an external network adapter that might not
86 79be populated on all boards, or likewise to work with an integrated controller
87Driver Binding 80that some boards might not hook up to any peripherals.
88~~~~~~~~~~~~~~ 81
89Legacy drivers assume they are bound to the device once they start up 82In some cases, boot firmware will export tables describing the devices
90and probe an I/O port. Divorcing them from this will be a difficult 83that are populated on a given board. Without such tables, often the
91process. However, that shouldn't prevent us from implementing 84only way for system setup code to set up the correct devices is to build
92firmware-based enumeration. 85a kernel for a specific target board. Such board-specific kernels are
93 86common with embedded and custom systems development.
94The firmware should notify the platform bus about devices before the 87
95legacy drivers have had a chance to load. Once the drivers are loaded, 88In many cases, the memory and IRQ resources associated with the platform
96they driver model core will attempt to bind the driver to any 89device are not enough to let the device's driver work. Board setup code
97previously-discovered devices. Once that has happened, it will be free 90will often provide additional information using the device's platform_data
98to discover any other devices it pleases. 91field to hold additional information.
92
93Embedded systems frequently need one or more clocks for platform devices,
94which are normally kept off until they're actively needed (to save power).
95System setup also associates those clocks with the device, so that that
96calls to clk_get(&pdev->dev, clock_name) return them as needed.
97
98
99Device Naming and Driver Binding
100~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
101The platform_device.dev.bus_id is the canonical name for the devices.
102It's built from two components:
103
104 * platform_device.name ... which is also used to for driver matching.
105
106 * platform_device.id ... the device instance number, or else "-1"
107 to indicate there's only one.
108
109These are catenated, so name/id "serial"/0 indicates bus_id "serial.0", and
110"serial/3" indicates bus_id "serial.3"; both would use the platform_driver
111named "serial". While "my_rtc"/-1 would be bus_id "my_rtc" (no instance id)
112and use the platform_driver called "my_rtc".
113
114Driver binding is performed automatically by the driver core, invoking
115driver probe() after finding a match between device and driver. If the
116probe() succeeds, the driver and device are bound as usual. There are
117three different ways to find such a match:
118
119 - Whenever a device is registered, the drivers for that bus are
120 checked for matches. Platform devices should be registered very
121 early during system boot.
122
123 - When a driver is registered using platform_driver_register(), all
124 unbound devices on that bus are checked for matches. Drivers
125 usually register later during booting, or by module loading.
126
127 - Registering a driver using platform_driver_probe() works just like
128 using platform_driver_register(), except that the the driver won't
129 be probed later if another device registers. (Which is OK, since
130 this interface is only for use with non-hotpluggable devices.)
99 131