Documentation/driver-api/device_connection.rst

   1 ==================
   2 Device connections
   3 ==================
   4
   5 Introduction
   6 ------------
   7
   8 Devices often have connections to other devices that are outside of the direct
   9 child/parent relationship. A serial or network communication controller, which
  10 could be a PCI device, may need to be able to get a reference to its PHY
  11 component, which could be attached for example to the I2C bus. Some device
  12 drivers need to be able to control the clocks or the GPIOs for their devices,
  13 and so on.
  14
  15 Device connections are generic descriptions of any type of connection between
  16 two separate devices.
  17
  18 Device connections alone do not create a dependency between the two devices.
  19 They are only descriptions which are not tied to either of the devices directly.
  20 A dependency between the two devices exists only if one of the two endpoint
  21 devices requests a reference to the other. The descriptions themselves can be
  22 defined in firmware (not yet supported) or they can be built-in.
  23
  24 Usage
  25 -----
  26
  27 Device connections should exist before device ``->probe`` callback is called for
  28 either endpoint device in the description. If the connections are defined in
  29 firmware, this is not a problem. It should be considered if the connection
  30 descriptions are "built-in", and need to be added separately.
  31
  32 The connection description consists of the names of the two devices with the
  33 connection, i.e. the endpoints, and unique identifier for the connection which
  34 is needed if there are multiple connections between the two devices.
  35
  36 After a description exists, the devices in it can request reference to the other
  37 endpoint device, or they can request the description itself.
  38
  39 API
  40 ---
  41
  42 .. kernel-doc:: drivers/base/devcon.c
  43    :functions: device_connection_find_match device_connection_find device_connection_add device_connection_remove