| .. _net_if_interface: |
| |
| Network Interface |
| ################# |
| |
| .. contents:: |
| :local: |
| :depth: 2 |
| |
| 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 |
| :kconfig: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 |
| :kconfig:option:`CONFIG_NET_DEFAULT_IF_FIRST` and |
| :kconfig:option:`CONFIG_NET_DEFAULT_IF_ETHERNET`. |
| See Kconfig file :zephyr_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 |
| :kconfig:option:`CONFIG_NET_TC_TX_COUNT` and :kconfig:option:`CONFIG_NET_TC_RX_COUNT` options. |
| |
| If the :kconfig:option:`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 :ref:`promiscuous_interface` 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 |
| :c:enumerator:`NET_IF_UP` flag and is controlled by the application. It can be |
| changed by calling :c:func:`net_if_up` or :c:func:`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 :c:enumerator:`NET_IF_LOWER_UP` flag and can |
| be changed with :c:func:`net_if_carrier_on` and :c:func:`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 :c:enumerator:`NET_IF_DORMANT` |
| flag and can be changed with :c:func:`net_if_dormant_on` and |
| :c:func:`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 :c:enumerator:`NET_IF_OPER_DOWN`. |
| |
| * ``net_if_is_admin_up() && !net_if_is_carrier_ok()`` |
| |
| Interface is in :c:enumerator:`NET_IF_OPER_DOWN` or |
| :c:enumerator:`NET_IF_OPER_LOWERLAYERDOWN` if the interface is stacked |
| (virtual). |
| |
| * ``net_if_is_admin_up() && net_if_is_carrier_ok() && net_if_is_dormant()`` |
| |
| Interface is in :c:enumerator:`NET_IF_OPER_DORMANT`. |
| |
| * ``net_if_is_admin_up() && net_if_is_carrier_ok() && !net_if_is_dormant()`` |
| |
| Interface is in :c:enumerator:`NET_IF_OPER_UP`. |
| |
| Only after an interface enters :c:enumerator:`NET_IF_OPER_UP` state the |
| :c:enumerator:`NET_IF_RUNNING` flag is set on the interface indicating that the |
| interface is ready to be used by the application. |
| |
| API Reference |
| ************* |
| |
| .. doxygengroup:: net_if |