path: root/lib/route/link/api.c

/* SPDX-License-Identifier: LGPL-2.1-only */
/*
 * Copyright (c) 2003-2008 Thomas Graf <tgraf@suug.ch>
 */

/**
 * @ingroup link
 * @defgroup link_API Link Modules API
 * @brief API for modules implementing specific link types/semantics.
 *
 * @par 1) Registering/Unregistering a new link info type
 * @code
 * static struct rtnl_link_info_ops vlan_info_ops = {
 * 	.io_name		= "vlan",
 * 	.io_alloc		= vlan_alloc,
 * 	.io_parse		= vlan_parse,
 * 	.io_dump[NL_DUMP_BRIEF]	= vlan_dump_brief,
 * 	.io_dump[NL_DUMP_FULL]	= vlan_dump_full,
 * 	.io_free		= vlan_free,
 * };
 *
 * static void __init vlan_init(void)
 * {
 * 	rtnl_link_register_info(&vlan_info_ops);
 * }
 *
 * static void __exit vlan_exit(void)
 * {
 * 	rtnl_link_unregister_info(&vlan_info_ops);
 * }
 * @endcode
 *
 * @{
 */

#include <netlink-private/netlink.h>
#include <netlink/netlink.h>
#include <netlink/utils.h>
#include <netlink/route/link.h>
#include <netlink-private/route/link/api.h>

static NL_LIST_HEAD(info_ops);

/* lock protecting info_ops and af_ops */
static NL_RW_LOCK(info_lock);

static struct rtnl_link_info_ops *__rtnl_link_info_ops_lookup(const char *name)
{
	struct rtnl_link_info_ops *ops;

	nl_list_for_each_entry(ops, &info_ops, io_list)
		if (!strcmp(ops->io_name, name))
			return ops;

	return NULL;
}

/**
 * @name Link Info Modules
 * @{
 */

/**
 * Return operations of a specific link info type
 * @arg name		Name of link info type.
 *
 * @note The returned pointer must be given back using rtnl_link_info_ops_put()
 *
 * @return Pointer to operations or NULL if unavailable.
 */
struct rtnl_link_info_ops *rtnl_link_info_ops_lookup(const char *name)
{
	struct rtnl_link_info_ops *ops;

	nl_write_lock(&info_lock);
	if ((ops = __rtnl_link_info_ops_lookup(name)))
		ops->io_refcnt++;
	nl_write_unlock(&info_lock);

	return ops;
}

/**
 * Take reference to a set of operations.
 * @arg ops		Link info operations.
 */
void rtnl_link_info_ops_get(struct rtnl_link_info_ops *ops)
{
	if (!ops)
		return;

	nl_write_lock(&info_lock);
	ops->io_refcnt++;
	nl_write_unlock(&info_lock);
}

/**
 * Give back reference to a set of operations.
 * @arg ops		Link info operations.
 */
void rtnl_link_info_ops_put(struct rtnl_link_info_ops *ops)
{
	if (!ops)
		return;

	nl_write_lock(&info_lock);
	_nl_assert(ops->io_refcnt > 0);
	ops->io_refcnt--;
	nl_write_unlock(&info_lock);
}

/**
 * Register operations for a link info type
 * @arg ops		Link info operations
 *
 * This function must be called by modules implementing a specific link
 * info type. It will make the operations implemented by the module
 * available for everyone else.
 *
 * @return 0 on success or a negative error code.
 * @return -NLE_INVAL Link info name not specified.
 * @return -NLE_EXIST Operations for address family already registered.
 */
int rtnl_link_register_info(struct rtnl_link_info_ops *ops)
{
	int err = 0;

	if (ops->io_name == NULL)
		return -NLE_INVAL;

	nl_write_lock(&info_lock);
	if (__rtnl_link_info_ops_lookup(ops->io_name)) {
		err = -NLE_EXIST;
		goto errout;
	}

	NL_DBG(1, "Registered link info operations %s\n", ops->io_name);

	nl_list_add_tail(&ops->io_list, &info_ops);
errout:
	nl_write_unlock(&info_lock);

	return err;
}

/**
 * Unregister operations for a link info type
 * @arg ops		Link info operations
 *
 * This function must be called if a module implementing a specific link
 * info type is unloaded or becomes unavailable. It must provide a
 * set of operations which have previously been registered using
 * rtnl_link_register_info().
 *
 * @return 0 on success or a negative error code
 * @return _NLE_OPNOTSUPP Link info operations not registered.
 * @return -NLE_BUSY Link info operations still in use.
 */
int rtnl_link_unregister_info(struct rtnl_link_info_ops *ops)
{
	struct rtnl_link_info_ops *t;
	int err = -NLE_OPNOTSUPP;

	nl_write_lock(&info_lock);

	nl_list_for_each_entry(t, &info_ops, io_list) {
		if (t == ops) {
			_nl_assert(t->io_refcnt >= 0);
			if (t->io_refcnt > 0) {
				err = -NLE_BUSY;
				goto errout;
			}

			nl_list_del(&t->io_list);

			NL_DBG(1, "Unregistered link info operations %s\n",
				ops->io_name);
			err = 0;
			goto errout;
		}
	}

errout:
	nl_write_unlock(&info_lock);

	return err;
}

/** @} */

/**
 * @name Link Address Family Modules
 * @{
 */

static struct rtnl_link_af_ops *af_ops[AF_MAX];

/**
 * Return operations of a specific link address family
 * @arg family		Address family
 *
 * @note The returned pointer must be given back using rtnl_link_af_ops_put()
 *
 * @return Pointer to operations or NULL if unavailable.
 */
struct rtnl_link_af_ops *rtnl_link_af_ops_lookup(const unsigned int family)
{
	if (family == AF_UNSPEC || family >= AF_MAX)
		return NULL;

	nl_write_lock(&info_lock);
	if (af_ops[family])
		af_ops[family]->ao_refcnt++;
	nl_write_unlock(&info_lock);

	return af_ops[family];
}

/**
 * Give back reference to a set of operations.
 * @arg ops		Address family operations.
 */
void rtnl_link_af_ops_put(struct rtnl_link_af_ops *ops)
{
	if (ops) {
		nl_write_lock(&info_lock);
		ops->ao_refcnt--;
		nl_write_unlock(&info_lock);
	}
}

/**
 * Allocate and return data buffer for link address family modules
 * @arg link		Link object
 * @arg ops		Address family operations
 *
 * This function must be called by link address family modules in all
 * cases where the API does not provide the data buffer as argument
 * already. This typically includes set functions the module provides.
 * Calling this function is strictly required to ensure proper allocation
 * of the buffer upon first use. Link objects will NOT proactively
 * allocate a data buffer for each registered link address family.
 *
 * @return Pointer to data buffer or NULL on error.
 */
void *rtnl_link_af_alloc(struct rtnl_link *link,
			 const struct rtnl_link_af_ops *ops)
{
	int family;

	if (!link || !ops)
		BUG();

	family = ops->ao_family;

	if (!link->l_af_data[family]) {
		if (!ops->ao_alloc)
			BUG();
		
		link->l_af_data[family] = ops->ao_alloc(link);
		if (!link->l_af_data[family])
			return NULL;
	}

	return link->l_af_data[family];
}

/**
 * Return data buffer for link address family modules
 * @arg link		Link object
 * @arg ops		Address family operations
 *
 * This function returns a pointer to the data buffer for the specified link
 * address family module or NULL if the buffer was not allocated yet. This
 * function is typically used by get functions of modules which are not
 * interested in having the data buffer allocated if no values have been set
 * yet.
 *
 * @return Pointer to data buffer or NULL on error.
 */
void *rtnl_link_af_data(const struct rtnl_link *link,
			const struct rtnl_link_af_ops *ops)
{
	if (!link || !ops)
		BUG();

	return link->l_af_data[ops->ao_family];
}

/**
 * Register operations for a link address family
 * @arg ops		Address family operations
 *
 * This function must be called by modules implementing a specific link
 * address family. It will make the operations implemented by the module
 * available for everyone else.
 *
 * @return 0 on success or a negative error code.
 * @return -NLE_INVAL Address family is out of range (0..AF_MAX)
 * @return -NLE_EXIST Operations for address family already registered.
 */
int rtnl_link_af_register(struct rtnl_link_af_ops *ops)
{
	int err = 0;

	if (ops->ao_family == AF_UNSPEC || ops->ao_family >= AF_MAX)
		return -NLE_INVAL;

	nl_write_lock(&info_lock);
	if (af_ops[ops->ao_family]) {
		err = -NLE_EXIST;
		goto errout;
	}

	ops->ao_refcnt = 0;
	af_ops[ops->ao_family] = ops;

	NL_DBG(1, "Registered link address family operations %u\n",
		ops->ao_family);

errout:
	nl_write_unlock(&info_lock);

	return err;
}

/**
 * Unregister operations for a link address family
 * @arg ops		Address family operations
 *
 * This function must be called if a module implementing a specific link
 * address family is unloaded or becomes unavailable. It must provide a
 * set of operations which have previously been registered using
 * rtnl_link_af_register().
 *
 * @return 0 on success or a negative error code
 * @return -NLE_INVAL ops is NULL
 * @return -NLE_OBJ_NOTFOUND Address family operations not registered.
 * @return -NLE_BUSY Address family operations still in use.
 */
int rtnl_link_af_unregister(struct rtnl_link_af_ops *ops)
{
	int err = -NLE_INVAL;

	if (!ops)
		return err;

	nl_write_lock(&info_lock);
	if (!af_ops[ops->ao_family]) {
		err = -NLE_OBJ_NOTFOUND;
		goto errout;
	}

	if (ops->ao_refcnt > 0) {
		err = -NLE_BUSY;
		goto errout;
	}

	af_ops[ops->ao_family] = NULL;

	NL_DBG(1, "Unregistered link address family operations %u\n",
		ops->ao_family);

errout:
	nl_write_unlock(&info_lock);

	return err;
}

/**
 * Compare af data for a link address family
 * @arg a		Link object a
 * @arg b		Link object b
 * @arg family		af data family
 *
 * This function will compare af_data between two links
 * a and b of family given by arg family
 *
 * @return 0 if address family specific data matches or is not present
 * or != 0 if it mismatches.
 */
int rtnl_link_af_data_compare(struct rtnl_link *a, struct rtnl_link *b,
			      int family)
{
	struct rtnl_link_af_ops *af_ops;
	int ret = 0;

	if (!a->l_af_data[family] && !b->l_af_data[family])
		return 0;

	if (!a->l_af_data[family] || !b->l_af_data[family])
		return ~0;

	af_ops = rtnl_link_af_ops_lookup(family);
	if (!af_ops)
		return ~0;

	if (af_ops->ao_compare == NULL) {
		ret = ~0;
		goto out;
	}

	ret = af_ops->ao_compare(a, b, family, ~0, 0);

out:
	rtnl_link_af_ops_put(af_ops);

	return ret;
}

/**
 * Compare link info data
 * @arg a              Link object a
 * @arg b              Link object b
 *
 * This function will compare link_info data between two links
 * a and b
 *
 * @return 0 if link_info data matches or is not present
 * or != 0 if it mismatches.
 */
int rtnl_link_info_data_compare(struct rtnl_link *a, struct rtnl_link *b, int flags)
{
	if (a->l_info_ops != b->l_info_ops)
		return ~0;

	if (!a->l_info_ops || !a->l_info_ops->io_compare)
		return 0;

	return a->l_info_ops->io_compare(a, b, flags);
}

/** @} */

/** @} */