0001 ============================
0002 Platform Devices and Drivers
0003 ============================
0004
0005 See <linux/platform_device.h> for the driver model interface to the
0006 platform bus: platform_device, and platform_driver. This pseudo-bus
0007 is used to connect devices on busses with minimal infrastructure,
0008 like those used to integrate peripherals on many system-on-chip
0009 processors, or some "legacy" PC interconnects; as opposed to large
0010 formally specified ones like PCI or USB.
0011
0012
0013 Platform devices
0014 ~~~~~~~~~~~~~~~~
0015 Platform devices are devices that typically appear as autonomous
0016 entities in the system. This includes legacy port-based devices and
0017 host bridges to peripheral buses, and most controllers integrated
0018 into system-on-chip platforms. What they usually have in common
0019 is direct addressing from a CPU bus. Rarely, a platform_device will
0020 be connected through a segment of some other kind of bus; but its
0021 registers will still be directly addressable.
0022
0023 Platform devices are given a name, used in driver binding, and a
0024 list of resources such as addresses and IRQs::
0025
0026 struct platform_device {
0027 const char *name;
0028 u32 id;
0029 struct device dev;
0030 u32 num_resources;
0031 struct resource *resource;
0032 };
0033
0034
0035 Platform drivers
0036 ~~~~~~~~~~~~~~~~
0037 Platform drivers follow the standard driver model convention, where
0038 discovery/enumeration is handled outside the drivers, and drivers
0039 provide probe() and remove() methods. They support power management
0040 and shutdown notifications using the standard conventions::
0041
0042 struct platform_driver {
0043 int (*probe)(struct platform_device *);
0044 int (*remove)(struct platform_device *);
0045 void (*shutdown)(struct platform_device *);
0046 int (*suspend)(struct platform_device *, pm_message_t state);
0047 int (*suspend_late)(struct platform_device *, pm_message_t state);
0048 int (*resume_early)(struct platform_device *);
0049 int (*resume)(struct platform_device *);
0050 struct device_driver driver;
0051 };
0052
0053 Note that probe() should in general verify that the specified device hardware
0054 actually exists; sometimes platform setup code can't be sure. The probing
0055 can use device resources, including clocks, and device platform_data.
0056
0057 Platform drivers register themselves the normal way::
0058
0059 int platform_driver_register(struct platform_driver *drv);
0060
0061 Or, in common situations where the device is known not to be hot-pluggable,
0062 the probe() routine can live in an init section to reduce the driver's
0063 runtime memory footprint::
0064
0065 int platform_driver_probe(struct platform_driver *drv,
0066 int (*probe)(struct platform_device *))
0067
0068 Kernel modules can be composed of several platform drivers. The platform core
0069 provides helpers to register and unregister an array of drivers::
0070
0071 int __platform_register_drivers(struct platform_driver * const *drivers,
0072 unsigned int count, struct module *owner);
0073 void platform_unregister_drivers(struct platform_driver * const *drivers,
0074 unsigned int count);
0075
0076 If one of the drivers fails to register, all drivers registered up to that
0077 point will be unregistered in reverse order. Note that there is a convenience
0078 macro that passes THIS_MODULE as owner parameter::
0079
0080 #define platform_register_drivers(drivers, count)
0081
0082
0083 Device Enumeration
0084 ~~~~~~~~~~~~~~~~~~
0085 As a rule, platform specific (and often board-specific) setup code will
0086 register platform devices::
0087
0088 int platform_device_register(struct platform_device *pdev);
0089
0090 int platform_add_devices(struct platform_device **pdevs, int ndev);
0091
0092 The general rule is to register only those devices that actually exist,
0093 but in some cases extra devices might be registered. For example, a kernel
0094 might be configured to work with an external network adapter that might not
0095 be populated on all boards, or likewise to work with an integrated controller
0096 that some boards might not hook up to any peripherals.
0097
0098 In some cases, boot firmware will export tables describing the devices
0099 that are populated on a given board. Without such tables, often the
0100 only way for system setup code to set up the correct devices is to build
0101 a kernel for a specific target board. Such board-specific kernels are
0102 common with embedded and custom systems development.
0103
0104 In many cases, the memory and IRQ resources associated with the platform
0105 device are not enough to let the device's driver work. Board setup code
0106 will often provide additional information using the device's platform_data
0107 field to hold additional information.
0108
0109 Embedded systems frequently need one or more clocks for platform devices,
0110 which are normally kept off until they're actively needed (to save power).
0111 System setup also associates those clocks with the device, so that
0112 calls to clk_get(&pdev->dev, clock_name) return them as needed.
0113
0114
0115 Legacy Drivers: Device Probing
0116 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
0117 Some drivers are not fully converted to the driver model, because they take
0118 on a non-driver role: the driver registers its platform device, rather than
0119 leaving that for system infrastructure. Such drivers can't be hotplugged
0120 or coldplugged, since those mechanisms require device creation to be in a
0121 different system component than the driver.
0122
0123 The only "good" reason for this is to handle older system designs which, like
0124 original IBM PCs, rely on error-prone "probe-the-hardware" models for hardware
0125 configuration. Newer systems have largely abandoned that model, in favor of
0126 bus-level support for dynamic configuration (PCI, USB), or device tables
0127 provided by the boot firmware (e.g. PNPACPI on x86). There are too many
0128 conflicting options about what might be where, and even educated guesses by
0129 an operating system will be wrong often enough to make trouble.
0130
0131 This style of driver is discouraged. If you're updating such a driver,
0132 please try to move the device enumeration to a more appropriate location,
0133 outside the driver. This will usually be cleanup, since such drivers
0134 tend to already have "normal" modes, such as ones using device nodes that
0135 were created by PNP or by platform device setup.
0136
0137 None the less, there are some APIs to support such legacy drivers. Avoid
0138 using these calls except with such hotplug-deficient drivers::
0139
0140 struct platform_device *platform_device_alloc(
0141 const char *name, int id);
0142
0143 You can use platform_device_alloc() to dynamically allocate a device, which
0144 you will then initialize with resources and platform_device_register().
0145 A better solution is usually::
0146
0147 struct platform_device *platform_device_register_simple(
0148 const char *name, int id,
0149 struct resource *res, unsigned int nres);
0150
0151 You can use platform_device_register_simple() as a one-step call to allocate
0152 and register a device.
0153
0154
0155 Device Naming and Driver Binding
0156 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
0157 The platform_device.dev.bus_id is the canonical name for the devices.
0158 It's built from two components:
0159
0160 * platform_device.name ... which is also used to for driver matching.
0161
0162 * platform_device.id ... the device instance number, or else "-1"
0163 to indicate there's only one.
0164
0165 These are concatenated, so name/id "serial"/0 indicates bus_id "serial.0", and
0166 "serial/3" indicates bus_id "serial.3"; both would use the platform_driver
0167 named "serial". While "my_rtc"/-1 would be bus_id "my_rtc" (no instance id)
0168 and use the platform_driver called "my_rtc".
0169
0170 Driver binding is performed automatically by the driver core, invoking
0171 driver probe() after finding a match between device and driver. If the
0172 probe() succeeds, the driver and device are bound as usual. There are
0173 three different ways to find such a match:
0174
0175 - Whenever a device is registered, the drivers for that bus are
0176 checked for matches. Platform devices should be registered very
0177 early during system boot.
0178
0179 - When a driver is registered using platform_driver_register(), all
0180 unbound devices on that bus are checked for matches. Drivers
0181 usually register later during booting, or by module loading.
0182
0183 - Registering a driver using platform_driver_probe() works just like
0184 using platform_driver_register(), except that the driver won't
0185 be probed later if another device registers. (Which is OK, since
0186 this interface is only for use with non-hotpluggable devices.)
0187
0188
0189 Early Platform Devices and Drivers
0190 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
0191 The early platform interfaces provide platform data to platform device
0192 drivers early on during the system boot. The code is built on top of the
0193 early_param() command line parsing and can be executed very early on.
0194
0195 Example: "earlyprintk" class early serial console in 6 steps
0196
0197 1. Registering early platform device data
0198 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
0199 The architecture code registers platform device data using the function
0200 early_platform_add_devices(). In the case of early serial console this
0201 should be hardware configuration for the serial port. Devices registered
0202 at this point will later on be matched against early platform drivers.
0203
0204 2. Parsing kernel command line
0205 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
0206 The architecture code calls parse_early_param() to parse the kernel
0207 command line. This will execute all matching early_param() callbacks.
0208 User specified early platform devices will be registered at this point.
0209 For the early serial console case the user can specify port on the
0210 kernel command line as "earlyprintk=serial.0" where "earlyprintk" is
0211 the class string, "serial" is the name of the platform driver and
0212 0 is the platform device id. If the id is -1 then the dot and the
0213 id can be omitted.
0214
0215 3. Installing early platform drivers belonging to a certain class
0216 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
0217 The architecture code may optionally force registration of all early
0218 platform drivers belonging to a certain class using the function
0219 early_platform_driver_register_all(). User specified devices from
0220 step 2 have priority over these. This step is omitted by the serial
0221 driver example since the early serial driver code should be disabled
0222 unless the user has specified port on the kernel command line.
0223
0224 4. Early platform driver registration
0225 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
0226 Compiled-in platform drivers making use of early_platform_init() are
0227 automatically registered during step 2 or 3. The serial driver example
0228 should use early_platform_init("earlyprintk", &platform_driver).
0229
0230 5. Probing of early platform drivers belonging to a certain class
0231 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
0232 The architecture code calls early_platform_driver_probe() to match
0233 registered early platform devices associated with a certain class with
0234 registered early platform drivers. Matched devices will get probed().
0235 This step can be executed at any point during the early boot. As soon
0236 as possible may be good for the serial port case.
0237
0238 6. Inside the early platform driver probe()
0239 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
0240 The driver code needs to take special care during early boot, especially
0241 when it comes to memory allocation and interrupt registration. The code
0242 in the probe() function can use is_early_platform_device() to check if
0243 it is called at early platform device or at the regular platform device
0244 time. The early serial driver performs register_console() at this point.
0245
0246 For further information, see <linux/platform_device.h>.
