net: stmmac: add documentation for clocks

Add documentation covering stmmac_clk, pclk, clk_ptp_ref and clk_tx_i
in the hope that this will help understand what each of these clocks
are for.

There is confusion around stmmac_clk and pclk which can't be easily
resolved today as the Imagination Technologies Pistachio board that
pclk was introduced for has no public documentation and is likely now
obsolete. So the origins of pclk are lost to the winds of time.

Signed-off-by: Russell King (Oracle) <rmk+kernel@armlinux.org.uk>
Tested-by: Mohd Ayaan Anwar <mohd.anwar@oss.qualcomm.com>
Link: https://patch.msgid.link/E1vzX5Z-0000000CVsb-1XTm@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 1af3a5e197c91309479d0cfff41ce43fee116a34..937985276e6b4c90e8434ab1ceb01ba602aff131 100644 (file)
--- a/include/linux/stmmac.h
+++ b/include/linux/stmmac.h
@@ -300,10 +300,41 @@ struct plat_stmmacenet_data {
        struct phylink_pcs *(*select_pcs)(struct stmmac_priv *priv,
                                          phy_interface_t interface);
        void *bsp_priv;
+
+       /* stmmac clocks:
+        *  stmmac_clk: CSR clock (which can be hclk_i, clk_csr_i, aclk_i,
+        *    or clk_app_i depending on GMAC configuration). This clock
+        *    generates the MDC clock.
+        *
+        *  pclk: introduced for Imagination Technologies Pistachio board -
+        *    see 5f9755d26fbf ("stmmac: Add an optional register interface
+        *    clock"). This is probably used for cases where separate clocks
+        *    are provided for the host interface and register interface. In
+        *    this case, as the MDC clock is derived from stmmac_clk, pclk
+        *    can only really be the "application clock" for the "host
+        *    interface" and not the "register interface" aka CSR clock as
+        *    it is never used when determining the divider for the MDC
+        *    clock.
+        *
+        *  clk_ptp_ref: optional PTP reference clock (clk_ptp_ref_i). When
+        *    present, this clock increments the timestamp value. Otherwise,
+        *    the rate of stmmac_clk will be used.
+        *
+        *  clk_tx_i: MAC transmit clock, which will be 2.5MHz for 10M,
+        *    25MHz for 100M, or 125MHz for 1G irrespective of the interface
+        *    mode. For the DWMAC PHY interface modes:
+        *
+        *    GMII/MII  PHY's transmit clock for 10M (2.5MHz) or 100M (25MHz),
+        *              or 125MHz local clock for 1G mode
+        *    RMII      50MHz RMII clock divided by 2 or 20.
+        *    RGMII     125MHz local clock divided by 1, 5, or 50.
+        *    SGMII     125MHz SerDes clock divided by 1, 5, or 50.
+        *    TBI/RTBI  125MHz SerDes clock
+        */
        struct clk *stmmac_clk;
        struct clk *pclk;
        struct clk *clk_ptp_ref;
-       struct clk *clk_tx_i;           /* clk_tx_i to MAC core */
+       struct clk *clk_tx_i;
        unsigned long clk_ptp_rate;
        unsigned long clk_ref_rate;
        struct clk_bulk_data *clks;