195 lines · plain
1.. SPDX-License-Identifier: GPL-2.02.. include:: <isonum.txt>3 4=======================5DPAA2 MAC / PHY support6=======================7 8:Copyright: |copy| 2019 NXP9 10Overview11--------12 13The DPAA2 MAC / PHY support consists of a set of APIs that help DPAA2 network14drivers (dpaa2-eth, dpaa2-ethsw) interact with the PHY library.15 16DPAA2 Software Architecture17---------------------------18 19Among other DPAA2 objects, the fsl-mc bus exports DPNI objects (abstracting a20network interface) and DPMAC objects (abstracting a MAC). The dpaa2-eth driver21probes on the DPNI object and connects to and configures a DPMAC object with22the help of phylink.23 24Data connections may be established between a DPNI and a DPMAC, or between two25DPNIs. Depending on the connection type, the netif_carrier_[on/off] is handled26directly by the dpaa2-eth driver or by phylink.27 28.. code-block:: none29 30 Sources of abstracted link state information presented by the MC firmware31 32 +--------------------------------------+33 +------------+ +---------+ | xgmac_mdio |34 | net_device | | phylink |--| +-----+ +-----+ +-----+ +-----+ |35 +------------+ +---------+ | | PHY | | PHY | | PHY | | PHY | |36 | | | +-----+ +-----+ +-----+ +-----+ |37 +------------------------------------+ | External MDIO bus |38 | dpaa2-eth | +--------------------------------------+39 +------------------------------------+40 | | Linux41 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~42 | | MC firmware43 | /| V44 +----------+ / | +----------+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 by65 the MC firmware by polling the MAC PCS. Without the need to register a66 phylink instance, the dpaa2-eth driver will not bind to the connected dpmac67 object at all.68 69- DPMAC_LINK_TYPE_PHY: The MC firmware is left waiting for link state update70 events, but those are in fact passed strictly between the dpaa2-mac (based on71 phylink) and its attached net_device driver (dpaa2-eth, dpaa2-ethsw),72 effectively bypassing the firmware.73 74Implementation75--------------76 77At probe time or when a DPNI's endpoint is dynamically changed, the dpaa2-eth78is responsible to find out if the peer object is a DPMAC and if this is the79case, to integrate it with PHYLINK using the dpaa2_mac_connect() API, which80will 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_device84 - 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 capabilities89 only when the phy_interface_t is RGMII_* (at the moment, this is the only90 link type supported by the driver).91 92 - .mac_config() will configure the MAC in the new configuration using the93 dpmac_set_link_state() MC firmware API.94 95 - .mac_link_up() / .mac_link_down() will update the MAC link using the same96 API described above.97 98At driver unbind() or when the DPNI object is disconnected from the DPMAC, the99dpaa2-eth driver calls dpaa2_mac_disconnect() which will, in turn, disconnect100from the PHY and destroy the PHYLINK instance.101 102In case of a DPNI-DPMAC connection, an 'ip link set dev eth0 up' would start103the 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 API108 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 associated111 net_device.112(6) The dpaa2-eth driver handles the LINK_STATE_CHANGE irq in order to113 enable/disable Rx taildrop based on the pause frame settings.114 115.. code-block:: none116 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 like142the following:143 144(1) ip link set dev eth0 up145(2) The dpni_enable() MC API called on the associated fsl_mc_device.146(3) ip link set dev eth1 up147(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-eth149 driver because now the operational link state is up.150(6) The netif_carrier_on() is called on the exported net_device from151 link_state_update().152 153.. code-block:: none154 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 API175------------176 177Any DPAA2 driver that drivers endpoints of DPMAC objects should service its178_EVENT_ENDPOINT_CHANGED irq and connect/disconnect from the associated DPMAC179when 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 of185``TYPE_FIXED``. This means it is either of ``TYPE_PHY``, or of186``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 for188this 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 the193dpaa2_mac structure with the associated net_device, a pointer to the MC portal194to be used and the actual fsl_mc_device structure of the DPMAC.195