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_DOWN or 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 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.

API Reference 

Related code samples

IPv4 autoconf client: Perform IPv4 autoconfiguration and self-assign a random IPv4 address
Network management socket: Listen to network management events using a network management socket.
Telnet console: Access Zephyr shell over telnet.
Virtual LAN: Setup two virtual LAN networks and use net-shell to view the networks' settings.

group net_if

Network Interface abstraction layer.

Defines

NET_DEVICE_INIT(dev_id, name, init_fn, pm, data, config, prio, api, l2, l2_ctx_type, mtu)

Create a network interface and bind it to network device.

Parameters:

dev_id – Network device id.
name – The name this instance of the driver exposes to the system.
init_fn – Address to the init function of the driver.
pm – Reference to struct pm_device associated with the device. (optional).
data – Pointer to the device’s private data.
config – The address to the structure containing the configuration information for this instance of the driver.
prio – The initialization level at which configuration occurs.
api – Provides an initial pointer to the API function struct used by the driver. Can be NULL.
l2 – Network L2 layer for this network interface.
l2_ctx_type – Type of L2 context data.
mtu – Maximum transfer unit in bytes for this network interface.

NET_DEVICE_DT_DEFINE(node_id, init_fn, pm, data, config, prio, api, l2, l2_ctx_type, mtu)

Like NET_DEVICE_INIT but taking metadata from a devicetree node.

Create a network interface and bind it to network device.

Parameters:

node_id – The devicetree node identifier.
init_fn – Address to the init function of the driver.
pm – Reference to struct pm_device associated with the device. (optional).
data – Pointer to the device’s private data.
config – The address to the structure containing the configuration information for this instance of the driver.
prio – The initialization level at which configuration occurs.
api – Provides an initial pointer to the API function struct used by the driver. Can be NULL.
l2 – Network L2 layer for this network interface.
l2_ctx_type – Type of L2 context data.
mtu – Maximum transfer unit in bytes for this network interface.

NET_DEVICE_DT_INST_DEFINE(inst, ...)

Like NET_DEVICE_DT_DEFINE for an instance of a DT_DRV_COMPAT compatible.

Parameters:

inst – instance number. This is replaced by DT_DRV_COMPAT(inst) in the call to NET_DEVICE_DT_DEFINE.
... – other parameters as expected by NET_DEVICE_DT_DEFINE.

NET_DEVICE_INIT_INSTANCE(dev_id, name, instance, init_fn, pm, data, config, prio, api, l2, l2_ctx_type, mtu)

Create multiple network interfaces and bind them to network device.

If your network device needs more than one instance of a network interface, use this macro below and provide a different instance suffix each time (0, 1, 2, … or a, b, c … whatever works for you)

Parameters:

dev_id – Network device id.
name – The name this instance of the driver exposes to the system.
instance – Instance identifier.
init_fn – Address to the init function of the driver.
pm – Reference to struct pm_device associated with the device. (optional).
data – Pointer to the device’s private data.
config – The address to the structure containing the configuration information for this instance of the driver.
prio – The initialization level at which configuration occurs.
api – Provides an initial pointer to the API function struct used by the driver. Can be NULL.
l2 – Network L2 layer for this network interface.
l2_ctx_type – Type of L2 context data.
mtu – Maximum transfer unit in bytes for this network interface.

NET_DEVICE_DT_DEFINE_INSTANCE(node_id, instance, init_fn, pm, data, config, prio, api, l2, l2_ctx_type, mtu)

Like NET_DEVICE_OFFLOAD_INIT but taking metadata from a devicetree.

Create multiple network interfaces and bind them to network device. If your network device needs more than one instance of a network interface, use this macro below and provide a different instance suffix each time (0, 1, 2, … or a, b, c … whatever works for you)

Parameters:

node_id – The devicetree node identifier.
instance – Instance identifier.
init_fn – Address to the init function of the driver.
pm – Reference to struct pm_device associated with the device. (optional).
data – Pointer to the device’s private data.
config – The address to the structure containing the configuration information for this instance of the driver.
prio – The initialization level at which configuration occurs.
api – Provides an initial pointer to the API function struct used by the driver. Can be NULL.
l2 – Network L2 layer for this network interface.
l2_ctx_type – Type of L2 context data.
mtu – Maximum transfer unit in bytes for this network interface.

NET_DEVICE_DT_INST_DEFINE_INSTANCE(inst, ...)

Like NET_DEVICE_DT_DEFINE_INSTANCE for an instance of a DT_DRV_COMPAT compatible.

Parameters:

inst – instance number. This is replaced by DT_DRV_COMPAT(inst) in the call to NET_DEVICE_DT_DEFINE_INSTANCE.
... – other parameters as expected by NET_DEVICE_DT_DEFINE_INSTANCE.

NET_DEVICE_OFFLOAD_INIT(dev_id, name, init_fn, pm, data, config, prio, api, mtu)

Create a offloaded network interface and bind it to network device.

The offloaded network interface is implemented by a device vendor HAL or similar.

Parameters:

dev_id – Network device id.
name – The name this instance of the driver exposes to the system.
init_fn – Address to the init function of the driver.
pm – Reference to struct pm_device associated with the device. (optional).
data – Pointer to the device’s private data.
config – The address to the structure containing the configuration information for this instance of the driver.
prio – The initialization level at which configuration occurs.
api – Provides an initial pointer to the API function struct used by the driver. Can be NULL.
mtu – Maximum transfer unit in bytes for this network interface.

NET_DEVICE_DT_OFFLOAD_DEFINE(node_id, init_fn, pm, data, config, prio, api, mtu)

Like NET_DEVICE_OFFLOAD_INIT but taking metadata from a devicetree node.

Create a offloaded network interface and bind it to network device. The offloaded network interface is implemented by a device vendor HAL or similar.

Parameters:

node_id – The devicetree node identifier.
init_fn – Address to the init function of the driver.
pm – Reference to struct pm_device associated with the device. (optional).
data – Pointer to the device’s private data.
config – The address to the structure containing the configuration information for this instance of the driver.
prio – The initialization level at which configuration occurs.
api – Provides an initial pointer to the API function struct used by the driver. Can be NULL.
mtu – Maximum transfer unit in bytes for this network interface.

NET_DEVICE_DT_INST_OFFLOAD_DEFINE(inst, ...)

Like NET_DEVICE_DT_OFFLOAD_DEFINE for an instance of a DT_DRV_COMPAT compatible.

Parameters:

inst – instance number. This is replaced by DT_DRV_COMPAT(inst) in the call to NET_DEVICE_DT_OFFLOAD_DEFINE.
... – other parameters as expected by NET_DEVICE_DT_OFFLOAD_DEFINE.

NET_IFACE_COUNT(_dst)

Count the number of network interfaces.

Parameters:

_dst – [out] Pointer to location where result is written.

Typedefs

typedef int (*net_socket_create_t)(int, int, int)

A function prototype to create an offloaded socket.

The prototype is compatible with socket() function.

typedef void (*net_if_ip_addr_cb_t)(struct net_if *iface, struct net_if_addr *addr, void *user_data)

Callback used while iterating over network interface IP addresses.

Param iface:: Pointer to the network interface the address belongs to
Param addr:: Pointer to current IP address
Param user_data:: A valid pointer to user data or NULL

typedef void (*net_if_ip_maddr_cb_t)(struct net_if *iface, struct net_if_mcast_addr *maddr, void *user_data)

Callback used while iterating over network interface multicast IP addresses.

Param iface:: Pointer to the network interface the address belongs to
Param maddr:: Pointer to current multicast IP address
Param user_data:: A valid pointer to user data or NULL

typedef void (*net_if_mcast_callback_t)(struct net_if *iface, const struct net_addr *addr, bool is_joined)

Define a callback that is called whenever a IPv6 or IPv4 multicast address group is joined or left.

Param iface:: A pointer to a struct net_if to which the multicast address is attached.
Param addr:: IP multicast address.
Param is_joined:: True if the multicast group is joined, false if group is left.

typedef void (*net_if_link_callback_t)(struct net_if *iface, struct net_linkaddr *dst, int status)

Define callback that is called after a network packet has been sent.

Param iface:: A pointer to a struct net_if to which the the net_pkt was sent to.
Param dst:: Link layer address of the destination where the network packet was sent.
Param status:: Send status, 0 is ok, < 0 error.

typedef void (*net_if_cb_t)(struct net_if *iface, void *user_data)

Callback used while iterating over network interfaces.

Param iface:: Pointer to current network interface
Param user_data:: A valid pointer to user data or NULL

Enums

enum net_if_flag

Network interface flags.

Values:

enumerator NET_IF_UP: Interface is admin up.

enumerator NET_IF_POINTOPOINT: Interface is pointopoint.

enumerator NET_IF_PROMISC: Interface is in promiscuous mode.

enumerator NET_IF_NO_AUTO_START

Do not start the interface immediately after initialization.

This requires that either the device driver or some other entity will need to manually take the interface up when needed. For example for Ethernet this will happen when the driver calls the net_eth_carrier_on() function.

enumerator NET_IF_SUSPENDED: Power management specific: interface is being suspended.

enumerator NET_IF_FORWARD_MULTICASTS

Flag defines if received multicasts of other interface are forwarded on this interface.

This activates multicast routing / forwarding for this interface.

enumerator NET_IF_IPV4: Interface supports IPv4.

enumerator NET_IF_IPV6: Interface supports IPv6.

enumerator NET_IF_RUNNING: Interface up and running (ready to receive and transmit).

enumerator NET_IF_LOWER_UP: Driver signals L1 is up.

enumerator NET_IF_DORMANT: Driver signals dormant.

enumerator NET_IF_IPV6_NO_ND: IPv6 Neighbor Discovery disabled.

enumerator NET_IF_IPV6_NO_MLD: IPv6 Multicast Listener Discovery disabled.

enumerator NET_IF_NO_TX_LOCK: Mutex locking on TX data path disabled on the interface.

enum net_if_oper_state

Network interface operational status (RFC 2863).

Values:

enumerator NET_IF_OPER_UNKNOWN: Initial (unknown) value.

enumerator NET_IF_OPER_NOTPRESENT: Hardware missing.

enumerator NET_IF_OPER_DOWN: Interface is down.

enumerator NET_IF_OPER_LOWERLAYERDOWN: Lower layer interface is down.

enumerator NET_IF_OPER_TESTING: Training mode.

enumerator NET_IF_OPER_DORMANT: Waiting external action.

enumerator NET_IF_OPER_UP: Interface is up.

Functions

static inline void net_if_flag_set(struct net_if *iface, enum net_if_flag value)

Set a value in network interface flags.

Parameters:

iface – Pointer to network interface
value – Flag value

static inline bool net_if_flag_test_and_set(struct net_if *iface, enum net_if_flag value)

Test and set a value in network interface flags.

Parameters:

iface – Pointer to network interface
value – Flag value

Returns:

true if the bit was set, false if it wasn’t.

static inline void net_if_flag_clear(struct net_if *iface, enum net_if_flag value)

Clear a value in network interface flags.

Parameters:

iface – Pointer to network interface
value – Flag value

static inline bool net_if_flag_test_and_clear(struct net_if *iface, enum net_if_flag value)

Test and clear a value in network interface flags.

Parameters:

iface – Pointer to network interface
value – Flag value

Returns:

true if the bit was set, false if it wasn’t.

static inline bool net_if_flag_is_set(struct net_if *iface, enum net_if_flag value)

Check if a value in network interface flags is set.

Parameters:

iface – Pointer to network interface
value – Flag value

Returns:

True if the value is set, false otherwise

static inline enum net_if_oper_state net_if_oper_state_set(struct net_if *iface, enum net_if_oper_state oper_state)

Set an operational state on an interface.

Parameters:

iface – Pointer to network interface
oper_state – Operational state to set

Returns:

The new operational state of an interface

static inline enum net_if_oper_state net_if_oper_state(struct net_if *iface)

Get an operational state of an interface.

Parameters:

iface – Pointer to network interface

Returns:

Operational state of an interface

enum net_verdict net_if_send_data(struct net_if *iface, struct net_pkt *pkt)

Send a packet through a net iface.

return verdict about the packet

Parameters:

iface – Pointer to a network interface structure
pkt – Pointer to a net packet to send

static inline const struct net_l2 *net_if_l2(struct net_if *iface)

Get a pointer to the interface L2.

Parameters:

iface – a valid pointer to a network interface structure

Returns:

a pointer to the iface L2

enum net_verdict net_if_recv_data(struct net_if *iface, struct net_pkt *pkt)

Input a packet through a net iface.

Parameters:

iface – Pointer to a network interface structure
pkt – Pointer to a net packet to input

Returns:

verdict about the packet

static inline void *net_if_l2_data(struct net_if *iface)

Get a pointer to the interface L2 private data.

Parameters:

iface – a valid pointer to a network interface structure

Returns:

a pointer to the iface L2 data

static inline const struct device *net_if_get_device(struct net_if *iface)

Get an network interface’s device.

Parameters:

iface – Pointer to a network interface structure

Returns:

a pointer to the device driver instance

void net_if_queue_tx(struct net_if *iface, struct net_pkt *pkt)

Queue a packet to the net interface TX queue.

Parameters:

iface – Pointer to a network interface structure
pkt – Pointer to a net packet to queue

static inline bool net_if_is_ip_offloaded(struct net_if *iface)

Return the IP offload status.

Parameters:

iface – Network interface

Returns:

True if IP offloading is active, false otherwise.

bool net_if_is_offloaded(struct net_if *iface)

Return offload status of a given network interface.

Parameters:

iface – Network interface

Returns:

True if IP or socket offloading is active, false otherwise.

static inline struct net_offload *net_if_offload(struct net_if *iface)

Return the IP offload plugin.

Parameters:

iface – Network interface

Returns:

NULL if there is no offload plugin defined, valid pointer otherwise

static inline bool net_if_is_socket_offloaded(struct net_if *iface)

Return the socket offload status.

Parameters:

iface – Network interface

Returns:

True if socket offloading is active, false otherwise.

static inline void net_if_socket_offload_set(struct net_if *iface, net_socket_create_t socket_offload)

Set the function to create an offloaded socket.

Parameters:

iface – Network interface
socket_offload – A function to create an offloaded socket

static inline net_socket_create_t net_if_socket_offload(struct net_if *iface)

Return the function to create an offloaded socket.

Parameters:

iface – Network interface

Returns:

NULL if the interface is not socket offloaded, valid pointer otherwise

static inline struct net_linkaddr *net_if_get_link_addr(struct net_if *iface)

Get an network interface’s link address.

Parameters:

iface – Pointer to a network interface structure

Returns:

a pointer to the network link address

static inline struct net_if_config *net_if_get_config(struct net_if *iface)

Return network configuration for this network interface.

Parameters:

iface – Pointer to a network interface structure

Returns:

Pointer to configuration

static inline void net_if_start_dad(struct net_if *iface)

Start duplicate address detection procedure.

Parameters:

iface – Pointer to a network interface structure

void net_if_start_rs(struct net_if *iface)

Start neighbor discovery and send router solicitation message.

Parameters:

iface – Pointer to a network interface structure

static inline void net_if_stop_rs(struct net_if *iface)

Stop neighbor discovery.

Parameters:

iface – Pointer to a network interface structure

static inline void net_if_nbr_reachability_hint(struct net_if *iface, const struct in6_addr *ipv6_addr)

Provide a reachability hint for IPv6 Neighbor Discovery.

This function is intended for upper-layer protocols to inform the IPv6 Neighbor Discovery process about an active link to a specific neighbor. By signaling a recent “forward progress” event, such as the reception of an ACK, this function can help reduce unnecessary ND traffic as per the guidelines in RFC 4861 (section 7.3).

Parameters:

iface – A pointer to the network interface.
ipv6_addr – Pointer to the IPv6 address of the neighbor node.

static inline int net_if_set_link_addr(struct net_if *iface, uint8_t *addr, uint8_t len, enum net_link_type type)

Set a network interface’s link address.

Parameters:

iface – Pointer to a network interface structure
addr – A pointer to a uint8_t buffer representing the address. The buffer must remain valid throughout interface lifetime.
len – length of the address buffer
type – network bearer type of this link address

Returns:

0 on success

static inline uint16_t net_if_get_mtu(struct net_if *iface)

Get an network interface’s MTU.

Parameters:

iface – Pointer to a network interface structure

Returns:

the MTU

static inline void net_if_set_mtu(struct net_if *iface, uint16_t mtu)

Set an network interface’s MTU.

Parameters:

iface – Pointer to a network interface structure
mtu – New MTU, note that we store only 16 bit mtu value.

static inline void net_if_addr_set_lf(struct net_if_addr *ifaddr, bool is_infinite)

Set the infinite status of the network interface address.

Parameters:

ifaddr – IP address for network interface
is_infinite – Infinite status

struct net_if *net_if_get_by_link_addr(struct net_linkaddr *ll_addr)

Get an interface according to link layer address.

Parameters:

ll_addr – Link layer address.

Returns:

Network interface or NULL if not found.

struct net_if *net_if_lookup_by_dev(const struct device *dev)

Find an interface from it’s related device.

Parameters:

dev – A valid struct device pointer to relate with an interface

Returns:

a valid struct net_if pointer on success, NULL otherwise

static inline struct net_if_config *net_if_config_get(struct net_if *iface)

Get network interface IP config.

Parameters:

iface – Interface to use.

Returns:

NULL if not found or pointer to correct config settings.

void net_if_router_rm(struct net_if_router *router)

Remove a router from the system.

Parameters:

router – Pointer to existing router

void net_if_set_default(struct net_if *iface)

Set the default network interface.

Parameters:

iface – New default interface, or NULL to revert to the one set by Kconfig.

struct net_if *net_if_get_default(void)

Get the default network interface.

Returns:: Default interface or NULL if no interfaces are configured.

struct net_if *net_if_get_first_by_type(const struct net_l2 *l2)

Get the first network interface according to its type.

Parameters:

l2 – Layer 2 type of the network interface.

Returns:

First network interface of a given type or NULL if no such interfaces was found.

struct net_if *net_if_get_first_up(void)

Get the first network interface which is up.

Returns:: First network interface which is up or NULL if all interfaces are down.

int net_if_config_ipv6_get(struct net_if *iface, struct net_if_ipv6 **ipv6)

Allocate network interface IPv6 config.

This function will allocate new IPv6 config.

Parameters:

iface – Interface to use.
ipv6 – Pointer to allocated IPv6 struct is returned to caller.

Returns:

0 if ok, <0 if error

int net_if_config_ipv6_put(struct net_if *iface)

Release network interface IPv6 config.

Parameters:

iface – Interface to use.

Returns:

0 if ok, <0 if error

struct net_if_addr *net_if_ipv6_addr_lookup(const struct in6_addr *addr, struct net_if **iface)

Check if this IPv6 address belongs to one of the interfaces.

Parameters:

addr – IPv6 address
iface – Pointer to interface is returned

Returns:

Pointer to interface address, NULL if not found.

struct net_if_addr *net_if_ipv6_addr_lookup_by_iface(struct net_if *iface, struct in6_addr *addr)

Check if this IPv6 address belongs to this specific interfaces.

Parameters:

iface – Network interface
addr – IPv6 address

Returns:

Pointer to interface address, NULL if not found.

int net_if_ipv6_addr_lookup_by_index(const struct in6_addr *addr)

Check if this IPv6 address belongs to one of the interface indices.

Parameters:

addr – IPv6 address

Returns:

>0 if address was found in given network interface index, all other values mean address was not found

struct net_if_addr *net_if_ipv6_addr_add(struct net_if *iface, struct in6_addr *addr, enum net_addr_type addr_type, uint32_t vlifetime)

Add a IPv6 address to an interface.

Parameters:

iface – Network interface
addr – IPv6 address
addr_type – IPv6 address type
vlifetime – Validity time for this address

Returns:

Pointer to interface address, NULL if cannot be added

bool net_if_ipv6_addr_add_by_index(int index, struct in6_addr *addr, enum net_addr_type addr_type, uint32_t vlifetime)

Add a IPv6 address to an interface by index.

Parameters:

index – Network interface index
addr – IPv6 address
addr_type – IPv6 address type
vlifetime – Validity time for this address

Returns:

True if ok, false if address could not be added

void net_if_ipv6_addr_update_lifetime(struct net_if_addr *ifaddr, uint32_t vlifetime)

Update validity lifetime time of an IPv6 address.

Parameters:

ifaddr – Network IPv6 address
vlifetime – Validity time for this address

bool net_if_ipv6_addr_rm(struct net_if *iface, const struct in6_addr *addr)

Remove an IPv6 address from an interface.

Parameters:

iface – Network interface
addr – IPv6 address

Returns:

True if successfully removed, false otherwise

bool net_if_ipv6_addr_rm_by_index(int index, const struct in6_addr *addr)

Remove an IPv6 address from an interface by index.

Parameters:

index – Network interface index
addr – IPv6 address

Returns:

True if successfully removed, false otherwise

void net_if_ipv6_addr_foreach(struct net_if *iface, net_if_ip_addr_cb_t cb, void *user_data)

Go through all IPv6 addresses on a network interface and call callback for each used address.

Parameters:

iface – Pointer to the network interface
cb – User-supplied callback function to call
user_data – User specified data

struct net_if_mcast_addr *net_if_ipv6_maddr_add(struct net_if *iface, const struct in6_addr *addr)

Add a IPv6 multicast address to an interface.

Parameters:

iface – Network interface
addr – IPv6 multicast address

Returns:

Pointer to interface multicast address, NULL if cannot be added

bool net_if_ipv6_maddr_rm(struct net_if *iface, const struct in6_addr *addr)

Remove an IPv6 multicast address from an interface.

Parameters:

iface – Network interface
addr – IPv6 multicast address

Returns:

True if successfully removed, false otherwise

void net_if_ipv6_maddr_foreach(struct net_if *iface, net_if_ip_maddr_cb_t cb, void *user_data)

Go through all IPv6 multicast addresses on a network interface and call callback for each used address.

Parameters:

iface – Pointer to the network interface
cb – User-supplied callback function to call
user_data – User specified data

struct net_if_mcast_addr *net_if_ipv6_maddr_lookup(const struct in6_addr *addr, struct net_if **iface)

Check if this IPv6 multicast address belongs to a specific interface or one of the interfaces.

Parameters:

addr – IPv6 address
iface – If *iface is null, then pointer to interface is returned, otherwise the *iface value needs to be matched.

Returns:

Pointer to interface multicast address, NULL if not found.

void net_if_mcast_mon_register(struct net_if_mcast_monitor *mon, struct net_if *iface, net_if_mcast_callback_t cb)

Register a multicast monitor.

Parameters:

mon – Monitor handle. This is a pointer to a monitor storage structure which should be allocated by caller, but does not need to be initialized.
iface – Network interface or NULL for all interfaces
cb – Monitor callback

void net_if_mcast_mon_unregister(struct net_if_mcast_monitor *mon)

Unregister a multicast monitor.

Parameters:

mon – Monitor handle

void net_if_mcast_monitor(struct net_if *iface, const struct net_addr *addr, bool is_joined)

Call registered multicast monitors.

Parameters:

iface – Network interface
addr – Multicast address
is_joined – Is this multicast address group joined (true) or not (false)

void net_if_ipv6_maddr_join(struct net_if *iface, struct net_if_mcast_addr *addr)

Mark a given multicast address to be joined.

Parameters:

iface – Network interface the address belongs to
addr – IPv6 multicast address

static inline bool net_if_ipv6_maddr_is_joined(struct net_if_mcast_addr *addr)

Check if given multicast address is joined or not.

Parameters:

addr – IPv6 multicast address

Returns:

True if address is joined, False otherwise.

void net_if_ipv6_maddr_leave(struct net_if *iface, struct net_if_mcast_addr *addr)

Mark a given multicast address to be left.

Parameters:

iface – Network interface the address belongs to
addr – IPv6 multicast address

struct net_if_ipv6_prefix *net_if_ipv6_prefix_get(struct net_if *iface, const struct in6_addr *addr)

Return prefix that corresponds to this IPv6 address.

Parameters:

iface – Network interface
addr – IPv6 address

Returns:

Pointer to prefix, NULL if not found.

struct net_if_ipv6_prefix *net_if_ipv6_prefix_lookup(struct net_if *iface, struct in6_addr *addr, uint8_t len)

Check if this IPv6 prefix belongs to this interface.

Parameters:

iface – Network interface
addr – IPv6 address
len – Prefix length

Returns:

Pointer to prefix, NULL if not found.

struct net_if_ipv6_prefix *net_if_ipv6_prefix_add(struct net_if *iface, struct in6_addr *prefix, uint8_t len, uint32_t lifetime)

Add a IPv6 prefix to an network interface.

Parameters:

iface – Network interface
prefix – IPv6 address
len – Prefix length
lifetime – Prefix lifetime in seconds

Returns:

Pointer to prefix, NULL if the prefix was not added.

bool net_if_ipv6_prefix_rm(struct net_if *iface, struct in6_addr *addr, uint8_t len)

Remove an IPv6 prefix from an interface.

Parameters:

iface – Network interface
addr – IPv6 prefix address
len – Prefix length

Returns:

True if successfully removed, false otherwise

static inline void net_if_ipv6_prefix_set_lf(struct net_if_ipv6_prefix *prefix, bool is_infinite)

Set the infinite status of the prefix.

Parameters:

prefix – IPv6 address
is_infinite – Infinite status

void net_if_ipv6_prefix_set_timer(struct net_if_ipv6_prefix *prefix, uint32_t lifetime)

Set the prefix lifetime timer.

Parameters:

prefix – IPv6 address
lifetime – Prefix lifetime in seconds

void net_if_ipv6_prefix_unset_timer(struct net_if_ipv6_prefix *prefix)

Unset the prefix lifetime timer.

Parameters:

prefix – IPv6 address

bool net_if_ipv6_addr_onlink(struct net_if **iface, struct in6_addr *addr)

Check if this IPv6 address is part of the subnet of our network interface.

Parameters:

iface – Network interface. This is returned to the caller. The iface can be NULL in which case we check all the interfaces.
addr – IPv6 address

Returns:

True if address is part of our subnet, false otherwise

static inline struct in6_addr *net_if_router_ipv6(struct net_if_router *router)

Get the IPv6 address of the given router.

Parameters:

router – a network router

Returns:

pointer to the IPv6 address, or NULL if none

struct net_if_router *net_if_ipv6_router_lookup(struct net_if *iface, struct in6_addr *addr)

Check if IPv6 address is one of the routers configured in the system.

Parameters:

iface – Network interface
addr – IPv6 address

Returns:

Pointer to router information, NULL if cannot be found

struct net_if_router *net_if_ipv6_router_find_default(struct net_if *iface, struct in6_addr *addr)

Find default router for this IPv6 address.

Parameters:

iface – Network interface. This can be NULL in which case we go through all the network interfaces to find a suitable router.
addr – IPv6 address

Returns:

Pointer to router information, NULL if cannot be found

void net_if_ipv6_router_update_lifetime(struct net_if_router *router, uint16_t lifetime)

Update validity lifetime time of a router.

Parameters:

router – Network IPv6 address
lifetime – Lifetime of this router.

struct net_if_router *net_if_ipv6_router_add(struct net_if *iface, struct in6_addr *addr, uint16_t router_lifetime)

Add IPv6 router to the system.

Parameters:

iface – Network interface
addr – IPv6 address
router_lifetime – Lifetime of the router

Returns:

Pointer to router information, NULL if could not be added

bool net_if_ipv6_router_rm(struct net_if_router *router)

Remove IPv6 router from the system.

Parameters:

router – Router information.

Returns:

True if successfully removed, false otherwise

uint8_t net_if_ipv6_get_hop_limit(struct net_if *iface)

Get IPv6 hop limit specified for a given interface.

This is the default value but can be overridden by the user.

Parameters:

iface – Network interface

Returns:

Hop limit

void net_if_ipv6_set_hop_limit(struct net_if *iface, uint8_t hop_limit)

Set the default IPv6 hop limit of a given interface.

Parameters:

iface – Network interface
hop_limit – New hop limit

uint8_t net_if_ipv6_get_mcast_hop_limit(struct net_if *iface)

Get IPv6 multicast hop limit specified for a given interface.

This is the default value but can be overridden by the user.

Parameters:

iface – Network interface

Returns:

Hop limit

void net_if_ipv6_set_mcast_hop_limit(struct net_if *iface, uint8_t hop_limit)

Set the default IPv6 multicast hop limit of a given interface.

Parameters:

iface – Network interface
hop_limit – New hop limit

static inline void net_if_ipv6_set_base_reachable_time(struct net_if *iface, uint32_t reachable_time)

Set IPv6 reachable time for a given interface.

Parameters:

iface – Network interface
reachable_time – New reachable time

static inline uint32_t net_if_ipv6_get_reachable_time(struct net_if *iface)

Get IPv6 reachable timeout specified for a given interface.

Parameters:

iface – Network interface

Returns:

Reachable timeout

uint32_t net_if_ipv6_calc_reachable_time(struct net_if_ipv6 *ipv6)

Calculate next reachable time value for IPv6 reachable time.

Parameters:

ipv6 – IPv6 address configuration

Returns:

Reachable time

static inline void net_if_ipv6_set_reachable_time(struct net_if_ipv6 *ipv6)

Set IPv6 reachable time for a given interface.

This requires that base reachable time is set for the interface.

Parameters:

ipv6 – IPv6 address configuration

static inline void net_if_ipv6_set_retrans_timer(struct net_if *iface, uint32_t retrans_timer)

Set IPv6 retransmit timer for a given interface.

Parameters:

iface – Network interface
retrans_timer – New retransmit timer

static inline uint32_t net_if_ipv6_get_retrans_timer(struct net_if *iface)

Get IPv6 retransmit timer specified for a given interface.

Parameters:

iface – Network interface

Returns:

Retransmit timer

static inline const struct in6_addr *net_if_ipv6_select_src_addr(struct net_if *iface, const struct in6_addr *dst)

Get a IPv6 source address that should be used when sending network data to destination.

Parameters:

iface – Interface that was used when packet was received. If the interface is not known, then NULL can be given.
dst – IPv6 destination address

Returns:

Pointer to IPv6 address to use, NULL if no IPv6 address could be found.

static inline const struct in6_addr *net_if_ipv6_select_src_addr_hint(struct net_if *iface, const struct in6_addr *dst, int flags)

Get a IPv6 source address that should be used when sending network data to destination.

Use a hint set to the socket to select the proper address.

Parameters:

iface – Interface that was used when packet was received. If the interface is not known, then NULL can be given.
dst – IPv6 destination address
flags – Hint from the related socket. See RFC 5014 for value details.

Returns:

Pointer to IPv6 address to use, NULL if no IPv6 address could be found.

static inline struct net_if *net_if_ipv6_select_src_iface(const struct in6_addr *dst)

Get a network interface that should be used when sending IPv6 network data to destination.

Parameters:

dst – IPv6 destination address

Returns:

Pointer to network interface to use, NULL if no suitable interface could be found.

struct in6_addr *net_if_ipv6_get_ll(struct net_if *iface, enum net_addr_state addr_state)

Get a IPv6 link local address in a given state.

Parameters:

iface – Interface to use. Must be a valid pointer to an interface.
addr_state – IPv6 address state (preferred, tentative, deprecated)

Returns:

Pointer to link local IPv6 address, NULL if no proper IPv6 address could be found.

struct in6_addr *net_if_ipv6_get_ll_addr(enum net_addr_state state, struct net_if **iface)

Return link local IPv6 address from the first interface that has a link local address matching give state.

Parameters:

state – IPv6 address state (ANY, TENTATIVE, PREFERRED, DEPRECATED)
iface – Pointer to interface is returned

Returns:

Pointer to IPv6 address, NULL if not found.

void net_if_ipv6_dad_failed(struct net_if *iface, const struct in6_addr *addr)

Stop IPv6 Duplicate Address Detection (DAD) procedure if we find out that our IPv6 address is already in use.

Parameters:

iface – Interface where the DAD was running.
addr – IPv6 address that failed DAD

struct in6_addr *net_if_ipv6_get_global_addr(enum net_addr_state state, struct net_if **iface)

Return global IPv6 address from the first interface that has a global IPv6 address matching the given state.

Parameters:

state – IPv6 address state (ANY, TENTATIVE, PREFERRED, DEPRECATED)
iface – Caller can give an interface to check. If iface is set to NULL, then all the interfaces are checked. Pointer to interface where the IPv6 address is defined is returned to the caller.

Returns:

Pointer to IPv6 address, NULL if not found.

int net_if_config_ipv4_get(struct net_if *iface, struct net_if_ipv4 **ipv4)

Allocate network interface IPv4 config.

This function will allocate new IPv4 config.

Parameters:

iface – Interface to use.
ipv4 – Pointer to allocated IPv4 struct is returned to caller.

Returns:

0 if ok, <0 if error

int net_if_config_ipv4_put(struct net_if *iface)

Release network interface IPv4 config.

Parameters:

iface – Interface to use.

Returns:

0 if ok, <0 if error

uint8_t net_if_ipv4_get_ttl(struct net_if *iface)

Get IPv4 time-to-live value specified for a given interface.

Parameters:

iface – Network interface

Returns:

Time-to-live

void net_if_ipv4_set_ttl(struct net_if *iface, uint8_t ttl)

Set IPv4 time-to-live value specified to a given interface.

Parameters:

iface – Network interface
ttl – Time-to-live value

uint8_t net_if_ipv4_get_mcast_ttl(struct net_if *iface)

Get IPv4 multicast time-to-live value specified for a given interface.

Parameters:

iface – Network interface

Returns:

Time-to-live

void net_if_ipv4_set_mcast_ttl(struct net_if *iface, uint8_t ttl)

Set IPv4 multicast time-to-live value specified to a given interface.

Parameters:

iface – Network interface
ttl – Time-to-live value

struct net_if_addr *net_if_ipv4_addr_lookup(const struct in_addr *addr, struct net_if **iface)

Check if this IPv4 address belongs to one of the interfaces.

Parameters:

addr – IPv4 address
iface – Interface is returned

Returns:

Pointer to interface address, NULL if not found.

struct net_if_addr *net_if_ipv4_addr_add(struct net_if *iface, struct in_addr *addr, enum net_addr_type addr_type, uint32_t vlifetime)

Add a IPv4 address to an interface.

Parameters:

iface – Network interface
addr – IPv4 address
addr_type – IPv4 address type
vlifetime – Validity time for this address

Returns:

Pointer to interface address, NULL if cannot be added

bool net_if_ipv4_addr_rm(struct net_if *iface, const struct in_addr *addr)

Remove a IPv4 address from an interface.

Parameters:

iface – Network interface
addr – IPv4 address

Returns:

True if successfully removed, false otherwise

int net_if_ipv4_addr_lookup_by_index(const struct in_addr *addr)

Check if this IPv4 address belongs to one of the interface indices.

Parameters:

addr – IPv4 address

Returns:

>0 if address was found in given network interface index, all other values mean address was not found

bool net_if_ipv4_addr_add_by_index(int index, struct in_addr *addr, enum net_addr_type addr_type, uint32_t vlifetime)

Add a IPv4 address to an interface by network interface index.

Parameters:

index – Network interface index
addr – IPv4 address
addr_type – IPv4 address type
vlifetime – Validity time for this address

Returns:

True if ok, false if the address could not be added

bool net_if_ipv4_addr_rm_by_index(int index, const struct in_addr *addr)

Remove a IPv4 address from an interface by interface index.

Parameters:

index – Network interface index
addr – IPv4 address

Returns:

True if successfully removed, false otherwise

void net_if_ipv4_addr_foreach(struct net_if *iface, net_if_ip_addr_cb_t cb, void *user_data)

Go through all IPv4 addresses on a network interface and call callback for each used address.

Parameters:

iface – Pointer to the network interface
cb – User-supplied callback function to call
user_data – User specified data

struct net_if_mcast_addr *net_if_ipv4_maddr_add(struct net_if *iface, const struct in_addr *addr)

Add a IPv4 multicast address to an interface.

Parameters:

iface – Network interface
addr – IPv4 multicast address

Returns:

Pointer to interface multicast address, NULL if cannot be added

bool net_if_ipv4_maddr_rm(struct net_if *iface, const struct in_addr *addr)

Remove an IPv4 multicast address from an interface.

Parameters:

iface – Network interface
addr – IPv4 multicast address

Returns:

True if successfully removed, false otherwise

void net_if_ipv4_maddr_foreach(struct net_if *iface, net_if_ip_maddr_cb_t cb, void *user_data)

Go through all IPv4 multicast addresses on a network interface and call callback for each used address.

Parameters:

iface – Pointer to the network interface
cb – User-supplied callback function to call
user_data – User specified data

struct net_if_mcast_addr *net_if_ipv4_maddr_lookup(const struct in_addr *addr, struct net_if **iface)

Check if this IPv4 multicast address belongs to a specific interface or one of the interfaces.

Parameters:

addr – IPv4 address
iface – If *iface is null, then pointer to interface is returned, otherwise the *iface value needs to be matched.

Returns:

Pointer to interface multicast address, NULL if not found.

void net_if_ipv4_maddr_join(struct net_if *iface, struct net_if_mcast_addr *addr)

Mark a given multicast address to be joined.

Parameters:

iface – Network interface the address belongs to
addr – IPv4 multicast address

static inline bool net_if_ipv4_maddr_is_joined(struct net_if_mcast_addr *addr)

Check if given multicast address is joined or not.

Parameters:

addr – IPv4 multicast address

Returns:

True if address is joined, False otherwise.

void net_if_ipv4_maddr_leave(struct net_if *iface, struct net_if_mcast_addr *addr)

Mark a given multicast address to be left.

Parameters:

iface – Network interface the address belongs to
addr – IPv4 multicast address

static inline struct in_addr *net_if_router_ipv4(struct net_if_router *router)

Get the IPv4 address of the given router.

Parameters:

router – a network router

Returns:

pointer to the IPv4 address, or NULL if none

struct net_if_router *net_if_ipv4_router_lookup(struct net_if *iface, struct in_addr *addr)

Check if IPv4 address is one of the routers configured in the system.

Parameters:

iface – Network interface
addr – IPv4 address

Returns:

Pointer to router information, NULL if cannot be found

struct net_if_router *net_if_ipv4_router_find_default(struct net_if *iface, struct in_addr *addr)

Find default router for this IPv4 address.

Parameters:

iface – Network interface. This can be NULL in which case we go through all the network interfaces to find a suitable router.
addr – IPv4 address

Returns:

Pointer to router information, NULL if cannot be found

struct net_if_router *net_if_ipv4_router_add(struct net_if *iface, struct in_addr *addr, bool is_default, uint16_t router_lifetime)

Add IPv4 router to the system.

Parameters:

iface – Network interface
addr – IPv4 address
is_default – Is this router the default one
router_lifetime – Lifetime of the router

Returns:

Pointer to router information, NULL if could not be added

bool net_if_ipv4_router_rm(struct net_if_router *router)

Remove IPv4 router from the system.

Parameters:

router – Router information.

Returns:

True if successfully removed, false otherwise

bool net_if_ipv4_addr_mask_cmp(struct net_if *iface, const struct in_addr *addr)

Check if the given IPv4 address belongs to local subnet.

Parameters:

iface – Interface to use. Must be a valid pointer to an interface.
addr – IPv4 address

Returns:

True if address is part of local subnet, false otherwise.

bool net_if_ipv4_is_addr_bcast(struct net_if *iface, const struct in_addr *addr)

Check if the given IPv4 address is a broadcast address.

Parameters:

iface – Interface to use. Must be a valid pointer to an interface.
addr – IPv4 address, this should be in network byte order

Returns:

True if address is a broadcast address, false otherwise.

static inline struct net_if *net_if_ipv4_select_src_iface(const struct in_addr *dst)

Get a network interface that should be used when sending IPv4 network data to destination.

Parameters:

dst – IPv4 destination address

Returns:

Pointer to network interface to use, NULL if no suitable interface could be found.

static inline const struct in_addr *net_if_ipv4_select_src_addr(struct net_if *iface, const struct in_addr *dst)

Get a IPv4 source address that should be used when sending network data to destination.

Parameters:

iface – Interface to use when sending the packet. If the interface is not known, then NULL can be given.
dst – IPv4 destination address

Returns:

Pointer to IPv4 address to use, NULL if no IPv4 address could be found.

struct in_addr *net_if_ipv4_get_ll(struct net_if *iface, enum net_addr_state addr_state)

Get a IPv4 link local address in a given state.

Parameters:

iface – Interface to use. Must be a valid pointer to an interface.
addr_state – IPv4 address state (preferred, tentative, deprecated)

Returns:

Pointer to link local IPv4 address, NULL if no proper IPv4 address could be found.

struct in_addr *net_if_ipv4_get_global_addr(struct net_if *iface, enum net_addr_state addr_state)

Get a IPv4 global address in a given state.

Parameters:

iface – Interface to use. Must be a valid pointer to an interface.
addr_state – IPv4 address state (preferred, tentative, deprecated)

Returns:

Pointer to link local IPv4 address, NULL if no proper IPv4 address could be found.

struct in_addr net_if_ipv4_get_netmask_by_addr(struct net_if *iface, const struct in_addr *addr)

Get IPv4 netmask related to an address of an interface.

Parameters:

iface – Interface to use.
addr – IPv4 address to check.

Returns:

The netmask set on the interface related to the give address, unspecified address if not found.

struct in_addr net_if_ipv4_get_netmask(struct net_if *iface)

Get IPv4 netmask of an interface.

Deprecated:: Use net_if_ipv4_get_netmask_by_addr() instead.

Parameters:

iface – Interface to use.

Returns:

The netmask set on the interface, unspecified address if not found.

void net_if_ipv4_set_netmask(struct net_if *iface, const struct in_addr *netmask)

Set IPv4 netmask for an interface.

Deprecated:: Use net_if_ipv4_set_netmask_by_addr() instead.

Parameters:

iface – Interface to use.
netmask – IPv4 netmask

bool net_if_ipv4_set_netmask_by_index(int index, const struct in_addr *netmask)

Set IPv4 netmask for an interface index.

Deprecated:: Use net_if_ipv4_set_netmask_by_addr() instead.

Parameters:

index – Network interface index
netmask – IPv4 netmask

Returns:

True if netmask was added, false otherwise.

bool net_if_ipv4_set_netmask_by_addr_by_index(int index, const struct in_addr *addr, const struct in_addr *netmask)

Set IPv4 netmask for an interface index for a given address.

Parameters:

index – Network interface index
addr – IPv4 address related to this netmask
netmask – IPv4 netmask

Returns:

True if netmask was added, false otherwise.

bool net_if_ipv4_set_netmask_by_addr(struct net_if *iface, const struct in_addr *addr, const struct in_addr *netmask)

Set IPv4 netmask for an interface index for a given address.

Parameters:

iface – Network interface
addr – IPv4 address related to this netmask
netmask – IPv4 netmask

Returns:

True if netmask was added, false otherwise.

void net_if_ipv4_set_gw(struct net_if *iface, const struct in_addr *gw)

Set IPv4 gateway for an interface.

Parameters:

iface – Interface to use.
gw – IPv4 address of an gateway

bool net_if_ipv4_set_gw_by_index(int index, const struct in_addr *gw)

Set IPv4 gateway for an interface index.

Parameters:

index – Network interface index
gw – IPv4 address of an gateway

Returns:

True if gateway was added, false otherwise.

struct net_if *net_if_select_src_iface(const struct sockaddr *dst)

Get a network interface that should be used when sending IPv6 or IPv4 network data to destination.

Parameters:

dst – IPv6 or IPv4 destination address

Returns:

Pointer to network interface to use. Note that the function will return the default network interface if the best network interface is not found.

void net_if_register_link_cb(struct net_if_link_cb *link, net_if_link_callback_t cb)

Register a link callback.

Parameters:

link – Caller specified handler for the callback.
cb – Callback to register.

void net_if_unregister_link_cb(struct net_if_link_cb *link)

Unregister a link callback.

Parameters:

link – Caller specified handler for the callback.

void net_if_call_link_cb(struct net_if *iface, struct net_linkaddr *lladdr, int status)

Call a link callback function.

Parameters:

iface – Network interface.
lladdr – Destination link layer address
status – 0 is ok, < 0 error

bool net_if_need_calc_rx_checksum(struct net_if *iface)

Check if received network packet checksum calculation can be avoided or not.

For example many ethernet devices support network packet offloading in which case the IP stack does not need to calculate the checksum.

Parameters:

iface – Network interface

Returns:

True if checksum needs to be calculated, false otherwise.

bool net_if_need_calc_tx_checksum(struct net_if *iface)

Check if network packet checksum calculation can be avoided or not when sending the packet.

For example many ethernet devices support network packet offloading in which case the IP stack does not need to calculate the checksum.

Parameters:

iface – Network interface

Returns:

True if checksum needs to be calculated, false otherwise.

struct net_if *net_if_get_by_index(int index)

Get interface according to index.

This is a syscall only to provide access to the object for purposes of assigning permissions.

Parameters:

index – Interface index

Returns:

Pointer to interface or NULL if not found.

int net_if_get_by_iface(struct net_if *iface)

Get interface index according to pointer.

Parameters:

iface – Pointer to network interface

Returns:

Interface index

void net_if_foreach(net_if_cb_t cb, void *user_data)

Go through all the network interfaces and call callback for each interface.

Parameters:

cb – User-supplied callback function to call
user_data – User specified data

int net_if_up(struct net_if *iface)

Bring interface up.

Parameters:

iface – Pointer to network interface

Returns:

0 on success

static inline bool net_if_is_up(struct net_if *iface)

Check if interface is is up and running.

Parameters:

iface – Pointer to network interface

Returns:

True if interface is up, False if it is down.

int net_if_down(struct net_if *iface)

Bring interface down.

Parameters:

iface – Pointer to network interface

Returns:

0 on success

static inline bool net_if_is_admin_up(struct net_if *iface)

Check if interface was brought up by the administrator.

Parameters:

iface – Pointer to network interface

Returns:

True if interface is admin up, false otherwise.

void net_if_carrier_on(struct net_if *iface)

Underlying network device has detected the carrier (cable connected).

The function should be used by the respective network device driver or L2 implementation to update its state on a network interface.

Parameters:

iface – Pointer to network interface

void net_if_carrier_off(struct net_if *iface)

Underlying network device has lost the carrier (cable disconnected).

The function should be used by the respective network device driver or L2 implementation to update its state on a network interface.

Parameters:

iface – Pointer to network interface

static inline bool net_if_is_carrier_ok(struct net_if *iface)

Check if carrier is present on network device.

Parameters:

iface – Pointer to network interface

Returns:

True if carrier is present, false otherwise.

void net_if_dormant_on(struct net_if *iface)

Mark interface as dormant.

Dormant state indicates that the interface is not ready to pass packets yet, but is waiting for some event (for example Wi-Fi network association).

The function should be used by the respective network device driver or L2 implementation to update its state on a network interface.

Parameters:

iface – Pointer to network interface

void net_if_dormant_off(struct net_if *iface)

Mark interface as not dormant.

The function should be used by the respective network device driver or L2 implementation to update its state on a network interface.

Parameters:

iface – Pointer to network interface

static inline bool net_if_is_dormant(struct net_if *iface)

Check if the interface is dormant.

Parameters:

iface – Pointer to network interface

Returns:

True if interface is dormant, false otherwise.

static inline int net_if_set_promisc(struct net_if *iface)

Set network interface into promiscuous mode.

Note that not all network technologies will support this.

Parameters:

iface – Pointer to network interface

Returns:

0 on success, <0 if error

static inline void net_if_unset_promisc(struct net_if *iface)

Set network interface into normal mode.

Parameters:

iface – Pointer to network interface

static inline bool net_if_is_promisc(struct net_if *iface)

Check if promiscuous mode is set or not.

Parameters:

iface – Pointer to network interface

Returns:

True if interface is in promisc mode, False if interface is not in in promiscuous mode.

static inline bool net_if_are_pending_tx_packets(struct net_if *iface)

Check if there are any pending TX network data for a given network interface.

Parameters:

iface – Pointer to network interface

Returns:

True if there are pending TX network packets for this network interface, False otherwise.

bool net_if_is_wifi(struct net_if *iface)

Check if the network interface supports Wi-Fi.

Parameters:

iface – Pointer to network interface

Returns:

True if interface supports Wi-Fi, False otherwise.

struct net_if *net_if_get_first_wifi(void)

Get first Wi-Fi network interface.

Returns:: Pointer to network interface, NULL if not found.

int net_if_get_name(struct net_if *iface, char *buf, int len)

Get network interface name.

If interface name support is not enabled, empty string is returned.

Parameters:

iface – Pointer to network interface
buf – User supplied buffer
len – Length of the user supplied buffer

Returns:

Length of the interface name copied to buf, -EINVAL if invalid parameters, -ERANGE if name cannot be copied to the user supplied buffer, -ENOTSUP if interface name support is disabled,

int net_if_set_name(struct net_if *iface, const char *buf)

Set network interface name.

Normally this function is not needed to call as the system will automatically assign a name to the network interface.

Parameters:

iface – Pointer to network interface
buf – User supplied name

Returns:

0 name is set correctly -ENOTSUP interface name support is disabled -EINVAL if invalid parameters are given, -ENAMETOOLONG if name is too long

int net_if_get_by_name(const char *name)

Get interface index according to its name.

Parameters:

name – Name of the network interface

Returns:

Interface index

struct net_if_addr

#include <net_if.h>

Network Interface unicast IP addresses.

Stores the unicast IP addresses assigned to this network interface.

Public Members

struct net_addr address: IP address.

atomic_t atomic_ref

Reference counter.

This is used to prevent address removal if there are sockets that have bound the local endpoint to this address.

enum net_addr_type addr_type: How the IP address was set.

enum net_addr_state addr_state: What is the current state of the address.

uint8_t is_infinite: Is the IP address valid forever.

uint8_t is_used: Is this IP address used or not.

uint8_t is_mesh_local: Is this IP address usage limited to the subnet (mesh) or not.

uint8_t is_temporary: Is this IP address temporary and generated for example by IPv6 privacy extension (RFC 8981)

struct net_if_mcast_addr

#include <net_if.h>

Network Interface multicast IP addresses.

Stores the multicast IP addresses assigned to this network interface.

Public Members

struct net_addr address: IP address.

uint8_t is_used: Is this multicast IP address used or not.

uint8_t is_joined: Did we join to this group.

struct net_if_ipv6_prefix

#include <net_if.h>

Network Interface IPv6 prefixes.

Stores the IPV6 prefixes assigned to this network interface.

Public Members

struct net_timeout lifetime: Prefix lifetime.

struct in6_addr prefix: IPv6 prefix.

struct net_if *iface: Backpointer to network interface where this prefix is used.

uint8_t len: Prefix length.

uint8_t is_infinite: Is the IP prefix valid forever.

uint8_t is_used: Is this prefix used or not.

struct net_if_router

#include <net_if.h>

Information about routers in the system.

Stores the router information.

Public Members

sys_snode_t node: Slist lifetime timer node.

struct net_addr address: IP address.

struct net_if *iface: Network interface the router is connected to.

uint32_t life_start: Router life timer start.

uint16_t lifetime: Router lifetime.

uint8_t is_used: Is this router used or not.

uint8_t is_default: Is default router.

uint8_t is_infinite: Is the router valid forever.

struct net_if_ipv6

#include <net_if.h>

IPv6 configuration.

Public Members

struct net_if_addr unicast[NET_IF_MAX_IPV6_ADDR]: Unicast IP addresses.

struct net_if_mcast_addr mcast[NET_IF_MAX_IPV6_MADDR]: Multicast IP addresses.

struct net_if_ipv6_prefix prefix[NET_IF_MAX_IPV6_PREFIX]: Prefixes.

uint32_t base_reachable_time: Default reachable time (RFC 4861, page 52)

uint32_t reachable_time: Reachable time (RFC 4861, page 20)

uint32_t retrans_timer: Retransmit timer (RFC 4861, page 52)

uint8_t hop_limit: IPv6 hop limit.

uint8_t mcast_hop_limit: IPv6 multicast hop limit.

struct net_if_addr_ipv4

#include <net_if.h>

Network Interface unicast IPv4 address and netmask.

Stores the unicast IPv4 address and related netmask.

Public Members

struct net_if_addr ipv4: IPv4 address.

struct in_addr netmask: Netmask.

struct net_if_ipv4

#include <net_if.h>

IPv4 configuration.

Public Members

struct net_if_addr_ipv4 unicast[NET_IF_MAX_IPV4_ADDR]: Unicast IP addresses.

struct net_if_mcast_addr mcast[NET_IF_MAX_IPV4_MADDR]: Multicast IP addresses.

struct in_addr gw: Gateway.

uint8_t ttl: IPv4 time-to-live.

uint8_t mcast_ttl: IPv4 time-to-live for multicast packets.

struct net_if_ip: #include <net_if.h>

Network interface IP address configuration.

struct net_if_config: #include <net_if.h>

IP and other configuration related data for network interface.

struct net_traffic_class

#include <net_if.h>

Network traffic class.

Traffic classes are used when sending or receiving data that is classified with different priorities. So some traffic can be marked as high priority and it will be sent or received first. Each network packet that is transmitted or received goes through a fifo to a thread that will transmit it.

Public Members

struct k_fifo fifo: Fifo for handling this Tx or Rx packet.

struct k_thread handler: Traffic class handler thread.

k_thread_stack_t *stack: Stack for this handler.

struct net_if_dev

#include <net_if.h>

Network Interface Device structure.

Used to handle a network interface on top of a device driver instance. There can be many net_if_dev instance against the same device.

Such interface is mainly to be used by the link layer, but is also tight to a network context: it then makes the relation with a network context and the network device.

Because of the strong relationship between a device driver and such network interface, each net_if_dev should be instantiated by one of the network device init macros found in net_if.h.

Public Members

const struct device *dev: The actually device driver instance the net_if is related to.

const struct net_l2 *const l2: Interface’s L2 layer.

void *l2_data: Interface’s private L2 data pointer.

atomic_t flags[ATOMIC_BITMAP_SIZE(NET_IF_NUM_FLAGS)]: For internal use.

struct net_linkaddr link_addr: The hardware link address.

uint16_t mtu: The hardware MTU.

enum net_if_oper_state oper_state: RFC 2863 operational status.

struct net_if

#include <net_if.h>

Network Interface structure.

Used to handle a network interface on top of a net_if_dev instance. There can be many net_if instance against the same net_if_dev instance.

Public Members

struct net_if_dev *if_dev: The net_if_dev instance the net_if is related to.

struct net_if_config config: Network interface instance configuration.

struct k_mutex lock: Mutex protecting this network interface instance.

struct k_mutex tx_lock: Mutex used when sending data.

uint8_t pe_enabled

Network interface specific flags.

Enable IPv6 privacy extension (RFC 8981), this is enabled by default if PE support is enabled in configuration.

uint8_t pe_prefer_public: If PE is enabled, then this tells whether public addresses are preferred over temporary ones for this interface.

struct net_if_mcast_monitor

#include <net_if.h>

Multicast monitor handler struct.

Stores the multicast callback information. Caller must make sure that the variable pointed by this is valid during the lifetime of registration. Typically this means that the variable cannot be allocated from stack.

Public Members

sys_snode_t node: Node information for the slist.

struct net_if *iface: Network interface.

net_if_mcast_callback_t cb: Multicast callback.

struct net_if_link_cb

#include <net_if.h>

Link callback handler struct.

Stores the link callback information. Caller must make sure that the variable pointed by this is valid during the lifetime of registration. Typically this means that the variable cannot be allocated from stack.

Public Members

sys_snode_t node: Node information for the slist.

net_if_link_callback_t cb: Link callback.

Network Interface

Overview

Network interface state management

API Reference

Overview 

Network interface state management 

API Reference 