Documentation/driver-model/platform.rst

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