network device (interface) convenience functions More...

Files
file	netdev.c
	Example lifecycle use of the API:

Data Structures
struct	netdev_netns_ctx

struct	osmo_netdev

Macros
#define	IFINDEX_UNUSED 0

#define	LOGNETDEV(netdev, lvl, fmt, args ...)

#define	NETDEV_NETNS_ENTER(netdev, switch_state, str_prefix)

#define	NETDEV_NETNS_EXIT(netdev, switch_state, str_prefix)

Functions
static struct netdev_netns_ctx *	netdev_netns_ctx_alloc (void ctx, const char netns_name)

static void	netdev_netns_ctx_free (struct netdev_netns_ctx *netns_ctx)

static int	netdev_netns_ctx_init (struct netdev_netns_ctx *netns_ctx)

static struct netdev_netns_ctx *	netdev_netns_ctx_find_by_netns_name (const char *netns_name)

static struct netdev_netns_ctx *	netdev_netns_ctx_get (const char *netns_name)

static void	netdev_netns_ctx_put (struct netdev_netns_ctx *netns_ctx)

struct osmo_netdev *	osmo_netdev_alloc (void ctx, const char name)
	Allocate a new netdev object. More...

void	osmo_netdev_free (struct osmo_netdev *netdev)
	Free an allocated netdev object. More...

int	osmo_netdev_register (struct osmo_netdev *netdev)
	Start managing the network device referenced by the netdev object. More...

int	osmo_netdev_unregister (struct osmo_netdev *netdev)
	Unregister the netdev object (stop managing /moniutoring the interface) More...

bool	osmo_netdev_is_registered (struct osmo_netdev *netdev)
	Retrieve whether the netdev object is in "registered" state. More...

void	osmo_netdev_set_priv_data (struct osmo_netdev netdev, void priv_data)
	Set private user data pointer on the netdev object. More...

void *	osmo_netdev_get_priv_data (struct osmo_netdev *netdev)
	Get private user data pointer from the netdev object. More...

void	osmo_netdev_set_ifupdown_ind_cb (struct osmo_netdev *netdev, osmo_netdev_ifupdown_ind_cb_t ifupdown_ind_cb)
	Set data_ind_cb callback, called when a new packet is received on the network interface. More...

void	osmo_netdev_set_dev_name_chg_cb (struct osmo_netdev *netdev, osmo_netdev_dev_name_chg_cb_t dev_name_chg_cb)
	Set dev_name_chg_cb callback, called when a change in the network name is detected. More...

void	osmo_netdev_set_mtu_chg_cb (struct osmo_netdev *netdev, osmo_netdev_mtu_chg_cb_t mtu_chg_cb)
	Set mtu_chg_cb callback, called when a change in the network name is detected. More...

const char *	osmo_netdev_get_name (const struct osmo_netdev *netdev)
	Get name used to identify the netdev object. More...

int	osmo_netdev_set_ifindex (struct osmo_netdev *netdev, unsigned int ifindex)
	Set (specify) interface index identifying the network interface to manage. More...

unsigned int	osmo_netdev_get_ifindex (const struct osmo_netdev *netdev)
	Get interface index identifying the interface managed by netdev. More...

int	osmo_netdev_set_netns_name (struct osmo_netdev netdev, const char netns_name)
	Set (specify) name of the network namespace where the network interface to manage is located. More...

const char *	osmo_netdev_get_netns_name (const struct osmo_netdev *netdev)
	Get name of network namespace used when opening the netdev interface. More...

const char *	osmo_netdev_get_dev_name (const struct osmo_netdev *netdev)
	Get name used to name the network interface created by the netdev object. More...

int	osmo_netdev_ifupdown (struct osmo_netdev *netdev, bool ifupdown)
	Bring netdev interface UP or DOWN. More...

int	osmo_netdev_add_addr (struct osmo_netdev netdev, const struct osmo_sockaddr addr, uint8_t prefixlen)
	Add IP address to netdev interface. More...

int	osmo_netdev_add_route (struct osmo_netdev netdev, const struct osmo_sockaddr dst_addr, uint8_t dst_prefixlen, const struct osmo_sockaddr *gw_addr)
	Add IP route to netdev interface. More...

Variables
static struct llist_head	g_netdev_netns_ctx_list = LLIST_HEAD_INIT(g_netdev_netns_ctx_list)

static struct llist_head	g_netdev_list = LLIST_HEAD_INIT(g_netdev_list)

Detailed Description

network device (interface) convenience functions

Macro Definition Documentation

◆ IFINDEX_UNUSED

#define IFINDEX_UNUSED 0

◆ LOGNETDEV

#define LOGNETDEV	(	netdev,
		lvl,
		fmt,
		args ...
	)

Value:

        LOGP(DLGLOBAL, lvl, "NETDEV(%s,if=%s/%u,ns=%s): " fmt, \
             (netdev)->name, osmo_netdev_get_dev_name(netdev) ? : "", \
             (netdev)->ifindex, (netdev)->netns_name ? : "", ## args)

◆ NETDEV_NETNS_ENTER

#define NETDEV_NETNS_ENTER	(	netdev,
		switch_state,
		str_prefix
	)

Value:

        do { \
                if ((netdev)->netns_name) { \
                        LOGNETDEV(netdev, LOGL_DEBUG, str_prefix ": Switch to netns '%s'\n", \
                               (netdev)->netns_name); \
                        int rc2 = osmo_netns_switch_enter((netdev)->netns_ctx->netns_fd, switch_state); \
                        if (rc2 < 0) { \
                                LOGNETDEV(netdev, LOGL_ERROR, str_prefix ": Cannot switch to netns '%s': %s (%d)\n", \
                                       (netdev)->netns_name, strerror(errno), errno); \
                                return -EACCES; \
                        } \
                } \
        } while (0)

◆ NETDEV_NETNS_EXIT

#define NETDEV_NETNS_EXIT	(	netdev,
		switch_state,
		str_prefix
	)

Value:

        do { \
                if ((netdev)->netns_name) { \
                        int rc2 = osmo_netns_switch_exit(switch_state); \
                        if (rc2 < 0) { \
                                LOGNETDEV(netdev, LOGL_ERROR, str_prefix ": Cannot switch back from netns '%s': %s\n", \
                                       (netdev)->netns_name, strerror(errno)); \
                                return rc2; \
                        } \
                        LOGNETDEV(netdev, LOGL_DEBUG, str_prefix ": Back from netns '%s'\n", \
                               (netdev)->netns_name); \
                } \
        } while (0)

Function Documentation

◆ netdev_netns_ctx_alloc()

static struct netdev_netns_ctx * netdev_netns_ctx_alloc	(	void *	ctx,
		const char *	netns_name
	)

static

References netdev_netns_ctx::entry, g_netdev_netns_ctx_list, llist_add_tail(), netdev_netns_ctx::netns_fd, netdev_netns_ctx::netns_name, and OSMO_ASSERT.

Referenced by netdev_netns_ctx_get().

◆ netdev_netns_ctx_find_by_netns_name()

static struct netdev_netns_ctx * netdev_netns_ctx_find_by_netns_name ( const char * netns_name )

static

References netdev_netns_ctx::entry, g_netdev_netns_ctx_list, llist_for_each_entry, and netdev_netns_ctx::netns_name.

Referenced by netdev_netns_ctx_get().

◆ netdev_netns_ctx_free()

static void netdev_netns_ctx_free ( struct netdev_netns_ctx * netns_ctx )

static

References netdev_netns_ctx::entry, llist_del(), netdev_netns_ctx::netns_fd, and osmo_mnl_destroy().

Referenced by netdev_netns_ctx_get(), and netdev_netns_ctx_put().

◆ netdev_netns_ctx_get()

static struct netdev_netns_ctx * netdev_netns_ctx_get ( const char * netns_name )

static

References netdev_netns_ctx_alloc(), netdev_netns_ctx_find_by_netns_name(), netdev_netns_ctx_free(), netdev_netns_ctx_init(), netdev_netns_ctx::netns_name, OSMO_ASSERT, and netdev_netns_ctx::refcount.

Referenced by osmo_netdev_register().

◆ netdev_netns_ctx_init()

static int netdev_netns_ctx_init ( struct netdev_netns_ctx * netns_ctx )

static

References DLGLOBAL, LOGL_ERROR, LOGL_INFO, LOGP, netdev_netns_ctx::netns_fd, netdev_netns_ctx::netns_name, and osmo_mnl_init().

Referenced by netdev_netns_ctx_get().

◆ netdev_netns_ctx_put()

static void netdev_netns_ctx_put ( struct netdev_netns_ctx * netns_ctx )

static

References netdev_netns_ctx_free(), OSMO_ASSERT, and netdev_netns_ctx::refcount.

Referenced by osmo_netdev_register(), and osmo_netdev_unregister().

◆ osmo_netdev_add_addr()

int osmo_netdev_add_addr	(	struct osmo_netdev *	netdev,
		const struct osmo_sockaddr *	addr,
		uint8_t	prefixlen
	)

Add IP address to netdev interface.

Parameters

[in]	netdev	The netdev object managing the netdev interface
[in]	addr	The local address to set on the interface
[in]	prefixlen	The network prefix of addr

Returns: 0 on succes; negative on error.

References osmo_netdev::dev_name, ENOTSUP, osmo_netdev::ifindex, LOGL_ERROR, LOGL_NOTICE, LOGNETDEV, NETDEV_NETNS_ENTER, NETDEV_NETNS_EXIT, osmo_netdev::netns_ctx, osmo_sockaddr_ntop(), osmo_netdev::registered, osmo_sockaddr::sa, and osmo_sockaddr::u.

◆ osmo_netdev_add_route()

int osmo_netdev_add_route	(	struct osmo_netdev *	netdev,
		const struct osmo_sockaddr *	dst_addr,
		uint8_t	dst_prefixlen,
		const struct osmo_sockaddr *	gw_addr
	)

Add IP route to netdev interface.

Parameters

[in]	netdev	The netdev object managing the netdev interface
[in]	dst_addr	The destination address of the route
[in]	dst_prefixlen	The network prefix of dst_addr
[in]	gw_addr	The gateway address. Optional, can be NULL.

Returns: 0 on succes; negative on error.

References osmo_netdev::dev_name, ENOTSUP, osmo_netdev::ifindex, LOGL_ERROR, LOGL_NOTICE, LOGNETDEV, NETDEV_NETNS_ENTER, NETDEV_NETNS_EXIT, osmo_netdev::netns_ctx, osmo_sockaddr_ntop(), osmo_netdev::registered, osmo_sockaddr::sa, and osmo_sockaddr::u.

◆ osmo_netdev_alloc()

struct osmo_netdev * osmo_netdev_alloc	(	void *	ctx,
		const char *	name
	)

Allocate a new netdev object.

Parameters

[in]	ctx	talloc context to use as a parent when allocating the netdev object
[in]	name	A name providen to identify the netdev object

Returns: newly allocated netdev object on success; NULL on error

References osmo_netdev::entry, g_netdev_list, llist_add_tail(), name, and osmo_netdev::name.

Referenced by osmo_tundev_alloc().

◆ osmo_netdev_free()

void osmo_netdev_free ( struct osmo_netdev * netdev )

Free an allocated netdev object.

Parameters

[in] netdev The netdev object to free

References osmo_netdev::entry, llist_del(), osmo_netdev_is_registered(), and osmo_netdev_unregister().

Referenced by osmo_tundev_free().

◆ osmo_netdev_get_dev_name()

const char * osmo_netdev_get_dev_name ( const struct osmo_netdev * netdev )

Get name used to name the network interface created by the netdev object.

Parameters

[in] netdev The netdev object from where to retrieve the field

Returns: The interface name (or NULL if unknown)

This information is retrieved internally once the netdev object enters the "registered" state. Hence, when not registered NULL can be returned.

References osmo_netdev::dev_name.

Referenced by tundev_dev_name_chg_cb().

◆ osmo_netdev_get_ifindex()

unsigned int osmo_netdev_get_ifindex ( const struct osmo_netdev * netdev )

Get interface index identifying the interface managed by netdev.

Parameters

[in] netdev The netdev object from where to retrieve the field

Returns: The current value of the configured netdev interface ifindex to use (0 = unset)

References osmo_netdev::ifindex.

◆ osmo_netdev_get_name()

const char * osmo_netdev_get_name ( const struct osmo_netdev * netdev )

Get name used to identify the netdev object.

Parameters

[in] netdev The netdev object from where to retrieve the field

Returns: The current value of the name used to identify the netdev object

References osmo_netdev::name.

◆ osmo_netdev_get_netns_name()

const char * osmo_netdev_get_netns_name ( const struct osmo_netdev * netdev )

Get name of network namespace used when opening the netdev interface.

Parameters

[in] netdev The netdev object from where to retrieve the field

Returns: The current value of the configured network namespace

References osmo_netdev::netns_name.

◆ osmo_netdev_get_priv_data()

void * osmo_netdev_get_priv_data ( struct osmo_netdev * netdev )

Get private user data pointer from the netdev object.

Parameters

[in] netdev The netdev object from where to retrieve the field

Returns: The current value of the priv_data field.

References osmo_netdev::priv_data.

Referenced by tundev_dev_name_chg_cb(), tundev_ifupdown_ind_cb(), and tundev_mtu_chg_cb().

◆ osmo_netdev_ifupdown()

int osmo_netdev_ifupdown	(	struct osmo_netdev *	netdev,
		bool	ifupdown
	)

Bring netdev interface UP or DOWN.

Parameters

[in]	netdev	The netdev object managing the netdev interface
[in]	ifupdown	true to set the interface UP, false to set it DOWN

Returns: 0 on succes; negative on error.

References osmo_netdev::dev_name, ENOTSUP, osmo_netdev::ifindex, LOGL_ERROR, LOGL_NOTICE, LOGNETDEV, NETDEV_NETNS_ENTER, NETDEV_NETNS_EXIT, osmo_netdev::netns_ctx, and osmo_netdev::registered.

◆ osmo_netdev_is_registered()

bool osmo_netdev_is_registered ( struct osmo_netdev * netdev )

Retrieve whether the netdev object is in "registered" state.

Parameters

[in] netdev The netdev object to check

Returns: true if in state "registered"; false otherwise

References osmo_netdev::registered.

Referenced by osmo_netdev_free().

◆ osmo_netdev_register()

int osmo_netdev_register ( struct osmo_netdev * netdev )

Start managing the network device referenced by the netdev object.

Parameters

[in] netdev The netdev object to open

Returns: 0 on success; negative on error

References osmo_netdev::dev_name, osmo_netdev::ifindex, netdev_netns_ctx_get(), netdev_netns_ctx_put(), NETDEV_NETNS_ENTER, NETDEV_NETNS_EXIT, osmo_netdev::netns_ctx, osmo_netdev::netns_name, osmo_talloc_replace_string(), and osmo_netdev::registered.

Referenced by osmo_tundev_open().

◆ osmo_netdev_set_dev_name_chg_cb()

void osmo_netdev_set_dev_name_chg_cb	(	struct osmo_netdev *	netdev,
		osmo_netdev_dev_name_chg_cb_t	dev_name_chg_cb
	)

Set dev_name_chg_cb callback, called when a change in the network name is detected.

Parameters

[in]	netdev	The netdev object where the field is set
[in]	dev_name_chg_cb	the user provided function to be called when a the interface is renamed

References osmo_netdev::dev_name_chg_cb.

Referenced by osmo_tundev_alloc().

◆ osmo_netdev_set_ifindex()

int osmo_netdev_set_ifindex	(	struct osmo_netdev *	netdev,
		unsigned int	ifindex
	)

Set (specify) interface index identifying the network interface to manage.

Parameters

[in]	netdev	The netdev object where the field is set
[in]	ifindex	The interface index identifying the interface

Returns: 0 on success; negative on error

The ifindex, together with the netns_name (see osmo_netdev_netns_name_set()), form together the key identifiers of a network interface to manage. This field is used during osmo_netdev_register() time, and hence must be set before calling that API, and cannot be changed when the netdev object is in "registered" state.

References osmo_netdev::ifindex, and osmo_netdev::registered.

Referenced by osmo_tundev_open().

◆ osmo_netdev_set_ifupdown_ind_cb()

void osmo_netdev_set_ifupdown_ind_cb	(	struct osmo_netdev *	netdev,
		osmo_netdev_ifupdown_ind_cb_t	ifupdown_ind_cb
	)

Set data_ind_cb callback, called when a new packet is received on the network interface.

Parameters

[in]	netdev	The netdev object where the field is set
[in]	data_ind_cb	the user provided function to be called when the link status (UP/DOWN) changes

References osmo_netdev::ifupdown_ind_cb.

Referenced by osmo_tundev_alloc().

◆ osmo_netdev_set_mtu_chg_cb()

void osmo_netdev_set_mtu_chg_cb	(	struct osmo_netdev *	netdev,
		osmo_netdev_mtu_chg_cb_t	mtu_chg_cb
	)

Set mtu_chg_cb callback, called when a change in the network name is detected.

Parameters

[in]	netdev	The netdev object where the field is set
[in]	mtu_chg_cb	the user provided function to be called when the configured MTU at the interface changes

References osmo_netdev::mtu_chg_cb.

Referenced by osmo_tundev_alloc().

◆ osmo_netdev_set_netns_name()

int osmo_netdev_set_netns_name	(	struct osmo_netdev *	netdev,
		const char *	netns_name
	)

Set (specify) name of the network namespace where the network interface to manage is located.

Parameters

[in]	netdev	The netdev object where the field is set
[in]	netns_name	The network namespace where the network interface is located

Returns: 0 on success; negative on error

The netns_name, together with the ifindex (see osmo_netdev_ifindex_set()), form together the key identifiers of a network interface to manage. This field is used during osmo_netdev_register() time, and hence must be set before calling that API, and cannot be changed when the netdev object is in "registered" state. If left as NULL (default), the management will be done in the current network namespace.

References osmo_netdev::netns_name, osmo_talloc_replace_string(), and osmo_netdev::registered.

Referenced by osmo_tundev_open().

◆ osmo_netdev_set_priv_data()

void osmo_netdev_set_priv_data	(	struct osmo_netdev *	netdev,
		void *	priv_data
	)

Set private user data pointer on the netdev object.

Parameters

[in] netdev The netdev object where the field is set

References osmo_netdev::priv_data.

Referenced by osmo_tundev_alloc().

◆ osmo_netdev_unregister()

int osmo_netdev_unregister ( struct osmo_netdev * netdev )

Unregister the netdev object (stop managing /moniutoring the interface)

Parameters

[in] netdev The netdev object to close

Returns: 0 on success; negative on error

References osmo_netdev::if_mtu_known, osmo_netdev::if_up_known, netdev_netns_ctx_put(), osmo_netdev::netns_ctx, and osmo_netdev::registered.

Referenced by osmo_netdev_free(), osmo_tundev_close(), and osmo_tundev_open().

Variable Documentation

◆ g_netdev_list

struct llist_head g_netdev_list = LLIST_HEAD_INIT(g_netdev_list)

static

Referenced by osmo_netdev_alloc().

◆ g_netdev_netns_ctx_list

struct llist_head g_netdev_netns_ctx_list = LLIST_HEAD_INIT(g_netdev_netns_ctx_list)

static

Referenced by netdev_netns_ctx_alloc(), and netdev_netns_ctx_find_by_netns_name().

Files

Data Structures

Macros

Functions

Variables

Detailed Description

Macro Definition Documentation

◆ IFINDEX_UNUSED

◆ LOGNETDEV

◆ NETDEV_NETNS_ENTER

◆ NETDEV_NETNS_EXIT

Function Documentation

◆ netdev_netns_ctx_alloc()

◆ netdev_netns_ctx_find_by_netns_name()

◆ netdev_netns_ctx_free()

◆ netdev_netns_ctx_get()

◆ netdev_netns_ctx_init()

◆ netdev_netns_ctx_put()

◆ osmo_netdev_add_addr()

◆ osmo_netdev_add_route()

◆ osmo_netdev_alloc()

◆ osmo_netdev_free()

◆ osmo_netdev_get_dev_name()

◆ osmo_netdev_get_ifindex()

◆ osmo_netdev_get_name()

◆ osmo_netdev_get_netns_name()

◆ osmo_netdev_get_priv_data()

◆ osmo_netdev_ifupdown()

◆ osmo_netdev_is_registered()

◆ osmo_netdev_register()

◆ osmo_netdev_set_dev_name_chg_cb()

◆ osmo_netdev_set_ifindex()

◆ osmo_netdev_set_ifupdown_ind_cb()

◆ osmo_netdev_set_mtu_chg_cb()

◆ osmo_netdev_set_netns_name()

◆ osmo_netdev_set_priv_data()

◆ osmo_netdev_unregister()

Variable Documentation

◆ g_netdev_list

◆ g_netdev_netns_ctx_list