net: stmmac: rework mac_interface and phy_interface documentation

Based on new research, it has come to light that the comment that I
added in a014c35556b9 ("net: stmmac: clarify difference between
"interface" and "phy_interface"") is not fully correct.

Update the comment to properly describe the difference between the two.

All of the DTS files in the kernel tree do not mention the "mac-mode"
property, which results in mac_interface and phy_interface being the
same. Also, none of the platform glue drivers set mac_interface to
anything but PHY_INTERFACE_MODE_NA. This means that for all the
platforms known to mainline, mac_interface is either the same as
phy_interface, or it is PHY_INTERFACE_MODE_NA.

Thus, updating the definition for mac_interface in stmmac.h has no
material effect on current uses known to mainline, but the change opens
the door to cleaning up all uses.

Signed-off-by: Russell King (Oracle) <rmk+kernel@armlinux.org.uk>
Link: https://patch.msgid.link/E1uytpB-00000006H23-0pRi@rmk-PC.armlinux.org.uk
Signed-off-by: Jakub Kicinski <kuba@kernel.org>

diff --git a/include/linux/stmmac.h b/include/linux/stmmac.h
index e284f04964bf67782893afd6ec57c3907d229cc0..f14f34ec6d5e2911985823714b71cd27ae885d1d 100644 (file)
--- a/include/linux/stmmac.h
+++ b/include/linux/stmmac.h
@@ -190,18 +190,32 @@ struct plat_stmmacenet_data {
        int bus_id;
        int phy_addr;
        /* MAC ----- optional PCS ----- SerDes ----- optional PHY ----- Media
-        *       ^                               ^
-        * mac_interface                   phy_interface
+        *                          ^            ^
+        *                    mac_interface phy_interface
         *
-        * mac_interface is the MAC-side interface, which may be the same
-        * as phy_interface if there is no intervening PCS. If there is a
-        * PCS, then mac_interface describes the interface mode between the
-        * MAC and PCS, and phy_interface describes the interface mode
-        * between the PCS and PHY.
+        * The Synopsys dwmac core only covers the MAC and an optional
+        * integrated PCS. Where the integrated PCS is used with a SerDes,
+        * e.g. for 1000base-X or Cisco SGMII, the connection between the
+        * PCS and SerDes will be TBI.
+        *
+        * Where the Synopsys dwmac core has been instantiated with multiple
+        * interface modes, these are selected via core-external configuration
+        * which is sampled when the dwmac core is reset. How this is done is
+        * platform glue specific, but this defines the interface used from
+        * the Synopsys dwmac core to the rest of the SoC.
+        *
+        * Where PCS other than the optional integrated Synopsys dwmac PCS
+        * is used, this counts as "the rest of the SoC" in the above
+        * paragraph.
+        *
+        * Thus, mac_interface is of little use inside the stmmac code;
+        * please do not use unless there is a definite requirement, and
+        * make sure to gain review feedback first.
         */
        phy_interface_t mac_interface;
        /* phy_interface is the PHY-side interface - the interface used by
-        * an attached PHY.
+        * an attached PHY or SFP etc. This is equivalent to the interface
+        * that phylink uses.
         */
        phy_interface_t phy_interface;
        struct stmmac_mdio_bus_data *mdio_bus_data;