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:

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.

API Reference

Network Interface abstraction layer