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. 195