Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 1 | Platform Devices and Drivers |
| 2 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
David Brownell | c957b32 | 2006-11-16 23:30:14 -0800 | [diff] [blame] | 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 | |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 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 |
David Brownell | c957b32 | 2006-11-16 23:30:14 -0800 | [diff] [blame] | 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 addressible. |
| 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 | }; |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 31 | |
| 32 | |
| 33 | Platform drivers |
| 34 | ~~~~~~~~~~~~~~~~ |
David Brownell | c957b32 | 2006-11-16 23:30:14 -0800 | [diff] [blame] | 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 *)) |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 65 | |
| 66 | |
David Brownell | c957b32 | 2006-11-16 23:30:14 -0800 | [diff] [blame] | 67 | Device Enumeration |
| 68 | ~~~~~~~~~~~~~~~~~~ |
| 69 | As a rule, platform specific (and often board-specific) setup code wil |
| 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. |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 97 | |
| 98 | |
David Brownell | c957b32 | 2006-11-16 23:30:14 -0800 | [diff] [blame] | 99 | Device Naming and Driver Binding |
| 100 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 101 | The platform_device.dev.bus_id is the canonical name for the devices. |
| 102 | It's built from two components: |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 103 | |
David Brownell | c957b32 | 2006-11-16 23:30:14 -0800 | [diff] [blame] | 104 | * platform_device.name ... which is also used to for driver matching. |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 105 | |
David Brownell | c957b32 | 2006-11-16 23:30:14 -0800 | [diff] [blame] | 106 | * platform_device.id ... the device instance number, or else "-1" |
| 107 | to indicate there's only one. |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 108 | |
David Brownell | c957b32 | 2006-11-16 23:30:14 -0800 | [diff] [blame] | 109 | These are catenated, so name/id "serial"/0 indicates bus_id "serial.0", and |
| 110 | "serial/3" indicates bus_id "serial.3"; both would use the platform_driver |
| 111 | named "serial". While "my_rtc"/-1 would be bus_id "my_rtc" (no instance id) |
| 112 | and use the platform_driver called "my_rtc". |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 113 | |
David Brownell | c957b32 | 2006-11-16 23:30:14 -0800 | [diff] [blame] | 114 | Driver binding is performed automatically by the driver core, invoking |
| 115 | driver probe() after finding a match between device and driver. If the |
| 116 | probe() succeeds, the driver and device are bound as usual. There are |
| 117 | three different ways to find such a match: |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 118 | |
David Brownell | c957b32 | 2006-11-16 23:30:14 -0800 | [diff] [blame] | 119 | - Whenever a device is registered, the drivers for that bus are |
| 120 | checked for matches. Platform devices should be registered very |
| 121 | early during system boot. |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 122 | |
David Brownell | c957b32 | 2006-11-16 23:30:14 -0800 | [diff] [blame] | 123 | - When a driver is registered using platform_driver_register(), all |
| 124 | unbound devices on that bus are checked for matches. Drivers |
| 125 | usually register later during booting, or by module loading. |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 126 | |
David Brownell | c957b32 | 2006-11-16 23:30:14 -0800 | [diff] [blame] | 127 | - Registering a driver using platform_driver_probe() works just like |
| 128 | using platform_driver_register(), except that the the driver won't |
| 129 | be probed later if another device registers. (Which is OK, since |
| 130 | this interface is only for use with non-hotpluggable devices.) |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 131 | |