Based on kernel version 2.6.38. Page generated on 2011-03-22 22:18 EST.
1 Platform Devices and Drivers 2 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 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 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 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 19 registers will still be directly addressable. 20 21 Platform devices are given a name, used in driver binding, and a 22 list of resources such as addresses and IRQs. 23 24 struct platform_device { 25 const char *name; 26 u32 id; 27 struct device dev; 28 u32 num_resources; 29 struct resource *resource; 30 }; 31 32 33 Platform drivers 34 ~~~~~~~~~~~~~~~~ 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 51 Note that probe() should general verify that the specified device hardware 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 66 67 Device Enumeration 68 ~~~~~~~~~~~~~~~~~~ 69 As a rule, platform specific (and often board-specific) setup code will 70 register 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 76 The general rule is to register only those devices that actually exist, 77 but in some cases extra devices might be registered. For example, a kernel 78 might be configured to work with an external network adapter that might not 79 be populated on all boards, or likewise to work with an integrated controller 80 that some boards might not hook up to any peripherals. 81 82 In some cases, boot firmware will export tables describing the devices 83 that are populated on a given board. Without such tables, often the 84 only way for system setup code to set up the correct devices is to build 85 a kernel for a specific target board. Such board-specific kernels are 86 common with embedded and custom systems development. 87 88 In many cases, the memory and IRQ resources associated with the platform 89 device are not enough to let the device's driver work. Board setup code 90 will often provide additional information using the device's platform_data 91 field to hold additional information. 92 93 Embedded systems frequently need one or more clocks for platform devices, 94 which are normally kept off until they're actively needed (to save power). 95 System setup also associates those clocks with the device, so that that 96 calls to clk_get(&pdev->dev, clock_name) return them as needed. 97 98 99 Legacy Drivers: Device Probing 100 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 101 Some drivers are not fully converted to the driver model, because they take 102 on a non-driver role: the driver registers its platform device, rather than 103 leaving that for system infrastructure. Such drivers can't be hotplugged 104 or coldplugged, since those mechanisms require device creation to be in a 105 different system component than the driver. 106 107 The only "good" reason for this is to handle older system designs which, like 108 original IBM PCs, rely on error-prone "probe-the-hardware" models for hardware 109 configuration. Newer systems have largely abandoned that model, in favor of 110 bus-level support for dynamic configuration (PCI, USB), or device tables 111 provided by the boot firmware (e.g. PNPACPI on x86). There are too many 112 conflicting options about what might be where, and even educated guesses by 113 an operating system will be wrong often enough to make trouble. 114 115 This style of driver is discouraged. If you're updating such a driver, 116 please try to move the device enumeration to a more appropriate location, 117 outside the driver. This will usually be cleanup, since such drivers 118 tend to already have "normal" modes, such as ones using device nodes that 119 were created by PNP or by platform device setup. 120 121 None the less, there are some APIs to support such legacy drivers. Avoid 122 using these calls except with such hotplug-deficient drivers. 123 124 struct platform_device *platform_device_alloc( 125 const char *name, int id); 126 127 You can use platform_device_alloc() to dynamically allocate a device, which 128 you will then initialize with resources and platform_device_register(). 129 A better solution is usually: 130 131 struct platform_device *platform_device_register_simple( 132 const char *name, int id, 133 struct resource *res, unsigned int nres); 134 135 You can use platform_device_register_simple() as a one-step call to allocate 136 and register a device. 137 138 139 Device Naming and Driver Binding 140 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 141 The platform_device.dev.bus_id is the canonical name for the devices. 142 It's built from two components: 143 144 * platform_device.name ... which is also used to for driver matching. 145 146 * platform_device.id ... the device instance number, or else "-1" 147 to indicate there's only one. 148 149 These are concatenated, so name/id "serial"/0 indicates bus_id "serial.0", and 150 "serial/3" indicates bus_id "serial.3"; both would use the platform_driver 151 named "serial". While "my_rtc"/-1 would be bus_id "my_rtc" (no instance id) 152 and use the platform_driver called "my_rtc". 153 154 Driver binding is performed automatically by the driver core, invoking 155 driver probe() after finding a match between device and driver. If the 156 probe() succeeds, the driver and device are bound as usual. There are 157 three different ways to find such a match: 158 159 - 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. 162 163 - 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. 166 167 - Registering a driver using platform_driver_probe() works just like 168 using platform_driver_register(), except that the driver won't 169 be probed later if another device registers. (Which is OK, since 170 this interface is only for use with non-hotpluggable devices.) 171 172 173 Early Platform Devices and Drivers 174 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 175 The early platform interfaces provide platform data to platform device 176 drivers early on during the system boot. The code is built on top of the 177 early_param() command line parsing and can be executed very early on. 178 179 Example: "earlyprintk" class early serial console in 6 steps 180 181 1. Registering early platform device data 182 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 183 The architecture code registers platform device data using the function 184 early_platform_add_devices(). In the case of early serial console this 185 should be hardware configuration for the serial port. Devices registered 186 at this point will later on be matched against early platform drivers. 187 188 2. Parsing kernel command line 189 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 190 The architecture code calls parse_early_param() to parse the kernel 191 command line. This will execute all matching early_param() callbacks. 192 User specified early platform devices will be registered at this point. 193 For the early serial console case the user can specify port on the 194 kernel command line as "earlyprintk=serial.0" where "earlyprintk" is 195 the class string, "serial" is the name of the platform driver and 196 0 is the platform device id. If the id is -1 then the dot and the 197 id can be omitted. 198 199 3. Installing early platform drivers belonging to a certain class 200 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 201 The architecture code may optionally force registration of all early 202 platform drivers belonging to a certain class using the function 203 early_platform_driver_register_all(). User specified devices from 204 step 2 have priority over these. This step is omitted by the serial 205 driver example since the early serial driver code should be disabled 206 unless the user has specified port on the kernel command line. 207 208 4. Early platform driver registration 209 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 210 Compiled-in platform drivers making use of early_platform_init() are 211 automatically registered during step 2 or 3. The serial driver example 212 should use early_platform_init("earlyprintk", &platform_driver). 213 214 5. Probing of early platform drivers belonging to a certain class 215 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 216 The architecture code calls early_platform_driver_probe() to match 217 registered early platform devices associated with a certain class with 218 registered early platform drivers. Matched devices will get probed(). 219 This step can be executed at any point during the early boot. As soon 220 as possible may be good for the serial port case. 221 222 6. Inside the early platform driver probe() 223 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 224 The driver code needs to take special care during early boot, especially 225 when it comes to memory allocation and interrupt registration. The code 226 in the probe() function can use is_early_platform_device() to check if 227 it is called at early platform device or at the regular platform device 228 time. The early serial driver performs register_console() at this point. 229 230 For further information, see <linux/platform_device.h>.