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