Merge branch 'feature/eth_iram_optimization_v5.1' into 'release/v5.1'

feat(esp_eth): added IRAM optimization option for internal EMAC (v5.1)

See merge request espressif/esp-idf!25842

components/esp_eth/CMakeLists.txt

@@ -2,6 +2,7 @@ idf_build_get_property(components_to_build BUILD_COMPONENTS)
 
 set(srcs)
 set(include)
+set(ld_fragments linker.lf)
 # As CONFIG_ETH_ENABLED comes from Kconfig, it is not evaluated yet
 # when components are being registered.
 # Thus, always add the (private) requirements, regardless of Kconfig
@@ -50,6 +51,7 @@ endif()
 
 idf_component_register(SRCS "${srcs}"
                        INCLUDE_DIRS ${include}
+                       LDFRAGMENTS ${ld_fragments}
                        REQUIRES esp_event # For using "ESP_EVENT_DECLARE_BASE" in header file
                        PRIV_REQUIRES ${priv_requires})
 if(CONFIG_ETH_ENABLED)

components/esp_eth/Kconfig

@@ -111,6 +111,13 @@ menu "Ethernet"
                     cause obvious performance loss.
         endif
 
+        config ETH_IRAM_OPTIMIZATION
+            bool "Enable IRAM optimization"
+            default n
+            help
+                If enabled, functions related to RX/TX are placed into IRAM. It can improve Ethernet throughput.
+                If disabled, all functions are placed into FLASH.
+
     endif # ETH_USE_ESP32_EMAC
 
     menuconfig ETH_USE_SPI_ETHERNET

components/esp_eth/linker.lf

@@ -0,0 +1,19 @@
+[mapping:esp_eth]
+archive: libesp_eth.a
+entries:
+  if ETH_IRAM_OPTIMIZATION = y:
+    esp_eth:esp_eth_transmit (noflash_text)
+    esp_eth:esp_eth_transmit_vargs (noflash_text)
+    esp_eth_mac_esp:emac_esp32_transmit (noflash_text)
+    esp_eth_mac_esp:emac_esp32_transmit_multiple_bufs (noflash_text)
+    esp_eth_mac_esp:emac_esp32_receive (noflash_text)
+    esp_eth_mac_esp:emac_esp32_rx_task (noflash_text)
+
+[mapping:esp_eth_hal]
+archive: libhal.a
+entries:
+  if ETH_IRAM_OPTIMIZATION = y:
+    emac_hal:emac_hal_transmit_frame (noflash)
+    emac_hal:emac_hal_transmit_multiple_buf_frame (noflash)
+    emac_hal:emac_hal_alloc_recv_buf (noflash)
+    emac_hal:emac_hal_receive_frame (noflash)

docs/en/api-guides/performance/speed.rst

@@ -244,6 +244,7 @@ Improving Network Speed
     :SOC_WIFI_SUPPORTED: * For Wi-Fi, see :ref:`How-to-improve-Wi-Fi-performance` and :ref:`wifi-buffer-usage`
     * For lwIP TCP/IP (Wi-Fi and Ethernet), see :ref:`lwip-performance`
     :SOC_WIFI_SUPPORTED: * The :example:`wifi/iperf` example contains a configuration that is heavily optimized for Wi-Fi TCP/IP throughput. Append the contents of the files :example_file:`wifi/iperf/sdkconfig.defaults`, :example_file:`wifi/iperf/sdkconfig.defaults.{IDF_TARGET_PATH_NAME}` and :example_file:`wifi/iperf/sdkconfig.ci.99` to the ``sdkconfig`` file in your project in order to add all of these options. Note that some of these options may have trade-offs in terms of reduced debuggability, increased firmware size, increased memory usage, or reduced performance of other features. To get the best result, read the documentation pages linked above and use related information to determine exactly which options are best suited for your app.
+    :SOC_EMAC_SUPPORTED: * The :example:`ethernet/iperf` example contains a configuration that is heavily optimized for Ethernet TCP/IP throughput. Examine :example_file:`ethernet/iperf/sdkconfig.defaults` for more details. Note that some of these options may have trade-offs in terms of reduced debuggability, increased firmware size, increased memory usage, or reduced performance of other features. To get the best result, read the documentation pages linked above and use related information to determine exactly which options are best suited for your app.
 
 Improving I/O Performance
 -------------------------

docs/zh_CN/api-guides/performance/speed.rst

@@ -244,6 +244,7 @@ ESP-IDF 支持动态 :doc:`/api-reference/system/intr_alloc` 和中断抢占。
     :SOC_WIFI_SUPPORTED: * 关于提高 Wi-Fi 网速，参见 :ref:`How-to-improve-Wi-Fi-performance` 和 :ref:`wifi-buffer-usage` 。
     * 关于提高 lwIP TCP/IP（Wi-Fi 和以太网）网速，参见 :ref:`lwip-performance` 。
     :SOC_WIFI_SUPPORTED: * 示例 :example:`wifi/iperf` 包含了一种针对 Wi-Fi TCP/IP 吞吐量进行了大量优化的配置。将文件 :example_file:`wifi/iperf/sdkconfig.defaults` 、 :example_file:`wifi/iperf/sdkconfig.defaults.{IDF_TARGET_PATH_NAME}` 和 :example_file:`wifi/iperf/sdkconfig.ci.99` 的内容追加到项目的 ``sdkconfig`` 文件中，即可添加所有相关选项。请注意，部分选项可能会导致可调试性降低、固件大小增加、内存使用增加或其他功能的性能降低等影响。为了获得最佳结果，请阅读上述链接文档，并据此确定哪些选项最适合当前应用程序。
+    :SOC_EMAC_SUPPORTED: * 示例 :example:`ethernet/iperf` 中的配置针对以太网 TCP/IP 吞吐量进行了大量优化。如需了解详情，请查看 :example_file:`ethernet/iperf/sdkconfig.defaults`。请注意，部分选项可能会导致可调试性降低、固件大小增加、内存使用增加或其他功能的性能降低等影响。为了获得最佳结果，请阅读上述链接文档，并据此确定哪些选项最适合当前应用程序。
 
 提高 I/O 性能
 ----------------------------------

examples/ethernet/iperf/sdkconfig.defaults

@@ -1,7 +1,8 @@
 # Increase main task stack size
 CONFIG_ESP_MAIN_TASK_STACK_SIZE=7168
 
-# Enable filesystem
+# Enable filesystem for console commands history storage
+CONFIG_ESPTOOLPY_FLASHSIZE_4MB=y
 CONFIG_PARTITION_TABLE_CUSTOM=y
 CONFIG_PARTITION_TABLE_CUSTOM_FILENAME="partitions_example.csv"
 CONFIG_PARTITION_TABLE_FILENAME="partitions_example.csv"
@@ -10,14 +11,22 @@ CONFIG_PARTITION_TABLE_FILENAME="partitions_example.csv"
 CONFIG_FREERTOS_USE_TRACE_FACILITY=y
 CONFIG_FREERTOS_USE_STATS_FORMATTING_FUNCTIONS=y
 
+# --------------------------------
+# Performance optimization options
+# --------------------------------
+# `lwIP` and `iperf` tasks have serial dependency to each other (i.e. `iperf` must wait for `lwIP`
+# to process the packets). Therefore, you don't gain much performance improvement when running
+# multi core mode. On the other hand, IRAM optimizations have greater effect for single core mode.
+
 # Run FreeRTOS only on the first core
 CONFIG_FREERTOS_UNICORE=y
 
-CONFIG_ESPTOOLPY_FLASHSIZE_4MB=y
-
 # Disable watch dog
 CONFIG_ESP_INT_WDT=n
 CONFIG_ESP_TASK_WDT_EN=n
 
 # Enable lwIP IRAM optimization
 CONFIG_LWIP_IRAM_OPTIMIZATION=y
+
+# Enable Ethernet IRAM optimization
+CONFIG_ETH_IRAM_OPTIMIZATION=y