Merge branch 'bugfix/eth_plus_wifi_doc_v5.0' into 'release/v5.0'

docs(esp_eth): added warning to not use ESP32 as ETH CLK source with WiFi (v5.0)

See merge request espressif/esp-idf!33248

components/esp_eth/Kconfig

@@ -59,13 +59,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
@@ -74,6 +72,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
 

components/esp_eth/include/esp_eth_mac.h

@@ -349,6 +349,8 @@ typedef enum {
 /**
  * @brief RMII Clock GPIO number Options
  *
+ * @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 {
     /**
@@ -362,10 +364,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,

docs/en/api-reference/network/esp_eth.rst

@@ -148,8 +148,20 @@ Ethernet driver is composed of two parts: MAC and PHY.
         * Disable or power down the crystal oscillator (as the case *b* in the picture).
         * Force the PHY device in reset status (as the case *a* in the picture). **This could fail for some PHY device** (i.e. it still outputs signal to GPIO0 even in reset state).
 
-    **No matter which RMII clock mode you select, you really need to take care of the signal integrity of REF_CLK in your hardware design!**
-    Keep the trace as short as possible. Keep it away from RF devices. Keep it away from inductor elements.
+        What is more, if you are not using PSRAM in your design, GPIO16 and GPIO17 are also available to output the reference clock signal. See :cpp:enumerator:`emac_rmii_clock_gpio_t::EMAC_CLK_OUT_GPIO` and :cpp:enumerator:`emac_rmii_clock_gpio_t::EMAC_CLK_OUT_180_GPIO` or :ref:`CONFIG_ETH_RMII_CLK_OUT_GPIO` for more information.
+
+        If the RMII clock mode is configured to :cpp:enumerator:`emac_rmii_clock_mode_t::EMAC_CLK_EXT_IN` (or ``CONFIG_ETH_RMII_CLK_INPUT`` is selected), then ``GPIO0`` is the only choice to input the ``REF_CLK`` signal. Please note that ``GPIO0`` is also an important strapping GPIO on ESP32. If GPIO0 samples a low level during power-up, ESP32 will go into download mode. The system will get halted until a manually reset. The workaround for this issue is disabling the ``REF_CLK`` in hardware by default so that the strapping pin is not interfered by other signals in the boot stage. Then, re-enable the ``REF_CLK`` in the Ethernet driver installation stage.
+
+        The ways to disable the ``REF_CLK`` signal can be:
+
+        * Disable or power down the crystal oscillator (as the case **b** in the picture).
+
+        * 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 Wi-Fi**, don’t select ESP32 as source of ``REF_CLK`` as it would result in ``REF_CLK`` instability. Either disable Wi-Fi or use a PHY or an external oscillator as the ``REF_CLK`` source.
+
+    **No matter which RMII clock mode you select, you really need to take care of the signal integrity of REF_CLK in your hardware design!** Keep the trace as short as possible. Keep the trace as short as possible. Keep it away from RF devices. Keep it away from inductor elements.
 
     .. note::
         ESP-IDF only supports the RMII interface (i.e. always select ``CONFIG_ETH_PHY_INTERFACE_RMII`` in Kconfig option :ref:`CONFIG_ETH_PHY_INTERFACE`).

docs/zh_CN/api-reference/network/esp_eth.rst

@@ -142,6 +142,10 @@ ESP-IDF 提供一系列功能强大且兼具一致性的 API，为内部以太
     .. note::
         ESP-IDF 只支持 RMII 接口（即在 Kconfig 选项 :ref:`CONFIG_ETH_PHY_INTERFACE` 中始终选择 ``CONFIG_ETH_PHY_INTERFACE_RMII``）。
 
+    .. warning::
+            如希望 **以太网与 Wi-Fi 一起工作**，不要选择 ESP32 作为 ``REF_CLK`` 的源，因为这会导致 ``REF_CLK`` 不稳定。可以选择禁用 Wi-Fi，或使用 PHY 或外部振荡器作为 ``REF_CLK`` 的源。
+
+
         在数据平面使用的信号通过 MUX 连接至特定的 GPIO，这些信号无法配置至其他 GPIO。在控制平面使用的信号则可以通过 Matrix 矩阵路由到任何空闲 GPIO。相关的硬件设计示例，请参考 `ESP32-Ethernet-Kit <https://docs.espressif.com/projects/esp-dev-kits/zh_CN/latest/esp32/esp32-ethernet-kit/index.html>`_。
 
 根据您的以太网板设计，需要分别为 MAC 和 PHY 配置必要的参数，通过两者完成驱动程序的安装。