1Platform Devices and Drivers
   3See <linux/platform_device.h> for the driver model interface to the
   4platform bus:  platform_device, and platform_driver.  This pseudo-bus
   5is used to connect devices on busses with minimal infrastructure,
   6like those used to integrate peripherals on many system-on-chip
   7processors, or some "legacy" PC interconnects; as opposed to large
   8formally specified ones like PCI or USB.
  11Platform devices
  13Platform devices are devices that typically appear as autonomous
  14entities in the system. This includes legacy port-based devices and
  15host bridges to peripheral buses, and most controllers integrated
  16into system-on-chip platforms.  What they usually have in common
  17is direct addressing from a CPU bus.  Rarely, a platform_device will
  18be connected through a segment of some other kind of bus; but its
  19registers will still be directly addressable.
  21Platform devices are given a name, used in driver binding, and a
  22list of resources such as addresses and IRQs.
  24struct platform_device {
  25        const char      *name;
  26        u32             id;
  27        struct device   dev;
  28        u32             num_resources;
  29        struct resource *resource;
  33Platform drivers
  35Platform drivers follow the standard driver model convention, where
  36discovery/enumeration is handled outside the drivers, and drivers
  37provide probe() and remove() methods.  They support power management
  38and shutdown notifications using the standard conventions.
  40struct 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;
  51Note that probe() should general verify that the specified device hardware
  52actually exists; sometimes platform setup code can't be sure.  The probing
  53can use device resources, including clocks, and device platform_data.
  55Platform drivers register themselves the normal way:
  57        int platform_driver_register(struct platform_driver *drv);
  59Or, in common situations where the device is known not to be hot-pluggable,
  60the probe() routine can live in an init section to reduce the driver's
  61runtime memory footprint:
  63        int platform_driver_probe(struct platform_driver *drv,
  64                          int (*probe)(struct platform_device *))
  67Device Enumeration
  69As a rule, platform specific (and often board-specific) setup code will
  70register platform devices:
  72        int platform_device_register(struct platform_device *pdev);
  74        int platform_add_devices(struct platform_device **pdevs, int ndev);
  76The general rule is to register only those devices that actually exist,
  77but in some cases extra devices might be registered.  For example, a kernel
  78might be configured to work with an external network adapter that might not
  79be populated on all boards, or likewise to work with an integrated controller
  80that some boards might not hook up to any peripherals.
  82In some cases, boot firmware will export tables describing the devices
  83that are populated on a given board.   Without such tables, often the
  84only way for system setup code to set up the correct devices is to build
  85a kernel for a specific target board.  Such board-specific kernels are
  86common with embedded and custom systems development.
  88In many cases, the memory and IRQ resources associated with the platform
  89device are not enough to let the device's driver work.  Board setup code
  90will often provide additional information using the device's platform_data
  91field to hold additional information.
  93Embedded systems frequently need one or more clocks for platform devices,
  94which are normally kept off until they're actively needed (to save power).
  95System setup also associates those clocks with the device, so that that
  96calls to clk_get(&pdev->dev, clock_name) return them as needed.
  99Legacy Drivers:  Device Probing
 101Some drivers are not fully converted to the driver model, because they take
 102on a non-driver role:  the driver registers its platform device, rather than
 103leaving that for system infrastructure.  Such drivers can't be hotplugged
 104or coldplugged, since those mechanisms require device creation to be in a
 105different system component than the driver.
 107The only "good" reason for this is to handle older system designs which, like
 108original IBM PCs, rely on error-prone "probe-the-hardware" models for hardware
 109configuration.  Newer systems have largely abandoned that model, in favor of
 110bus-level support for dynamic configuration (PCI, USB), or device tables
 111provided by the boot firmware (e.g. PNPACPI on x86).  There are too many
 112conflicting options about what might be where, and even educated guesses by
 113an operating system will be wrong often enough to make trouble.
 115This style of driver is discouraged.  If you're updating such a driver,
 116please try to move the device enumeration to a more appropriate location,
 117outside the driver.  This will usually be cleanup, since such drivers
 118tend to already have "normal" modes, such as ones using device nodes that
 119were created by PNP or by platform device setup.
 121None the less, there are some APIs to support such legacy drivers.  Avoid
 122using these calls except with such hotplug-deficient drivers.
 124        struct platform_device *platform_device_alloc(
 125                        const char *name, int id);
 127You can use platform_device_alloc() to dynamically allocate a device, which
 128you will then initialize with resources and platform_device_register().
 129A better solution is usually:
 131        struct platform_device *platform_device_register_simple(
 132                        const char *name, int id,
 133                        struct resource *res, unsigned int nres);
 135You can use platform_device_register_simple() as a one-step call to allocate
 136and register a device.
 139Device Naming and Driver Binding
 141The is the canonical name for the devices.
 142It's built from two components:
 144    * ... which is also used to for driver matching.
 146    * ... the device instance number, or else "-1"
 147      to indicate there's only one.
 149These 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
 151named "serial".  While "my_rtc"/-1 would be bus_id "my_rtc" (no instance id)
 152and use the platform_driver called "my_rtc".
 154Driver binding is performed automatically by the driver core, invoking
 155driver probe() after finding a match between device and driver.  If the
 156probe() succeeds, the driver and device are bound as usual.  There are
 157three different ways to find such a match:
 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.
 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.
 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.)
 173Early Platform Devices and Drivers
 175The early platform interfaces provide platform data to platform device
 176drivers early on during the system boot. The code is built on top of the
 177early_param() command line parsing and can be executed very early on.
 179Example: "earlyprintk" class early serial console in 6 steps
 1811. Registering early platform device data
 183The architecture code registers platform device data using the function
 184early_platform_add_devices(). In the case of early serial console this
 185should be hardware configuration for the serial port. Devices registered
 186at this point will later on be matched against early platform drivers.
 1882. Parsing kernel command line
 190The architecture code calls parse_early_param() to parse the kernel
 191command line. This will execute all matching early_param() callbacks.
 192User specified early platform devices will be registered at this point.
 193For the early serial console case the user can specify port on the
 194kernel command line as "earlyprintk=serial.0" where "earlyprintk" is
 195the class string, "serial" is the name of the platfrom driver and
 1960 is the platform device id. If the id is -1 then the dot and the
 197id can be omitted.
 1993. Installing early platform drivers belonging to a certain class
 201The architecture code may optionally force registration of all early
 202platform drivers belonging to a certain class using the function
 203early_platform_driver_register_all(). User specified devices from
 204step 2 have priority over these. This step is omitted by the serial
 205driver example since the early serial driver code should be disabled
 206unless the user has specified port on the kernel command line.
 2084. Early platform driver registration
 210Compiled-in platform drivers making use of early_platform_init() are
 211automatically registered during step 2 or 3. The serial driver example
 212should use early_platform_init("earlyprintk", &platform_driver).
 2145. Probing of early platform drivers belonging to a certain class
 216The architecture code calls early_platform_driver_probe() to match
 217registered early platform devices associated with a certain class with
 218registered early platform drivers. Matched devices will get probed().
 219This step can be executed at any point during the early boot. As soon
 220as possible may be good for the serial port case.
 2226. Inside the early platform driver probe()
 224The driver code needs to take special care during early boot, especially
 225when it comes to memory allocation and interrupt registration. The code
 226in the probe() function can use is_early_platform_device() to check if
 227it is called at early platform device or at the regular platform device
 228time. The early serial driver performs register_console() at this point.
 230For further information, see <linux/platform_device.h>.