Merge branch 'fix/esp_netif_docs' into 'master'

fix(esp_netif): Fix ESP-NETIF user documentation

Closes IDF-9946, DOC-1229, and DOC-6162

See merge request espressif/esp-idf!31777

Author: david-cermak

components/esp_netif/include/esp_netif.h

@@ -595,12 +595,16 @@ esp_err_t esp_netif_napt_disable(esp_netif_t *esp_netif);
  * @brief  Set or Get DHCP server option
  *
  * @note Please note that not all combinations of identifiers and options are supported.
+ *
  * Get operations:
+ *
  *  * IP_ADDRESS_LEASE_TIME
  *  * ESP_NETIF_SUBNET_MASK/REQUESTED_IP_ADDRESS (both options do the same, they reflect dhcps_lease_t)
  *  * ROUTER_SOLICITATION_ADDRESS
  *  * DOMAIN_NAME_SERVER
+ *
  * Set operations:
+ *
  *  * IP_ADDRESS_LEASE_TIME
  *  * ESP_NETIF_SUBNET_MASK -- set operation is allowed only if the configured mask corresponds to the settings,
  *                             if not, please use esp_netif_set_ip_info() to prevent misconfiguration of DHCPS.
@@ -631,10 +635,14 @@ esp_netif_dhcps_option(esp_netif_t *esp_netif, esp_netif_dhcp_option_mode_t opt_
  * @brief  Set or Get DHCP client option
  *
  * @note Please note that not all combinations of identifiers and options are supported.
+ *
  * Get operations:
+ *
  *  * ESP_NETIF_IP_REQUEST_RETRY_TIME
  *  * ESP_NETIF_VENDOR_SPECIFIC_INFO -- only available if ESP_DHCP_DISABLE_VENDOR_CLASS_IDENTIFIER=n
+ *
  * Set operations:
+ *
  *  * ESP_NETIF_IP_REQUEST_RETRY_TIME
  *  * ESP_NETIF_VENDOR_SPECIFIC_INFO -- only available if ESP_DHCP_DISABLE_VENDOR_CLASS_IDENTIFIER=n
  *                                      lwip layer creates its own copy of the supplied identifier.

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

@@ -1,8 +1,16 @@
-ESP-NETIF Custom I/O Driver
-===========================
+ESP-NETIF Developer's manual
+============================
 
 :link_to_translation:`zh_CN:[中文]`
 
+As shown in the :ref:`esp-netif structure` diagram, ESP-NETIF is in fact an intermediary between the I/O driver and the TCP/IP stack. This manual describes customization of these two sides, that is if you need to implement :ref:`esp_netif_custom_driver` or if you need to employ :ref:`esp_netif_tcpip_stack`.
+
+
+.. _esp_netif_custom_driver:
+
+ESP-NETIF Custom I/O Driver
+---------------------------
+
 This section outlines implementing a new I/O driver with ESP-NETIF connection capabilities.
 
 By convention, the I/O driver has to register itself as an ESP-NETIF driver, and thus holds a dependency on ESP-NETIF component and is responsible for providing data path functions, post-attach callback and in most cases, also default event handlers to define network interface actions based on driver's lifecycle transitions.
@@ -88,7 +96,24 @@ Network Stack Connection
 
 The packet data path functions for transmitting and freeing the rx buffer (defined in the I/O driver) are called from the ESP-NETIF, specifically from its TCP/IP stack connecting layer.
 
-Note that ESP-IDF provides several network stack configurations for the most common network interfaces, such as for the Wi-Fi station or Ethernet. These configurations are defined in :component_file:`esp_netif/include/esp_netif_defaults.h` and should be sufficient for most network drivers. In rare cases, expert users might want to define custom lwIP based interface layers; it is possible, but an explicit dependency to lwIP needs to be set.
+Note that ESP-IDF provides several network stack configurations for the most common network interfaces, such as for the Wi-Fi station or Ethernet. These configurations are defined in :component_file:`esp_netif/include/esp_netif_defaults.h` and should be sufficient for most network drivers.
+
+In some cases, you might want to define a custom lwIP based interface, for example if you need to update :component_file:`esp_netif/lwip/netif/wlanif.c` with a specific packet pool. In that case, you would have to define an explicit dependency to lwIP and include :component_file:`esp_netif/include/lwip/esp_netif_net_stack.h` for the relevant lwIP configuration structures.
+
+
+.. _esp_netif_tcpip_stack:
+
+ESP-NETIF Custom TCP/IP Stack
+-----------------------------
+
+It is possible to use a custom TCP/IP stack with ESP-IDF, provided it implements BSD API. You can add support for your own TCP/IP stack, while using the generic ESP-NETIF functionality, so the application code can stay the same as with the lwIP.
+
+In this case, please choose ``ESP_NETIF_PROVIDE_CUSTOM_IMPLEMENTATION`` in the ESP-NETIF component configuration menu. This option will disable lwIP implementation of the ESP-NETIF functions and provide only header files with declarations of types and API. You will have to supply the necessary implementation in your custom component. You can refer to the :component_file:`esp_netif/loopback/esp_netif_loopback.c` for example of dummy implementations of these functions.
+
+It is also possible to build ESP-IDF without lwIP, please refer to :idf_file:`components/esp_netif_stack/README.md`.
+
+API Reference
+-------------
 
 The following API reference outlines these network stack interaction with the ESP-NETIF: