Root/
| 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>. |
| 231 |
Branches:
ben-wpan
ben-wpan-stefan
javiroman/ks7010
jz-2.6.34
jz-2.6.34-rc5
jz-2.6.34-rc6
jz-2.6.34-rc7
jz-2.6.35
jz-2.6.36
jz-2.6.37
jz-2.6.38
jz-2.6.39
jz-3.0
jz-3.1
jz-3.11
jz-3.12
jz-3.13
jz-3.15
jz-3.16
jz-3.18-dt
jz-3.2
jz-3.3
jz-3.4
jz-3.5
jz-3.6
jz-3.6-rc2-pwm
jz-3.9
jz-3.9-clk
jz-3.9-rc8
jz47xx
jz47xx-2.6.38
master
Tags:
od-2011-09-04
od-2011-09-18
v2.6.34-rc5
v2.6.34-rc6
v2.6.34-rc7
v3.9
