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