platform.txt 5.4 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131
  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. Platform devices
  10. ~~~~~~~~~~~~~~~~
  11. Platform devices are devices that typically appear as autonomous
  12. entities in the system. This includes legacy port-based devices and
  13. host bridges to peripheral buses, and most controllers integrated
  14. into system-on-chip platforms. What they usually have in common
  15. is direct addressing from a CPU bus. Rarely, a platform_device will
  16. be connected through a segment of some other kind of bus; but its
  17. registers will still be directly addressible.
  18. Platform devices are given a name, used in driver binding, and a
  19. list of resources such as addresses and IRQs.
  20. struct platform_device {
  21. const char *name;
  22. u32 id;
  23. struct device dev;
  24. u32 num_resources;
  25. struct resource *resource;
  26. };
  27. Platform drivers
  28. ~~~~~~~~~~~~~~~~
  29. Platform drivers follow the standard driver model convention, where
  30. discovery/enumeration is handled outside the drivers, and drivers
  31. provide probe() and remove() methods. They support power management
  32. and shutdown notifications using the standard conventions.
  33. struct platform_driver {
  34. int (*probe)(struct platform_device *);
  35. int (*remove)(struct platform_device *);
  36. void (*shutdown)(struct platform_device *);
  37. int (*suspend)(struct platform_device *, pm_message_t state);
  38. int (*suspend_late)(struct platform_device *, pm_message_t state);
  39. int (*resume_early)(struct platform_device *);
  40. int (*resume)(struct platform_device *);
  41. struct device_driver driver;
  42. };
  43. Note that probe() should general verify that the specified device hardware
  44. actually exists; sometimes platform setup code can't be sure. The probing
  45. can use device resources, including clocks, and device platform_data.
  46. Platform drivers register themselves the normal way:
  47. int platform_driver_register(struct platform_driver *drv);
  48. Or, in common situations where the device is known not to be hot-pluggable,
  49. the probe() routine can live in an init section to reduce the driver's
  50. runtime memory footprint:
  51. int platform_driver_probe(struct platform_driver *drv,
  52. int (*probe)(struct platform_device *))
  53. Device Enumeration
  54. ~~~~~~~~~~~~~~~~~~
  55. As a rule, platform specific (and often board-specific) setup code will
  56. register platform devices:
  57. int platform_device_register(struct platform_device *pdev);
  58. int platform_add_devices(struct platform_device **pdevs, int ndev);
  59. The general rule is to register only those devices that actually exist,
  60. but in some cases extra devices might be registered. For example, a kernel
  61. might be configured to work with an external network adapter that might not
  62. be populated on all boards, or likewise to work with an integrated controller
  63. that some boards might not hook up to any peripherals.
  64. In some cases, boot firmware will export tables describing the devices
  65. that are populated on a given board. Without such tables, often the
  66. only way for system setup code to set up the correct devices is to build
  67. a kernel for a specific target board. Such board-specific kernels are
  68. common with embedded and custom systems development.
  69. In many cases, the memory and IRQ resources associated with the platform
  70. device are not enough to let the device's driver work. Board setup code
  71. will often provide additional information using the device's platform_data
  72. field to hold additional information.
  73. Embedded systems frequently need one or more clocks for platform devices,
  74. which are normally kept off until they're actively needed (to save power).
  75. System setup also associates those clocks with the device, so that that
  76. calls to clk_get(&pdev->dev, clock_name) return them as needed.
  77. Device Naming and Driver Binding
  78. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  79. The platform_device.dev.bus_id is the canonical name for the devices.
  80. It's built from two components:
  81. * platform_device.name ... which is also used to for driver matching.
  82. * platform_device.id ... the device instance number, or else "-1"
  83. to indicate there's only one.
  84. These are concatenated, so name/id "serial"/0 indicates bus_id "serial.0", and
  85. "serial/3" indicates bus_id "serial.3"; both would use the platform_driver
  86. named "serial". While "my_rtc"/-1 would be bus_id "my_rtc" (no instance id)
  87. and use the platform_driver called "my_rtc".
  88. Driver binding is performed automatically by the driver core, invoking
  89. driver probe() after finding a match between device and driver. If the
  90. probe() succeeds, the driver and device are bound as usual. There are
  91. three different ways to find such a match:
  92. - Whenever a device is registered, the drivers for that bus are
  93. checked for matches. Platform devices should be registered very
  94. early during system boot.
  95. - When a driver is registered using platform_driver_register(), all
  96. unbound devices on that bus are checked for matches. Drivers
  97. usually register later during booting, or by module loading.
  98. - Registering a driver using platform_driver_probe() works just like
  99. using platform_driver_register(), except that the the driver won't
  100. be probed later if another device registers. (Which is OK, since
  101. this interface is only for use with non-hotpluggable devices.)