1============================
2Platform Devices and Drivers
3============================
4
5See <linux/platform_device.h> for the driver model interface to the
6platform bus:  platform_device, and platform_driver.  This pseudo-bus
7is used to connect devices on busses with minimal infrastructure,
8like those used to integrate peripherals on many system-on-chip
9processors, or some "legacy" PC interconnects; as opposed to large
10formally specified ones like PCI or USB.
11
12
13Platform devices
14~~~~~~~~~~~~~~~~
15Platform devices are devices that typically appear as autonomous
16entities in the system. This includes legacy port-based devices and
17host bridges to peripheral buses, and most controllers integrated
18into system-on-chip platforms.  What they usually have in common
19is direct addressing from a CPU bus.  Rarely, a platform_device will
20be connected through a segment of some other kind of bus; but its
21registers will still be directly addressable.
22
23Platform devices are given a name, used in driver binding, and a
24list of resources such as addresses and IRQs::
25
26  struct platform_device {
27	const char	*name;
28	u32		id;
29	struct device	dev;
30	u32		num_resources;
31	struct resource	*resource;
32  };
33
34
35Platform drivers
36~~~~~~~~~~~~~~~~
37Platform drivers follow the standard driver model convention, where
38discovery/enumeration is handled outside the drivers, and drivers
39provide probe() and remove() methods.  They support power management
40and shutdown notifications using the standard conventions::
41
42  struct platform_driver {
43	int (*probe)(struct platform_device *);
44	int (*remove)(struct platform_device *);
45	void (*shutdown)(struct platform_device *);
46	int (*suspend)(struct platform_device *, pm_message_t state);
47	int (*suspend_late)(struct platform_device *, pm_message_t state);
48	int (*resume_early)(struct platform_device *);
49	int (*resume)(struct platform_device *);
50	struct device_driver driver;
51  };
52
53Note that probe() should in general verify that the specified device hardware
54actually exists; sometimes platform setup code can't be sure.  The probing
55can use device resources, including clocks, and device platform_data.
56
57Platform drivers register themselves the normal way::
58
59	int platform_driver_register(struct platform_driver *drv);
60
61Or, in common situations where the device is known not to be hot-pluggable,
62the probe() routine can live in an init section to reduce the driver's
63runtime memory footprint::
64
65	int platform_driver_probe(struct platform_driver *drv,
66			  int (*probe)(struct platform_device *))
67
68Kernel modules can be composed of several platform drivers. The platform core
69provides helpers to register and unregister an array of drivers::
70
71	int __platform_register_drivers(struct platform_driver * const *drivers,
72				      unsigned int count, struct module *owner);
73	void platform_unregister_drivers(struct platform_driver * const *drivers,
74					 unsigned int count);
75
76If one of the drivers fails to register, all drivers registered up to that
77point will be unregistered in reverse order. Note that there is a convenience
78macro that passes THIS_MODULE as owner parameter::
79
80	#define platform_register_drivers(drivers, count)
81
82
83Device Enumeration
84~~~~~~~~~~~~~~~~~~
85As a rule, platform specific (and often board-specific) setup code will
86register platform devices::
87
88	int platform_device_register(struct platform_device *pdev);
89
90	int platform_add_devices(struct platform_device **pdevs, int ndev);
91
92The general rule is to register only those devices that actually exist,
93but in some cases extra devices might be registered.  For example, a kernel
94might be configured to work with an external network adapter that might not
95be populated on all boards, or likewise to work with an integrated controller
96that some boards might not hook up to any peripherals.
97
98In some cases, boot firmware will export tables describing the devices
99that are populated on a given board.   Without such tables, often the
100only way for system setup code to set up the correct devices is to build
101a kernel for a specific target board.  Such board-specific kernels are
102common with embedded and custom systems development.
103
104In many cases, the memory and IRQ resources associated with the platform
105device are not enough to let the device's driver work.  Board setup code
106will often provide additional information using the device's platform_data
107field to hold additional information.
108
109Embedded systems frequently need one or more clocks for platform devices,
110which are normally kept off until they're actively needed (to save power).
111System setup also associates those clocks with the device, so that that
112calls to clk_get(&pdev->dev, clock_name) return them as needed.
113
114
115Legacy Drivers:  Device Probing
116~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
117Some drivers are not fully converted to the driver model, because they take
118on a non-driver role:  the driver registers its platform device, rather than
119leaving that for system infrastructure.  Such drivers can't be hotplugged
120or coldplugged, since those mechanisms require device creation to be in a
121different system component than the driver.
122
123The only "good" reason for this is to handle older system designs which, like
124original IBM PCs, rely on error-prone "probe-the-hardware" models for hardware
125configuration.  Newer systems have largely abandoned that model, in favor of
126bus-level support for dynamic configuration (PCI, USB), or device tables
127provided by the boot firmware (e.g. PNPACPI on x86).  There are too many
128conflicting options about what might be where, and even educated guesses by
129an operating system will be wrong often enough to make trouble.
130
131This style of driver is discouraged.  If you're updating such a driver,
132please try to move the device enumeration to a more appropriate location,
133outside the driver.  This will usually be cleanup, since such drivers
134tend to already have "normal" modes, such as ones using device nodes that
135were created by PNP or by platform device setup.
136
137None the less, there are some APIs to support such legacy drivers.  Avoid
138using these calls except with such hotplug-deficient drivers::
139
140	struct platform_device *platform_device_alloc(
141			const char *name, int id);
142
143You can use platform_device_alloc() to dynamically allocate a device, which
144you will then initialize with resources and platform_device_register().
145A better solution is usually::
146
147	struct platform_device *platform_device_register_simple(
148			const char *name, int id,
149			struct resource *res, unsigned int nres);
150
151You can use platform_device_register_simple() as a one-step call to allocate
152and register a device.
153
154
155Device Naming and Driver Binding
156~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
157The platform_device.dev.bus_id is the canonical name for the devices.
158It's built from two components:
159
160    * platform_device.name ... which is also used to for driver matching.
161
162    * platform_device.id ... the device instance number, or else "-1"
163      to indicate there's only one.
164
165These are concatenated, so name/id "serial"/0 indicates bus_id "serial.0", and
166"serial/3" indicates bus_id "serial.3"; both would use the platform_driver
167named "serial".  While "my_rtc"/-1 would be bus_id "my_rtc" (no instance id)
168and use the platform_driver called "my_rtc".
169
170Driver binding is performed automatically by the driver core, invoking
171driver probe() after finding a match between device and driver.  If the
172probe() succeeds, the driver and device are bound as usual.  There are
173three different ways to find such a match:
174
175    - Whenever a device is registered, the drivers for that bus are
176      checked for matches.  Platform devices should be registered very
177      early during system boot.
178
179    - When a driver is registered using platform_driver_register(), all
180      unbound devices on that bus are checked for matches.  Drivers
181      usually register later during booting, or by module loading.
182
183    - Registering a driver using platform_driver_probe() works just like
184      using platform_driver_register(), except that the driver won't
185      be probed later if another device registers.  (Which is OK, since
186      this interface is only for use with non-hotpluggable devices.)
187
188
189Early Platform Devices and Drivers
190~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
191The early platform interfaces provide platform data to platform device
192drivers early on during the system boot. The code is built on top of the
193early_param() command line parsing and can be executed very early on.
194
195Example: "earlyprintk" class early serial console in 6 steps
196
1971. Registering early platform device data
198~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
199The architecture code registers platform device data using the function
200early_platform_add_devices(). In the case of early serial console this
201should be hardware configuration for the serial port. Devices registered
202at this point will later on be matched against early platform drivers.
203
2042. Parsing kernel command line
205~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
206The architecture code calls parse_early_param() to parse the kernel
207command line. This will execute all matching early_param() callbacks.
208User specified early platform devices will be registered at this point.
209For the early serial console case the user can specify port on the
210kernel command line as "earlyprintk=serial.0" where "earlyprintk" is
211the class string, "serial" is the name of the platform driver and
2120 is the platform device id. If the id is -1 then the dot and the
213id can be omitted.
214
2153. Installing early platform drivers belonging to a certain class
216~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
217The architecture code may optionally force registration of all early
218platform drivers belonging to a certain class using the function
219early_platform_driver_register_all(). User specified devices from
220step 2 have priority over these. This step is omitted by the serial
221driver example since the early serial driver code should be disabled
222unless the user has specified port on the kernel command line.
223
2244. Early platform driver registration
225~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
226Compiled-in platform drivers making use of early_platform_init() are
227automatically registered during step 2 or 3. The serial driver example
228should use early_platform_init("earlyprintk", &platform_driver).
229
2305. Probing of early platform drivers belonging to a certain class
231~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
232The architecture code calls early_platform_driver_probe() to match
233registered early platform devices associated with a certain class with
234registered early platform drivers. Matched devices will get probed().
235This step can be executed at any point during the early boot. As soon
236as possible may be good for the serial port case.
237
2386. Inside the early platform driver probe()
239~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
240The driver code needs to take special care during early boot, especially
241when it comes to memory allocation and interrupt registration. The code
242in the probe() function can use is_early_platform_device() to check if
243it is called at early platform device or at the regular platform device
244time. The early serial driver performs register_console() at this point.
245
246For further information, see <linux/platform_device.h>.
247