Platform Devices and Drivers

kernel/Documentation/driver-model/platform.txt

Platform Devices and Drivers~~~~~~~~~~~~~~~~~~~~~~~~~~~~See <linux/platform_device.h> for the driver model interface to theplatform bus:  platform_device, and platform_driver.  This pseudo-busis used to connect devices on busses with minimal infrastructure,like those used to integrate peripherals on many system-on-chipprocessors, or some "legacy" PC interconnects; as opposed to largeformally specified ones like PCI or USB.Platform devices~~~~~~~~~~~~~~~~Platform devices are devices that typically appear as autonomousentities in the system. This includes legacy port-based devices andhost bridges to peripheral buses, and most controllers integratedinto system-on-chip platforms.  What they usually have in commonis direct addressing from a CPU bus.  Rarely, a platform_device willbe connected through a segment of some other kind of bus; but itsregisters will still be directly addressable.Platform devices are given a name, used in driver binding, and alist of resources such as addresses and IRQs.struct platform_device {const char*name;u32id;struct devicedev;u32num_resources;struct resource*resource;};Platform drivers~~~~~~~~~~~~~~~~Platform drivers follow the standard driver model convention, wherediscovery/enumeration is handled outside the drivers, and driversprovide probe() and remove() methods.  They support power managementand shutdown notifications using the standard conventions.struct platform_driver {int (*probe)(struct platform_device *);int (*remove)(struct platform_device *);void (*shutdown)(struct platform_device *);int (*suspend)(struct platform_device *, pm_message_t state);int (*suspend_late)(struct platform_device *, pm_message_t state);int (*resume_early)(struct platform_device *);int (*resume)(struct platform_device *);struct device_driver driver;};Note that probe() should general verify that the specified device hardwareactually exists; sometimes platform setup code can't be sure.  The probingcan use device resources, including clocks, and device platform_data.Platform drivers register themselves the normal way:int platform_driver_register(struct platform_driver *drv);Or, in common situations where the device is known not to be hot-pluggable,the probe() routine can live in an init section to reduce the driver'sruntime memory footprint:int platform_driver_probe(struct platform_driver *drv,  int (*probe)(struct platform_device *))Device Enumeration~~~~~~~~~~~~~~~~~~As a rule, platform specific (and often board-specific) setup code willregister platform devices:int platform_device_register(struct platform_device *pdev);int platform_add_devices(struct platform_device **pdevs, int ndev);The general rule is to register only those devices that actually exist,but in some cases extra devices might be registered.  For example, a kernelmight be configured to work with an external network adapter that might notbe populated on all boards, or likewise to work with an integrated controllerthat some boards might not hook up to any peripherals.In some cases, boot firmware will export tables describing the devicesthat are populated on a given board.   Without such tables, often theonly way for system setup code to set up the correct devices is to builda kernel for a specific target board.  Such board-specific kernels arecommon with embedded and custom systems development.In many cases, the memory and IRQ resources associated with the platformdevice are not enough to let the device's driver work.  Board setup codewill often provide additional information using the device's platform_datafield to hold additional information.Embedded systems frequently need one or more clocks for platform devices,which are normally kept off until they're actively needed (to save power).System setup also associates those clocks with the device, so that thatcalls to clk_get(&pdev->dev, clock_name) return them as needed.Legacy Drivers:  Device Probing~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~Some drivers are not fully converted to the driver model, because they takeon a non-driver role:  the driver registers its platform device, rather thanleaving that for system infrastructure.  Such drivers can't be hotpluggedor coldplugged, since those mechanisms require device creation to be in adifferent system component than the driver.The only "good" reason for this is to handle older system designs which, likeoriginal IBM PCs, rely on error-prone "probe-the-hardware" models for hardwareconfiguration.  Newer systems have largely abandoned that model, in favor ofbus-level support for dynamic configuration (PCI, USB), or device tablesprovided by the boot firmware (e.g. PNPACPI on x86).  There are too manyconflicting options about what might be where, and even educated guesses byan operating system will be wrong often enough to make trouble.This style of driver is discouraged.  If you're updating such a driver,please try to move the device enumeration to a more appropriate location,outside the driver.  This will usually be cleanup, since such driverstend to already have "normal" modes, such as ones using device nodes thatwere created by PNP or by platform device setup.None the less, there are some APIs to support such legacy drivers.  Avoidusing these calls except with such hotplug-deficient drivers.struct platform_device *platform_device_alloc(const char *name, int id);You can use platform_device_alloc() to dynamically allocate a device, whichyou will then initialize with resources and platform_device_register().A better solution is usually:struct platform_device *platform_device_register_simple(const char *name, int id,struct resource *res, unsigned int nres);You can use platform_device_register_simple() as a one-step call to allocateand register a device.Device Naming and Driver Binding~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~The platform_device.dev.bus_id is the canonical name for the devices.It's built from two components:    * platform_device.name ... which is also used to for driver matching.    * platform_device.id ... the device instance number, or else "-1"      to indicate there's only one.These are concatenated, so name/id "serial"/0 indicates bus_id "serial.0", and"serial/3" indicates bus_id "serial.3"; both would use the platform_drivernamed "serial".  While "my_rtc"/-1 would be bus_id "my_rtc" (no instance id)and use the platform_driver called "my_rtc".Driver binding is performed automatically by the driver core, invokingdriver probe() after finding a match between device and driver.  If theprobe() succeeds, the driver and device are bound as usual.  There arethree different ways to find such a match:    - Whenever a device is registered, the drivers for that bus are      checked for matches.  Platform devices should be registered very      early during system boot.    - When a driver is registered using platform_driver_register(), all      unbound devices on that bus are checked for matches.  Drivers      usually register later during booting, or by module loading.    - Registering a driver using platform_driver_probe() works just like      using platform_driver_register(), except that the driver won't      be probed later if another device registers.  (Which is OK, since      this interface is only for use with non-hotpluggable devices.)Early Platform Devices and Drivers~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~The early platform interfaces provide platform data to platform devicedrivers early on during the system boot. The code is built on top of theearly_param() command line parsing and can be executed very early on.Example: "earlyprintk" class early serial console in 6 steps1. Registering early platform device data~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~The architecture code registers platform device data using the functionearly_platform_add_devices(). In the case of early serial console thisshould be hardware configuration for the serial port. Devices registeredat this point will later on be matched against early platform drivers.2. Parsing kernel command line~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~The architecture code calls parse_early_param() to parse the kernelcommand line. This will execute all matching early_param() callbacks.User specified early platform devices will be registered at this point.For the early serial console case the user can specify port on thekernel command line as "earlyprintk=serial.0" where "earlyprintk" isthe class string, "serial" is the name of the platform driver and0 is the platform device id. If the id is -1 then the dot and theid can be omitted.3. Installing early platform drivers belonging to a certain class~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~The architecture code may optionally force registration of all earlyplatform drivers belonging to a certain class using the functionearly_platform_driver_register_all(). User specified devices fromstep 2 have priority over these. This step is omitted by the serialdriver example since the early serial driver code should be disabledunless the user has specified port on the kernel command line.4. Early platform driver registration~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~Compiled-in platform drivers making use of early_platform_init() areautomatically registered during step 2 or 3. The serial driver exampleshould use early_platform_init("earlyprintk", &platform_driver).5. Probing of early platform drivers belonging to a certain class~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~The architecture code calls early_platform_driver_probe() to matchregistered early platform devices associated with a certain class withregistered early platform drivers. Matched devices will get probed().This step can be executed at any point during the early boot. As soonas possible may be good for the serial port case.6. Inside the early platform driver probe()~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~The driver code needs to take special care during early boot, especiallywhen it comes to memory allocation and interrupt registration. The codein the probe() function can use is_early_platform_device() to check ifit is called at early platform device or at the regular platform devicetime. The early serial driver performs register_console() at this point.For further information, see <linux/platform_device.h>.