From 50704ffa70b6144a08efe2d2328f2a81960ad807 Mon Sep 17 00:00:00 2001
From: Ondrej Kosta <ondrej.kosta@espressif.com>
Date: Fri, 9 Aug 2024 15:53:08 +0200
Subject: [PATCH] docs(esp_eth): added warning to not use ESP32 as ETH CLK
 source with WiFi

---
 components/esp_eth/Kconfig                   | 14 +++++++-------
 components/esp_eth/include/esp_eth_mac_esp.h |  8 ++++----
 docs/en/api-reference/network/esp_eth.rst    |  3 +++
 3 files changed, 14 insertions(+), 11 deletions(-)

diff --git a/components/esp_eth/Kconfig b/components/esp_eth/Kconfig
index fe8fd3961d..a5edf4d9fe 100644
--- a/components/esp_eth/Kconfig
+++ b/components/esp_eth/Kconfig
@@ -62,13 +62,11 @@ menu "Ethernet"
                 bool "Output RMII clock from GPIO0 (Experimental!)"
                 default n
                 help
-                    GPIO0 can be set to output a pre-divided PLL clock (test only!).
-                    Enabling this option will configure GPIO0 to output a 50MHz clock.
-                    In fact this clock doesn't have directly relationship with EMAC peripheral.
-                    Sometimes this clock won't work well with your PHY chip. You might need to
-                    add some extra devices after GPIO0 (e.g. inverter).
-                    Note that outputting RMII clock on GPIO0 is an experimental practice.
-                    If you want the Ethernet to work with WiFi, don't select GPIO0 output mode for stability.
+                    GPIO0 can be set to output a pre-divided PLL clock. Enabling this option will configure
+                    GPIO0 to output a 50MHz clock. In fact this clock doesn't have directly relationship with
+                    EMAC peripheral. Sometimes this clock may not work well with your PHY chip.
+                    WARNING: If you want the Ethernet to work with WiFi, don’t select ESP32 as RMII CLK output
+                    as it would result in clock instability!
 
             if !ETH_RMII_CLK_OUTPUT_GPIO0
                 config ETH_RMII_CLK_OUT_GPIO
@@ -78,6 +76,8 @@ menu "Ethernet"
                     default 17
                     help
                         Set the GPIO number to output RMII Clock.
+                        WARNING: If you want the Ethernet to work with WiFi, don’t select ESP32 as RMII CLK output
+                        as it would result in clock instability!
             endif # !ETH_RMII_CLK_OUTPUT_GPIO0
         endif # ETH_RMII_CLK_OUTPUT
 
diff --git a/components/esp_eth/include/esp_eth_mac_esp.h b/components/esp_eth/include/esp_eth_mac_esp.h
index 14bb0d274a..f18bf4d75c 100644
--- a/components/esp_eth/include/esp_eth_mac_esp.h
+++ b/components/esp_eth/include/esp_eth_mac_esp.h
@@ -51,6 +51,8 @@ typedef enum {
 /**
  * @brief RMII Clock GPIO number Options for ESP32
  *
+ * @warning If you want the Ethernet to work with WiFi, don’t select ESP32 as RMII CLK output as it would result in clock instability.
+ *
  */
 typedef enum {
     /**
@@ -64,10 +66,8 @@ typedef enum {
     /**
      * @brief Output RMII Clock from internal APLL Clock available at GPIO0
      *
-     * @note GPIO0 can be set to output a pre-divided PLL clock (test only!). Enabling this option will configure GPIO0 to output a 50MHz clock.
-     * In fact this clock doesn’t have directly relationship with EMAC peripheral. Sometimes this clock won’t work well with your PHY chip.
-     * You might need to add some extra devices after GPIO0 (e.g. inverter). Note that outputting RMII clock on GPIO0 is an experimental practice.
-     * If you want the Ethernet to work with WiFi, don’t select GPIO0 output mode for stability.
+     * @note GPIO0 can be set to output a pre-divided PLL clock. Enabling this option will configure GPIO0 to output a 50MHz clock.
+     * In fact this clock doesn’t have directly relationship with EMAC peripheral. Sometimes this clock may not work well with your PHY chip.
      *
      */
     EMAC_APPL_CLK_OUT_GPIO = 0,
diff --git a/docs/en/api-reference/network/esp_eth.rst b/docs/en/api-reference/network/esp_eth.rst
index c90390da9a..5c98f7447e 100644
--- a/docs/en/api-reference/network/esp_eth.rst
+++ b/docs/en/api-reference/network/esp_eth.rst
@@ -165,6 +165,9 @@ The Ethernet driver is composed of two parts: MAC and PHY.
 
             * Force the PHY device to reset status (as the case **a** in the picture). **This could fail for some PHY device** (i.e., it still outputs signals to GPIO0 even in reset state).
 
+        .. warning::
+            If you want the **Ethernet to work with WiFi**, don’t select ESP32 as source of ``REF_CLK`` as it would result in ``REF_CLK`` instability. Either disable WiFi or use a PHY or an external oscillator as the ``REF_CLK`` source.
+
     .. only:: not esp32
 
         .. note::