From d91bbdf7b9a0f6f091ca3c2a7218841abd7ddc07 Mon Sep 17 00:00:00 2001 From: Ondrej Kosta Date: Thu, 4 Nov 2021 09:11:59 +0100 Subject: [PATCH] esp_eth: esp_eth_ioctl v5.0 migration guide --- docs/en/migration-guides/ethernet.rst | 33 ++++++++++++++++++++++++ docs/en/migration-guides/index.rst | 1 + docs/zh_CN/migration-guides/ethernet.rst | 1 + docs/zh_CN/migration-guides/index.rst | 1 + 4 files changed, 36 insertions(+) create mode 100644 docs/en/migration-guides/ethernet.rst create mode 100644 docs/zh_CN/migration-guides/ethernet.rst diff --git a/docs/en/migration-guides/ethernet.rst b/docs/en/migration-guides/ethernet.rst new file mode 100644 index 0000000000..36ee9c7749 --- /dev/null +++ b/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); diff --git a/docs/en/migration-guides/index.rst b/docs/en/migration-guides/index.rst index e6266a1137..783e0184ff 100644 --- a/docs/en/migration-guides/index.rst +++ b/docs/en/migration-guides/index.rst @@ -8,3 +8,4 @@ ESP-IDF 5.0 Migration Guides Peripherals Build System System + Ethernet diff --git a/docs/zh_CN/migration-guides/ethernet.rst b/docs/zh_CN/migration-guides/ethernet.rst new file mode 100644 index 0000000000..75f8623dbe --- /dev/null +++ b/docs/zh_CN/migration-guides/ethernet.rst @@ -0,0 +1 @@ +.. include:: ../../en/migration-guides/ethernet.rst diff --git a/docs/zh_CN/migration-guides/index.rst b/docs/zh_CN/migration-guides/index.rst index c0526385c1..d4fa90df37 100644 --- a/docs/zh_CN/migration-guides/index.rst +++ b/docs/zh_CN/migration-guides/index.rst @@ -8,3 +8,4 @@ ESP-IDF 5.0 迁移指南 外设 构建系统 系统 + 以太网