|
|
@@ -1,21 +1,23 @@
|
|
|
ESP-NETIF Custom I/O Driver
|
|
|
===========================
|
|
|
|
|
|
-This section outlines implementing a new I/O driver with esp-netif connection capabilities.
|
|
|
+:link_to_translation:`zh_CN:[中文]`
|
|
|
|
|
|
-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.
|
|
|
+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.
|
|
|
|
|
|
|
|
|
Packet Input/Output
|
|
|
^^^^^^^^^^^^^^^^^^^
|
|
|
|
|
|
-As shown in the diagram, the following three API functions for the packet data path must be defined for connecting with esp-netif:
|
|
|
+According to the diagram shown in the :ref:`esp-netif structure` part, the following three API functions for the packet data path must be defined for connecting with ESP-NETIF:
|
|
|
|
|
|
* :cpp:func:`esp_netif_transmit()`
|
|
|
* :cpp:func:`esp_netif_free_rx_buffer()`
|
|
|
* :cpp:func:`esp_netif_receive()`
|
|
|
|
|
|
-The first two functions for transmitting and freeing the rx buffer are provided as callbacks, i.e., they get called from esp-netif (and its underlying TCP/IP stack) and I/O driver provides their implementation.
|
|
|
+The first two functions for transmitting and freeing the rx buffer are provided as callbacks, i.e., they get called from ESP-NETIF (and its underlying TCP/IP stack) and I/O driver provides their implementation.
|
|
|
|
|
|
The receiving function on the other hand gets called from the I/O driver, so that the driver's code simply calls :cpp:func:`esp_netif_receive()` on a new data received event.
|
|
|
|
|
|
@@ -23,18 +25,18 @@ The receiving function on the other hand gets called from the I/O driver, so tha
|
|
|
Post Attach Callback
|
|
|
^^^^^^^^^^^^^^^^^^^^
|
|
|
|
|
|
-A final part of the network interface initialization consists of attaching the esp-netif instance to the I/O driver, by means of calling the following API:
|
|
|
+A final part of the network interface initialization consists of attaching the ESP-NETIF instance to the I/O driver, by means of calling the following API:
|
|
|
|
|
|
.. code:: c
|
|
|
|
|
|
esp_err_t esp_netif_attach(esp_netif_t *esp_netif, esp_netif_iodriver_handle driver_handle);
|
|
|
|
|
|
-It is assumed that the ``esp_netif_iodriver_handle`` is a pointer to driver's object, a struct derived from ``struct esp_netif_driver_base_s``, so that the first member of I/O driver structure must be this base structure with pointers to
|
|
|
+It is assumed that the ``esp_netif_iodriver_handle`` is a pointer to driver's object, a struct derived from ``struct esp_netif_driver_base_s``, so that the first member of I/O driver structure must be this base structure with pointers to:
|
|
|
|
|
|
* post-attach function callback
|
|
|
-* related esp-netif instance
|
|
|
+* related ESP-NETIF instance
|
|
|
|
|
|
-As a consequence the I/O driver has to create an instance of the struct per below:
|
|
|
+As a result, the I/O driver has to create an instance of the struct per below:
|
|
|
|
|
|
.. code:: c
|
|
|
|
|
|
@@ -45,7 +47,7 @@ As a consequence the I/O driver has to create an instance of the struct per belo
|
|
|
|
|
|
with actual values of ``my_netif_driver_t::base.post_attach`` and the actual drivers handle ``my_netif_driver_t::h``.
|
|
|
|
|
|
-So when the :cpp:func:`esp_netif_attach()` gets called from the initialization code, the post-attach callback from I/O driver's code gets executed to mutually register callbacks between esp-netif and I/O driver instances. Typically the driver is started as well in the post-attach callback. An example of a simple post-attach callback is outlined below:
|
|
|
+So when the :cpp:func:`esp_netif_attach()` gets called from the initialization code, the post-attach callback from I/O driver's code gets executed to mutually register callbacks between ESP-NETIF and I/O driver instances. Typically the driver is started as well in the post-attach callback. An example of a simple post-attach callback is outlined below:
|
|
|
|
|
|
.. code:: c
|
|
|
|
|
|
@@ -67,7 +69,8 @@ So when the :cpp:func:`esp_netif_attach()` gets called from the initialization c
|
|
|
Default Handlers
|
|
|
^^^^^^^^^^^^^^^^
|
|
|
|
|
|
-I/O drivers also typically provide default definitions of lifecycle behaviour of related network interfaces based on state transitions of I/O drivers. For example *driver start* ``->`` *network start*, etc.
|
|
|
+I/O drivers also typically provide default definitions of lifecycle behavior of related network interfaces based on state transitions of I/O drivers. For example *driver start* ``->`` *network start*, etc.
|
|
|
+
|
|
|
An example of such a default handler is provided below:
|
|
|
|
|
|
.. code:: c
|
|
|
@@ -83,11 +86,10 @@ An example of such a default handler is provided below:
|
|
|
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.
|
|
|
+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 WiFi 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 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.
|
|
|
|
|
|
-The following API reference outlines these network stack interaction with the esp-netif:
|
|
|
+The following API reference outlines these network stack interaction with the ESP-NETIF:
|
|
|
|
|
|
.. include-build-file:: inc/esp_netif_net_stack.inc
|
Ren Pei Ying