248 lines · plain
1============================2Platform Devices and Drivers3============================4 5See <linux/platform_device.h> for the driver model interface to the6platform bus: platform_device, and platform_driver. This pseudo-bus7is used to connect devices on busses with minimal infrastructure,8like those used to integrate peripherals on many system-on-chip9processors, or some "legacy" PC interconnects; as opposed to large10formally specified ones like PCI or USB.11 12 13Platform devices14~~~~~~~~~~~~~~~~15Platform devices are devices that typically appear as autonomous16entities in the system. This includes legacy port-based devices and17host bridges to peripheral buses, and most controllers integrated18into system-on-chip platforms. What they usually have in common19is direct addressing from a CPU bus. Rarely, a platform_device will20be connected through a segment of some other kind of bus; but its21registers will still be directly addressable.22 23Platform devices are given a name, used in driver binding, and a24list 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 35Platform drivers36~~~~~~~~~~~~~~~~37Platform drivers follow the standard driver model convention, where38discovery/enumeration is handled outside the drivers, and drivers39provide probe() and remove() methods. They support power management40and shutdown notifications using the standard conventions::41 42 struct platform_driver {43 int (*probe)(struct platform_device *);44 void (*remove)(struct platform_device *);45 void (*shutdown)(struct platform_device *);46 int (*suspend)(struct platform_device *, pm_message_t state);47 int (*resume)(struct platform_device *);48 struct device_driver driver;49 const struct platform_device_id *id_table;50 bool prevent_deferred_probe;51 bool driver_managed_dma;52 };53 54Note that probe() should in general verify that the specified device hardware55actually exists; sometimes platform setup code can't be sure. The probing56can use device resources, including clocks, and device platform_data.57 58Platform drivers register themselves the normal way::59 60 int platform_driver_register(struct platform_driver *drv);61 62Or, in common situations where the device is known not to be hot-pluggable,63the probe() routine can live in an init section to reduce the driver's64runtime memory footprint::65 66 int platform_driver_probe(struct platform_driver *drv,67 int (*probe)(struct platform_device *))68 69Kernel modules can be composed of several platform drivers. The platform core70provides helpers to register and unregister an array of drivers::71 72 int __platform_register_drivers(struct platform_driver * const *drivers,73 unsigned int count, struct module *owner);74 void platform_unregister_drivers(struct platform_driver * const *drivers,75 unsigned int count);76 77If one of the drivers fails to register, all drivers registered up to that78point will be unregistered in reverse order. Note that there is a convenience79macro that passes THIS_MODULE as owner parameter::80 81 #define platform_register_drivers(drivers, count)82 83 84Device Enumeration85~~~~~~~~~~~~~~~~~~86As a rule, platform specific (and often board-specific) setup code will87register platform devices::88 89 int platform_device_register(struct platform_device *pdev);90 91 int platform_add_devices(struct platform_device **pdevs, int ndev);92 93The general rule is to register only those devices that actually exist,94but in some cases extra devices might be registered. For example, a kernel95might be configured to work with an external network adapter that might not96be populated on all boards, or likewise to work with an integrated controller97that some boards might not hook up to any peripherals.98 99In some cases, boot firmware will export tables describing the devices100that are populated on a given board. Without such tables, often the101only way for system setup code to set up the correct devices is to build102a kernel for a specific target board. Such board-specific kernels are103common with embedded and custom systems development.104 105In many cases, the memory and IRQ resources associated with the platform106device are not enough to let the device's driver work. Board setup code107will often provide additional information using the device's platform_data108field to hold additional information.109 110Embedded systems frequently need one or more clocks for platform devices,111which are normally kept off until they're actively needed (to save power).112System setup also associates those clocks with the device, so that113calls to clk_get(&pdev->dev, clock_name) return them as needed.114 115 116Legacy Drivers: Device Probing117~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~118Some drivers are not fully converted to the driver model, because they take119on a non-driver role: the driver registers its platform device, rather than120leaving that for system infrastructure. Such drivers can't be hotplugged121or coldplugged, since those mechanisms require device creation to be in a122different system component than the driver.123 124The only "good" reason for this is to handle older system designs which, like125original IBM PCs, rely on error-prone "probe-the-hardware" models for hardware126configuration. Newer systems have largely abandoned that model, in favor of127bus-level support for dynamic configuration (PCI, USB), or device tables128provided by the boot firmware (e.g. PNPACPI on x86). There are too many129conflicting options about what might be where, and even educated guesses by130an operating system will be wrong often enough to make trouble.131 132This style of driver is discouraged. If you're updating such a driver,133please try to move the device enumeration to a more appropriate location,134outside the driver. This will usually be cleanup, since such drivers135tend to already have "normal" modes, such as ones using device nodes that136were created by PNP or by platform device setup.137 138None the less, there are some APIs to support such legacy drivers. Avoid139using these calls except with such hotplug-deficient drivers::140 141 struct platform_device *platform_device_alloc(142 const char *name, int id);143 144You can use platform_device_alloc() to dynamically allocate a device, which145you will then initialize with resources and platform_device_register().146A better solution is usually::147 148 struct platform_device *platform_device_register_simple(149 const char *name, int id,150 struct resource *res, unsigned int nres);151 152You can use platform_device_register_simple() as a one-step call to allocate153and register a device.154 155 156Device Naming and Driver Binding157~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~158The platform_device.dev.bus_id is the canonical name for the devices.159It's built from two components:160 161 * platform_device.name ... which is also used to for driver matching.162 163 * platform_device.id ... the device instance number, or else "-1"164 to indicate there's only one.165 166These are concatenated, so name/id "serial"/0 indicates bus_id "serial.0", and167"serial/3" indicates bus_id "serial.3"; both would use the platform_driver168named "serial". While "my_rtc"/-1 would be bus_id "my_rtc" (no instance id)169and use the platform_driver called "my_rtc".170 171Driver binding is performed automatically by the driver core, invoking172driver probe() after finding a match between device and driver. If the173probe() succeeds, the driver and device are bound as usual. There are174three different ways to find such a match:175 176 - Whenever a device is registered, the drivers for that bus are177 checked for matches. Platform devices should be registered very178 early during system boot.179 180 - When a driver is registered using platform_driver_register(), all181 unbound devices on that bus are checked for matches. Drivers182 usually register later during booting, or by module loading.183 184 - Registering a driver using platform_driver_probe() works just like185 using platform_driver_register(), except that the driver won't186 be probed later if another device registers. (Which is OK, since187 this interface is only for use with non-hotpluggable devices.)188 189 190Early Platform Devices and Drivers191~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~192The early platform interfaces provide platform data to platform device193drivers early on during the system boot. The code is built on top of the194early_param() command line parsing and can be executed very early on.195 196Example: "earlyprintk" class early serial console in 6 steps197 1981. Registering early platform device data199~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~200The architecture code registers platform device data using the function201early_platform_add_devices(). In the case of early serial console this202should be hardware configuration for the serial port. Devices registered203at this point will later on be matched against early platform drivers.204 2052. Parsing kernel command line206~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~207The architecture code calls parse_early_param() to parse the kernel208command line. This will execute all matching early_param() callbacks.209User specified early platform devices will be registered at this point.210For the early serial console case the user can specify port on the211kernel command line as "earlyprintk=serial.0" where "earlyprintk" is212the class string, "serial" is the name of the platform driver and2130 is the platform device id. If the id is -1 then the dot and the214id can be omitted.215 2163. Installing early platform drivers belonging to a certain class217~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~218The architecture code may optionally force registration of all early219platform drivers belonging to a certain class using the function220early_platform_driver_register_all(). User specified devices from221step 2 have priority over these. This step is omitted by the serial222driver example since the early serial driver code should be disabled223unless the user has specified port on the kernel command line.224 2254. Early platform driver registration226~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~227Compiled-in platform drivers making use of early_platform_init() are228automatically registered during step 2 or 3. The serial driver example229should use early_platform_init("earlyprintk", &platform_driver).230 2315. Probing of early platform drivers belonging to a certain class232~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~233The architecture code calls early_platform_driver_probe() to match234registered early platform devices associated with a certain class with235registered early platform drivers. Matched devices will get probed().236This step can be executed at any point during the early boot. As soon237as possible may be good for the serial port case.238 2396. Inside the early platform driver probe()240~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~241The driver code needs to take special care during early boot, especially242when it comes to memory allocation and interrupt registration. The code243in the probe() function can use is_early_platform_device() to check if244it is called at early platform device or at the regular platform device245time. The early serial driver performs register_console() at this point.246 247For further information, see <linux/platform_device.h>.248