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