blob: 2a97320ee17f1d1b1c5a9b1efc138bbea4631f0e [file] [log] [blame]
Linus Torvalds1da177e2005-04-16 15:20:36 -07001Platform Devices and Drivers
2~~~~~~~~~~~~~~~~~~~~~~~~~~~~
David Brownellc957b322006-11-16 23:30:14 -08003See <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
Linus Torvalds1da177e2005-04-16 15:20:36 -070010
11Platform devices
12~~~~~~~~~~~~~~~~
13Platform devices are devices that typically appear as autonomous
14entities in the system. This includes legacy port-based devices and
David Brownellc957b322006-11-16 23:30:14 -080015host bridges to peripheral buses, and most controllers integrated
16into system-on-chip platforms. What they usually have in common
17is direct addressing from a CPU bus. Rarely, a platform_device will
18be connected through a segment of some other kind of bus; but its
Matt LaPlantea982ac02007-05-09 07:35:06 +020019registers will still be directly addressable.
David Brownellc957b322006-11-16 23:30:14 -080020
21Platform devices are given a name, used in driver binding, and a
22list of resources such as addresses and IRQs.
23
24struct platform_device {
25 const char *name;
26 u32 id;
27 struct device dev;
28 u32 num_resources;
29 struct resource *resource;
30};
Linus Torvalds1da177e2005-04-16 15:20:36 -070031
32
33Platform drivers
34~~~~~~~~~~~~~~~~
David Brownellc957b322006-11-16 23:30:14 -080035Platform drivers follow the standard driver model convention, where
36discovery/enumeration is handled outside the drivers, and drivers
37provide probe() and remove() methods. They support power management
38and shutdown notifications using the standard conventions.
39
40struct platform_driver {
41 int (*probe)(struct platform_device *);
42 int (*remove)(struct platform_device *);
43 void (*shutdown)(struct platform_device *);
44 int (*suspend)(struct platform_device *, pm_message_t state);
45 int (*suspend_late)(struct platform_device *, pm_message_t state);
46 int (*resume_early)(struct platform_device *);
47 int (*resume)(struct platform_device *);
48 struct device_driver driver;
49};
50
51Note that probe() should general verify that the specified device hardware
52actually exists; sometimes platform setup code can't be sure. The probing
53can use device resources, including clocks, and device platform_data.
54
55Platform drivers register themselves the normal way:
56
57 int platform_driver_register(struct platform_driver *drv);
58
59Or, in common situations where the device is known not to be hot-pluggable,
60the probe() routine can live in an init section to reduce the driver's
61runtime memory footprint:
62
63 int platform_driver_probe(struct platform_driver *drv,
64 int (*probe)(struct platform_device *))
Linus Torvalds1da177e2005-04-16 15:20:36 -070065
66
David Brownellc957b322006-11-16 23:30:14 -080067Device Enumeration
68~~~~~~~~~~~~~~~~~~
Erik Hovlandbe7d2f72007-02-17 19:29:21 +010069As a rule, platform specific (and often board-specific) setup code will
David Brownellc957b322006-11-16 23:30:14 -080070register platform devices:
71
72 int platform_device_register(struct platform_device *pdev);
73
74 int platform_add_devices(struct platform_device **pdevs, int ndev);
75
76The general rule is to register only those devices that actually exist,
77but in some cases extra devices might be registered. For example, a kernel
78might be configured to work with an external network adapter that might not
79be populated on all boards, or likewise to work with an integrated controller
80that some boards might not hook up to any peripherals.
81
82In some cases, boot firmware will export tables describing the devices
83that are populated on a given board. Without such tables, often the
84only way for system setup code to set up the correct devices is to build
85a kernel for a specific target board. Such board-specific kernels are
86common with embedded and custom systems development.
87
88In many cases, the memory and IRQ resources associated with the platform
89device are not enough to let the device's driver work. Board setup code
90will often provide additional information using the device's platform_data
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.
Linus Torvalds1da177e2005-04-16 15:20:36 -070097
98
David Brownelladfdebc2007-05-10 22:36:14 -070099Legacy Drivers: Device Probing
100~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
101Some drivers are not fully converted to the driver model, because they take
102on a non-driver role: the driver registers its platform device, rather than
103leaving that for system infrastructure. Such drivers can't be hotplugged
104or coldplugged, since those mechanisms require device creation to be in a
105different system component than the driver.
106
107The only "good" reason for this is to handle older system designs which, like
108original IBM PCs, rely on error-prone "probe-the-hardware" models for hardware
109configuration. Newer systems have largely abandoned that model, in favor of
110bus-level support for dynamic configuration (PCI, USB), or device tables
111provided by the boot firmware (e.g. PNPACPI on x86). There are too many
112conflicting options about what might be where, and even educated guesses by
113an operating system will be wrong often enough to make trouble.
114
115This style of driver is discouraged. If you're updating such a driver,
116please try to move the device enumeration to a more appropriate location,
117outside the driver. This will usually be cleanup, since such drivers
118tend to already have "normal" modes, such as ones using device nodes that
119were created by PNP or by platform device setup.
120
121None the less, there are some APIs to support such legacy drivers. Avoid
122using these calls except with such hotplug-deficient drivers.
123
124 struct platform_device *platform_device_alloc(
125 char *name, unsigned id);
126
127You can use platform_device_alloc() to dynamically allocate a device, which
128you will then initialize with resources and platform_device_register().
129A better solution is usually:
130
131 struct platform_device *platform_device_register_simple(
132 char *name, unsigned id,
133 struct resource *res, unsigned nres);
134
135You can use platform_device_register_simple() as a one-step call to allocate
136and register a device.
137
138
David Brownellc957b322006-11-16 23:30:14 -0800139Device Naming and Driver Binding
140~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
141The platform_device.dev.bus_id is the canonical name for the devices.
142It's built from two components:
Linus Torvalds1da177e2005-04-16 15:20:36 -0700143
David Brownellc957b322006-11-16 23:30:14 -0800144 * platform_device.name ... which is also used to for driver matching.
Linus Torvalds1da177e2005-04-16 15:20:36 -0700145
David Brownellc957b322006-11-16 23:30:14 -0800146 * platform_device.id ... the device instance number, or else "-1"
147 to indicate there's only one.
Linus Torvalds1da177e2005-04-16 15:20:36 -0700148
Erik Hovlandbe7d2f72007-02-17 19:29:21 +0100149These are concatenated, so name/id "serial"/0 indicates bus_id "serial.0", and
David Brownellc957b322006-11-16 23:30:14 -0800150"serial/3" indicates bus_id "serial.3"; both would use the platform_driver
151named "serial". While "my_rtc"/-1 would be bus_id "my_rtc" (no instance id)
152and use the platform_driver called "my_rtc".
Linus Torvalds1da177e2005-04-16 15:20:36 -0700153
David Brownellc957b322006-11-16 23:30:14 -0800154Driver binding is performed automatically by the driver core, invoking
155driver probe() after finding a match between device and driver. If the
156probe() succeeds, the driver and device are bound as usual. There are
157three different ways to find such a match:
Linus Torvalds1da177e2005-04-16 15:20:36 -0700158
David Brownellc957b322006-11-16 23:30:14 -0800159 - Whenever a device is registered, the drivers for that bus are
160 checked for matches. Platform devices should be registered very
161 early during system boot.
Linus Torvalds1da177e2005-04-16 15:20:36 -0700162
David Brownellc957b322006-11-16 23:30:14 -0800163 - When a driver is registered using platform_driver_register(), all
164 unbound devices on that bus are checked for matches. Drivers
165 usually register later during booting, or by module loading.
Linus Torvalds1da177e2005-04-16 15:20:36 -0700166
David Brownellc957b322006-11-16 23:30:14 -0800167 - Registering a driver using platform_driver_probe() works just like
Michael Opdenacker59c51592007-05-09 08:57:56 +0200168 using platform_driver_register(), except that the driver won't
David Brownellc957b322006-11-16 23:30:14 -0800169 be probed later if another device registers. (Which is OK, since
170 this interface is only for use with non-hotpluggable devices.)
Linus Torvalds1da177e2005-04-16 15:20:36 -0700171