tjh.dev / kernel
Linux kernel mirror (for testing) git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
kernel os linux
1
fork

Configure Feed

Select the types of activity you want to include in your feed.

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>

authored by

Russell King (Oracle) and committed by
Jakub Kicinski 32a8d2a1 6a46e4fa

+22 -8
+22 -8
include/linux/stmmac.h
··· 190 190 int bus_id; 191 191 int phy_addr; 192 192 /* MAC ----- optional PCS ----- SerDes ----- optional PHY ----- Media 193 - * ^ ^ 194 - * mac_interface phy_interface 193 + * ^ ^ 194 + * mac_interface phy_interface 195 195 * 196 - * mac_interface is the MAC-side interface, which may be the same 197 - * as phy_interface if there is no intervening PCS. If there is a 198 - * PCS, then mac_interface describes the interface mode between the 199 - * MAC and PCS, and phy_interface describes the interface mode 200 - * between the PCS and PHY. 196 + * The Synopsys dwmac core only covers the MAC and an optional 197 + * integrated PCS. Where the integrated PCS is used with a SerDes, 198 + * e.g. for 1000base-X or Cisco SGMII, the connection between the 199 + * PCS and SerDes will be TBI. 200 + * 201 + * Where the Synopsys dwmac core has been instantiated with multiple 202 + * interface modes, these are selected via core-external configuration 203 + * which is sampled when the dwmac core is reset. How this is done is 204 + * platform glue specific, but this defines the interface used from 205 + * the Synopsys dwmac core to the rest of the SoC. 206 + * 207 + * Where PCS other than the optional integrated Synopsys dwmac PCS 208 + * is used, this counts as "the rest of the SoC" in the above 209 + * paragraph. 210 + * 211 + * Thus, mac_interface is of little use inside the stmmac code; 212 + * please do not use unless there is a definite requirement, and 213 + * make sure to gain review feedback first. 201 214 */ 202 215 phy_interface_t mac_interface; 203 216 /* phy_interface is the PHY-side interface - the interface used by 204 - * an attached PHY. 217 + * an attached PHY or SFP etc. This is equivalent to the interface 218 + * that phylink uses. 205 219 */ 206 220 phy_interface_t phy_interface; 207 221 struct stmmac_mdio_bus_data *mdio_bus_data;