Documentation/driver-model/platform.txt

   1 Platform Devices and Drivers
   2 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
   3
   4 Platform devices
   5 ~~~~~~~~~~~~~~~~
   6 Platform devices are devices that typically appear as autonomous
   7 entities in the system. This includes legacy port-based devices and
   8 host bridges to peripheral buses.
   9
  10
  11 Platform drivers
  12 ~~~~~~~~~~~~~~~~
  13 Drivers for platform devices are typically very simple and
  14 unstructured. Either the device was present at a particular I/O port
  15 and the driver was loaded, or it was not. There was no possibility
  16 of hotplugging or alternative discovery besides probing at a specific
  17 I/O address and expecting a specific response.
  18
  19
  20 Other Architectures, Modern Firmware, and new Platforms
  21 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  22 These devices are not always at the legacy I/O ports. This is true on
  23 other architectures and on some modern architectures. In most cases,
  24 the drivers are modified to discover the devices at other well-known
  25 ports for the given platform. However, the firmware in these systems
  26 does usually know where exactly these devices reside, and in some
  27 cases, it's the only way of discovering them.
  28
  29
  30 The Platform Bus
  31 ~~~~~~~~~~~~~~~~
  32 A platform bus has been created to deal with these issues. First and
  33 foremost, it groups all the legacy devices under a common bus, and
  34 gives them a common parent if they don't already have one.
  35
  36 But, besides the organizational benefits, the platform bus can also
  37 accommodate firmware-based enumeration.
  38
  39
  40 Device Discovery
  41 ~~~~~~~~~~~~~~~~
  42 The platform bus has no concept of probing for devices. Devices
  43 discovery is left up to either the legacy drivers or the
  44 firmware. These entities are expected to notify the platform of
  45 devices that it discovers via the bus's add() callback:
  46
  47         platform_bus.add(parent,bus_id).
  48
  49
  50 Bus IDs
  51 ~~~~~~~
  52 Bus IDs are the canonical names for the devices. There is no globally
  53 standard addressing mechanism for legacy devices. In the IA-32 world,
  54 we have Pnp IDs to use, as well as the legacy I/O ports. However,
  55 neither tell what the device really is or have any meaning on other
  56 platforms.
  57
  58 Since both PnP IDs and the legacy I/O ports (and other standard I/O
  59 ports for specific devices) have a 1:1 mapping, we map the
  60 platform-specific name or identifier to a generic name (at least
  61 within the scope of the kernel).
  62
  63 For example, a serial driver might find a device at I/O 0x3f8. The
  64 ACPI firmware might also discover a device with PnP ID (_HID)
  65 PNP0501. Both correspond to the same device and should be mapped to the
  66 canonical name 'serial'.
  67
  68 The bus_id field should be a concatenation of the canonical name and
  69 the instance of that type of device. For example, the device at I/O
  70 port 0x3f8 should have a bus_id of "serial0". This places the
  71 responsibility of enumerating devices of a particular type up to the
  72 discovery mechanism. But, they are the entity that should know best
  73 (as opposed to the platform bus driver).
  74
  75
  76 Drivers
  77 ~~~~~~~
  78 Drivers for platform devices should have a name that is the same as
  79 the canonical name of the devices they support. This allows the
  80 platform bus driver to do simple matching with the basic data
  81 structures to determine if a driver supports a certain device.
  82
  83 For example, a legacy serial driver should have a name of 'serial' and
  84 register itself with the platform bus.
  85
  86
  87 Driver Binding
  88 ~~~~~~~~~~~~~~
  89 Legacy drivers assume they are bound to the device once they start up
  90 and probe an I/O port. Divorcing them from this will be a difficult
  91 process. However, that shouldn't prevent us from implementing
  92 firmware-based enumeration.
  93
  94 The firmware should notify the platform bus about devices before the
  95 legacy drivers have had a chance to load. Once the drivers are loaded,
  96 they driver model core will attempt to bind the driver to any
  97 previously-discovered devices. Once that has happened, it will be free
  98 to discover any other devices it pleases.
  99