1.. _net_if_interface:
2
3Network Interface
4#################
5
6.. contents::
7    :local:
8    :depth: 2
9
10Overview
11********
12
13The network interface is a nexus that ties the network device drivers
14and the upper part of the network stack together. All the sent and received
15data is transferred via a network interface. The network interfaces cannot be
16created at runtime. A special linker section will contain information about them
17and that section is populated at linking time.
18
19Network interfaces are created by ``NET_DEVICE_INIT()`` macro.
20For Ethernet network, a macro called ``ETH_NET_DEVICE_INIT()`` should be used
21instead as it will create VLAN interfaces automatically if
22:kconfig:option:`CONFIG_NET_VLAN` is enabled. These macros are typically used in
23network device driver source code.
24
25The network interface can be turned ON by calling ``net_if_up()`` and OFF
26by calling ``net_if_down()``. When the device is powered ON, the network
27interface is also turned ON by default.
28
29The network interfaces can be referenced either by a ``struct net_if *``
30pointer or by a network interface index. The network interface can be
31resolved from its index by calling ``net_if_get_by_index()`` and from interface
32pointer by calling ``net_if_get_by_iface()``.
33
34.. _net_if_interface_ip_management:
35
36The IP address for network devices must be set for them to be connectable.
37In a typical dynamic network environment, IP addresses are set automatically
38by DHCPv4, for example. If needed though, the application can set a device's
39IP address manually.  See the API documentation below for functions such as
40``net_if_ipv4_addr_add()`` that do that.
41
42The ``net_if_get_default()`` returns a *default* network interface. What
43this default interface means can be configured via options like
44:kconfig:option:`CONFIG_NET_DEFAULT_IF_FIRST` and
45:kconfig:option:`CONFIG_NET_DEFAULT_IF_ETHERNET`.
46See Kconfig file :zephyr_file:`subsys/net/ip/Kconfig` what options are available for
47selecting the default network interface.
48
49The transmitted and received network packets can be classified via a network
50packet priority. This is typically done in Ethernet networks when virtual LANs
51(VLANs) are used. Higher priority packets can be sent or received earlier than
52lower priority packets. The traffic class setup can be configured by
53:kconfig:option:`CONFIG_NET_TC_TX_COUNT` and :kconfig:option:`CONFIG_NET_TC_RX_COUNT` options.
54
55If the :kconfig:option:`CONFIG_NET_PROMISCUOUS_MODE` is enabled and if the underlying
56network technology supports promiscuous mode, then it is possible to receive
57all the network packets that the network device driver is able to receive.
58See :ref:`promiscuous_interface` API for more details.
59
60.. _net_if_interface_state_management:
61
62Network interface state management
63**********************************
64
65Zephyr distinguishes between two interface states: administrative state and
66operational state, as described in RFC 2863. The administrative state indicate
67whether an interface is turned ON or OFF. This state is represented by
68:c:enumerator:`NET_IF_UP` flag and is controlled by the application. It can be
69changed by calling :c:func:`net_if_up` or :c:func:`net_if_down` functions.
70Network drivers or L2 implementations should not change administrative state on
71their own.
72
73Bringing an interface up however not always means that the interface is ready to
74transmit packets. Because of that, operational state, which represents the
75internal interface status, was implemented. The operational state is updated
76whenever one of the following conditions take place:
77
78  * The interface is brought up/down by the application (administrative state
79    changes).
80  * The interface is notified by the driver/L2 that PHY status has changed.
81  * The interface is notified by the driver/L2 that it joined/left a network.
82
83The PHY status is represented with :c:enumerator:`NET_IF_LOWER_UP` flag and can
84be changed with :c:func:`net_if_carrier_on` and :c:func:`net_if_carrier_off`. By
85default, the flag is set on a newly initialized interface. An example of an
86event that changes the carrier state is Ethernet cable being plugged in or out.
87
88The network association status is represented with :c:enumerator:`NET_IF_DORMANT`
89flag and can be changed with :c:func:`net_if_dormant_on` and
90:c:func:`net_if_dormant_off`. By default, the flag is cleared on a newly
91initialized interface. An example of an event that changes the dormant state is
92a Wi-Fi driver successfully connecting to an access point. In this scenario,
93driver should set the dormant state to ON during initialization, and once it
94detects that it connected to a Wi-Fi network, the dormant state should be set
95to OFF.
96
97The operational state of an interface is updated as follows:
98
99  * ``!net_if_is_admin_up()``
100
101    Interface is in :c:enumerator:`NET_IF_OPER_DOWN`.
102
103  * ``net_if_is_admin_up() && !net_if_is_carrier_ok()``
104
105    Interface is in :c:enumerator:`NET_IF_OPER_DOWN` or
106    :c:enumerator:`NET_IF_OPER_LOWERLAYERDOWN` if the interface is stacked
107    (virtual).
108
109  * ``net_if_is_admin_up() && net_if_is_carrier_ok() && net_if_is_dormant()``
110
111    Interface is in :c:enumerator:`NET_IF_OPER_DORMANT`.
112
113  * ``net_if_is_admin_up() && net_if_is_carrier_ok() && !net_if_is_dormant()``
114
115    Interface is in :c:enumerator:`NET_IF_OPER_UP`.
116
117Only after an interface enters :c:enumerator:`NET_IF_OPER_UP` state the
118:c:enumerator:`NET_IF_RUNNING` flag is set on the interface indicating that the
119interface is ready to be used by the application.
120
121API Reference
122*************
123
124.. doxygengroup:: net_if
125