esp-idf/components/esp_netif
David Čermák a7cba03a28 Merge branch 'fix/netif_macro_semicolon' into 'master'
esp_netif: Remove semicolons from ESP_IP4ADDR_INIT and ESP_IP6ADDR_INIT macros (GitHub PR)

Closes IDFGH-10189

See merge request espressif/esp-idf!26759
2023-11-03 18:25:15 +08:00
..
include Merge branch 'fix/netif_macro_semicolon' into 'master' 2023-11-03 18:25:15 +08:00
linux/stubs/include/machine lwip: Support for linux target 2023-01-31 08:43:45 +01:00
loopback Merge branch 'refactor/components_linux_compatible' into 'master' 2023-10-18 20:17:49 +08:00
lwip Merge branch 'lost_timer_failed_to_start_when_sta_is_connected' into 'master' 2023-10-19 14:12:17 +08:00
private_include fix(esp_netif): Mark esp_netif_next deprecated and fix usages 2023-10-13 15:56:45 +02:00
test_apps Merge branch 'fix/esp_netif_lock' into 'master' 2023-10-17 21:36:39 +08:00
vfs_l2tap fix(esp_netif): Mark esp_netif_next deprecated and fix usages 2023-10-13 15:56:45 +02:00
CMakeLists.txt feat(esp_netif): PPP: Use RAM allocated pbufs instead of POOL (fixed size) 2023-09-25 16:48:48 +02:00
esp_netif_defaults.c esp_wifi: Add support for NAN Discovery and Datapath 2023-03-10 11:18:23 +05:30
esp_netif_handlers.c esp_netif: Fix Wno-format issues 2023-08-14 14:13:33 +02:00
esp_netif_objects.c fix(esp_netif): Lock netif list with TCPIP context 2023-10-13 15:54:53 +02:00
Kconfig refactor(linux): excluded all non-Linux components from build 2023-10-16 17:06:54 +08:00
linker.lf esp_netif/lwip: Fix deps cycles to "lwip -> esp_netif -> phy-drivers" 2022-07-20 14:59:07 +02:00
README.md esp_netif: remove dependency of L2 TAP Interface from netif_lwip 2022-04-08 16:40:29 +02:00

ESP-NETIF architecture

                       |          (A) USER CODE                 |
                       |                                        |
      .................| init          settings      events     |
      .                +----------------------------------------+
      .                   .                |           *
      .                   .                |           *
  --------+            +===========================+   *     +-----------------------+
          |            | new/config     get/set    |   *     |                       |
          |            |                           |...*.....| init                  |
          |            |---------------------------|   *     |                       |
    init  |            |                           |****     |                       |
    start |************|  event handler            |*********|  DHCP                 |
    stop  |            |                           |         |                       |
          |            |---------------------------|         |                       |
          |            |                           |         |    NETIF              |
    +-----|            |                           |         +-----------------+     |
    | glue|---<----|---|  esp_netif_transmit       |--<------| netif_output    |     |
    |     |        |   |                           |         |                 |     |
    |     |--->----|---|  esp_netif_receive        |-->------| netif_input     |     |
    |     |        |   |                           |         + ----------------+     |
    |     |...<....|...|  esp_netif_free_rx_buffer |...<.....| packet buffer         |
    +-----|     |  |   |                           |         |                       |
          |     |  |   |                           |         |         (D)           |
    (B)   |     |  |   |          (C)              |         +-----------------------+
  --------+     |  |   +===========================+
communication   |  |                                               NETWORK STACK
DRIVER          |  |           ESP-NETIF
                |  |                                         +------------------+
                |  |   +---------------------------+.........| open/close       |
                |  |   |                           |         |                  |
                |  -<--|  l2tap_write              |-----<---|  write           |
                |      |                           |         |                  |
                ---->--|  esp_vfs_l2tap_eth_filter |----->---|  read            |
                       |                           |         |                  |
                       |            (E)            |         +------------------+
                       +---------------------------+
                                                                  USER CODE
                            ESP-NETIF L2 TAP

Data/event flow:

  • ........ Initialization line from user code to esp-netif and comm driver

  • --<--->-- Data packets going from communication media to TCP/IP stack and back

  • ******** Events agregated in ESP-NETIP propagates to driver, user code and network stack

  • | User settings and runtime configuration

Components:

A) User code, boiler plate

Overall application interaction with communication media and network stack

  • initialization code
    • create a new instance of ESP-NETIF
    • configure the object with
      1. netif specific options (flags, behaviour, name)
      2. network stack options (netif init and input functions, not publicly available)
      3. IO driver specific options (transmit, tx_free functions, IO driver handle)
    • setup event handlers
    • use default handlers for common interfaces defined in IO drivers; or define a specific handlers for customised behaviour/new interfaces
    • register handlers for app related events (such as IP lost/acquired)
  • interact with network interfaces using ESP-NETIF API

B) Communication driver, IO driver, media driver

  • event handler
    • define behaviour patterns of interaction with ESP-NETIF (example: ehternet link-up -> turn netif on)
  • glue IO layer: adapt the input/output functions to use esp-netif transmit/input/free_rx
    • install driver_transmit to appropriate ESP-NETIF object, so that outgoing packets from network stack are passed to the IO driver
    • calls esp_netif_receive to pass incoming data to network stack

C) ESP-NETIF

  • init API (new, configure)
  • IO API: for passing data between IO driver and network stack
  • event/action API (esp-netif lifecycle management)
    • building blocks for designing event handlers
  • setters, getters
  • network stack abstraction: enabling user interaction with TCP/IP stack
    • netif up/down
    • DHCP server, client
    • DNS API
  • driver conversion utilities

D) Network stack: no public interaction with user code (wrtt interfaces)

E) ESP-NETIF L2 TAP Interface

The ESP-NETIF L2 TAP interface is ESP-IDF mechanism utilized to access Data Link Layer (L2 per OSI/ISO) for frame reception and transmission from user application. Its typical usage in embedded world might be implementation of non-IP related protocols such as PTP, Wake on LAN and others. Note that only Ethernet (IEEE 802.3) is currently supported.

From user perspective, the ESP-NETIF L2 TAP interface is accessed using file descriptors of VFS which provides a file-like interfacing (using functions like open(), read(), write(), etc).

There is only one ESP-NETIF L2 TAP interface device (path name) available. However multiple file descriptors with different configuration can be opened at a time since the ESP-NETIF L2 TAP interface can be understood as generic entry point to the NETIF internal structure. Important is then specific configuration of particular file descriptor. It can be configured to give an access to specific Network Interface identified 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). Filtering only specific frames is crucial since the ESP-NETIF L2 TAP needs to work along with IP stack and so the IP related traffic (IP, ARP, etc.) should not be passed directly to the user application. Even though such option is still configurable, it is not recommended in standard use cases. Filtering is also advantageous from a perspective the users application gets access only to frame types it is interested in and the remaining traffic is either passed to other L2 TAP file descriptors or to IP stack.