0001 .. SPDX-License-Identifier: GPL-2.0
0002 .. include:: <isonum.txt>
0003
0004 =======================
0005 DPAA2 MAC / PHY support
0006 =======================
0007
0008 :Copyright: |copy| 2019 NXP
0009
0010 Overview
0011 --------
0012
0013 The DPAA2 MAC / PHY support consists of a set of APIs that help DPAA2 network
0014 drivers (dpaa2-eth, dpaa2-ethsw) interract with the PHY library.
0015
0016 DPAA2 Software Architecture
0017 ---------------------------
0018
0019 Among other DPAA2 objects, the fsl-mc bus exports DPNI objects (abstracting a
0020 network interface) and DPMAC objects (abstracting a MAC). The dpaa2-eth driver
0021 probes on the DPNI object and connects to and configures a DPMAC object with
0022 the help of phylink.
0023
0024 Data connections may be established between a DPNI and a DPMAC, or between two
0025 DPNIs. Depending on the connection type, the netif_carrier_[on/off] is handled
0026 directly by the dpaa2-eth driver or by phylink.
0027
0028 .. code-block:: none
0029
0030 Sources of abstracted link state information presented by the MC firmware
0031
0032 +--------------------------------------+
0033 +------------+ +---------+ | xgmac_mdio |
0034 | net_device | | phylink |--| +-----+ +-----+ +-----+ +-----+ |
0035 +------------+ +---------+ | | PHY | | PHY | | PHY | | PHY | |
0036 | | | +-----+ +-----+ +-----+ +-----+ |
0037 +------------------------------------+ | External MDIO bus |
0038 | dpaa2-eth | +--------------------------------------+
0039 +------------------------------------+
0040 | | Linux
0041 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
0042 | | MC firmware
0043 | /| V
0044 +----------+ / | +----------+
0045 | | / | | |
0046 | | | | | |
0047 | DPNI |<------| |<------| DPMAC |
0048 | | | | | |
0049 | | \ |<---+ | |
0050 +----------+ \ | | +----------+
0051 \| |
0052 |
0053 +--------------------------------------+
0054 | MC firmware polling MAC PCS for link |
0055 | +-----+ +-----+ +-----+ +-----+ |
0056 | | PCS | | PCS | | PCS | | PCS | |
0057 | +-----+ +-----+ +-----+ +-----+ |
0058 | Internal MDIO bus |
0059 +--------------------------------------+
0060
0061
0062 Depending on an MC firmware configuration setting, each MAC may be in one of two modes:
0063
0064 - DPMAC_LINK_TYPE_FIXED: the link state management is handled exclusively by
0065 the MC firmware by polling the MAC PCS. Without the need to register a
0066 phylink instance, the dpaa2-eth driver will not bind to the connected dpmac
0067 object at all.
0068
0069 - DPMAC_LINK_TYPE_PHY: The MC firmware is left waiting for link state update
0070 events, but those are in fact passed strictly between the dpaa2-mac (based on
0071 phylink) and its attached net_device driver (dpaa2-eth, dpaa2-ethsw),
0072 effectively bypassing the firmware.
0073
0074 Implementation
0075 --------------
0076
0077 At probe time or when a DPNI's endpoint is dynamically changed, the dpaa2-eth
0078 is responsible to find out if the peer object is a DPMAC and if this is the
0079 case, to integrate it with PHYLINK using the dpaa2_mac_connect() API, which
0080 will do the following:
0081
0082 - look up the device tree for PHYLINK-compatible of binding (phy-handle)
0083 - will create a PHYLINK instance associated with the received net_device
0084 - connect to the PHY using phylink_of_phy_connect()
0085
0086 The following phylink_mac_ops callback are implemented:
0087
0088 - .validate() will populate the supported linkmodes with the MAC capabilities
0089 only when the phy_interface_t is RGMII_* (at the moment, this is the only
0090 link type supported by the driver).
0091
0092 - .mac_config() will configure the MAC in the new configuration using the
0093 dpmac_set_link_state() MC firmware API.
0094
0095 - .mac_link_up() / .mac_link_down() will update the MAC link using the same
0096 API described above.
0097
0098 At driver unbind() or when the DPNI object is disconnected from the DPMAC, the
0099 dpaa2-eth driver calls dpaa2_mac_disconnect() which will, in turn, disconnect
0100 from the PHY and destroy the PHYLINK instance.
0101
0102 In case of a DPNI-DPMAC connection, an 'ip link set dev eth0 up' would start
0103 the following sequence of operations:
0104
0105 (1) phylink_start() called from .dev_open().
0106 (2) The .mac_config() and .mac_link_up() callbacks are called by PHYLINK.
0107 (3) In order to configure the HW MAC, the MC Firmware API
0108 dpmac_set_link_state() is called.
0109 (4) The firmware will eventually setup the HW MAC in the new configuration.
0110 (5) A netif_carrier_on() call is made directly from PHYLINK on the associated
0111 net_device.
0112 (6) The dpaa2-eth driver handles the LINK_STATE_CHANGE irq in order to
0113 enable/disable Rx taildrop based on the pause frame settings.
0114
0115 .. code-block:: none
0116
0117 +---------+ +---------+
0118 | PHYLINK |-------------->| eth0 |
0119 +---------+ (5) +---------+
0120 (1) ^ |
0121 | |
0122 | v (2)
0123 +-----------------------------------+
0124 | dpaa2-eth |
0125 +-----------------------------------+
0126 | ^ (6)
0127 | |
0128 v (3) |
0129 +---------+---------------+---------+
0130 | DPMAC | | DPNI |
0131 +---------+ +---------+
0132 | MC Firmware |
0133 +-----------------------------------+
0134 |
0135 |
0136 v (4)
0137 +-----------------------------------+
0138 | HW MAC |
0139 +-----------------------------------+
0140
0141 In case of a DPNI-DPNI connection, a usual sequence of operations looks like
0142 the following:
0143
0144 (1) ip link set dev eth0 up
0145 (2) The dpni_enable() MC API called on the associated fsl_mc_device.
0146 (3) ip link set dev eth1 up
0147 (4) The dpni_enable() MC API called on the associated fsl_mc_device.
0148 (5) The LINK_STATE_CHANGED irq is received by both instances of the dpaa2-eth
0149 driver because now the operational link state is up.
0150 (6) The netif_carrier_on() is called on the exported net_device from
0151 link_state_update().
0152
0153 .. code-block:: none
0154
0155 +---------+ +---------+
0156 | eth0 | | eth1 |
0157 +---------+ +---------+
0158 | ^ ^ |
0159 | | | |
0160 (1) v | (6) (6) | v (3)
0161 +---------+ +---------+
0162 |dpaa2-eth| |dpaa2-eth|
0163 +---------+ +---------+
0164 | ^ ^ |
0165 | | | |
0166 (2) v | (5) (5) | v (4)
0167 +---------+---------------+---------+
0168 | DPNI | | DPNI |
0169 +---------+ +---------+
0170 | MC Firmware |
0171 +-----------------------------------+
0172
0173
0174 Exported API
0175 ------------
0176
0177 Any DPAA2 driver that drivers endpoints of DPMAC objects should service its
0178 _EVENT_ENDPOINT_CHANGED irq and connect/disconnect from the associated DPMAC
0179 when necessary using the below listed API::
0180
0181 - int dpaa2_mac_connect(struct dpaa2_mac *mac);
0182 - void dpaa2_mac_disconnect(struct dpaa2_mac *mac);
0183
0184 A phylink integration is necessary only when the partner DPMAC is not of TYPE_FIXED.
0185 One can check for this condition using the below API::
0186
0187 - bool dpaa2_mac_is_type_fixed(struct fsl_mc_device *dpmac_dev,struct fsl_mc_io *mc_io);
0188
0189 Before connection to a MAC, the caller must allocate and populate the
0190 dpaa2_mac structure with the associated net_device, a pointer to the MC portal
0191 to be used and the actual fsl_mc_device structure of the DPMAC.
