Merge branch 'bugfix/eth_driver_cleanup' into 'master'

Ethernet driver and documentation clean-up

Closes IDF-6339

See merge request espressif/esp-idf!23051

components/esp_eth/src/esp_eth_phy.c

@@ -1,36 +0,0 @@
-/*
- * SPDX-FileCopyrightText: 2019-2022 Espressif Systems (Shanghai) CO LTD
- *
- * SPDX-License-Identifier: Apache-2.0
- */
-#include <string.h>
-#include <stdlib.h>
-#include "esp_log.h"
-#include "esp_eth_driver.h"
-#include "eth_phy_regs_struct.h"
-
-static const char *TAG = "esp_eth.phy";
-
-esp_err_t esp_eth_detect_phy_addr(esp_eth_mediator_t *eth, int *detected_addr)
-{
-    if (!eth || !detected_addr) {
-        ESP_LOGE(TAG, "eth and detected_addr can't be null");
-        return ESP_ERR_INVALID_ARG;
-    }
-    int addr_try = 0;
-    uint32_t reg_value = 0;
-    for (; addr_try < 16; addr_try++) {
-        eth->phy_reg_read(eth, addr_try, ETH_PHY_IDR1_REG_ADDR, &reg_value);
-        if (reg_value != 0xFFFF && reg_value != 0x00) {
-            *detected_addr = addr_try;
-            break;
-        }
-    }
-    if (addr_try < 16) {
-        ESP_LOGD(TAG, "Found PHY address: %d", addr_try);
-        return ESP_OK;
-    } else {
-        ESP_LOGE(TAG, "No PHY device detected");
-        return ESP_ERR_NOT_FOUND;
-    }
-}

components/hal/esp32/include/hal/emac_ll.h

@@ -241,7 +241,7 @@ static inline void emac_ll_set_back_off_limit(emac_mac_dev_t *mac_regs, uint32_t
 
 static inline void emac_ll_deferral_check_enable(emac_mac_dev_t *mac_regs, bool enable)
 {
-    mac_regs->gmacconfig.padcrcstrip = enable;
+    mac_regs->gmacconfig.deferralcheck = enable;
 }
 
 static inline void emac_ll_set_preamble_length(emac_mac_dev_t *mac_regs, uint32_t len)

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

@@ -191,10 +191,11 @@ The Ethernet driver is implemented in an Object-Oriented style. Any operation on
 
     ::
 
-        eth_mac_config_t mac_config = ETH_MAC_DEFAULT_CONFIG();      // apply default MAC configuration
-        mac_config.smi_mdc_gpio_num = CONFIG_EXAMPLE_ETH_MDC_GPIO;   // alter the GPIO used for MDC signal
-        mac_config.smi_mdio_gpio_num = CONFIG_EXAMPLE_ETH_MDIO_GPIO; // alter the GPIO used for MDIO signal
-        esp_eth_mac_t *mac = esp_eth_mac_new_esp32(&mac_config);     // create MAC instance
+        eth_mac_config_t mac_config = ETH_MAC_DEFAULT_CONFIG();                      // apply default common MAC configuration
+        eth_esp32_emac_config_t esp32_emac_config = ETH_ESP32_EMAC_DEFAULT_CONFIG(); // apply default vendor-specific MAC configuration
+        esp32_emac_config.smi_mdc_gpio_num = CONFIG_EXAMPLE_ETH_MDC_GPIO;            // alter the GPIO used for MDC signal
+        esp32_emac_config.smi_mdio_gpio_num = CONFIG_EXAMPLE_ETH_MDIO_GPIO;          // alter the GPIO used for MDIO signal
+        esp_eth_mac_t *mac = esp_eth_mac_new_esp32(&esp32_emac_config, &mac_config); // create MAC instance
 
         eth_phy_config_t phy_config = ETH_PHY_DEFAULT_CONFIG();      // apply default PHY configuration
         phy_config.phy_addr = CONFIG_EXAMPLE_ETH_PHY_ADDR;           // alter the PHY address according to your board design
@@ -214,14 +215,14 @@ The Ethernet driver is implemented in an Object-Oriented style. Any operation on
 
     ::
 
-        eth_mac_config_t mac_config = ETH_MAC_DEFAULT_CONFIG(); // apply default MAC configuration
+        eth_esp32_emac_config_t esp32_emac_config = ETH_ESP32_EMAC_DEFAULT_CONFIG(); // apply default vendor-specific MAC configuration
 
         // ...
 
-        mac_config.interface = EMAC_DATA_INTERFACE_RMII; // alter EMAC Data Interface
-        mac_config.clock_config.rmii.clock_mode = EMAC_CLK_OUT; // select EMAC REF_CLK mode
-        mac_config.clock_config.rmii.clock_gpio = EMAC_CLK_OUT_GPIO; // select GPIO number used to input/output EMAC REF_CLK
-        esp_eth_mac_t *mac = esp_eth_mac_new_esp32(&mac_config); // create MAC instance
+        esp32_emac_config.interface = EMAC_DATA_INTERFACE_RMII;                      // alter EMAC Data Interface
+        esp32_emac_config.clock_config.rmii.clock_mode = EMAC_CLK_OUT;               // select EMAC REF_CLK mode
+        esp32_emac_config.clock_config.rmii.clock_gpio = EMAC_CLK_OUT_GPIO;          // select GPIO number used to input/output EMAC REF_CLK
+        esp_eth_mac_t *mac = esp_eth_mac_new_esp32(&esp32_emac_config, &mac_config); // create MAC instance
 
 
 SPI-Ethernet Module
@@ -231,7 +232,7 @@ SPI-Ethernet Module
 
 ::
 
-    eth_mac_config_t mac_config = ETH_MAC_DEFAULT_CONFIG();      // apply default MAC configuration
+    eth_mac_config_t mac_config = ETH_MAC_DEFAULT_CONFIG();      // apply default common MAC configuration
     eth_phy_config_t phy_config = ETH_PHY_DEFAULT_CONFIG();      // apply default PHY configuration
     phy_config.phy_addr = CONFIG_EXAMPLE_ETH_PHY_ADDR;           // alter the PHY address according to your board design
     phy_config.reset_gpio_num = CONFIG_EXAMPLE_ETH_PHY_RST_GPIO; // alter the GPIO used for PHY reset

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

@@ -191,10 +191,11 @@ ESP-IDF 在宏 :c:macro:`ETH_MAC_DEFAULT_CONFIG` 和 :c:macro:`ETH_PHY_DEFAULT_C
 
     ::
 
-        eth_mac_config_t mac_config = ETH_MAC_DEFAULT_CONFIG();      // 应用默认的 MAC 配置
-        mac_config.smi_mdc_gpio_num = CONFIG_EXAMPLE_ETH_MDC_GPIO;   // 更改用于 MDC 信号的 GPIO
-        mac_config.smi_mdio_gpio_num = CONFIG_EXAMPLE_ETH_MDIO_GPIO; // 更改用于 MDIO 信号的 GPIO
-        esp_eth_mac_t *mac = esp_eth_mac_new_esp32(&mac_config);     // 创建 MAC 实例
+        eth_mac_config_t mac_config = ETH_MAC_DEFAULT_CONFIG();                      // 应用默认的通用 MAC 配置
+        eth_esp32_emac_config_t esp32_emac_config = ETH_ESP32_EMAC_DEFAULT_CONFIG(); // 应用默认的供应商特定 MAC 配置
+        esp32_emac_config.smi_mdc_gpio_num = CONFIG_EXAMPLE_ETH_MDC_GPIO;            // 更改用于 MDC 信号的 GPIO
+        esp32_emac_config.smi_mdio_gpio_num = CONFIG_EXAMPLE_ETH_MDIO_GPIO;          // 更改用于 MDIO 信号的 GPIO
+        esp_eth_mac_t *mac = esp_eth_mac_new_esp32(&esp32_emac_config, &mac_config); // 创建 MAC 实例
 
         eth_phy_config_t phy_config = ETH_PHY_DEFAULT_CONFIG();      // 应用默认的 PHY 配置
         phy_config.phy_addr = CONFIG_EXAMPLE_ETH_PHY_ADDR;           // 根据开发板设计更改 PHY 地址
@@ -214,14 +215,14 @@ ESP-IDF 在宏 :c:macro:`ETH_MAC_DEFAULT_CONFIG` 和 :c:macro:`ETH_PHY_DEFAULT_C
 
     ::
 
-        eth_mac_config_t mac_config = ETH_MAC_DEFAULT_CONFIG(); // 应用默认的 MAC 配置
+        eth_esp32_emac_config_t esp32_emac_config = ETH_ESP32_EMAC_DEFAULT_CONFIG(); // 应用默认的供应商特定 MAC 配置
 
         // ...
 
-        mac_config.interface = EMAC_DATA_INTERFACE_RMII; // 更改 EMAC 数据接口
-        mac_config.clock_config.rmii.clock_mode = EMAC_CLK_OUT; //  配置 EMAC REF_CLK 模式
-        mac_config.clock_config.rmii.clock_gpio = EMAC_CLK_OUT_GPIO; // 配置用于输入/输出 EMAC REF_CLK 的 GPIO 编号
-        esp_eth_mac_t *mac = esp_eth_mac_new_esp32(&mac_config); // 创建 MAC 实例
+        esp32_emac_config.interface = EMAC_DATA_INTERFACE_RMII;                      // 更改 EMAC 数据接口
+        esp32_emac_config.clock_config.rmii.clock_mode = EMAC_CLK_OUT;               // 配置 EMAC REF_CLK 模式
+        esp32_emac_config.clock_config.rmii.clock_gpio = EMAC_CLK_OUT_GPIO;          // 配置用于输入/输出 EMAC REF_CLK 的 GPIO 编号
+        esp_eth_mac_t *mac = esp_eth_mac_new_esp32(&esp32_emac_config, &mac_config); // 创建 MAC 实例
 
 
 SPI-Ethernet 模块
@@ -231,7 +232,7 @@ SPI-Ethernet 模块
 
 ::
 
-    eth_mac_config_t mac_config = ETH_MAC_DEFAULT_CONFIG();      // 应用默认的 MAC 配置
+    eth_mac_config_t mac_config = ETH_MAC_DEFAULT_CONFIG();      // 应用默认的通用 MAC 配置
     eth_phy_config_t phy_config = ETH_PHY_DEFAULT_CONFIG();      // 应用默认的 PHY 配置
     phy_config.phy_addr = CONFIG_EXAMPLE_ETH_PHY_ADDR;           // 根据开发板设计更改 PHY 地址
     phy_config.reset_gpio_num = CONFIG_EXAMPLE_ETH_PHY_RST_GPIO; // 更改用于 PHY 复位的 GPIO