1fe34c89dSMauro Carvalho Chehab============================ 2fe34c89dSMauro Carvalho ChehabPlatform Devices and Drivers 3fe34c89dSMauro Carvalho Chehab============================ 4fe34c89dSMauro Carvalho Chehab 5fe34c89dSMauro Carvalho ChehabSee <linux/platform_device.h> for the driver model interface to the 6fe34c89dSMauro Carvalho Chehabplatform bus: platform_device, and platform_driver. This pseudo-bus 7fe34c89dSMauro Carvalho Chehabis used to connect devices on busses with minimal infrastructure, 8fe34c89dSMauro Carvalho Chehablike those used to integrate peripherals on many system-on-chip 9fe34c89dSMauro Carvalho Chehabprocessors, or some "legacy" PC interconnects; as opposed to large 10fe34c89dSMauro Carvalho Chehabformally specified ones like PCI or USB. 11fe34c89dSMauro Carvalho Chehab 12fe34c89dSMauro Carvalho Chehab 13fe34c89dSMauro Carvalho ChehabPlatform devices 14fe34c89dSMauro Carvalho Chehab~~~~~~~~~~~~~~~~ 15fe34c89dSMauro Carvalho ChehabPlatform devices are devices that typically appear as autonomous 16fe34c89dSMauro Carvalho Chehabentities in the system. This includes legacy port-based devices and 17fe34c89dSMauro Carvalho Chehabhost bridges to peripheral buses, and most controllers integrated 18fe34c89dSMauro Carvalho Chehabinto system-on-chip platforms. What they usually have in common 19fe34c89dSMauro Carvalho Chehabis direct addressing from a CPU bus. Rarely, a platform_device will 20fe34c89dSMauro Carvalho Chehabbe connected through a segment of some other kind of bus; but its 21fe34c89dSMauro Carvalho Chehabregisters will still be directly addressable. 22fe34c89dSMauro Carvalho Chehab 23fe34c89dSMauro Carvalho ChehabPlatform devices are given a name, used in driver binding, and a 24fe34c89dSMauro Carvalho Chehablist of resources such as addresses and IRQs:: 25fe34c89dSMauro Carvalho Chehab 26fe34c89dSMauro Carvalho Chehab struct platform_device { 27fe34c89dSMauro Carvalho Chehab const char *name; 28fe34c89dSMauro Carvalho Chehab u32 id; 29fe34c89dSMauro Carvalho Chehab struct device dev; 30fe34c89dSMauro Carvalho Chehab u32 num_resources; 31fe34c89dSMauro Carvalho Chehab struct resource *resource; 32fe34c89dSMauro Carvalho Chehab }; 33fe34c89dSMauro Carvalho Chehab 34fe34c89dSMauro Carvalho Chehab 35fe34c89dSMauro Carvalho ChehabPlatform drivers 36fe34c89dSMauro Carvalho Chehab~~~~~~~~~~~~~~~~ 37fe34c89dSMauro Carvalho ChehabPlatform drivers follow the standard driver model convention, where 38fe34c89dSMauro Carvalho Chehabdiscovery/enumeration is handled outside the drivers, and drivers 39fe34c89dSMauro Carvalho Chehabprovide probe() and remove() methods. They support power management 40fe34c89dSMauro Carvalho Chehaband shutdown notifications using the standard conventions:: 41fe34c89dSMauro Carvalho Chehab 42fe34c89dSMauro Carvalho Chehab struct platform_driver { 43fe34c89dSMauro Carvalho Chehab int (*probe)(struct platform_device *); 44fe34c89dSMauro Carvalho Chehab int (*remove)(struct platform_device *); 45fe34c89dSMauro Carvalho Chehab void (*shutdown)(struct platform_device *); 46fe34c89dSMauro Carvalho Chehab int (*suspend)(struct platform_device *, pm_message_t state); 47fe34c89dSMauro Carvalho Chehab int (*suspend_late)(struct platform_device *, pm_message_t state); 48fe34c89dSMauro Carvalho Chehab int (*resume_early)(struct platform_device *); 49fe34c89dSMauro Carvalho Chehab int (*resume)(struct platform_device *); 50fe34c89dSMauro Carvalho Chehab struct device_driver driver; 51fe34c89dSMauro Carvalho Chehab }; 52fe34c89dSMauro Carvalho Chehab 53fe34c89dSMauro Carvalho ChehabNote that probe() should in general verify that the specified device hardware 54fe34c89dSMauro Carvalho Chehabactually exists; sometimes platform setup code can't be sure. The probing 55fe34c89dSMauro Carvalho Chehabcan use device resources, including clocks, and device platform_data. 56fe34c89dSMauro Carvalho Chehab 57fe34c89dSMauro Carvalho ChehabPlatform drivers register themselves the normal way:: 58fe34c89dSMauro Carvalho Chehab 59fe34c89dSMauro Carvalho Chehab int platform_driver_register(struct platform_driver *drv); 60fe34c89dSMauro Carvalho Chehab 61fe34c89dSMauro Carvalho ChehabOr, in common situations where the device is known not to be hot-pluggable, 62fe34c89dSMauro Carvalho Chehabthe probe() routine can live in an init section to reduce the driver's 63fe34c89dSMauro Carvalho Chehabruntime memory footprint:: 64fe34c89dSMauro Carvalho Chehab 65fe34c89dSMauro Carvalho Chehab int platform_driver_probe(struct platform_driver *drv, 66fe34c89dSMauro Carvalho Chehab int (*probe)(struct platform_device *)) 67fe34c89dSMauro Carvalho Chehab 68fe34c89dSMauro Carvalho ChehabKernel modules can be composed of several platform drivers. The platform core 69fe34c89dSMauro Carvalho Chehabprovides helpers to register and unregister an array of drivers:: 70fe34c89dSMauro Carvalho Chehab 71fe34c89dSMauro Carvalho Chehab int __platform_register_drivers(struct platform_driver * const *drivers, 72fe34c89dSMauro Carvalho Chehab unsigned int count, struct module *owner); 73fe34c89dSMauro Carvalho Chehab void platform_unregister_drivers(struct platform_driver * const *drivers, 74fe34c89dSMauro Carvalho Chehab unsigned int count); 75fe34c89dSMauro Carvalho Chehab 76fe34c89dSMauro Carvalho ChehabIf one of the drivers fails to register, all drivers registered up to that 77fe34c89dSMauro Carvalho Chehabpoint will be unregistered in reverse order. Note that there is a convenience 78fe34c89dSMauro Carvalho Chehabmacro that passes THIS_MODULE as owner parameter:: 79fe34c89dSMauro Carvalho Chehab 80fe34c89dSMauro Carvalho Chehab #define platform_register_drivers(drivers, count) 81fe34c89dSMauro Carvalho Chehab 82fe34c89dSMauro Carvalho Chehab 83fe34c89dSMauro Carvalho ChehabDevice Enumeration 84fe34c89dSMauro Carvalho Chehab~~~~~~~~~~~~~~~~~~ 85fe34c89dSMauro Carvalho ChehabAs a rule, platform specific (and often board-specific) setup code will 86fe34c89dSMauro Carvalho Chehabregister platform devices:: 87fe34c89dSMauro Carvalho Chehab 88fe34c89dSMauro Carvalho Chehab int platform_device_register(struct platform_device *pdev); 89fe34c89dSMauro Carvalho Chehab 90fe34c89dSMauro Carvalho Chehab int platform_add_devices(struct platform_device **pdevs, int ndev); 91fe34c89dSMauro Carvalho Chehab 92fe34c89dSMauro Carvalho ChehabThe general rule is to register only those devices that actually exist, 93fe34c89dSMauro Carvalho Chehabbut in some cases extra devices might be registered. For example, a kernel 94fe34c89dSMauro Carvalho Chehabmight be configured to work with an external network adapter that might not 95fe34c89dSMauro Carvalho Chehabbe populated on all boards, or likewise to work with an integrated controller 96fe34c89dSMauro Carvalho Chehabthat some boards might not hook up to any peripherals. 97fe34c89dSMauro Carvalho Chehab 98fe34c89dSMauro Carvalho ChehabIn some cases, boot firmware will export tables describing the devices 99fe34c89dSMauro Carvalho Chehabthat are populated on a given board. Without such tables, often the 100fe34c89dSMauro Carvalho Chehabonly way for system setup code to set up the correct devices is to build 101fe34c89dSMauro Carvalho Chehaba kernel for a specific target board. Such board-specific kernels are 102fe34c89dSMauro Carvalho Chehabcommon with embedded and custom systems development. 103fe34c89dSMauro Carvalho Chehab 104fe34c89dSMauro Carvalho ChehabIn many cases, the memory and IRQ resources associated with the platform 105fe34c89dSMauro Carvalho Chehabdevice are not enough to let the device's driver work. Board setup code 106fe34c89dSMauro Carvalho Chehabwill often provide additional information using the device's platform_data 107fe34c89dSMauro Carvalho Chehabfield to hold additional information. 108fe34c89dSMauro Carvalho Chehab 109fe34c89dSMauro Carvalho ChehabEmbedded systems frequently need one or more clocks for platform devices, 110fe34c89dSMauro Carvalho Chehabwhich are normally kept off until they're actively needed (to save power). 111*105fbc22SRandy DunlapSystem setup also associates those clocks with the device, so that 112fe34c89dSMauro Carvalho Chehabcalls to clk_get(&pdev->dev, clock_name) return them as needed. 113fe34c89dSMauro Carvalho Chehab 114fe34c89dSMauro Carvalho Chehab 115fe34c89dSMauro Carvalho ChehabLegacy Drivers: Device Probing 116fe34c89dSMauro Carvalho Chehab~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 117fe34c89dSMauro Carvalho ChehabSome drivers are not fully converted to the driver model, because they take 118fe34c89dSMauro Carvalho Chehabon a non-driver role: the driver registers its platform device, rather than 119fe34c89dSMauro Carvalho Chehableaving that for system infrastructure. Such drivers can't be hotplugged 120fe34c89dSMauro Carvalho Chehabor coldplugged, since those mechanisms require device creation to be in a 121fe34c89dSMauro Carvalho Chehabdifferent system component than the driver. 122fe34c89dSMauro Carvalho Chehab 123fe34c89dSMauro Carvalho ChehabThe only "good" reason for this is to handle older system designs which, like 124fe34c89dSMauro Carvalho Chehaboriginal IBM PCs, rely on error-prone "probe-the-hardware" models for hardware 125fe34c89dSMauro Carvalho Chehabconfiguration. Newer systems have largely abandoned that model, in favor of 126fe34c89dSMauro Carvalho Chehabbus-level support for dynamic configuration (PCI, USB), or device tables 127fe34c89dSMauro Carvalho Chehabprovided by the boot firmware (e.g. PNPACPI on x86). There are too many 128fe34c89dSMauro Carvalho Chehabconflicting options about what might be where, and even educated guesses by 129fe34c89dSMauro Carvalho Chehaban operating system will be wrong often enough to make trouble. 130fe34c89dSMauro Carvalho Chehab 131fe34c89dSMauro Carvalho ChehabThis style of driver is discouraged. If you're updating such a driver, 132fe34c89dSMauro Carvalho Chehabplease try to move the device enumeration to a more appropriate location, 133fe34c89dSMauro Carvalho Chehaboutside the driver. This will usually be cleanup, since such drivers 134fe34c89dSMauro Carvalho Chehabtend to already have "normal" modes, such as ones using device nodes that 135fe34c89dSMauro Carvalho Chehabwere created by PNP or by platform device setup. 136fe34c89dSMauro Carvalho Chehab 137fe34c89dSMauro Carvalho ChehabNone the less, there are some APIs to support such legacy drivers. Avoid 138fe34c89dSMauro Carvalho Chehabusing these calls except with such hotplug-deficient drivers:: 139fe34c89dSMauro Carvalho Chehab 140fe34c89dSMauro Carvalho Chehab struct platform_device *platform_device_alloc( 141fe34c89dSMauro Carvalho Chehab const char *name, int id); 142fe34c89dSMauro Carvalho Chehab 143fe34c89dSMauro Carvalho ChehabYou can use platform_device_alloc() to dynamically allocate a device, which 144fe34c89dSMauro Carvalho Chehabyou will then initialize with resources and platform_device_register(). 145fe34c89dSMauro Carvalho ChehabA better solution is usually:: 146fe34c89dSMauro Carvalho Chehab 147fe34c89dSMauro Carvalho Chehab struct platform_device *platform_device_register_simple( 148fe34c89dSMauro Carvalho Chehab const char *name, int id, 149fe34c89dSMauro Carvalho Chehab struct resource *res, unsigned int nres); 150fe34c89dSMauro Carvalho Chehab 151fe34c89dSMauro Carvalho ChehabYou can use platform_device_register_simple() as a one-step call to allocate 152fe34c89dSMauro Carvalho Chehaband register a device. 153fe34c89dSMauro Carvalho Chehab 154fe34c89dSMauro Carvalho Chehab 155fe34c89dSMauro Carvalho ChehabDevice Naming and Driver Binding 156fe34c89dSMauro Carvalho Chehab~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 157fe34c89dSMauro Carvalho ChehabThe platform_device.dev.bus_id is the canonical name for the devices. 158fe34c89dSMauro Carvalho ChehabIt's built from two components: 159fe34c89dSMauro Carvalho Chehab 160fe34c89dSMauro Carvalho Chehab * platform_device.name ... which is also used to for driver matching. 161fe34c89dSMauro Carvalho Chehab 162fe34c89dSMauro Carvalho Chehab * platform_device.id ... the device instance number, or else "-1" 163fe34c89dSMauro Carvalho Chehab to indicate there's only one. 164fe34c89dSMauro Carvalho Chehab 165fe34c89dSMauro Carvalho ChehabThese are concatenated, so name/id "serial"/0 indicates bus_id "serial.0", and 166fe34c89dSMauro Carvalho Chehab"serial/3" indicates bus_id "serial.3"; both would use the platform_driver 167fe34c89dSMauro Carvalho Chehabnamed "serial". While "my_rtc"/-1 would be bus_id "my_rtc" (no instance id) 168fe34c89dSMauro Carvalho Chehaband use the platform_driver called "my_rtc". 169fe34c89dSMauro Carvalho Chehab 170fe34c89dSMauro Carvalho ChehabDriver binding is performed automatically by the driver core, invoking 171fe34c89dSMauro Carvalho Chehabdriver probe() after finding a match between device and driver. If the 172fe34c89dSMauro Carvalho Chehabprobe() succeeds, the driver and device are bound as usual. There are 173fe34c89dSMauro Carvalho Chehabthree different ways to find such a match: 174fe34c89dSMauro Carvalho Chehab 175fe34c89dSMauro Carvalho Chehab - Whenever a device is registered, the drivers for that bus are 176fe34c89dSMauro Carvalho Chehab checked for matches. Platform devices should be registered very 177fe34c89dSMauro Carvalho Chehab early during system boot. 178fe34c89dSMauro Carvalho Chehab 179fe34c89dSMauro Carvalho Chehab - When a driver is registered using platform_driver_register(), all 180fe34c89dSMauro Carvalho Chehab unbound devices on that bus are checked for matches. Drivers 181fe34c89dSMauro Carvalho Chehab usually register later during booting, or by module loading. 182fe34c89dSMauro Carvalho Chehab 183fe34c89dSMauro Carvalho Chehab - Registering a driver using platform_driver_probe() works just like 184fe34c89dSMauro Carvalho Chehab using platform_driver_register(), except that the driver won't 185fe34c89dSMauro Carvalho Chehab be probed later if another device registers. (Which is OK, since 186fe34c89dSMauro Carvalho Chehab this interface is only for use with non-hotpluggable devices.) 187fe34c89dSMauro Carvalho Chehab 188fe34c89dSMauro Carvalho Chehab 189fe34c89dSMauro Carvalho ChehabEarly Platform Devices and Drivers 190fe34c89dSMauro Carvalho Chehab~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 191fe34c89dSMauro Carvalho ChehabThe early platform interfaces provide platform data to platform device 192fe34c89dSMauro Carvalho Chehabdrivers early on during the system boot. The code is built on top of the 193fe34c89dSMauro Carvalho Chehabearly_param() command line parsing and can be executed very early on. 194fe34c89dSMauro Carvalho Chehab 195fe34c89dSMauro Carvalho ChehabExample: "earlyprintk" class early serial console in 6 steps 196fe34c89dSMauro Carvalho Chehab 197fe34c89dSMauro Carvalho Chehab1. Registering early platform device data 198fe34c89dSMauro Carvalho Chehab~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 199fe34c89dSMauro Carvalho ChehabThe architecture code registers platform device data using the function 200fe34c89dSMauro Carvalho Chehabearly_platform_add_devices(). In the case of early serial console this 201fe34c89dSMauro Carvalho Chehabshould be hardware configuration for the serial port. Devices registered 202fe34c89dSMauro Carvalho Chehabat this point will later on be matched against early platform drivers. 203fe34c89dSMauro Carvalho Chehab 204fe34c89dSMauro Carvalho Chehab2. Parsing kernel command line 205fe34c89dSMauro Carvalho Chehab~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 206fe34c89dSMauro Carvalho ChehabThe architecture code calls parse_early_param() to parse the kernel 207fe34c89dSMauro Carvalho Chehabcommand line. This will execute all matching early_param() callbacks. 208fe34c89dSMauro Carvalho ChehabUser specified early platform devices will be registered at this point. 209fe34c89dSMauro Carvalho ChehabFor the early serial console case the user can specify port on the 210fe34c89dSMauro Carvalho Chehabkernel command line as "earlyprintk=serial.0" where "earlyprintk" is 211fe34c89dSMauro Carvalho Chehabthe class string, "serial" is the name of the platform driver and 212fe34c89dSMauro Carvalho Chehab0 is the platform device id. If the id is -1 then the dot and the 213fe34c89dSMauro Carvalho Chehabid can be omitted. 214fe34c89dSMauro Carvalho Chehab 215fe34c89dSMauro Carvalho Chehab3. Installing early platform drivers belonging to a certain class 216fe34c89dSMauro Carvalho Chehab~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 217fe34c89dSMauro Carvalho ChehabThe architecture code may optionally force registration of all early 218fe34c89dSMauro Carvalho Chehabplatform drivers belonging to a certain class using the function 219fe34c89dSMauro Carvalho Chehabearly_platform_driver_register_all(). User specified devices from 220fe34c89dSMauro Carvalho Chehabstep 2 have priority over these. This step is omitted by the serial 221fe34c89dSMauro Carvalho Chehabdriver example since the early serial driver code should be disabled 222fe34c89dSMauro Carvalho Chehabunless the user has specified port on the kernel command line. 223fe34c89dSMauro Carvalho Chehab 224fe34c89dSMauro Carvalho Chehab4. Early platform driver registration 225fe34c89dSMauro Carvalho Chehab~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 226fe34c89dSMauro Carvalho ChehabCompiled-in platform drivers making use of early_platform_init() are 227fe34c89dSMauro Carvalho Chehabautomatically registered during step 2 or 3. The serial driver example 228fe34c89dSMauro Carvalho Chehabshould use early_platform_init("earlyprintk", &platform_driver). 229fe34c89dSMauro Carvalho Chehab 230fe34c89dSMauro Carvalho Chehab5. Probing of early platform drivers belonging to a certain class 231fe34c89dSMauro Carvalho Chehab~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 232fe34c89dSMauro Carvalho ChehabThe architecture code calls early_platform_driver_probe() to match 233fe34c89dSMauro Carvalho Chehabregistered early platform devices associated with a certain class with 234fe34c89dSMauro Carvalho Chehabregistered early platform drivers. Matched devices will get probed(). 235fe34c89dSMauro Carvalho ChehabThis step can be executed at any point during the early boot. As soon 236fe34c89dSMauro Carvalho Chehabas possible may be good for the serial port case. 237fe34c89dSMauro Carvalho Chehab 238fe34c89dSMauro Carvalho Chehab6. Inside the early platform driver probe() 239fe34c89dSMauro Carvalho Chehab~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 240fe34c89dSMauro Carvalho ChehabThe driver code needs to take special care during early boot, especially 241fe34c89dSMauro Carvalho Chehabwhen it comes to memory allocation and interrupt registration. The code 242fe34c89dSMauro Carvalho Chehabin the probe() function can use is_early_platform_device() to check if 243fe34c89dSMauro Carvalho Chehabit is called at early platform device or at the regular platform device 244fe34c89dSMauro Carvalho Chehabtime. The early serial driver performs register_console() at this point. 245fe34c89dSMauro Carvalho Chehab 246fe34c89dSMauro Carvalho ChehabFor further information, see <linux/platform_device.h>. 247