summaryrefslogtreecommitdiffstats
path: root/lib/northbound.h
diff options
context:
space:
mode:
Diffstat (limited to 'lib/northbound.h')
-rw-r--r--lib/northbound.h1316
1 files changed, 1316 insertions, 0 deletions
diff --git a/lib/northbound.h b/lib/northbound.h
new file mode 100644
index 0000000..a330bd1
--- /dev/null
+++ b/lib/northbound.h
@@ -0,0 +1,1316 @@
+/*
+ * Copyright (C) 2018 NetDEF, Inc.
+ * Renato Westphal
+ *
+ * This program is free software; you can redistribute it and/or modify it
+ * under the terms of the GNU General Public License as published by the Free
+ * Software Foundation; either version 2 of the License, or (at your option)
+ * any later version.
+ *
+ * This program is distributed in the hope that it will be useful, but WITHOUT
+ * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+ * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for
+ * more details.
+ *
+ * You should have received a copy of the GNU General Public License along
+ * with this program; see the file COPYING; if not, write to the Free Software
+ * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA
+ */
+
+#ifndef _FRR_NORTHBOUND_H_
+#define _FRR_NORTHBOUND_H_
+
+#include "thread.h"
+#include "hook.h"
+#include "linklist.h"
+#include "openbsd-tree.h"
+#include "yang.h"
+#include "yang_translator.h"
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/* Forward declaration(s). */
+struct vty;
+struct debug;
+
+/* Northbound events. */
+enum nb_event {
+ /*
+ * The configuration callback is supposed to verify that the changes are
+ * valid and can be applied.
+ */
+ NB_EV_VALIDATE,
+
+ /*
+ * The configuration callback is supposed to prepare all resources
+ * required to apply the changes.
+ */
+ NB_EV_PREPARE,
+
+ /*
+ * Transaction has failed, the configuration callback needs to release
+ * all resources previously allocated.
+ */
+ NB_EV_ABORT,
+
+ /*
+ * The configuration changes need to be applied. The changes can't be
+ * rejected at this point (errors are logged and ignored).
+ */
+ NB_EV_APPLY,
+};
+
+/*
+ * Northbound operations.
+ *
+ * Refer to the documentation comments of nb_callbacks for more details.
+ */
+enum nb_operation {
+ NB_OP_CREATE,
+ NB_OP_MODIFY,
+ NB_OP_DESTROY,
+ NB_OP_MOVE,
+ NB_OP_PRE_VALIDATE,
+ NB_OP_APPLY_FINISH,
+ NB_OP_GET_ELEM,
+ NB_OP_GET_NEXT,
+ NB_OP_GET_KEYS,
+ NB_OP_LOOKUP_ENTRY,
+ NB_OP_RPC,
+};
+
+union nb_resource {
+ int fd;
+ void *ptr;
+};
+
+/*
+ * Northbound callbacks parameters.
+ */
+
+struct nb_cb_create_args {
+ /* Context of the configuration transaction. */
+ struct nb_context *context;
+
+ /*
+ * The transaction phase. Refer to the documentation comments of
+ * nb_event for more details.
+ */
+ enum nb_event event;
+
+ /* libyang data node that is being created. */
+ const struct lyd_node *dnode;
+
+ /*
+ * Pointer to store resource(s) allocated during the NB_EV_PREPARE
+ * phase. The same pointer can be used during the NB_EV_ABORT and
+ * NB_EV_APPLY phases to either release or make use of the allocated
+ * resource(s). It's set to NULL when the event is NB_EV_VALIDATE.
+ */
+ union nb_resource *resource;
+
+ /* Buffer to store human-readable error message in case of error. */
+ char *errmsg;
+
+ /* Size of errmsg. */
+ size_t errmsg_len;
+};
+
+struct nb_cb_modify_args {
+ /* Context of the configuration transaction. */
+ struct nb_context *context;
+
+ /*
+ * The transaction phase. Refer to the documentation comments of
+ * nb_event for more details.
+ */
+ enum nb_event event;
+
+ /* libyang data node that is being modified. */
+ const struct lyd_node *dnode;
+
+ /*
+ * Pointer to store resource(s) allocated during the NB_EV_PREPARE
+ * phase. The same pointer can be used during the NB_EV_ABORT and
+ * NB_EV_APPLY phases to either release or make use of the allocated
+ * resource(s). It's set to NULL when the event is NB_EV_VALIDATE.
+ */
+ union nb_resource *resource;
+
+ /* Buffer to store human-readable error message in case of error. */
+ char *errmsg;
+
+ /* Size of errmsg. */
+ size_t errmsg_len;
+};
+
+struct nb_cb_destroy_args {
+ /* Context of the configuration transaction. */
+ struct nb_context *context;
+
+ /*
+ * The transaction phase. Refer to the documentation comments of
+ * nb_event for more details.
+ */
+ enum nb_event event;
+
+ /* libyang data node that is being deleted. */
+ const struct lyd_node *dnode;
+
+ /* Buffer to store human-readable error message in case of error. */
+ char *errmsg;
+
+ /* Size of errmsg. */
+ size_t errmsg_len;
+};
+
+struct nb_cb_move_args {
+ /* Context of the configuration transaction. */
+ struct nb_context *context;
+
+ /*
+ * The transaction phase. Refer to the documentation comments of
+ * nb_event for more details.
+ */
+ enum nb_event event;
+
+ /* libyang data node that is being moved. */
+ const struct lyd_node *dnode;
+
+ /* Buffer to store human-readable error message in case of error. */
+ char *errmsg;
+
+ /* Size of errmsg. */
+ size_t errmsg_len;
+};
+
+struct nb_cb_pre_validate_args {
+ /* Context of the configuration transaction. */
+ struct nb_context *context;
+
+ /* libyang data node associated with the 'pre_validate' callback. */
+ const struct lyd_node *dnode;
+
+ /* Buffer to store human-readable error message in case of error. */
+ char *errmsg;
+
+ /* Size of errmsg. */
+ size_t errmsg_len;
+};
+
+struct nb_cb_apply_finish_args {
+ /* Context of the configuration transaction. */
+ struct nb_context *context;
+
+ /* libyang data node associated with the 'apply_finish' callback. */
+ const struct lyd_node *dnode;
+
+ /* Buffer to store human-readable error message in case of error. */
+ char *errmsg;
+
+ /* Size of errmsg. */
+ size_t errmsg_len;
+};
+
+struct nb_cb_get_elem_args {
+ /* YANG data path of the data we want to get. */
+ const char *xpath;
+
+ /* Pointer to list entry (might be NULL). */
+ const void *list_entry;
+};
+
+struct nb_cb_get_next_args {
+ /* Pointer to parent list entry. */
+ const void *parent_list_entry;
+
+ /* Pointer to (leaf-)list entry. */
+ const void *list_entry;
+};
+
+struct nb_cb_get_keys_args {
+ /* Pointer to list entry. */
+ const void *list_entry;
+
+ /*
+ * Structure to be filled based on the attributes of the provided list
+ * entry.
+ */
+ struct yang_list_keys *keys;
+};
+
+struct nb_cb_lookup_entry_args {
+ /* Pointer to parent list entry. */
+ const void *parent_list_entry;
+
+ /* Structure containing the keys of the list entry. */
+ const struct yang_list_keys *keys;
+};
+
+struct nb_cb_rpc_args {
+ /* XPath of the YANG RPC or action. */
+ const char *xpath;
+
+ /* Read-only list of input parameters. */
+ const struct list *input;
+
+ /* List of output parameters to be populated by the callback. */
+ struct list *output;
+
+ /* Buffer to store human-readable error message in case of error. */
+ char *errmsg;
+
+ /* Size of errmsg. */
+ size_t errmsg_len;
+};
+
+/*
+ * Set of configuration callbacks that can be associated to a northbound node.
+ */
+struct nb_callbacks {
+ /*
+ * Configuration callback.
+ *
+ * A presence container, list entry, leaf-list entry or leaf of type
+ * empty has been created.
+ *
+ * For presence-containers and list entries, the callback is supposed to
+ * initialize the default values of its children (if any) from the YANG
+ * models.
+ *
+ * args
+ * Refer to the documentation comments of nb_cb_create_args for
+ * details.
+ *
+ * Returns:
+ * - NB_OK on success.
+ * - NB_ERR_VALIDATION when a validation error occurred.
+ * - NB_ERR_RESOURCE when the callback failed to allocate a resource.
+ * - NB_ERR_INCONSISTENCY when an inconsistency was detected.
+ * - NB_ERR for other errors.
+ */
+ int (*create)(struct nb_cb_create_args *args);
+
+ /*
+ * Configuration callback.
+ *
+ * The value of a leaf has been modified.
+ *
+ * List keys don't need to implement this callback. When a list key is
+ * modified, the northbound treats this as if the list was deleted and a
+ * new one created with the updated key value.
+ *
+ * args
+ * Refer to the documentation comments of nb_cb_modify_args for
+ * details.
+ *
+ * Returns:
+ * - NB_OK on success.
+ * - NB_ERR_VALIDATION when a validation error occurred.
+ * - NB_ERR_RESOURCE when the callback failed to allocate a resource.
+ * - NB_ERR_INCONSISTENCY when an inconsistency was detected.
+ * - NB_ERR for other errors.
+ */
+ int (*modify)(struct nb_cb_modify_args *args);
+
+ /*
+ * Configuration callback.
+ *
+ * A presence container, list entry, leaf-list entry or optional leaf
+ * has been deleted.
+ *
+ * The callback is supposed to delete the entire configuration object,
+ * including its children when they exist.
+ *
+ * args
+ * Refer to the documentation comments of nb_cb_destroy_args for
+ * details.
+ *
+ * Returns:
+ * - NB_OK on success.
+ * - NB_ERR_VALIDATION when a validation error occurred.
+ * - NB_ERR_INCONSISTENCY when an inconsistency was detected.
+ * - NB_ERR for other errors.
+ */
+ int (*destroy)(struct nb_cb_destroy_args *args);
+
+ /*
+ * Configuration callback.
+ *
+ * A list entry or leaf-list entry has been moved. Only applicable when
+ * the "ordered-by user" statement is present.
+ *
+ * args
+ * Refer to the documentation comments of nb_cb_move_args for
+ * details.
+ *
+ * Returns:
+ * - NB_OK on success.
+ * - NB_ERR_VALIDATION when a validation error occurred.
+ * - NB_ERR_INCONSISTENCY when an inconsistency was detected.
+ * - NB_ERR for other errors.
+ */
+ int (*move)(struct nb_cb_move_args *args);
+
+ /*
+ * Optional configuration callback.
+ *
+ * This callback can be used to validate subsections of the
+ * configuration being committed before validating the configuration
+ * changes themselves. It's useful to perform more complex validations
+ * that depend on the relationship between multiple nodes.
+ *
+ * args
+ * Refer to the documentation comments of nb_cb_pre_validate_args for
+ * details.
+ *
+ * Returns:
+ * - NB_OK on success.
+ * - NB_ERR_VALIDATION when a validation error occurred.
+ */
+ int (*pre_validate)(struct nb_cb_pre_validate_args *args);
+
+ /*
+ * Optional configuration callback.
+ *
+ * The 'apply_finish' callbacks are called after all other callbacks
+ * during the apply phase (NB_EV_APPLY). These callbacks are called only
+ * under one of the following two cases:
+ * - The data node has been created or modified (but not deleted);
+ * - Any change was made within the descendants of the data node (e.g. a
+ * child leaf was modified, created or deleted).
+ *
+ * In the second case above, the 'apply_finish' callback is called only
+ * once even if multiple changes occurred within the descendants of the
+ * data node.
+ *
+ * args
+ * Refer to the documentation comments of nb_cb_apply_finish_args for
+ * details.
+ */
+ void (*apply_finish)(struct nb_cb_apply_finish_args *args);
+
+ /*
+ * Operational data callback.
+ *
+ * The callback function should return the value of a specific leaf,
+ * leaf-list entry or inform if a typeless value (presence containers or
+ * leafs of type empty) exists or not.
+ *
+ * args
+ * Refer to the documentation comments of nb_cb_get_elem_args for
+ * details.
+ *
+ * Returns:
+ * Pointer to newly created yang_data structure, or NULL to indicate
+ * the absence of data.
+ */
+ struct yang_data *(*get_elem)(struct nb_cb_get_elem_args *args);
+
+ /*
+ * Operational data callback for YANG lists and leaf-lists.
+ *
+ * The callback function should return the next entry in the list or
+ * leaf-list. The 'list_entry' parameter will be NULL on the first
+ * invocation.
+ *
+ * args
+ * Refer to the documentation comments of nb_cb_get_next_args for
+ * details.
+ *
+ * Returns:
+ * Pointer to the next entry in the (leaf-)list, or NULL to signal
+ * that the end of the (leaf-)list was reached.
+ */
+ const void *(*get_next)(struct nb_cb_get_next_args *args);
+
+ /*
+ * Operational data callback for YANG lists.
+ *
+ * The callback function should fill the 'keys' parameter based on the
+ * given list_entry. Keyless lists don't need to implement this
+ * callback.
+ *
+ * args
+ * Refer to the documentation comments of nb_cb_get_keys_args for
+ * details.
+ *
+ * Returns:
+ * NB_OK on success, NB_ERR otherwise.
+ */
+ int (*get_keys)(struct nb_cb_get_keys_args *args);
+
+ /*
+ * Operational data callback for YANG lists.
+ *
+ * The callback function should return a list entry based on the list
+ * keys given as a parameter. Keyless lists don't need to implement this
+ * callback.
+ *
+ * args
+ * Refer to the documentation comments of nb_cb_lookup_entry_args for
+ * details.
+ *
+ * Returns:
+ * Pointer to the list entry if found, or NULL if not found.
+ */
+ const void *(*lookup_entry)(struct nb_cb_lookup_entry_args *args);
+
+ /*
+ * RPC and action callback.
+ *
+ * Both 'input' and 'output' are lists of 'yang_data' structures. The
+ * callback should fetch all the input parameters from the 'input' list,
+ * and add output parameters to the 'output' list if necessary.
+ *
+ * args
+ * Refer to the documentation comments of nb_cb_rpc_args for details.
+ *
+ * Returns:
+ * NB_OK on success, NB_ERR otherwise.
+ */
+ int (*rpc)(struct nb_cb_rpc_args *args);
+
+ /*
+ * Optional callback to compare the data nodes when printing
+ * the CLI commands associated with them.
+ *
+ * dnode1
+ * The first data node to compare.
+ *
+ * dnode2
+ * The second data node to compare.
+ *
+ * Returns:
+ * <0 when the CLI command for the dnode1 should be printed first
+ * >0 when the CLI command for the dnode2 should be printed first
+ * 0 when there is no difference
+ */
+ int (*cli_cmp)(const struct lyd_node *dnode1,
+ const struct lyd_node *dnode2);
+
+ /*
+ * Optional callback to show the CLI command associated to the given
+ * YANG data node.
+ *
+ * vty
+ * The vty terminal to dump the configuration to.
+ *
+ * dnode
+ * libyang data node that should be shown in the form of a CLI
+ * command.
+ *
+ * show_defaults
+ * Specify whether to display default configuration values or not.
+ * This parameter can be ignored most of the time since the
+ * northbound doesn't call this callback for default leaves or
+ * non-presence containers that contain only default child nodes.
+ * The exception are commands associated to multiple configuration
+ * nodes, in which case it might be desirable to hide one or more
+ * parts of the command when this parameter is set to false.
+ */
+ void (*cli_show)(struct vty *vty, const struct lyd_node *dnode,
+ bool show_defaults);
+
+ /*
+ * Optional callback to show the CLI node end for lists or containers.
+ *
+ * vty
+ * The vty terminal to dump the configuration to.
+ *
+ * dnode
+ * libyang data node that should be shown in the form of a CLI
+ * command.
+ */
+ void (*cli_show_end)(struct vty *vty, const struct lyd_node *dnode);
+};
+
+struct nb_dependency_callbacks {
+ void (*get_dependant_xpath)(const struct lyd_node *dnode, char *xpath);
+ void (*get_dependency_xpath)(const struct lyd_node *dnode, char *xpath);
+};
+
+/*
+ * Northbound-specific data that is allocated for each schema node of the native
+ * YANG modules.
+ */
+struct nb_node {
+ /* Back pointer to the libyang schema node. */
+ const struct lysc_node *snode;
+
+ /* Data path of this YANG node. */
+ char xpath[XPATH_MAXLEN];
+
+ /* Priority - lower priorities are processed first. */
+ uint32_t priority;
+
+ struct nb_dependency_callbacks dep_cbs;
+
+ /* Callbacks implemented for this node. */
+ struct nb_callbacks cbs;
+
+ /*
+ * Pointer to the parent node (disconsidering non-presence containers).
+ */
+ struct nb_node *parent;
+
+ /* Pointer to the nearest parent list, if any. */
+ struct nb_node *parent_list;
+
+ /* Flags. */
+ uint8_t flags;
+
+#ifdef HAVE_CONFD
+ /* ConfD hash value corresponding to this YANG path. */
+ int confd_hash;
+#endif
+};
+/* The YANG container or list contains only config data. */
+#define F_NB_NODE_CONFIG_ONLY 0x01
+/* The YANG list doesn't contain key leafs. */
+#define F_NB_NODE_KEYLESS_LIST 0x02
+
+/*
+ * HACK: old gcc versions (< 5.x) have a bug that prevents C99 flexible arrays
+ * from working properly on shared libraries. For those compilers, use a fixed
+ * size array to work around the problem.
+ */
+#define YANG_MODULE_MAX_NODES 2000
+
+struct frr_yang_module_info {
+ /* YANG module name. */
+ const char *name;
+
+ /* Northbound callbacks. */
+ const struct {
+ /* Data path of this YANG node. */
+ const char *xpath;
+
+ /* Callbacks implemented for this node. */
+ struct nb_callbacks cbs;
+
+ /* Priority - lower priorities are processed first. */
+ uint32_t priority;
+#if defined(__GNUC__) && ((__GNUC__ - 0) < 5) && !defined(__clang__)
+ } nodes[YANG_MODULE_MAX_NODES + 1];
+#else
+ } nodes[];
+#endif
+};
+
+/* Northbound error codes. */
+enum nb_error {
+ NB_OK = 0,
+ NB_ERR,
+ NB_ERR_NO_CHANGES,
+ NB_ERR_NOT_FOUND,
+ NB_ERR_LOCKED,
+ NB_ERR_VALIDATION,
+ NB_ERR_RESOURCE,
+ NB_ERR_INCONSISTENCY,
+};
+
+/* Default priority. */
+#define NB_DFLT_PRIORITY (UINT32_MAX / 2)
+
+/* Default maximum of configuration rollbacks to store. */
+#define NB_DLFT_MAX_CONFIG_ROLLBACKS 20
+
+/* Northbound clients. */
+enum nb_client {
+ NB_CLIENT_NONE = 0,
+ NB_CLIENT_CLI,
+ NB_CLIENT_CONFD,
+ NB_CLIENT_SYSREPO,
+ NB_CLIENT_GRPC,
+ NB_CLIENT_PCEP,
+};
+
+/* Northbound context. */
+struct nb_context {
+ /* Northbound client. */
+ enum nb_client client;
+
+ /* Northbound user (can be NULL). */
+ const void *user;
+
+ /* Client-specific data. */
+#if 0
+ union {
+ struct {
+ } cli;
+ struct {
+ } confd;
+ struct {
+ } sysrepo;
+ struct {
+ } grpc;
+ struct {
+ } pcep;
+ } client_data;
+#endif
+};
+
+/* Northbound configuration. */
+struct nb_config {
+ struct lyd_node *dnode;
+ uint32_t version;
+};
+
+/* Northbound configuration callback. */
+struct nb_config_cb {
+ RB_ENTRY(nb_config_cb) entry;
+ enum nb_operation operation;
+ uint32_t seq;
+ const struct nb_node *nb_node;
+ const struct lyd_node *dnode;
+};
+RB_HEAD(nb_config_cbs, nb_config_cb);
+RB_PROTOTYPE(nb_config_cbs, nb_config_cb, entry, nb_config_cb_compare);
+
+/* Northbound configuration change. */
+struct nb_config_change {
+ struct nb_config_cb cb;
+ union nb_resource resource;
+ bool prepare_ok;
+};
+
+/* Northbound configuration transaction. */
+struct nb_transaction {
+ struct nb_context *context;
+ char comment[80];
+ struct nb_config *config;
+ struct nb_config_cbs changes;
+};
+
+/* Callback function used by nb_oper_data_iterate(). */
+typedef int (*nb_oper_data_cb)(const struct lysc_node *snode,
+ struct yang_translator *translator,
+ struct yang_data *data, void *arg);
+
+/* Iterate over direct child nodes only. */
+#define NB_OPER_DATA_ITER_NORECURSE 0x0001
+
+/* Hooks. */
+DECLARE_HOOK(nb_notification_send, (const char *xpath, struct list *arguments),
+ (xpath, arguments));
+DECLARE_HOOK(nb_client_debug_config_write, (struct vty *vty), (vty));
+DECLARE_HOOK(nb_client_debug_set_all, (uint32_t flags, bool set), (flags, set));
+
+/* Northbound debugging records */
+extern struct debug nb_dbg_cbs_config;
+extern struct debug nb_dbg_cbs_state;
+extern struct debug nb_dbg_cbs_rpc;
+extern struct debug nb_dbg_notif;
+extern struct debug nb_dbg_events;
+extern struct debug nb_dbg_libyang;
+
+/* Global running configuration. */
+extern struct nb_config *running_config;
+
+/* Wrappers for the northbound callbacks. */
+extern struct yang_data *nb_callback_get_elem(const struct nb_node *nb_node,
+ const char *xpath,
+ const void *list_entry);
+extern const void *nb_callback_get_next(const struct nb_node *nb_node,
+ const void *parent_list_entry,
+ const void *list_entry);
+extern int nb_callback_get_keys(const struct nb_node *nb_node,
+ const void *list_entry,
+ struct yang_list_keys *keys);
+extern const void *nb_callback_lookup_entry(const struct nb_node *nb_node,
+ const void *parent_list_entry,
+ const struct yang_list_keys *keys);
+extern int nb_callback_rpc(const struct nb_node *nb_node, const char *xpath,
+ const struct list *input, struct list *output,
+ char *errmsg, size_t errmsg_len);
+
+/*
+ * Create a northbound node for all YANG schema nodes.
+ */
+void nb_nodes_create(void);
+
+/*
+ * Delete all northbound nodes from all YANG schema nodes.
+ */
+void nb_nodes_delete(void);
+
+/*
+ * Find the northbound node corresponding to a YANG data path.
+ *
+ * xpath
+ * XPath to search for (with or without predicates).
+ *
+ * Returns:
+ * Pointer to northbound node if found, NULL otherwise.
+ */
+extern struct nb_node *nb_node_find(const char *xpath);
+
+extern void nb_node_set_dependency_cbs(const char *dependency_xpath,
+ const char *dependant_xpath,
+ struct nb_dependency_callbacks *cbs);
+
+bool nb_node_has_dependency(struct nb_node *node);
+
+/*
+ * Create a new northbound configuration.
+ *
+ * dnode
+ * Pointer to a libyang data node containing the configuration data. If NULL
+ * is given, an empty configuration will be created.
+ *
+ * Returns:
+ * Pointer to newly created northbound configuration.
+ */
+extern struct nb_config *nb_config_new(struct lyd_node *dnode);
+
+/*
+ * Delete a northbound configuration.
+ *
+ * config
+ * Pointer to the config that is going to be deleted.
+ */
+extern void nb_config_free(struct nb_config *config);
+
+/*
+ * Duplicate a northbound configuration.
+ *
+ * config
+ * Northbound configuration to duplicate.
+ *
+ * Returns:
+ * Pointer to duplicated configuration.
+ */
+extern struct nb_config *nb_config_dup(const struct nb_config *config);
+
+/*
+ * Merge one configuration into another.
+ *
+ * config_dst
+ * Configuration to merge to.
+ *
+ * config_src
+ * Configuration to merge config_dst with.
+ *
+ * preserve_source
+ * Specify whether config_src should be deleted or not after the merge
+ * operation.
+ *
+ * Returns:
+ * NB_OK on success, NB_ERR otherwise.
+ */
+extern int nb_config_merge(struct nb_config *config_dst,
+ struct nb_config *config_src, bool preserve_source);
+
+/*
+ * Replace one configuration by another.
+ *
+ * config_dst
+ * Configuration to be replaced.
+ *
+ * config_src
+ * Configuration to replace config_dst.
+ *
+ * preserve_source
+ * Specify whether config_src should be deleted or not after the replace
+ * operation.
+ */
+extern void nb_config_replace(struct nb_config *config_dst,
+ struct nb_config *config_src,
+ bool preserve_source);
+
+/*
+ * Edit a candidate configuration.
+ *
+ * candidate
+ * Candidate configuration to edit.
+ *
+ * nb_node
+ * Northbound node associated to the configuration being edited.
+ *
+ * operation
+ * Operation to apply.
+ *
+ * xpath
+ * XPath of the configuration node being edited.
+ *
+ * previous
+ * Previous value of the configuration node. Should be used only when the
+ * operation is NB_OP_MOVE, otherwise this parameter is ignored.
+ *
+ * data
+ * New value of the configuration node.
+ *
+ * Returns:
+ * - NB_OK on success.
+ * - NB_ERR_NOT_FOUND when the element to be deleted was not found.
+ * - NB_ERR for other errors.
+ */
+extern int nb_candidate_edit(struct nb_config *candidate,
+ const struct nb_node *nb_node,
+ enum nb_operation operation, const char *xpath,
+ const struct yang_data *previous,
+ const struct yang_data *data);
+
+/*
+ * Check if a candidate configuration is outdated and needs to be updated.
+ *
+ * candidate
+ * Candidate configuration to check.
+ *
+ * Returns:
+ * true if the candidate is outdated, false otherwise.
+ */
+extern bool nb_candidate_needs_update(const struct nb_config *candidate);
+
+/*
+ * Update a candidate configuration by rebasing the changes on top of the latest
+ * running configuration. Resolve conflicts automatically by giving preference
+ * to the changes done in the candidate configuration.
+ *
+ * candidate
+ * Candidate configuration to update.
+ *
+ * Returns:
+ * NB_OK on success, NB_ERR otherwise.
+ */
+extern int nb_candidate_update(struct nb_config *candidate);
+
+/*
+ * Validate a candidate configuration. Perform both YANG syntactic/semantic
+ * validation and code-level validation using the northbound callbacks.
+ *
+ * WARNING: the candidate can be modified as part of the validation process
+ * (e.g. add default nodes).
+ *
+ * context
+ * Context of the northbound transaction.
+ *
+ * candidate
+ * Candidate configuration to validate.
+ *
+ * errmsg
+ * Buffer to store human-readable error message in case of error.
+ *
+ * errmsg_len
+ * Size of errmsg.
+ *
+ * Returns:
+ * NB_OK on success, NB_ERR_VALIDATION otherwise.
+ */
+extern int nb_candidate_validate(struct nb_context *context,
+ struct nb_config *candidate, char *errmsg,
+ size_t errmsg_len);
+
+/*
+ * Create a new configuration transaction but do not commit it yet. Only
+ * validate the candidate and prepare all resources required to apply the
+ * configuration changes.
+ *
+ * context
+ * Context of the northbound transaction.
+ *
+ * candidate
+ * Candidate configuration to commit.
+ *
+ * comment
+ * Optional comment describing the commit.
+ *
+ * transaction
+ * Output parameter providing the created transaction when one is created
+ * successfully. In this case, it must be either aborted using
+ * nb_candidate_commit_abort() or committed using
+ * nb_candidate_commit_apply().
+ *
+ * errmsg
+ * Buffer to store human-readable error message in case of error.
+ *
+ * errmsg_len
+ * Size of errmsg.
+ *
+ * Returns:
+ * - NB_OK on success.
+ * - NB_ERR_NO_CHANGES when the candidate is identical to the running
+ * configuration.
+ * - NB_ERR_LOCKED when there's already another transaction in progress.
+ * - NB_ERR_VALIDATION when the candidate fails the validation checks.
+ * - NB_ERR_RESOURCE when the system fails to allocate resources to apply
+ * the candidate configuration.
+ * - NB_ERR for other errors.
+ */
+extern int nb_candidate_commit_prepare(struct nb_context *context,
+ struct nb_config *candidate,
+ const char *comment,
+ struct nb_transaction **transaction,
+ char *errmsg, size_t errmsg_len);
+
+/*
+ * Abort a previously created configuration transaction, releasing all resources
+ * allocated during the preparation phase.
+ *
+ * transaction
+ * Candidate configuration to abort. It's consumed by this function.
+ *
+ * errmsg
+ * Buffer to store human-readable error message in case of error.
+ *
+ * errmsg_len
+ * Size of errmsg.
+ */
+extern void nb_candidate_commit_abort(struct nb_transaction *transaction,
+ char *errmsg, size_t errmsg_len);
+
+/*
+ * Commit a previously created configuration transaction.
+ *
+ * transaction
+ * Configuration transaction to commit. It's consumed by this function.
+ *
+ * save_transaction
+ * Specify whether the transaction should be recorded in the transactions log
+ * or not.
+ *
+ * transaction_id
+ * Optional output parameter providing the ID of the committed transaction.
+ *
+ * errmsg
+ * Buffer to store human-readable error message in case of error.
+ *
+ * errmsg_len
+ * Size of errmsg.
+ */
+extern void nb_candidate_commit_apply(struct nb_transaction *transaction,
+ bool save_transaction,
+ uint32_t *transaction_id, char *errmsg,
+ size_t errmsg_len);
+
+/*
+ * Create a new transaction to commit a candidate configuration. This is a
+ * convenience function that performs the two-phase commit protocol
+ * transparently to the user. The cost is reduced flexibility, since
+ * network-wide and multi-daemon transactions require the network manager to
+ * take into account the results of the preparation phase of multiple managed
+ * entities.
+ *
+ * context
+ * Context of the northbound transaction.
+ *
+ * candidate
+ * Candidate configuration to commit. It's preserved regardless if the commit
+ * operation fails or not.
+ *
+ * save_transaction
+ * Specify whether the transaction should be recorded in the transactions log
+ * or not.
+ *
+ * comment
+ * Optional comment describing the commit.
+ *
+ * transaction_id
+ * Optional output parameter providing the ID of the committed transaction.
+ *
+ * errmsg
+ * Buffer to store human-readable error message in case of error.
+ *
+ * errmsg_len
+ * Size of errmsg.
+ *
+ * Returns:
+ * - NB_OK on success.
+ * - NB_ERR_NO_CHANGES when the candidate is identical to the running
+ * configuration.
+ * - NB_ERR_LOCKED when there's already another transaction in progress.
+ * - NB_ERR_VALIDATION when the candidate fails the validation checks.
+ * - NB_ERR_RESOURCE when the system fails to allocate resources to apply
+ * the candidate configuration.
+ * - NB_ERR for other errors.
+ */
+extern int nb_candidate_commit(struct nb_context *context,
+ struct nb_config *candidate,
+ bool save_transaction, const char *comment,
+ uint32_t *transaction_id, char *errmsg,
+ size_t errmsg_len);
+
+/*
+ * Lock the running configuration.
+ *
+ * client
+ * Northbound client.
+ *
+ * user
+ * Northbound user (can be NULL).
+ *
+ * Returns:
+ * 0 on success, -1 when the running configuration is already locked.
+ */
+extern int nb_running_lock(enum nb_client client, const void *user);
+
+/*
+ * Unlock the running configuration.
+ *
+ * client
+ * Northbound client.
+ *
+ * user
+ * Northbound user (can be NULL).
+ *
+ * Returns:
+ * 0 on success, -1 when the running configuration is already unlocked or
+ * locked by another client/user.
+ */
+extern int nb_running_unlock(enum nb_client client, const void *user);
+
+/*
+ * Check if the running configuration is locked or not for the given
+ * client/user.
+ *
+ * client
+ * Northbound client.
+ *
+ * user
+ * Northbound user (can be NULL).
+ *
+ * Returns:
+ * 0 if the running configuration is unlocked or if the client/user owns the
+ * lock, -1 otherwise.
+ */
+extern int nb_running_lock_check(enum nb_client client, const void *user);
+
+/*
+ * Iterate over operational data.
+ *
+ * xpath
+ * Data path of the YANG data we want to iterate over.
+ *
+ * translator
+ * YANG module translator (might be NULL).
+ *
+ * flags
+ * NB_OPER_DATA_ITER_ flags to control how the iteration is performed.
+ *
+ * cb
+ * Function to call with each data node.
+ *
+ * arg
+ * Arbitrary argument passed as the fourth parameter in each call to 'cb'.
+ *
+ * Returns:
+ * NB_OK on success, NB_ERR otherwise.
+ */
+extern int nb_oper_data_iterate(const char *xpath,
+ struct yang_translator *translator,
+ uint32_t flags, nb_oper_data_cb cb, void *arg);
+
+/*
+ * Validate if the northbound operation is valid for the given node.
+ *
+ * operation
+ * Operation we want to check.
+ *
+ * snode
+ * libyang schema node we want to check.
+ *
+ * Returns:
+ * true if the operation is valid, false otherwise.
+ */
+extern bool nb_operation_is_valid(enum nb_operation operation,
+ const struct lysc_node *snode);
+
+/*
+ * Send a YANG notification. This is a no-op unless the 'nb_notification_send'
+ * hook was registered by a northbound plugin.
+ *
+ * xpath
+ * XPath of the YANG notification.
+ *
+ * arguments
+ * Linked list containing the arguments that should be sent. This list is
+ * deleted after being used.
+ *
+ * Returns:
+ * NB_OK on success, NB_ERR otherwise.
+ */
+extern int nb_notification_send(const char *xpath, struct list *arguments);
+
+/*
+ * Associate a user pointer to a configuration node.
+ *
+ * This should be called by northbound 'create' callbacks in the NB_EV_APPLY
+ * phase only.
+ *
+ * dnode
+ * libyang data node - only its XPath is used.
+ *
+ * entry
+ * Arbitrary user-specified pointer.
+ */
+extern void nb_running_set_entry(const struct lyd_node *dnode, void *entry);
+
+/*
+ * Move an entire tree of user pointer nodes.
+ *
+ * Suppose we have xpath A/B/C/D, with user pointers associated to C and D. We
+ * need to move B to be under Z, so the new xpath is Z/B/C/D. Because user
+ * pointers are indexed with their absolute path, We need to move all user
+ * pointers at and below B to their new absolute paths; this function does
+ * that.
+ *
+ * xpath_from
+ * base xpath of tree to move (A/B)
+ *
+ * xpath_to
+ * base xpath of new location of tree (Z/B)
+ */
+extern void nb_running_move_tree(const char *xpath_from, const char *xpath_to);
+
+/*
+ * Unset the user pointer associated to a configuration node.
+ *
+ * This should be called by northbound 'destroy' callbacks in the NB_EV_APPLY
+ * phase only.
+ *
+ * dnode
+ * libyang data node - only its XPath is used.
+ *
+ * Returns:
+ * The user pointer that was unset.
+ */
+extern void *nb_running_unset_entry(const struct lyd_node *dnode);
+
+/*
+ * Find the user pointer (if any) associated to a configuration node.
+ *
+ * The XPath associated to the configuration node can be provided directly or
+ * indirectly through a libyang data node.
+ *
+ * If an user point is not found, this function follows the parent nodes in the
+ * running configuration until an user pointer is found or until the root node
+ * is reached.
+ *
+ * dnode
+ * libyang data node - only its XPath is used (can be NULL if 'xpath' is
+ * provided).
+ *
+ * xpath
+ * XPath of the configuration node (can be NULL if 'dnode' is provided).
+ *
+ * abort_if_not_found
+ * When set to true, abort the program if no user pointer is found.
+ *
+ * As a rule of thumb, this parameter should be set to true in the following
+ * scenarios:
+ * - Calling this function from any northbound configuration callback during
+ * the NB_EV_APPLY phase.
+ * - Calling this function from a 'delete' northbound configuration callback
+ * during any phase.
+ *
+ * In both the above cases, the given configuration node should contain an
+ * user pointer except when there's a bug in the code, in which case it's
+ * better to abort the program right away and eliminate the need for
+ * unnecessary NULL checks.
+ *
+ * In all other cases, this parameter should be set to false and the caller
+ * should check if the function returned NULL or not.
+ *
+ * Returns:
+ * User pointer if found, NULL otherwise.
+ */
+extern void *nb_running_get_entry(const struct lyd_node *dnode,
+ const char *xpath, bool abort_if_not_found);
+
+/*
+ * Same as 'nb_running_get_entry', but doesn't search within parent nodes
+ * recursively if an user point is not found.
+ */
+extern void *nb_running_get_entry_non_rec(const struct lyd_node *dnode,
+ const char *xpath,
+ bool abort_if_not_found);
+
+/*
+ * Return a human-readable string representing a northbound event.
+ *
+ * event
+ * Northbound event.
+ *
+ * Returns:
+ * String representation of the given northbound event.
+ */
+extern const char *nb_event_name(enum nb_event event);
+
+/*
+ * Return a human-readable string representing a northbound operation.
+ *
+ * operation
+ * Northbound operation.
+ *
+ * Returns:
+ * String representation of the given northbound operation.
+ */
+extern const char *nb_operation_name(enum nb_operation operation);
+
+/*
+ * Return a human-readable string representing a northbound error.
+ *
+ * error
+ * Northbound error.
+ *
+ * Returns:
+ * String representation of the given northbound error.
+ */
+extern const char *nb_err_name(enum nb_error error);
+
+/*
+ * Return a human-readable string representing a northbound client.
+ *
+ * client
+ * Northbound client.
+ *
+ * Returns:
+ * String representation of the given northbound client.
+ */
+extern const char *nb_client_name(enum nb_client client);
+
+/*
+ * Validate all northbound callbacks.
+ *
+ * Some errors, like missing callbacks or invalid priorities, are fatal and
+ * can't be recovered from. Other errors, like unneeded callbacks, are logged
+ * but otherwise ignored.
+ *
+ * Whenever a YANG module is loaded after startup, *all* northbound callbacks
+ * need to be validated and not only the callbacks from the newly loaded module.
+ * This is because augmentations can change the properties of the augmented
+ * module, making mandatory the implementation of additional callbacks.
+ */
+void nb_validate_callbacks(void);
+
+/*
+ * Initialize the northbound layer. Should be called only once during the
+ * daemon initialization process.
+ *
+ * modules
+ * Array of YANG modules to parse and initialize.
+ *
+ * nmodules
+ * Size of the modules array.
+ *
+ * db_enabled
+ * Set this to record the transactions in the transaction log.
+ */
+extern void nb_init(struct thread_master *tm,
+ const struct frr_yang_module_info *const modules[],
+ size_t nmodules, bool db_enabled);
+
+/*
+ * Finish the northbound layer gracefully. Should be called only when the daemon
+ * is exiting.
+ */
+extern void nb_terminate(void);
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif /* _FRR_NORTHBOUND_H_ */