diff options
author | Linus Torvalds <torvalds@woody.osdl.org> | 2006-12-01 19:41:07 -0500 |
---|---|---|
committer | Linus Torvalds <torvalds@woody.osdl.org> | 2006-12-01 19:41:07 -0500 |
commit | 4549df891a31b9a05b7d183106c09049b79327be (patch) | |
tree | d4dfd0921f0dd0dba2525fd33c0962b26ba5ff1e /Documentation | |
parent | 6b8cc71ab2619a776b02869fd733ac1ead3db4e8 (diff) | |
parent | e17e0f51aeea4e59c7e450a1c0f26605b91c1260 (diff) |
Merge master.kernel.org:/pub/scm/linux/kernel/git/gregkh/driver-2.6
* master.kernel.org:/pub/scm/linux/kernel/git/gregkh/driver-2.6: (36 commits)
Driver core: show drivers in /sys/module/
Documentation/driver-model/platform.txt update/rewrite
Driver core: platform_driver_probe(), can save codespace
driver core: Use klist_remove() in device_move()
driver core: Introduce device_move(): move a device to a new parent.
Driver core: make drivers/base/core.c:setup_parent() static
driver core: Introduce device_find_child().
sysfs: sysfs_write_file() writes zero terminated data
cpu topology: consider sysfs_create_group return value
Driver core: Call platform_notify_remove later
ACPI: Change ACPI to use dev_archdata instead of firmware_data
Driver core: add dev_archdata to struct device
Driver core: convert sound core to use struct device
Driver core: change mem class_devices to be real devices
Driver core: convert fb code to use struct device
Driver core: convert firmware code to use struct device
Driver core: convert mmc code to use struct device
Driver core: convert ppdev code to use struct device
Driver core: convert PPP code to use struct device
Driver core: convert cpuid code to use struct device
...
Diffstat (limited to 'Documentation')
-rw-r--r-- | Documentation/driver-model/platform.txt | 204 |
1 files changed, 118 insertions, 86 deletions
diff --git a/Documentation/driver-model/platform.txt b/Documentation/driver-model/platform.txt index 5eee3e0bfc4c..9f0bc3bfd776 100644 --- a/Documentation/driver-model/platform.txt +++ b/Documentation/driver-model/platform.txt | |||
@@ -1,99 +1,131 @@ | |||
1 | Platform Devices and Drivers | 1 | Platform Devices and Drivers |
2 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | 2 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
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 | |||
3 | 10 | ||
4 | Platform devices | 11 | Platform devices |
5 | ~~~~~~~~~~~~~~~~ | 12 | ~~~~~~~~~~~~~~~~ |
6 | Platform devices are devices that typically appear as autonomous | 13 | Platform devices are devices that typically appear as autonomous |
7 | entities in the system. This includes legacy port-based devices and | 14 | entities in the system. This includes legacy port-based devices and |
8 | host bridges to peripheral buses. | 15 | host bridges to peripheral buses, and most controllers integrated |
9 | 16 | into system-on-chip platforms. What they usually have in common | |
10 | 17 | is direct addressing from a CPU bus. Rarely, a platform_device will | |
11 | Platform drivers | 18 | be connected through a segment of some other kind of bus; but its |
12 | ~~~~~~~~~~~~~~~~ | 19 | registers will still be directly addressible. |
13 | Drivers for platform devices are typically very simple and | ||
14 | unstructured. Either the device was present at a particular I/O port | ||
15 | and the driver was loaded, or it was not. There was no possibility | ||
16 | of hotplugging or alternative discovery besides probing at a specific | ||
17 | I/O address and expecting a specific response. | ||
18 | 20 | ||
21 | Platform devices are given a name, used in driver binding, and a | ||
22 | list of resources such as addresses and IRQs. | ||
19 | 23 | ||
20 | Other Architectures, Modern Firmware, and new Platforms | 24 | struct platform_device { |
21 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | 25 | const char *name; |
22 | These devices are not always at the legacy I/O ports. This is true on | 26 | u32 id; |
23 | other architectures and on some modern architectures. In most cases, | 27 | struct device dev; |
24 | the drivers are modified to discover the devices at other well-known | 28 | u32 num_resources; |
25 | ports for the given platform. However, the firmware in these systems | 29 | struct resource *resource; |
26 | does usually know where exactly these devices reside, and in some | 30 | }; |
27 | cases, it's the only way of discovering them. | ||
28 | 31 | ||
29 | 32 | ||
30 | The Platform Bus | 33 | Platform drivers |
31 | ~~~~~~~~~~~~~~~~ | ||
32 | A platform bus has been created to deal with these issues. First and | ||
33 | foremost, it groups all the legacy devices under a common bus, and | ||
34 | gives them a common parent if they don't already have one. | ||
35 | |||
36 | But, besides the organizational benefits, the platform bus can also | ||
37 | accommodate firmware-based enumeration. | ||
38 | |||
39 | |||
40 | Device Discovery | ||
41 | ~~~~~~~~~~~~~~~~ | 34 | ~~~~~~~~~~~~~~~~ |
42 | The platform bus has no concept of probing for devices. Devices | 35 | Platform drivers follow the standard driver model convention, where |
43 | discovery is left up to either the legacy drivers or the | 36 | discovery/enumeration is handled outside the drivers, and drivers |
44 | firmware. These entities are expected to notify the platform of | 37 | provide probe() and remove() methods. They support power management |
45 | devices that it discovers via the bus's add() callback: | 38 | and shutdown notifications using the standard conventions. |
46 | 39 | ||
47 | platform_bus.add(parent,bus_id). | 40 | struct platform_driver { |
48 | 41 | int (*probe)(struct platform_device *); | |
49 | 42 | int (*remove)(struct platform_device *); | |
50 | Bus IDs | 43 | void (*shutdown)(struct platform_device *); |
51 | ~~~~~~~ | 44 | int (*suspend)(struct platform_device *, pm_message_t state); |
52 | Bus IDs are the canonical names for the devices. There is no globally | 45 | int (*suspend_late)(struct platform_device *, pm_message_t state); |
53 | standard addressing mechanism for legacy devices. In the IA-32 world, | 46 | int (*resume_early)(struct platform_device *); |
54 | we have Pnp IDs to use, as well as the legacy I/O ports. However, | 47 | int (*resume)(struct platform_device *); |
55 | neither tell what the device really is or have any meaning on other | 48 | struct device_driver driver; |
56 | platforms. | 49 | }; |
57 | 50 | ||
58 | Since both PnP IDs and the legacy I/O ports (and other standard I/O | 51 | Note that probe() should general verify that the specified device hardware |
59 | ports for specific devices) have a 1:1 mapping, we map the | 52 | actually exists; sometimes platform setup code can't be sure. The probing |
60 | platform-specific name or identifier to a generic name (at least | 53 | can use device resources, including clocks, and device platform_data. |
61 | within the scope of the kernel). | 54 | |
62 | 55 | Platform drivers register themselves the normal way: | |
63 | For example, a serial driver might find a device at I/O 0x3f8. The | 56 | |
64 | ACPI firmware might also discover a device with PnP ID (_HID) | 57 | int platform_driver_register(struct platform_driver *drv); |
65 | PNP0501. Both correspond to the same device and should be mapped to the | 58 | |
66 | canonical name 'serial'. | 59 | Or, in common situations where the device is known not to be hot-pluggable, |
67 | 60 | the probe() routine can live in an init section to reduce the driver's | |
68 | The bus_id field should be a concatenation of the canonical name and | 61 | runtime memory footprint: |
69 | the instance of that type of device. For example, the device at I/O | 62 | |
70 | port 0x3f8 should have a bus_id of "serial0". This places the | 63 | int platform_driver_probe(struct platform_driver *drv, |
71 | responsibility of enumerating devices of a particular type up to the | 64 | int (*probe)(struct platform_device *)) |
72 | discovery mechanism. But, they are the entity that should know best | 65 | |
73 | (as opposed to the platform bus driver). | 66 | |
74 | 67 | Device Enumeration | |
75 | 68 | ~~~~~~~~~~~~~~~~~~ | |
76 | Drivers | 69 | As a rule, platform specific (and often board-specific) setup code wil |
77 | ~~~~~~~ | 70 | register platform devices: |
78 | Drivers for platform devices should have a name that is the same as | 71 | |
79 | the canonical name of the devices they support. This allows the | 72 | int platform_device_register(struct platform_device *pdev); |
80 | platform bus driver to do simple matching with the basic data | 73 | |
81 | structures to determine if a driver supports a certain device. | 74 | int platform_add_devices(struct platform_device **pdevs, int ndev); |
82 | 75 | ||
83 | For example, a legacy serial driver should have a name of 'serial' and | 76 | The general rule is to register only those devices that actually exist, |
84 | register itself with the platform bus. | 77 | but in some cases extra devices might be registered. For example, a kernel |
85 | 78 | might be configured to work with an external network adapter that might not | |
86 | 79 | be populated on all boards, or likewise to work with an integrated controller | |
87 | Driver Binding | 80 | that some boards might not hook up to any peripherals. |
88 | ~~~~~~~~~~~~~~ | 81 | |
89 | Legacy drivers assume they are bound to the device once they start up | 82 | In some cases, boot firmware will export tables describing the devices |
90 | and probe an I/O port. Divorcing them from this will be a difficult | 83 | that are populated on a given board. Without such tables, often the |
91 | process. However, that shouldn't prevent us from implementing | 84 | only way for system setup code to set up the correct devices is to build |
92 | firmware-based enumeration. | 85 | a kernel for a specific target board. Such board-specific kernels are |
93 | 86 | common with embedded and custom systems development. | |
94 | The firmware should notify the platform bus about devices before the | 87 | |
95 | legacy drivers have had a chance to load. Once the drivers are loaded, | 88 | In many cases, the memory and IRQ resources associated with the platform |
96 | they driver model core will attempt to bind the driver to any | 89 | device are not enough to let the device's driver work. Board setup code |
97 | previously-discovered devices. Once that has happened, it will be free | 90 | will often provide additional information using the device's platform_data |
98 | to discover any other devices it pleases. | 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.) | ||
99 | 131 | ||