1ESP-NETIF Custom I/O Driver
2===========================
3
4This section outlines implementing a new I/O driver with esp-netif connection capabilities.
5By convention the I/O driver has to register itself as an esp-netif driver and thus holds a dependency on esp-netif component
6and is responsible for providing data path functions, post-attach callback and in most cases also default event handlers to define network interface
7actions based on driver's lifecycle transitions.
8
9
10Packet input/output
11^^^^^^^^^^^^^^^^^^^
12
13As shown in the diagram, the following three API functions for the packet data path must be defined for connecting with esp-netif:
14
15* :cpp:func:`esp_netif_transmit()`
16* :cpp:func:`esp_netif_free_rx_buffer()`
17* :cpp:func:`esp_netif_receive()`
18
19The first two functions for transmitting and freeing the rx buffer are provided as callbacks, i.e. they get called from
20esp-netif (and its underlying TCP/IP stack) and I/O driver provides their implementation.
21
22The 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()`
23on a new data received event.
24
25
26Post attach callback
27^^^^^^^^^^^^^^^^^^^^
28
29A final part of the network interface initialization consists of attaching the esp-netif instance to the I/O driver, by means
30of calling the following API:
31
32.. code:: c
33
34    esp_err_t esp_netif_attach(esp_netif_t *esp_netif, esp_netif_iodriver_handle driver_handle);
35
36It 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``,
37so that the first member of I/O driver structure must be this base structure with pointers to
38
39* post-attach function callback
40* related esp-netif instance
41
42As a consequence the I/O driver has to create an instance of the struct per below:
43
44.. code:: c
45
46    typedef struct my_netif_driver_s {
47            esp_netif_driver_base_t base;           /*!< base structure reserved as esp-netif driver */
48            driver_impl             *h;             /*!< handle of driver implementation */
49        } my_netif_driver_t;
50
51with actual values of ``my_netif_driver_t::base.post_attach`` and the actual drivers handle ``my_netif_driver_t::h``.
52So when the :cpp:func:`esp_netif_attach()` gets called from the initialization code, the post-attach callback from I/O driver's code
53gets executed to mutually register callbacks between esp-netif and I/O driver instances. Typically the driver is started
54as well in the post-attach callback. An example of a simple post-attach callback is outlined below:
55
56.. code:: c
57
58    static esp_err_t my_post_attach_start(esp_netif_t * esp_netif, void * args)
59    {
60        my_netif_driver_t *driver = args;
61        const esp_netif_driver_ifconfig_t driver_ifconfig = {
62                .driver_free_rx_buffer = my_free_rx_buf,
63                .transmit = my_transmit,
64                .handle = driver->driver_impl
65        };
66        driver->base.netif = esp_netif;
67        ESP_ERROR_CHECK(esp_netif_set_driver_config(esp_netif, &driver_ifconfig));
68        my_driver_start(driver->driver_impl);
69        return ESP_OK;
70    }
71
72
73Default handlers
74^^^^^^^^^^^^^^^^
75
76I/O drivers also typically provide default definitions of lifecycle behaviour of related network interfaces based
77on state transitions of I/O drivers. For example *driver start* ``->`` *network start*, etc.
78An example of such a default handler is provided below:
79
80.. code:: c
81
82    esp_err_t my_driver_netif_set_default_handlers(my_netif_driver_t *driver, esp_netif_t * esp_netif)
83    {
84        driver_set_event_handler(driver->driver_impl, esp_netif_action_start, MY_DRV_EVENT_START, esp_netif);
85        driver_set_event_handler(driver->driver_impl, esp_netif_action_stop, MY_DRV_EVENT_STOP, esp_netif);
86        return ESP_OK;
87    }
88
89
90Network stack connection
91------------------------
92
93The packet data path functions for transmitting and freeing the rx buffer (defined in the I/O driver) are called from
94the esp-netif, specifically from its TCP/IP stack connecting layer. The following API reference outlines these network stack
95interaction with the esp-netif.
96
97.. include-build-file:: inc/esp_netif_net_stack.inc
98