1.. _network_stack_architecture: 2 3Network Stack Architecture 4########################## 5 6.. toctree:: 7 :maxdepth: 1 8 :hidden: 9 10 net_pkt_processing_stats.rst 11 12The Zephyr network stack is a native network stack specifically designed 13for Zephyr OS. It consists of layers, each meant to provide certain services 14to other layers. Network stack functionality is highly configurable via Kconfig 15options. 16 17.. contents:: 18 :local: 19 :depth: 2 20 21High level overview of the network stack 22**************************************** 23 24.. figure:: zephyr_netstack_overview.svg 25 :alt: Overview of the network stack architecture 26 :figclass: align-center 27 28 Network stack overview 29 30The network stack is layered and consists of the following parts: 31 32* **Network Application.** The network application can either use the provided 33 application-level protocol libraries or access the 34 :ref:`BSD socket API <bsd_sockets_interface>` directly to create a network 35 connection, send or receive data, and close a connection. The application can 36 also use the :ref:`network management API <net_mgmt_interface>` to configure 37 the network and set related parameters such as network link options, 38 starting a scan (when applicable), listen network configuration events, etc. 39 The :ref:`network interface API <net_if_interface>` can be used to set IP 40 address to a network interface, taking the network interface down, etc. 41 42* **Network Protocols.** This provides implementations for 43 various protocols such as 44 45 * Application-level network protocols like CoAP, LWM2M, and MQTT. 46 See :ref:`application protocols chapter <net_protocols>` for information 47 about them. 48 * Core network protocols like IPv6, IPv4, UDP, TCP, ICMPv4, and ICMPv6. 49 You access these protocols by using the 50 :ref:`BSD socket API <bsd_sockets_interface>`. 51 52* **Network Interface Abstraction.** This provides functionality 53 that is common in all the network interfaces, such as setting network 54 interface down, etc. There can be multiple network interfaces in the system. 55 See :ref:`network interface overview <net_if_interface>` for more details. 56 57* **L2 Network Technologies.** This provides a common API for sending and 58 receiving data to and from an actual network device. 59 See :ref:`L2 overview <net_l2_interface>` for more details. 60 These network technologies include :ref:`Ethernet <ethernet_interface>`, 61 :ref:`IEEE 802.15.4 <ieee802154_interface>`, 62 :ref:`Bluetooth <bluetooth_api>`, :ref:`CANBUS <can_api>`, etc. 63 Some of these technologies support IPv6 header compression (6Lo), 64 see `RFC 6282 <https://tools.ietf.org/html/rfc6282>`_ for details. 65 For example `ARP <https://tools.ietf.org/html/rfc826>`_ for IPv4 is done by 66 the :ref:`Ethernet component <ethernet_interface>`. 67 68* **Network Device Drivers.** The actual low-level device drivers handle the 69 physical sending or receiving of network packets. 70 71Network data flow 72***************** 73 74An application typically consists of one or more :ref:`threads <threads_v2>` 75that execute the application logic. When using the 76:ref:`BSD socket API <bsd_sockets_interface>`, the following things will 77happen. 78 79.. figure:: zephyr_netstack_overview-rx_sequence.svg 80 :alt: Network RX data flow 81 :figclass: align-center 82 83 Network RX data flow 84 85Data receiving (RX) 86------------------- 87 881. A network data packet is received by a device driver. 89 902. The device driver allocates enough network buffers to store the received 91 data. The network packet is placed in the proper RX queue (implemented by 92 :ref:`k_fifo <fifos_v2>`). By default there is only one receive queue in 93 the system, but it is possible to have up to 8 receive queues. 94 These queues will process incoming packets with different priority. 95 See :ref:`traffic-class-support` for more details. The receive queues also 96 act as a way to separate the data processing pipeline (bottom-half) as 97 the device driver is running in an interrupt context and it must do its 98 processing as fast as possible. 99 1003. The network packet is then passed to the correct L2 driver. The L2 driver 101 can check if the packet is proper and modify it if needed, e.g. strip L2 102 header and frame check sequence, etc. 103 1044. The packet is processed by a network interface. The network statistics are 105 collected if enabled by :kconfig:option:`CONFIG_NET_STATISTICS`. 106 1075. The packet is then passed to L3 processing. If the packet is IP based, 108 then the L3 layer checks if the packet is a proper IPv6 or IPv4 packet. 109 1106. A socket handler then finds an active socket to which the network packet 111 belongs and puts it in a queue for that socket, in order to separate the 112 networking code from the application. Typically the application is run in 113 userspace context and the network stack is run in kernel context. 114 1157. The application will then receive the data and can process it as needed. 116 The application should have used the 117 :ref:`BSD socket API <bsd_sockets_interface>` to create a socket 118 that will receive the data. 119 120 121.. figure:: zephyr_netstack_overview-tx_sequence.svg 122 :alt: Network TX data flow 123 :figclass: align-center 124 125 Network TX data flow 126 127Data sending (TX) 128----------------- 129 1301. The application should use the 131 :ref:`BSD socket API <bsd_sockets_interface>` when sending the data. 132 1332. The application data is prepared for sending to kernel space and then 134 copied to internal net_buf structures. 135 1363. Depending on the socket type, a protocol header is added in front of the 137 data. For example, if the socket is a UDP socket, then a UDP header is 138 constructed and placed in front of the data. 139 1404. An IP header is added to the network packet for a UDP or TCP packet. 141 1425. The network stack will check that the network interface is properly set 143 for the network packet, and also will make sure that the network interface 144 is enabled before the data is queued to be sent. 145 1466. The network packet is then classified and placed to the proper transmit 147 queue (implemented by :ref:`k_fifo <fifos_v2>`). By default there is only 148 one transmit queue in the system, but it is possible to have up to 8 149 transmit queues. These queues will process the sent packets with different 150 priority. See :ref:`traffic-class-support` for more details. 151 After the transmit packet classification, the packet is checked by the 152 correct L2 layer module. The L2 module will do additional checks for the 153 data and it will also create any L2 headers for the network packet. 154 If everything is ok, the data is given to the network device driver to be 155 sent out. 156 1577. The device driver will send the packet to the network. 158 159Note that in both the TX and RX data paths, the queues 160(:ref:`k_fifo's <fifos_v2>`) form separation points where data is passed from 161one :ref:`thread <threads_v2>` to another. 162These :ref:`threads <threads_v2>` might run in different contexts 163(:ref:`kernel <kernel_api>` vs. :ref:`userspace <usermode_api>`) and with different 164:ref:`priorities <scheduling_v2>`. 165 166 167Network packet processing statistics 168************************************ 169 170See information about network processing statistics 171:ref:`here <net_pkt_processing_stats>`. 172
