Documentation/networking/device_drivers/ethernet/freescale/dpaa2/mac-phy-support.rst

   1 .. SPDX-License-Identifier: GPL-2.0
   2 .. include:: <isonum.txt>
   3
   4 =======================
   5 DPAA2 MAC / PHY support
   6 =======================
   7
   8 :Copyright: |copy| 2019 NXP
   9
  10 Overview
  11 --------
  12
  13 The DPAA2 MAC / PHY support consists of a set of APIs that help DPAA2 network
  14 drivers (dpaa2-eth, dpaa2-ethsw) interract with the PHY library.
  15
  16 DPAA2 Software Architecture
  17 ---------------------------
  18
  19 Among other DPAA2 objects, the fsl-mc bus exports DPNI objects (abstracting a
  20 network interface) and DPMAC objects (abstracting a MAC). The dpaa2-eth driver
  21 probes on the DPNI object and connects to and configures a DPMAC object with
  22 the help of phylink.
  23
  24 Data connections may be established between a DPNI and a DPMAC, or between two
  25 DPNIs. Depending on the connection type, the netif_carrier_[on/off] is handled
  26 directly by the dpaa2-eth driver or by phylink.
  27
  28 .. code-block:: none
  29
  30   Sources of abstracted link state information presented by the MC firmware
  31
  32                                                +--------------------------------------+
  33   +------------+                  +---------+  |                           xgmac_mdio |
  34   | net_device |                  | phylink |--|  +-----+  +-----+  +-----+  +-----+  |
  35   +------------+                  +---------+  |  | PHY |  | PHY |  | PHY |  | PHY |  |
  36         |                             |        |  +-----+  +-----+  +-----+  +-----+  |
  37       +------------------------------------+   |                    External MDIO bus |
  38       |            dpaa2-eth               |   +--------------------------------------+
  39       +------------------------------------+
  40         |                             |                                           Linux
  41   ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  42         |                             |                                     MC firmware
  43         |              /|             V
  44   +----------+        / |       +----------+
  45   |          |       /  |       |          |
  46   |          |       |  |       |          |
  47   |   DPNI   |<------|  |<------|   DPMAC  |
  48   |          |       |  |       |          |
  49   |          |       \  |<---+  |          |
  50   +----------+        \ |    |  +----------+
  51                        \|    |
  52                              |
  53            +--------------------------------------+
  54            | MC firmware polling MAC PCS for link |
  55            |  +-----+  +-----+  +-----+  +-----+  |
  56            |  | PCS |  | PCS |  | PCS |  | PCS |  |
  57            |  +-----+  +-----+  +-----+  +-----+  |
  58            |                    Internal MDIO bus |
  59            +--------------------------------------+
  60
  61
  62 Depending on an MC firmware configuration setting, each MAC may be in one of two modes:
  63
  64 - DPMAC_LINK_TYPE_FIXED: the link state management is handled exclusively by
  65   the MC firmware by polling the MAC PCS. Without the need to register a
  66   phylink instance, the dpaa2-eth driver will not bind to the connected dpmac
  67   object at all.
  68
  69 - DPMAC_LINK_TYPE_PHY: The MC firmware is left waiting for link state update
  70   events, but those are in fact passed strictly between the dpaa2-mac (based on
  71   phylink) and its attached net_device driver (dpaa2-eth, dpaa2-ethsw),
  72   effectively bypassing the firmware.
  73
  74 Implementation
  75 --------------
  76
  77 At probe time or when a DPNI's endpoint is dynamically changed, the dpaa2-eth
  78 is responsible to find out if the peer object is a DPMAC and if this is the
  79 case, to integrate it with PHYLINK using the dpaa2_mac_connect() API, which
  80 will do the following:
  81
  82  - look up the device tree for PHYLINK-compatible of binding (phy-handle)
  83  - will create a PHYLINK instance associated with the received net_device
  84  - connect to the PHY using phylink_of_phy_connect()
  85
  86 The following phylink_mac_ops callback are implemented:
  87
  88  - .validate() will populate the supported linkmodes with the MAC capabilities
  89    only when the phy_interface_t is RGMII_* (at the moment, this is the only
  90    link type supported by the driver).
  91
  92  - .mac_config() will configure the MAC in the new configuration using the
  93    dpmac_set_link_state() MC firmware API.
  94
  95  - .mac_link_up() / .mac_link_down() will update the MAC link using the same
  96    API described above.
  97
  98 At driver unbind() or when the DPNI object is disconnected from the DPMAC, the
  99 dpaa2-eth driver calls dpaa2_mac_disconnect() which will, in turn, disconnect
 100 from the PHY and destroy the PHYLINK instance.
 101
 102 In case of a DPNI-DPMAC connection, an 'ip link set dev eth0 up' would start
 103 the following sequence of operations:
 104
 105 (1) phylink_start() called from .dev_open().
 106 (2) The .mac_config() and .mac_link_up() callbacks are called by PHYLINK.
 107 (3) In order to configure the HW MAC, the MC Firmware API
 108     dpmac_set_link_state() is called.
 109 (4) The firmware will eventually setup the HW MAC in the new configuration.
 110 (5) A netif_carrier_on() call is made directly from PHYLINK on the associated
 111     net_device.
 112 (6) The dpaa2-eth driver handles the LINK_STATE_CHANGE irq in order to
 113     enable/disable Rx taildrop based on the pause frame settings.
 114
 115 .. code-block:: none
 116
 117   +---------+               +---------+
 118   | PHYLINK |-------------->|  eth0   |
 119   +---------+           (5) +---------+
 120   (1) ^  |
 121       |  |
 122       |  v (2)
 123   +-----------------------------------+
 124   |             dpaa2-eth             |
 125   +-----------------------------------+
 126          |                    ^ (6)
 127          |                    |
 128          v (3)                |
 129   +---------+---------------+---------+
 130   |  DPMAC  |               |  DPNI   |
 131   +---------+               +---------+
 132   |            MC Firmware            |
 133   +-----------------------------------+
 134          |
 135          |
 136          v (4)
 137   +-----------------------------------+
 138   |             HW MAC                |
 139   +-----------------------------------+
 140
 141 In case of a DPNI-DPNI connection, a usual sequence of operations looks like
 142 the following:
 143
 144 (1) ip link set dev eth0 up
 145 (2) The dpni_enable() MC API called on the associated fsl_mc_device.
 146 (3) ip link set dev eth1 up
 147 (4) The dpni_enable() MC API called on the associated fsl_mc_device.
 148 (5) The LINK_STATE_CHANGED irq is received by both instances of the dpaa2-eth
 149     driver because now the operational link state is up.
 150 (6) The netif_carrier_on() is called on the exported net_device from
 151     link_state_update().
 152
 153 .. code-block:: none
 154
 155   +---------+               +---------+
 156   |  eth0   |               |  eth1   |
 157   +---------+               +---------+
 158       |  ^                     ^  |
 159       |  |                     |  |
 160   (1) v  | (6)             (6) |  v (3)
 161   +---------+               +---------+
 162   |dpaa2-eth|               |dpaa2-eth|
 163   +---------+               +---------+
 164       |  ^                     ^  |
 165       |  |                     |  |
 166   (2) v  | (5)             (5) |  v (4)
 167   +---------+---------------+---------+
 168   |  DPNI   |               |  DPNI   |
 169   +---------+               +---------+
 170   |            MC Firmware            |
 171   +-----------------------------------+
 172
 173
 174 Exported API
 175 ------------
 176
 177 Any DPAA2 driver that drivers endpoints of DPMAC objects should service its
 178 _EVENT_ENDPOINT_CHANGED irq and connect/disconnect from the associated DPMAC
 179 when necessary using the below listed API::
 180
 181  - int dpaa2_mac_connect(struct dpaa2_mac *mac);
 182  - void dpaa2_mac_disconnect(struct dpaa2_mac *mac);
 183
 184 A phylink integration is necessary only when the partner DPMAC is not of TYPE_FIXED.
 185 One can check for this condition using the below API::
 186
 187  - bool dpaa2_mac_is_type_fixed(struct fsl_mc_device *dpmac_dev,struct fsl_mc_io *mc_io);
 188
 189 Before connection to a MAC, the caller must allocate and populate the
 190 dpaa2_mac structure with the associated net_device, a pointer to the MC portal
 191 to be used and the actual fsl_mc_device structure of the DPMAC.