lib/yang.h

   1 /*
   2  * Copyright (C) 2018  NetDEF, Inc.
   3  *                     Renato Westphal
   4  *
   5  * This program is free software; you can redistribute it and/or modify it
   6  * under the terms of the GNU General Public License as published by the Free
   7  * Software Foundation; either version 2 of the License, or (at your option)
   8  * any later version.
   9  *
  10  * This program is distributed in the hope that it will be useful, but WITHOUT
  11  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
  12  * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License for
  13  * more details.
  14  *
  15  * You should have received a copy of the GNU General Public License along
  16  * with this program; see the file COPYING; if not, write to the Free Software
  17  * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA
  18  */
  19
  20 #ifndef _FRR_YANG_H_
  21 #define _FRR_YANG_H_
  22
  23 #include "memory.h"
  24
  25 #include <libyang/libyang.h>
  26 #ifdef HAVE_SYSREPO
  27 #include <sysrepo.h>
  28 #endif
  29
  30 #include "yang_wrappers.h"
  31
  32 #ifdef __cplusplus
  33 extern "C" {
  34 #endif
  35
  36 DECLARE_MTYPE(YANG_MODULE)
  37 DECLARE_MTYPE(YANG_DATA)
  38
  39 /* Maximum XPath length. */
  40 #define XPATH_MAXLEN 256
  41
  42 /* Maximum list key length. */
  43 #define LIST_MAXKEYS 8
  44
  45 /* Maximum list key length. */
  46 #define LIST_MAXKEYLEN 128
  47
  48 /* Maximum string length of an YANG value. */
  49 #define YANG_VALUE_MAXLEN 1024
  50
  51 struct yang_module_embed {
  52         struct yang_module_embed *next;
  53         const char *mod_name, *mod_rev;
  54         const char *data;
  55         LYS_INFORMAT format;
  56 };
  57
  58 struct yang_module {
  59         RB_ENTRY(yang_module) entry;
  60         const char *name;
  61         const struct lys_module *info;
  62 #ifdef HAVE_CONFD
  63         int confd_hash;
  64 #endif
  65 #ifdef HAVE_SYSREPO
  66         sr_subscription_ctx_t *sr_subscription;
  67 #endif
  68 };
  69 RB_HEAD(yang_modules, yang_module);
  70 RB_PROTOTYPE(yang_modules, yang_module, entry, yang_module_compare);
  71
  72 struct yang_data {
  73         /* XPath identifier of the data element. */
  74         char xpath[XPATH_MAXLEN];
  75
  76         /* Value encoded as a raw string. */
  77         char *value;
  78 };
  79
  80 struct yang_list_keys {
  81         /* Number os keys (max: LIST_MAXKEYS). */
  82         uint8_t num;
  83
  84         /* Value encoded as a raw string. */
  85         char key[LIST_MAXKEYS][LIST_MAXKEYLEN];
  86 };
  87
  88 enum yang_path_type {
  89         YANG_PATH_SCHEMA = 0,
  90         YANG_PATH_DATA,
  91 };
  92
  93 enum yang_iter_flags {
  94         /* Filter non-presence containers. */
  95         YANG_ITER_FILTER_NPCONTAINERS = (1<<0),
  96
  97         /* Filter list keys (leafs). */
  98         YANG_ITER_FILTER_LIST_KEYS = (1<<1),
  99
 100         /* Filter RPC input/output nodes. */
 101         YANG_ITER_FILTER_INPUT_OUTPUT = (1<<2),
 102
 103         /* Filter implicitely created nodes. */
 104         YANG_ITER_FILTER_IMPLICIT = (1<<3),
 105
 106         /* Allow iteration over augmentations. */
 107         YANG_ITER_ALLOW_AUGMENTATIONS = (1<<4),
 108 };
 109
 110 /* Callback used by the yang_snodes_iterate_*() family of functions. */
 111 typedef int (*yang_iterate_cb)(const struct lys_node *snode, void *arg);
 112
 113 /* Return values of the 'yang_iterate_cb' callback. */
 114 #define YANG_ITER_CONTINUE 0
 115 #define YANG_ITER_STOP -1
 116
 117 /* Global libyang context for native FRR models. */
 118 extern struct ly_ctx *ly_native_ctx;
 119
 120 /* Tree of all loaded YANG modules. */
 121 extern struct yang_modules yang_modules;
 122
 123 /*
 124  * Create a new YANG module and load it using libyang. If the YANG module is not
 125  * found in the YANG_MODELS_PATH directory, the program will exit with an error.
 126  * Once loaded, a YANG module can't be unloaded anymore.
 127  *
 128  * module_name
 129  *    Name of the YANG module.
 130  *
 131  * Returns:
 132  *    Pointer to newly created YANG module.
 133  */
 134 extern struct yang_module *yang_module_load(const char *module_name);
 135
 136 /*
 137  * Load all FRR native YANG models.
 138  */
 139 extern void yang_module_load_all(void);
 140
 141 /*
 142  * Find a YANG module by its name.
 143  *
 144  * module_name
 145  *    Name of the YANG module.
 146  *
 147  * Returns:
 148  *    Pointer to YANG module if found, NULL otherwise.
 149  */
 150 extern struct yang_module *yang_module_find(const char *module_name);
 151
 152 /*
 153  * Register a YANG module embedded in the binary file.  Should be called
 154  * from a constructor function.
 155  *
 156  * embed
 157  *    YANG module embedding structure to register.  (static global provided
 158  *    by caller.)
 159  */
 160 extern void yang_module_embed(struct yang_module_embed *embed);
 161
 162 /*
 163  * Iterate recursively over all children of a schema node.
 164  *
 165  * snode
 166  *    YANG schema node to operate on.
 167  *
 168  * cb
 169  *    Function to call with each schema node.
 170  *
 171  * flags
 172  *    YANG_ITER_* flags to control how the iteration is performed.
 173  *
 174  * arg
 175  *    Arbitrary argument passed as the second parameter in each call to 'cb'.
 176  *
 177  * Returns:
 178  *    The return value of the last called callback.
 179  */
 180 extern int yang_snodes_iterate_subtree(const struct lys_node *snode,
 181                                        yang_iterate_cb cb, uint16_t flags,
 182                                        void *arg);
 183
 184 /*
 185  * Iterate over all libyang schema nodes from the given YANG module.
 186  *
 187  * module
 188  *    YANG module to operate on.
 189  *
 190  * cb
 191  *    Function to call with each schema node.
 192  *
 193  * flags
 194  *    YANG_ITER_* flags to control how the iteration is performed.
 195  *
 196  * arg
 197  *    Arbitrary argument passed as the second parameter in each call to 'cb'.
 198  *
 199  * Returns:
 200  *    The return value of the last called callback.
 201  */
 202 extern int yang_snodes_iterate_module(const struct lys_module *module,
 203                                       yang_iterate_cb cb, uint16_t flags,
 204                                       void *arg);
 205
 206 /*
 207  * Iterate over all libyang schema nodes from all loaded YANG modules.
 208  *
 209  * cb
 210  *    Function to call with each schema node.
 211  *
 212  * flags
 213  *    YANG_ITER_* flags to control how the iteration is performed.
 214  *
 215  * arg
 216  *    Arbitrary argument passed as the second parameter in each call to 'cb'.
 217  *
 218  * Returns:
 219  *    The return value of the last called callback.
 220  */
 221 extern int yang_snodes_iterate_all(yang_iterate_cb cb, uint16_t flags,
 222                                    void *arg);
 223
 224 /*
 225  * Build schema path or data path of the schema node.
 226  *
 227  * snode
 228  *    libyang schema node to be processed.
 229  *
 230  * type
 231  *    Specify whether a schema path or a data path should be built.
 232  *
 233  * xpath
 234  *    Pointer to previously allocated buffer.
 235  *
 236  * xpath_len
 237  *    Size of the xpath buffer.
 238  */
 239 extern void yang_snode_get_path(const struct lys_node *snode,
 240                                 enum yang_path_type type, char *xpath,
 241                                 size_t xpath_len);
 242
 243 /*
 244  * Find first parent schema node which is a presence-container or a list
 245  * (non-presence containers are ignored).
 246  *
 247  * snode
 248  *    libyang schema node to operate on.
 249  *
 250  * Returns:
 251  *    The parent libyang schema node if found, or NULL if not found.
 252  */
 253 extern struct lys_node *yang_snode_real_parent(const struct lys_node *snode);
 254
 255 /*
 256  * Find first parent schema node which is a list.
 257  *
 258  * snode
 259  *    libyang schema node to operate on.
 260  *
 261  * Returns:
 262  *    The parent libyang schema node (list) if found, or NULL if not found.
 263  */
 264 extern struct lys_node *yang_snode_parent_list(const struct lys_node *snode);
 265
 266 /*
 267  * Check if the libyang schema node represents typeless data (e.g. containers,
 268  * leafs of type empty, etc).
 269  *
 270  * snode
 271  *    libyang schema node to operate on.
 272  *
 273  * Returns:
 274  *    true if the schema node represents typeless data, false otherwise.
 275  */
 276 extern bool yang_snode_is_typeless_data(const struct lys_node *snode);
 277
 278 /*
 279  * Get the default value associated to a YANG leaf or leaf-list.
 280  *
 281  * snode
 282  *    libyang schema node to operate on.
 283  *
 284  * Returns:
 285  *    The default value if it exists, NULL otherwise.
 286  */
 287 extern const char *yang_snode_get_default(const struct lys_node *snode);
 288
 289 /*
 290  * Get the type structure of a leaf of leaf-list. If the type is a leafref, the
 291  * final (if there is a chain of leafrefs) target's type is found.
 292  *
 293  * snode
 294  *    libyang schema node to operate on.
 295  *
 296  * Returns:
 297  *    The found type if the schema node represents a leaf or a leaf-list, NULL
 298  *    otherwise.
 299  */
 300 extern const struct lys_type *yang_snode_get_type(const struct lys_node *snode);
 301
 302 /*
 303  * Build data path of the data node.
 304  *
 305  * dnode
 306  *    libyang data node to be processed.
 307  *
 308  * xpath
 309  *    Pointer to previously allocated buffer.
 310  *
 311  * xpath_len
 312  *    Size of the xpath buffer.
 313  */
 314 extern void yang_dnode_get_path(const struct lyd_node *dnode, char *xpath,
 315                                 size_t xpath_len);
 316
 317 /*
 318  * Return the schema name of the given libyang data node.
 319  *
 320  * dnode
 321  *    libyang data node.
 322  *
 323  * xpath_fmt
 324  *    Optional XPath expression (absolute or relative) to specify a different
 325  *    data node to operate on in the same data tree.
 326  *
 327  * Returns:
 328  *    Schema name of the libyang data node.
 329  */
 330 extern const char *yang_dnode_get_schema_name(const struct lyd_node *dnode,
 331                                               const char *xpath_fmt, ...);
 332
 333 /*
 334  * Find a libyang data node by its YANG data path.
 335  *
 336  * dnode
 337  *    Base libyang data node to operate on.
 338  *
 339  * xpath_fmt
 340  *    XPath expression (absolute or relative).
 341  *
 342  * Returns:
 343  *    The libyang data node if found, or NULL if not found.
 344  */
 345 extern struct lyd_node *yang_dnode_get(const struct lyd_node *dnode,
 346                                        const char *xpath_fmt, ...);
 347
 348 /*
 349  * Check if a libyang data node exists.
 350  *
 351  * dnode
 352  *    Base libyang data node to operate on.
 353  *
 354  * xpath_fmt
 355  *    XPath expression (absolute or relative).
 356  *
 357  * Returns:
 358  *    true if the libyang data node was found, false otherwise.
 359  */
 360 extern bool yang_dnode_exists(const struct lyd_node *dnode,
 361                               const char *xpath_fmt, ...);
 362
 363 /*
 364  * Check if the libyang data node contains a default value. Non-presence
 365  * containers are assumed to always contain a default value.
 366  *
 367  * dnode
 368  *    Base libyang data node to operate on.
 369  *
 370  * xpath_fmt
 371  *    Optional XPath expression (absolute or relative) to specify a different
 372  *    data node to operate on in the same data tree.
 373  *
 374  * Returns:
 375  *    true if the data node contains the default value, false otherwise.
 376  */
 377 extern bool yang_dnode_is_default(const struct lyd_node *dnode,
 378                                   const char *xpath_fmt, ...);
 379
 380 /*
 381  * Check if the libyang data node and all of its children contain default
 382  * values. Non-presence containers are assumed to always contain a default
 383  * value.
 384  *
 385  * dnode
 386  *    libyang data node to operate on.
 387  *
 388  * Returns:
 389  *    true if the data node and all of its children contain default values,
 390  *    false otherwise.
 391  */
 392 extern bool yang_dnode_is_default_recursive(const struct lyd_node *dnode);
 393
 394 /*
 395  * Change the value of a libyang leaf node.
 396  *
 397  * dnode
 398  *    libyang data node to operate on.
 399  *
 400  * value
 401  *    String representing the new value.
 402  */
 403 extern void yang_dnode_change_leaf(struct lyd_node *dnode, const char *value);
 404
 405 /*
 406  * Set the libyang private pointer to a user pointer. Can only be used on YANG
 407  * lists and containers.
 408  *
 409  * dnode
 410  *    libyang data node to operate on.
 411  *
 412  * entry
 413  *    Arbitrary user-specified pointer.
 414  */
 415 extern void yang_dnode_set_entry(const struct lyd_node *dnode, void *entry);
 416
 417 /*
 418  * Find the user pointer associated to the given libyang data node.
 419  *
 420  * The data node is traversed by following the parent pointers until an user
 421  * pointer is found or until the root node is reached.
 422  *
 423  * dnode
 424  *    libyang data node to operate on.
 425  *
 426  * abort_if_not_found
 427  *    When set to true, abort the program if no user pointer is found.
 428  *
 429  *    As a rule of thumb, this parameter should be set to true in the following
 430  *    scenarios:
 431  *    - Calling this function from any northbound configuration callback during
 432  *      the NB_EV_APPLY phase.
 433  *    - Calling this function from a 'delete' northbound configuration callback
 434  *      during any phase.
 435  *
 436  *    In both the above cases, the libyang data node should contain an user
 437  *    pointer except when there's a bug in the code, in which case it's better
 438  *    to abort the program right away and eliminate the need for unnecessary
 439  *    NULL checks.
 440  *
 441  *    In all other cases, this parameter should be set to false and the caller
 442  *    should check if the function returned NULL or not.
 443  *
 444  * Returns:
 445  *    User pointer if found, NULL otherwise.
 446  */
 447 extern void *yang_dnode_get_entry(const struct lyd_node *dnode,
 448                                   bool abort_if_not_found);
 449
 450 /*
 451  * Create a new libyang data node.
 452  *
 453  * ly_ctx
 454  *    libyang context to operate on.
 455  *
 456  * config
 457  *    Specify whether the data node will contain only configuration data (true)
 458  *    or both configuration data and state data (false).
 459  *
 460  * Returns:
 461  *    Pointer to newly created libyang data node.
 462  */
 463 extern struct lyd_node *yang_dnode_new(struct ly_ctx *ly_ctx, bool config_only);
 464
 465 /*
 466  * Duplicate a libyang data node.
 467  *
 468  * dnode
 469  *    libyang data node to duplicate.
 470  *
 471  * Returns:
 472  *    Pointer to duplicated libyang data node.
 473  */
 474 extern struct lyd_node *yang_dnode_dup(const struct lyd_node *dnode);
 475
 476 /*
 477  * Delete a libyang data node.
 478  *
 479  * dnode
 480  *    Pointer to the libyang data node that is going to be deleted.
 481  */
 482 extern void yang_dnode_free(struct lyd_node *dnode);
 483
 484 /*
 485  * Create a new yang_data structure.
 486  *
 487  * xpath
 488  *    Data path of the YANG data.
 489  *
 490  * value
 491  *    String representing the value of the YANG data.
 492  *
 493  * Returns:
 494  *    Pointer to newly created yang_data structure.
 495  */
 496 extern struct yang_data *yang_data_new(const char *xpath, const char *value);
 497
 498 /*
 499  * Delete a yang_data structure.
 500  *
 501  * data
 502  *    yang_data to delete.
 503  */
 504 extern void yang_data_free(struct yang_data *data);
 505
 506 /*
 507  * Create a new linked list of yang_data structures. The list 'del' callback is
 508  * initialized appropriately so that the entire list can be deleted safely with
 509  * list_delete_and_null().
 510  *
 511  * Returns:
 512  *    Pointer to newly created linked list.
 513  */
 514 extern struct list *yang_data_list_new(void);
 515
 516 /*
 517  * Create and set up a libyang context (for use by the translator)
 518  */
 519 extern struct ly_ctx *yang_ctx_new_setup(void);
 520
 521 /*
 522  * Initialize the YANG subsystem. Should be called only once during the
 523  * daemon initialization process.
 524  */
 525 extern void yang_init(void);
 526
 527 /*
 528  * Finish the YANG subsystem gracefully. Should be called only when the daemon
 529  * is exiting.
 530  */
 531 extern void yang_terminate(void);
 532
 533 #ifdef __cplusplus
 534 }
 535 #endif
 536
 537 #endif /* _FRR_YANG_H_ */