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) --- include/linux/stmmac.h | 30 ++++++++++++++++++++++-------- 1 file changed, 22 insertions(+), 8 deletions(-) diff --git a/include/linux/stmmac.h b/include/linux/stmmac.h index e284f04964bf..f14f34ec6d5e 100644 --- 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; -- 2.47.3