Merge branch 'feature/eth_ioctl_speed_duplex' into 'master'

esp_eth:  esp_eth_ioctl update

Closes IDF-1240 and IDF-4060

See merge request espressif/esp-idf!15607

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

@@ -428,7 +428,16 @@ Ethernet on MCU usually has a limitation in the number of frames it can handle d
 
 Pause frame is a special Ethernet frame used to carry the pause command, whose EtherType field is 0x8808, with the Control opcode set to 0x0001. Only stations configured for full-duplex operation may send pause frames. When a station wishes to pause the other end of a link, it sends a pause frame to the 48-bit reserved multicast address of 01-80-C2-00-00-01. The pause frame also includes the period of pause time being requested, in the form of a two-byte integer, ranging from 0 to 65535.
 
-After Ethernet driver installation, the flow control feature is disabled by default. You can enable it by invoking `esp_eth_ioctl(eth_handle, ETH_CMD_S_FLOW_CTRL, true);`. One thing should be kept in mind, is that the pause frame ability will be advertised to peer end by PHY during auto negotiation. Ethernet driver sends pause frame only when both sides of the link support it.
+After Ethernet driver installation, the flow control feature is disabled by default. You can enable it by:
+
+.. highlight:: c
+
+::
+
+    bool flow_ctrl_enable = true;
+    esp_eth_ioctl(eth_handle, ETH_CMD_S_FLOW_CTRL, &flow_ctrl_enable);
+
+One thing should be kept in mind, is that the pause frame ability will be advertised to peer end by PHY during auto negotiation. Ethernet driver sends pause frame only when both sides of the link support it.
 
 .. -------------------------------- Examples -----------------------------------
 

docs/en/migration-guides/ethernet.rst

@@ -0,0 +1,33 @@
+Migrate Ethernet Drivers to ESP-IDF 5.0
+=======================================
+
+esp_eth_ioctl() API
+-------------------
+:cpp:func:`esp_eth_ioctl` third argument could take `int` (`bool`) number as an input in some cases. However, it was not properly documented and, in addition, the number had to be "unnaturally" type casted to `void *` datatype to prevent compiler warnings as shown in below example:
+
+.. highlight:: c
+
+::
+
+    esp_eth_ioctl(eth_handle, ETH_CMD_S_FLOW_CTRL, (void *)true);
+
+
+This could lead to misuse of the :cpp:func:`esp_eth_ioctl`. Therefore, ESP-IDF 5.0 unified usage of :cpp:func:`esp_eth_ioctl`. Its third argument now always acts as pointer to a memory location of specific type from/to where the configuration option is read/stored.
+
+Usage example to set Ethernet configuration:
+
+.. highlight:: c
+
+::
+
+    eth_duplex_t new_duplex_mode = ETH_DUPLEX_HALF;
+    esp_eth_ioctl(eth_handle, ETH_CMD_S_DUPLEX_MODE, &new_duplex_mode);
+
+Usage example to get Ethernet configuration:
+
+.. highlight:: c
+
+::
+
+    eth_duplex_t duplex_mode;
+    esp_eth_ioctl(eth_handle, ETH_CMD_G_DUPLEX_MODE, &duplex_mode);

docs/en/migration-guides/index.rst

@@ -8,3 +8,4 @@ ESP-IDF 5.0 Migration Guides
     Peripherals <peripherals>
     Build System <build-system>
     System <system>
+    Ethernet <ethernet>

docs/zh_CN/migration-guides/ethernet.rst

@@ -0,0 +1 @@
+.. include:: ../../en/migration-guides/ethernet.rst

docs/zh_CN/migration-guides/index.rst

@@ -8,3 +8,4 @@ ESP-IDF 5.0 迁移指南
     外设 <peripherals>
     构建系统 <build-system>
     系统 <system>
+    以太网 <ethernet>