lib/yang.h

   1 // SPDX-License-Identifier: GPL-2.0-or-later
   2 /*
   3  * Copyright (C) 2018  NetDEF, Inc.
   4  *                     Renato Westphal
   5  */
   6
   7 #ifndef _FRR_YANG_H_
   8 #define _FRR_YANG_H_
   9
  10 #include "memory.h"
  11
  12 #include <libyang/libyang.h>
  13 #ifdef HAVE_SYSREPO
  14 #include <sysrepo.h>
  15 #endif
  16
  17 #include "yang_wrappers.h"
  18
  19 #ifdef __cplusplus
  20 extern "C" {
  21 #endif
  22
  23 /* Maximum XPath length. */
  24 #define XPATH_MAXLEN 1024
  25
  26 /* Maximum list key length. */
  27 #define LIST_MAXKEYS 8
  28
  29 /* Maximum list key length. */
  30 #define LIST_MAXKEYLEN 128
  31
  32 /* Maximum string length of an YANG value. */
  33 #define YANG_VALUE_MAXLEN 1024
  34
  35 struct yang_module_embed {
  36         struct yang_module_embed *next;
  37         const char *mod_name, *mod_rev;
  38         const char *sub_mod_name;
  39         const char *sub_mod_rev;
  40         const char *data;
  41         LYS_INFORMAT format;
  42 };
  43
  44 struct yang_module {
  45         RB_ENTRY(yang_module) entry;
  46         const char *name;
  47         const struct lys_module *info;
  48 #ifdef HAVE_CONFD
  49         int confd_hash;
  50 #endif
  51 #ifdef HAVE_SYSREPO
  52         sr_subscription_ctx_t *sr_subscription;
  53         struct event *sr_thread;
  54 #endif
  55 };
  56 RB_HEAD(yang_modules, yang_module);
  57 RB_PROTOTYPE(yang_modules, yang_module, entry, yang_module_compare);
  58
  59 struct yang_data {
  60         /* XPath identifier of the data element. */
  61         char xpath[XPATH_MAXLEN];
  62
  63         /* Value encoded as a raw string. */
  64         char *value;
  65 };
  66
  67 struct yang_list_keys {
  68         /* Number os keys (max: LIST_MAXKEYS). */
  69         uint8_t num;
  70
  71         /* Value encoded as a raw string. */
  72         char key[LIST_MAXKEYS][LIST_MAXKEYLEN];
  73 };
  74
  75 enum yang_path_type {
  76         YANG_PATH_SCHEMA = 0,
  77         YANG_PATH_DATA,
  78 };
  79
  80 enum yang_iter_flags {
  81         /* Filter non-presence containers. */
  82         YANG_ITER_FILTER_NPCONTAINERS = (1<<0),
  83
  84         /* Filter list keys (leafs). */
  85         YANG_ITER_FILTER_LIST_KEYS = (1<<1),
  86
  87         /* Filter RPC input/output nodes. */
  88         YANG_ITER_FILTER_INPUT_OUTPUT = (1<<2),
  89 };
  90
  91 /* Callback used by the yang_snodes_iterate_*() family of functions. */
  92 typedef int (*yang_iterate_cb)(const struct lysc_node *snode, void *arg);
  93
  94 /* Callback used by the yang_dnode_iterate() function. */
  95 typedef int (*yang_dnode_iter_cb)(const struct lyd_node *dnode, void *arg);
  96
  97 /* Return values of the 'yang_iterate_cb' callback. */
  98 #define YANG_ITER_CONTINUE 0
  99 #define YANG_ITER_STOP -1
 100
 101 /* Global libyang context for native FRR models. */
 102 extern struct ly_ctx *ly_native_ctx;
 103
 104 /* Tree of all loaded YANG modules. */
 105 extern struct yang_modules yang_modules;
 106
 107 /*
 108  * Create a new YANG module and load it using libyang. If the YANG module is not
 109  * found in the YANG_MODELS_PATH directory, the program will exit with an error.
 110  * Once loaded, a YANG module can't be unloaded anymore.
 111  *
 112  * module_name
 113  *    Name of the YANG module.
 114  *
 115  * Returns:
 116  *    Pointer to newly created YANG module.
 117  */
 118 extern struct yang_module *yang_module_load(const char *module_name);
 119
 120 /*
 121  * Load all FRR native YANG models.
 122  */
 123 extern void yang_module_load_all(void);
 124
 125 /*
 126  * Find a YANG module by its name.
 127  *
 128  * module_name
 129  *    Name of the YANG module.
 130  *
 131  * Returns:
 132  *    Pointer to YANG module if found, NULL otherwise.
 133  */
 134 extern struct yang_module *yang_module_find(const char *module_name);
 135
 136 /*
 137  * Register a YANG module embedded in the binary file.  Should be called
 138  * from a constructor function.
 139  *
 140  * embed
 141  *    YANG module embedding structure to register.  (static global provided
 142  *    by caller.)
 143  */
 144 extern void yang_module_embed(struct yang_module_embed *embed);
 145
 146 /*
 147  * Iterate recursively over all children of a schema node.
 148  *
 149  * snode
 150  *    YANG schema node to operate on.
 151  *
 152  * module
 153  *    When set, iterate over all nodes of the specified module only.
 154  *
 155  * cb
 156  *    Function to call with each schema node.
 157  *
 158  * flags
 159  *    YANG_ITER_* flags to control how the iteration is performed.
 160  *
 161  * arg
 162  *    Arbitrary argument passed as the second parameter in each call to 'cb'.
 163  *
 164  * Returns:
 165  *    The return value of the last called callback.
 166  */
 167 extern int yang_snodes_iterate_subtree(const struct lysc_node *snode,
 168                                        const struct lys_module *module,
 169                                        yang_iterate_cb cb, uint16_t flags,
 170                                        void *arg);
 171
 172 /*
 173  * Iterate over all libyang schema nodes from all loaded modules of the
 174  * given YANG module.
 175  *
 176  * module
 177  *    When set, iterate over all nodes of the specified module only.
 178  *
 179  * cb
 180  *    Function to call with each schema node.
 181  *
 182  * flags
 183  *    YANG_ITER_* flags to control how the iteration is performed.
 184  *
 185  * arg
 186  *    Arbitrary argument passed as the second parameter in each call to 'cb'.
 187  *
 188  * Returns:
 189  *    The return value of the last called callback.
 190  */
 191 extern int yang_snodes_iterate(const struct lys_module *module,
 192                                yang_iterate_cb cb, uint16_t flags, void *arg);
 193
 194 /*
 195  * Build schema path or data path of the schema node.
 196  *
 197  * snode
 198  *    libyang schema node to be processed.
 199  *
 200  * type
 201  *    Specify whether a schema path or a data path should be built.
 202  *
 203  * xpath
 204  *    Pointer to previously allocated buffer.
 205  *
 206  * xpath_len
 207  *    Size of the xpath buffer.
 208  */
 209 extern void yang_snode_get_path(const struct lysc_node *snode,
 210                                 enum yang_path_type type, char *xpath,
 211                                 size_t xpath_len);
 212
 213
 214 /*
 215  * Find libyang schema node for the given xpath. Uses `lys_find_xpath`,
 216  * returning only the first of a set of nodes -- normally there should only
 217  * be one.
 218  *
 219  * ly_ctx
 220  *    libyang context to operate on.
 221  *
 222  * xpath
 223  *    XPath expression (absolute or relative) to find the schema node for.
 224  *
 225  * options
 226  *    Libyang findxpathoptions value (see lys_find_xpath).
 227  *
 228  * Returns:
 229  *    The libyang schema node if found, or NULL if not found.
 230  */
 231 extern struct lysc_node *yang_find_snode(struct ly_ctx *ly_ctx,
 232                                          const char *xpath, uint32_t options);
 233
 234 /*
 235  * Find first parent schema node which is a presence-container or a list
 236  * (non-presence containers are ignored).
 237  *
 238  * snode
 239  *    libyang schema node to operate on.
 240  *
 241  * Returns:
 242  *    The parent libyang schema node if found, or NULL if not found.
 243  */
 244 extern struct lysc_node *yang_snode_real_parent(const struct lysc_node *snode);
 245
 246 /*
 247  * Find first parent schema node which is a list.
 248  *
 249  * snode
 250  *    libyang schema node to operate on.
 251  *
 252  * Returns:
 253  *    The parent libyang schema node (list) if found, or NULL if not found.
 254  */
 255 extern struct lysc_node *yang_snode_parent_list(const struct lysc_node *snode);
 256
 257 /*
 258  * Check if the libyang schema node represents typeless data (e.g. containers,
 259  * leafs of type empty, etc).
 260  *
 261  * snode
 262  *    libyang schema node to operate on.
 263  *
 264  * Returns:
 265  *    true if the schema node represents typeless data, false otherwise.
 266  */
 267 extern bool yang_snode_is_typeless_data(const struct lysc_node *snode);
 268
 269 /*
 270  * Get the default value associated to a YANG leaf or leaf-list.
 271  *
 272  * snode
 273  *    libyang schema node to operate on.
 274  *
 275  * Returns:
 276  *    The default value if it exists, NULL otherwise.
 277  */
 278 extern const char *yang_snode_get_default(const struct lysc_node *snode);
 279
 280 /*
 281  * Get the type structure of a leaf of leaf-list. If the type is a leafref, the
 282  * final (if there is a chain of leafrefs) target's type is found.
 283  *
 284  * snode
 285  *    libyang schema node to operate on.
 286  *
 287  * Returns:
 288  *    The found type if the schema node represents a leaf or a leaf-list, NULL
 289  *    otherwise.
 290  */
 291 extern const struct lysc_type *
 292 yang_snode_get_type(const struct lysc_node *snode);
 293
 294 /*
 295  * Get the number of key nodes for the given list.
 296  *
 297  * snode
 298  *    libyang (LYS_LIST) schema node to operate on.
 299  *
 300  * Returns:
 301  *    The number of key LYS_LEAFs as children of this list node.
 302  */
 303 extern unsigned int yang_snode_num_keys(const struct lysc_node *snode);
 304
 305 #define LY_FOR_KEYS(snode, skey)                                               \
 306         for ((skey) = (const struct lysc_node_leaf *)lysc_node_child((snode)); \
 307              (skey); (skey) = (const struct lysc_node_leaf *)((skey)->next))   \
 308                 if (!lysc_is_key(skey)) {                                      \
 309                         break;                                                 \
 310                 } else
 311
 312
 313 /*
 314  * Build data path of the data node.
 315  *
 316  * dnode
 317  *    libyang data node to be processed.
 318  *
 319  * xpath
 320  *    Pointer to previously allocated buffer.
 321  *
 322  * xpath_len
 323  *    Size of the xpath buffer.
 324  */
 325 extern void yang_dnode_get_path(const struct lyd_node *dnode, char *xpath,
 326                                 size_t xpath_len);
 327
 328 /*
 329  * Return the schema name of the given libyang data node.
 330  *
 331  * dnode
 332  *    libyang data node.
 333  *
 334  * xpath_fmt
 335  *    Optional XPath expression (absolute or relative) to specify a different
 336  *    data node to operate on in the same data tree.
 337  *
 338  * Returns:
 339  *    Schema name of the libyang data node.
 340  */
 341 extern const char *yang_dnode_get_schema_name(const struct lyd_node *dnode,
 342                                               const char *xpath_fmt, ...)
 343         PRINTFRR(2, 3);
 344
 345 /*
 346  * Find a libyang data node by its YANG data path.
 347  *
 348  * dnode
 349  *    Base libyang data node to operate on.
 350  *
 351  * xpath
 352  *    Limited XPath (absolute or relative) string. See Path in libyang
 353  *    documentation for restrictions.
 354  *
 355  * Returns:
 356  *    The libyang data node if found, or NULL if not found.
 357  */
 358 extern struct lyd_node *yang_dnode_get(const struct lyd_node *dnode,
 359                                        const char *xpath);
 360
 361 /*
 362  * Find a libyang data node by its YANG data path.
 363  *
 364  * dnode
 365  *    Base libyang data node to operate on.
 366  *
 367  * xpath_fmt
 368  *    Limited XPath (absolute or relative) format string. See Path in libyang
 369  *    documentation for restrictions.
 370  *
 371  * ...
 372  *    any parameters for xpath_fmt.
 373  *
 374  * Returns:
 375  *    The libyang data node if found, or NULL if not found.
 376  */
 377 extern struct lyd_node *yang_dnode_getf(const struct lyd_node *dnode,
 378                                         const char *path_fmt, ...)
 379         PRINTFRR(2, 3);
 380
 381 /*
 382  * Check if a libyang data node exists.
 383  *
 384  * dnode
 385  *    Base libyang data node to operate on.
 386  *
 387  * xpath
 388  *    Limited XPath (absolute or relative) string. See Path in libyang
 389  *    documentation for restrictions.
 390  *
 391  * Returns:
 392  *    true if a libyang data node was found, false otherwise.
 393  */
 394 extern bool yang_dnode_exists(const struct lyd_node *dnode, const char *xpath);
 395
 396 /*
 397  * Check if a libyang data node exists.
 398  *
 399  * dnode
 400  *    Base libyang data node to operate on.
 401  *
 402  * xpath_fmt
 403  *    Limited XPath (absolute or relative) format string. See Path in
 404  *    libyang documentation for restrictions.
 405  *
 406  * ...
 407  *    any parameters for xpath_fmt.
 408  *
 409  * Returns:
 410  *    true if a libyang data node was found, false otherwise.
 411  */
 412 extern bool yang_dnode_existsf(const struct lyd_node *dnode,
 413                                const char *xpath_fmt, ...) PRINTFRR(2, 3);
 414
 415 /*
 416  * Iterate over all libyang data nodes that satisfy an XPath query.
 417  *
 418  * cb
 419  *    Function to call with each data node.
 420  *
 421  * arg
 422  *    Arbitrary argument passed as the second parameter in each call to 'cb'.
 423  *
 424  * dnode
 425  *    Base libyang data node to operate on.
 426  *
 427  * xpath_fmt
 428  *    XPath expression (absolute or relative).
 429  *
 430  * ...
 431  *    any parameters for xpath_fmt.
 432  */
 433 void yang_dnode_iterate(yang_dnode_iter_cb cb, void *arg,
 434                         const struct lyd_node *dnode, const char *xpath_fmt,
 435                         ...) PRINTFRR(4, 5);
 436
 437 /*
 438  * Check if the libyang data node contains a default value. Non-presence
 439  * containers are assumed to always contain a default value.
 440  *
 441  * dnode
 442  *    Base libyang data node to operate on.
 443  *
 444  * xpath
 445  *    Optional XPath expression (absolute or relative) to specify a different
 446  *    data node to operate on in the same data tree.
 447  *
 448  * Returns:
 449  *    true if the data node contains the default value, false otherwise.
 450  */
 451 extern bool yang_dnode_is_default(const struct lyd_node *dnode,
 452                                   const char *xpath);
 453
 454 /*
 455  * Check if the libyang data node contains a default value. Non-presence
 456  * containers are assumed to always contain a default value.
 457  *
 458  * dnode
 459  *    Base libyang data node to operate on.
 460  *
 461  * xpath
 462  *    Optional limited XPath (absolute or relative) format string. See Path in
 463  *    libyang documentation for restrictions.
 464  *
 465  * ...
 466  *    any parameters for xpath_fmt.
 467  *
 468  * Returns:
 469  *    true if the data node contains the default value, false otherwise.
 470  */
 471 extern bool yang_dnode_is_defaultf(const struct lyd_node *dnode,
 472                                    const char *xpath_fmt, ...) PRINTFRR(2, 3);
 473
 474 /*
 475  * Check if the libyang data node and all of its children contain default
 476  * values. Non-presence containers are assumed to always contain a default
 477  * value.
 478  *
 479  * dnode
 480  *    libyang data node to operate on.
 481  *
 482  * Returns:
 483  *    true if the data node and all of its children contain default values,
 484  *    false otherwise.
 485  */
 486 extern bool yang_dnode_is_default_recursive(const struct lyd_node *dnode);
 487
 488 /*
 489  * Change the value of a libyang leaf node.
 490  *
 491  * dnode
 492  *    libyang data node to operate on.
 493  *
 494  * value
 495  *    String representing the new value.
 496  */
 497 extern void yang_dnode_change_leaf(struct lyd_node *dnode, const char *value);
 498
 499 /*
 500  * Create a new libyang data node.
 501  *
 502  * ly_ctx
 503  *    libyang context to operate on.
 504  *
 505  * config
 506  *    Specify whether the data node will contain only configuration data (true)
 507  *    or both configuration data and state data (false).
 508  *
 509  * Returns:
 510  *    Pointer to newly created libyang data node.
 511  */
 512 extern struct lyd_node *yang_dnode_new(struct ly_ctx *ly_ctx, bool config_only);
 513
 514 /*
 515  * Duplicate a libyang data node.
 516  *
 517  * dnode
 518  *    libyang data node to duplicate.
 519  *
 520  * Returns:
 521  *    Pointer to duplicated libyang data node.
 522  */
 523 extern struct lyd_node *yang_dnode_dup(const struct lyd_node *dnode);
 524
 525 /*
 526  * Delete a libyang data node.
 527  *
 528  * dnode
 529  *    Pointer to the libyang data node that is going to be deleted along with
 530  *    the entire tree it belongs to.
 531  */
 532 extern void yang_dnode_free(struct lyd_node *dnode);
 533
 534 /*
 535  * Create a new yang_data structure.
 536  *
 537  * xpath
 538  *    Data path of the YANG data.
 539  *
 540  * value
 541  *    String representing the value of the YANG data.
 542  *
 543  * Returns:
 544  *    Pointer to newly created yang_data structure.
 545  */
 546 extern struct yang_data *yang_data_new(const char *xpath, const char *value);
 547
 548 /*
 549  * Delete a yang_data structure.
 550  *
 551  * data
 552  *    yang_data to delete.
 553  */
 554 extern void yang_data_free(struct yang_data *data);
 555
 556 /*
 557  * Create a new linked list of yang_data structures. The list 'del' callback is
 558  * initialized appropriately so that the entire list can be deleted safely with
 559  * list_delete_and_null().
 560  *
 561  * Returns:
 562  *    Pointer to newly created linked list.
 563  */
 564 extern struct list *yang_data_list_new(void);
 565
 566 /*
 567  * Find the yang_data structure corresponding to an XPath in a list.
 568  *
 569  * list
 570  *    list of yang_data structures to operate on.
 571  *
 572  * xpath_fmt
 573  *    XPath to search for (format string).
 574  *
 575  * Returns:
 576  *    Pointer to yang_data if found, NULL otherwise.
 577  */
 578 extern struct yang_data *yang_data_list_find(const struct list *list,
 579                                              const char *xpath_fmt, ...)
 580         PRINTFRR(2, 3);
 581
 582 /*
 583  * Create and set up a libyang context (for use by the translator)
 584  *
 585  * embedded_modules
 586  *    Specify whether libyang should attempt to look for embedded YANG modules.
 587  *
 588  * explicit_compile
 589  *    True if the caller will later call ly_ctx_compile to compile all loaded
 590  *    modules at once.
 591  */
 592 extern struct ly_ctx *yang_ctx_new_setup(bool embedded_modules,
 593                                          bool explicit_compile);
 594
 595 /*
 596  * Enable or disable libyang verbose debugging.
 597  *
 598  * enable
 599  *    When set to true, enable libyang verbose debugging, otherwise disable it.
 600  */
 601 extern void yang_debugging_set(bool enable);
 602
 603 /*
 604  * Print libyang error messages into the provided buffer.
 605  *
 606  * ly_ctx
 607  *    libyang context to operate on.
 608  *
 609  * buf
 610  *    Buffer to store the libyang error messages.
 611  *
 612  * buf_len
 613  *    Size of buf.
 614  *
 615  * Returns:
 616  *    The provided buffer.
 617  */
 618 extern const char *yang_print_errors(struct ly_ctx *ly_ctx, char *buf,
 619                                      size_t buf_len);
 620
 621 /*
 622  * Initialize the YANG subsystem. Should be called only once during the
 623  * daemon initialization process.
 624  *
 625  * embedded_modules
 626  *    Specify whether libyang should attempt to look for embedded YANG modules.
 627  * defer_compile
 628  *    Hold off on compiling modules until yang_init_loading_complete is called.
 629  */
 630 extern void yang_init(bool embedded_modules, bool defer_compile);
 631
 632 /*
 633  * Should be called after yang_init and all yang_module_load()s have been done,
 634  * compiles all modules loaded into the yang context.
 635  */
 636 extern void yang_init_loading_complete(void);
 637
 638 /*
 639  * Finish the YANG subsystem gracefully. Should be called only when the daemon
 640  * is exiting.
 641  */
 642 extern void yang_terminate(void);
 643
 644 /*
 645  * API to return the parent dnode having a given schema-node name
 646  * Use case: One has to access the parent dnode's private pointer
 647  * for a given child node.
 648  * For that there is a need to find parent dnode first.
 649  *
 650  * dnode The starting node to work on
 651  *
 652  * name  The name of container/list schema-node
 653  *
 654  * Returns The dnode matched with the given name
 655  */
 656 extern const struct lyd_node *
 657 yang_dnode_get_parent(const struct lyd_node *dnode, const char *name);
 658
 659
 660 /*
 661  * In some cases there is a need to auto delete the parent nodes
 662  * if the given node is last in the list.
 663  * It tries to delete all the parents in a given tree in a given module.
 664  * The use case is with static routes and route maps
 665  * example : ip route 1.1.1.1/32 ens33
 666  *           ip route 1.1.1.1/32 ens34
 667  * After this no ip route 1.1.1.1/32 ens34 came, now staticd
 668  * has to find out upto which level it has to delete the dnodes.
 669  * For this case it has to send delete nexthop
 670  * After this no ip route 1.1.1.1/32 ens33 came, now staticd has to
 671  * clear nexthop, path and route nodes.
 672  * The same scheme is required for routemaps also
 673  * dnode The starting node to work on
 674  *
 675  * Returns The final parent node selected for deletion
 676  */
 677 extern const struct lyd_node *
 678 yang_get_subtree_with_no_sibling(const struct lyd_node *dnode);
 679
 680 /* To get the relative position of a node in list */
 681 extern uint32_t yang_get_list_pos(const struct lyd_node *node);
 682
 683 /* To get the number of elements in a list
 684  *
 685  * dnode : The head of list
 686  * Returns : The number of dnodes present in the list
 687  */
 688 extern uint32_t yang_get_list_elements_count(const struct lyd_node *node);
 689
 690 /* API to check if the given node is last node in the list */
 691 bool yang_is_last_list_dnode(const struct lyd_node *dnode);
 692
 693 /* API to check if the given node is last node in the data tree level */
 694 bool yang_is_last_level_dnode(const struct lyd_node *dnode);
 695
 696 #ifdef __cplusplus
 697 }
 698 #endif
 699
 700 #endif /* _FRR_YANG_H_ */