Documentation/driver-model/platform.txt

   1 Platform Devices and Drivers
   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
  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
  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 addressable.
  20
  21 Platform devices are given a name, used in driver binding, and a
  22 list of resources such as addresses and IRQs.
  23
  24 struct platform_device {
  25         const char      *name;
  26         u32             id;
  27         struct device   dev;
  28         u32             num_resources;
  29         struct resource *resource;
  30 };
  31
  32
  33 Platform drivers
  34 ~~~~~~~~~~~~~~~~
  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 will
  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 Legacy Drivers:  Device Probing
 100 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 101 Some drivers are not fully converted to the driver model, because they take
 102 on a non-driver role:  the driver registers its platform device, rather than
 103 leaving that for system infrastructure.  Such drivers can't be hotplugged
 104 or coldplugged, since those mechanisms require device creation to be in a
 105 different system component than the driver.
 106
 107 The only "good" reason for this is to handle older system designs which, like
 108 original IBM PCs, rely on error-prone "probe-the-hardware" models for hardware
 109 configuration.  Newer systems have largely abandoned that model, in favor of
 110 bus-level support for dynamic configuration (PCI, USB), or device tables
 111 provided by the boot firmware (e.g. PNPACPI on x86).  There are too many
 112 conflicting options about what might be where, and even educated guesses by
 113 an operating system will be wrong often enough to make trouble.
 114
 115 This style of driver is discouraged.  If you're updating such a driver,
 116 please try to move the device enumeration to a more appropriate location,
 117 outside the driver.  This will usually be cleanup, since such drivers
 118 tend to already have "normal" modes, such as ones using device nodes that
 119 were created by PNP or by platform device setup.
 120
 121 None the less, there are some APIs to support such legacy drivers.  Avoid
 122 using these calls except with such hotplug-deficient drivers.
 123
 124         struct platform_device *platform_device_alloc(
 125                         const char *name, int id);
 126
 127 You can use platform_device_alloc() to dynamically allocate a device, which
 128 you will then initialize with resources and platform_device_register().
 129 A better solution is usually:
 130
 131         struct platform_device *platform_device_register_simple(
 132                         const char *name, int id,
 133                         struct resource *res, unsigned int nres);
 134
 135 You can use platform_device_register_simple() as a one-step call to allocate
 136 and register a device.
 137
 138
 139 Device Naming and Driver Binding
 140 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 141 The platform_device.dev.bus_id is the canonical name for the devices.
 142 It's built from two components:
 143
 144     * platform_device.name ... which is also used to for driver matching.
 145
 146     * platform_device.id ... the device instance number, or else "-1"
 147       to indicate there's only one.
 148
 149 These are concatenated, so name/id "serial"/0 indicates bus_id "serial.0", and
 150 "serial/3" indicates bus_id "serial.3"; both would use the platform_driver
 151 named "serial".  While "my_rtc"/-1 would be bus_id "my_rtc" (no instance id)
 152 and use the platform_driver called "my_rtc".
 153
 154 Driver binding is performed automatically by the driver core, invoking
 155 driver probe() after finding a match between device and driver.  If the
 156 probe() succeeds, the driver and device are bound as usual.  There are
 157 three different ways to find such a match:
 158
 159     - Whenever a device is registered, the drivers for that bus are
 160       checked for matches.  Platform devices should be registered very
 161       early during system boot.
 162
 163     - When a driver is registered using platform_driver_register(), all
 164       unbound devices on that bus are checked for matches.  Drivers
 165       usually register later during booting, or by module loading.
 166
 167     - Registering a driver using platform_driver_probe() works just like
 168       using platform_driver_register(), except that the driver won't
 169       be probed later if another device registers.  (Which is OK, since
 170       this interface is only for use with non-hotpluggable devices.)
 171