TEXT   57

platform.txt

Guest on 1st August 2021 06:09:47 AM

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

Raw Paste


Login or Register to edit or fork this paste. It's free.