dlan17/linux
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

net: stmmac: rework mac_interface and phy_interface documentation

Browse Source 
Based on new research, it has come to light that the comment that I
added in a014c35556 ("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>
This commit is contained in:
Russell King (Oracle)
2025-09-19 17:19:44 -07:00
committed by Jakub Kicinski
parent 6a46e4faa8
commit 32a8d2a197
1 changed files with 22 additions and 8 deletions
Download Patch File Download Diff File Expand all files Collapse all files
include/linux/stmmac.h
+22 -8
View File
@@ -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;