doc: net: Enhance network interface documentation
Add overview to network interface API documentation.
Signed-off-by: Jukka Rissanen <jukka.rissanen@linux.intel.com>
diff --git a/doc/reference/networking/net_if.rst b/doc/reference/networking/net_if.rst
index d1cbb9a..2ad4492 100644
--- a/doc/reference/networking/net_if.rst
+++ b/doc/reference/networking/net_if.rst
@@ -6,6 +6,50 @@
Overview
********
+The network interface is a nexus that ties the network device drivers
+and the upper part of the network stack together. All the sent and received
+data is transferred via a network interface. The network interfaces cannot be
+created at runtime. A special linker section will contain information about them
+and that section is populated at linking time.
+
+Network interfaces are created by ``NET_DEVICE_INIT()`` macro.
+For Ethernet network, a macro called ``ETH_NET_DEVICE_INIT()`` should be used
+instead as it will create VLAN interfaces automatically if
+:option:`CONFIG_NET_VLAN` is enabled. These macros are typically used in
+network device driver source code.
+
+The network interface can be turned ON by calling ``net_if_up()`` and OFF
+by calling ``net_if_down()``. When the device is powered ON, the network
+interface is also turned ON by default.
+
+The network interfaces can be referenced either by a ``struct net_if *``
+pointer or by a network interface index. The network interface can be
+resolved from its index by calling ``net_if_get_by_index()`` and from interface
+pointer by calling ``net_if_get_by_iface()``.
+
+The IP address for network devices must be set for them to be connectable.
+In a typical dynamic network environment, IP addresses are set automatically
+by DHCPv4, for example. If needed though, the application can set a device's
+IP address manually. See the API documentation below for functions such as
+``net_if_ipv4_addr_add()`` that do that.
+
+The ``net_if_get_default()`` returns a *default* network interface. What
+this default interface means can be configured via options like
+:option:`CONFIG_NET_DEFAULT_IF_FIRST` and
+:option:`CONFIG_NET_DEFAULT_IF_ETHERNET`.
+See Kconfig file :file:`subsys/net/ip/Kconfig` what options are available for
+selecting the default network interface.
+
+The transmitted and received network packets can be classified via a network
+packet priority. This is typically done in Ethernet networks when virtual LANs
+(VLANs) are used. Higher priority packets can be sent or received earlier than
+lower priority packets. The traffic class setup can be configured by
+:option:`CONFIG_NET_TC_TX_COUNT` and :option:`CONFIG_NET_TC_RX_COUNT` options.
+
+If the :option:`CONFIG_NET_PROMISCUOUS_MODE` is enabled and if the underlaying
+network technology supports promiscuous mode, then it is possible to receive
+all the network packets that the network device driver is able to receive.
+See :ref:`promiscuous_interface` API for more details.
API Reference
*************
