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