mac-phy-support.rst

  1.. SPDX-License-Identifier: GPL-2.0
  2.. include:: <isonum.txt>
  3
  4=======================
  5DPAA2 MAC / PHY support
  6=======================
  7
  8:Copyright: |copy| 2019 NXP
  9
 10Overview
 11--------
 12
 13The DPAA2 MAC / PHY support consists of a set of APIs that help DPAA2 network
 14drivers (dpaa2-eth, dpaa2-ethsw) interact with the PHY library.
 15
 16DPAA2 Software Architecture
 17---------------------------
 18
 19Among other DPAA2 objects, the fsl-mc bus exports DPNI objects (abstracting a
 20network interface) and DPMAC objects (abstracting a MAC). The dpaa2-eth driver
 21probes on the DPNI object and connects to and configures a DPMAC object with
 22the help of phylink.
 23
 24Data connections may be established between a DPNI and a DPMAC, or between two
 25DPNIs. Depending on the connection type, the netif_carrier_[on/off] is handled
 26directly 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
 62Depending 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
 74Implementation
 75--------------
 76
 77At probe time or when a DPNI's endpoint is dynamically changed, the dpaa2-eth
 78is responsible to find out if the peer object is a DPMAC and if this is the
 79case, to integrate it with PHYLINK using the dpaa2_mac_connect() API, which
 80will 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
 86The 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
 98At driver unbind() or when the DPNI object is disconnected from the DPMAC, the
 99dpaa2-eth driver calls dpaa2_mac_disconnect() which will, in turn, disconnect
100from the PHY and destroy the PHYLINK instance.
101
102In case of a DPNI-DPMAC connection, an 'ip link set dev eth0 up' would start
103the 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
141In case of a DPNI-DPNI connection, a usual sequence of operations looks like
142the 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
174Exported API
175------------
176
177Any DPAA2 driver that drivers endpoints of DPMAC objects should service its
178_EVENT_ENDPOINT_CHANGED irq and connect/disconnect from the associated DPMAC
179when 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
184A phylink integration is necessary only when the partner DPMAC is not of
185``TYPE_FIXED``. This means it is either of ``TYPE_PHY``, or of
186``TYPE_BACKPLANE`` (the difference being the two that in the ``TYPE_BACKPLANE``
187mode, the MC firmware does not access the PCS registers). One can check for
188this condition using the following helper::
189
190 - static inline bool dpaa2_mac_is_type_phy(struct dpaa2_mac *mac);
191
192Before connection to a MAC, the caller must allocate and populate the
193dpaa2_mac structure with the associated net_device, a pointer to the MC portal
194to be used and the actual fsl_mc_device structure of the DPMAC.