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