Commit | Line | Data |
---|---|---|
1da177e4 LT |
1 | Platform Devices and Drivers |
2 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
c957b324 DB |
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 | ||
1da177e4 LT |
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 | |
c957b324 DB |
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. | |
1da177e4 | 20 | |
c957b324 DB |
21 | Platform devices are given a name, used in driver binding, and a |
22 | list of resources such as addresses and IRQs. | |
1da177e4 | 23 | |
c957b324 DB |
24 | struct platform_device { |
25 | const char *name; | |
26 | u32 id; | |
27 | struct device dev; | |
28 | u32 num_resources; | |
29 | struct resource *resource; | |
30 | }; | |
1da177e4 LT |
31 | |
32 | ||
c957b324 | 33 | Platform drivers |
1da177e4 | 34 | ~~~~~~~~~~~~~~~~ |
c957b324 DB |
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 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. | |
97 | ||
98 | ||
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: | |
103 | ||
104 | * platform_device.name ... which is also used to for driver matching. | |
105 | ||
106 | * platform_device.id ... the device instance number, or else "-1" | |
107 | to indicate there's only one. | |
108 | ||
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". | |
113 | ||
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: | |
118 | ||
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. | |
122 | ||
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. | |
126 | ||
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.) | |
1da177e4 | 131 |