Network Interface
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
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
CONFIG_NET_DEFAULT_IF_FIRST and
CONFIG_NET_DEFAULT_IF_ETHERNET.
See Kconfig 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
CONFIG_NET_TC_TX_COUNT and CONFIG_NET_TC_RX_COUNT options.
If the CONFIG_NET_PROMISCUOUS_MODE is enabled and if the underlying
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 Promiscuous Mode API for more details.
Network interface state management
Zephyr distinguishes between two interface states: administrative state and
operational state, as described in RFC 2863. The administrative state indicate
whether an interface is turned ON or OFF. This state is represented by
NET_IF_UP flag and is controlled by the application. It can be
changed by calling net_if_up() or net_if_down() functions.
Network drivers or L2 implementations should not change administrative state on
their own.
Bringing an interface up however not always means that the interface is ready to transmit packets. Because of that, operational state, which represents the internal interface status, was implemented. The operational state is updated whenever one of the following conditions take place:
The interface is brought up/down by the application (administrative state changes).
The interface is notified by the driver/L2 that PHY status has changed.
The interface is notified by the driver/L2 that it joined/left a network.
The PHY status is represented with NET_IF_LOWER_UP flag and can
be changed with net_if_carrier_on() and net_if_carrier_off(). By
default, the flag is set on a newly initialized interface. An example of an
event that changes the carrier state is Ethernet cable being plugged in or out.
The network association status is represented with NET_IF_DORMANT
flag and can be changed with net_if_dormant_on() and
net_if_dormant_off(). By default, the flag is cleared on a newly
initialized interface. An example of an event that changes the dormant state is
a Wi-Fi driver successfully connecting to an access point. In this scenario,
driver should set the dormant state to ON during initialization, and once it
detects that it connected to a Wi-Fi network, the dormant state should be set
to OFF.
The operational state of an interface is updated as follows:
!net_if_is_admin_up()Interface is in
NET_IF_OPER_DOWN.
net_if_is_admin_up() && !net_if_is_carrier_ok()Interface is in
NET_IF_OPER_DOWNorNET_IF_OPER_LOWERLAYERDOWNif the interface is stacked (virtual).
net_if_is_admin_up() && net_if_is_carrier_ok() && net_if_is_dormant()Interface is in
NET_IF_OPER_DORMANT.
net_if_is_admin_up() && net_if_is_carrier_ok() && !net_if_is_dormant()Interface is in
NET_IF_OPER_UP.
Only after an interface enters NET_IF_OPER_UP state the
NET_IF_RUNNING flag is set on the interface indicating that the
interface is ready to be used by the application.