1# ESP-NETIF architecture
2
3                           |          (A) USER CODE                 |
4                           |                                        |
5          .................| init          settings      events     |
6          .                +----------------------------------------+
7          .                   .                |           *
8          .                   .                |           *
9      --------+            +===========================+   *     +-----------------------+
10              |            | new/config     get/set    |   *     |                       |
11              |            |                           |...*.....| init                  |
12              |            |---------------------------|   *     |                       |
13        init  |            |                           |****     |                       |
14        start |************|  event handler            |*********|  DHCP                 |
15        stop  |            |                           |         |                       |
16              |            |---------------------------|         |                       |
17              |            |                           |         |    NETIF              |
18        +-----|            |                           |         +-----------------+     |
19        | glue|---<----|---|  esp_netif_transmit       |--<------| netif_output    |     |
20        |     |        |   |                           |         |                 |     |
21        |     |--->----|---|  esp_netif_receive        |-->------| netif_input     |     |
22        |     |        |   |                           |         + ----------------+     |
23        |     |...<....|...|  esp_netif_free_rx_buffer |...<.....| packet buffer         |
24        +-----|     |  |   |                           |         |                       |
25              |     |  |   |                           |         |         (D)           |
26        (B)   |     |  |   |          (C)              |         +-----------------------+
27      --------+     |  |   +===========================+
28    communication   |  |                                               NETWORK STACK
29    DRIVER          |  |           ESP-NETIF
30                    |  |                                         +------------------+
31                    |  |   +---------------------------+.........| open/close       |
32                    |  |   |                           |         |                  |
33                    |  -<--|  l2tap_write              |-----<---|  write           |
34                    |      |                           |         |                  |
35                    ---->--|  esp_vfs_l2tap_eth_filter |----->---|  read            |
36                           |                           |         |                  |
37                           |            (E)            |         +------------------+
38                           +---------------------------+
39                                                                      USER CODE
40                                ESP-NETIF L2 TAP
41
42##  Data/event flow:
43
44* `........`     Initialization line from user code to esp-netif and comm driver
45
46* `--<--->--`    Data packets going from communication media to TCP/IP stack and back
47
48* `********`     Events agregated in ESP-NETIP propagates to driver, user code and network stack
49
50*  `|`           User settings and runtime configuration
51
52##  Components:
53
54###  A) User code, boiler plate
55Overall application interaction with communication media and network stack
56
57  * initialization code
58      - create a new instance of ESP-NETIF
59      - configure the object with
60          1) netif specific options (flags, behaviour, name)
61          2) network stack options (netif init and input functions, not publicly available)
62          3) IO driver specific options (transmit, tx_free functions, IO driver handle)
63    - setup event handlers
64    - use default handlers for common interfaces defined in IO drivers; or define a specific handlers
65                        for customised behaviour/new interfaces
66    - register handlers for app related events (such as IP lost/acquired)
67  - interact with network interfaces using ESP-NETIF API
68
69###  B) Communication driver, IO driver, media driver
70  * event handler
71      - define behaviour patterns of interaction with ESP-NETIF (example: ehternet link-up -> turn netif on)
72  * glue IO layer: adapt the input/output functions to use esp-netif transmit/input/free_rx
73      - install driver_transmit to appropriate ESP-NETIF object, so that outgoing packets from
74                network stack are passed to the IO driver
75      - calls esp_netif_receive to pass incoming data to network stack
76
77###  C) ESP-NETIF
78* init API (new, configure)
79* IO API: for passing data between IO driver and network stack
80* event/action API (esp-netif lifecycle management)
81  - building blocks for designing event handlers
82* setters, getters
83* network stack abstraction: enabling user interaction with TCP/IP stack
84  - netif up/down
85  - DHCP server, client
86  - DNS API
87* driver conversion utilities
88
89###  D) Network stack: no public interaction with user code (wrtt interfaces)
90
91###  E) ESP-NETIF L2 TAP Interface
92The ESP-NETIF L2 TAP interface is ESP-IDF mechanism utilized to access Data Link Layer (L2 per OSI/ISO) for frame reception and
93transmission from user application. Its typical usage in embedded world might be implementation of non-IP related protocols
94such as PTP, Wake on LAN and others. Note that only Ethernet (IEEE 802.3)
95is currently supported.
96
97From user perspective, the ESP-NETIF L2 TAP interface is accessed using file descriptors of VFS which provides a file-like interfacing
98(using functions like ``open()``, ``read()``, ``write()``, etc).
99
100There is only one ESP-NETIF L2 TAP interface device (path name) available. However multiple file descriptors with different configuration
101can be opened at a time since the ESP-NETIF L2 TAP interface can be understood as generic entry point to the NETIF internal structure.
102Important is then specific configuration of particular file descriptor. It can be configured to give an access to specific Network Interface
103identified by ``if_key`` (e.g. `ETH_DEF`) and to filter only specific frames based on their type (e.g. Ethernet type in case of IEEE 802.3).
104Filtering only specific frames is crucial since the ESP-NETIF L2 TAP needs to work along with IP stack and so the IP related traffic
105(IP, ARP, etc.) should not be passed directly to the user application. Even though such option is still configurable, it is not recommended in
106standard use cases. Filtering is also advantageous from a perspective the user’s application gets access only to frame types it is interested
107in and the remaining traffic is either passed to other L2 TAP file descriptors or to IP stack.
108