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 thread *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  * Find first parent schema node which is a presence-container or a list
 215  * (non-presence containers are ignored).
 216  *
 217  * snode
 218  *    libyang schema node to operate on.
 219  *
 220  * Returns:
 221  *    The parent libyang schema node if found, or NULL if not found.
 222  */
 223 extern struct lysc_node *yang_snode_real_parent(const struct lysc_node *snode);
 224
 225 /*
 226  * Find first parent schema node which is a list.
 227  *
 228  * snode
 229  *    libyang schema node to operate on.
 230  *
 231  * Returns:
 232  *    The parent libyang schema node (list) if found, or NULL if not found.
 233  */
 234 extern struct lysc_node *yang_snode_parent_list(const struct lysc_node *snode);
 235
 236 /*
 237  * Check if the libyang schema node represents typeless data (e.g. containers,
 238  * leafs of type empty, etc).
 239  *
 240  * snode
 241  *    libyang schema node to operate on.
 242  *
 243  * Returns:
 244  *    true if the schema node represents typeless data, false otherwise.
 245  */
 246 extern bool yang_snode_is_typeless_data(const struct lysc_node *snode);
 247
 248 /*
 249  * Get the default value associated to a YANG leaf or leaf-list.
 250  *
 251  * snode
 252  *    libyang schema node to operate on.
 253  *
 254  * Returns:
 255  *    The default value if it exists, NULL otherwise.
 256  */
 257 extern const char *yang_snode_get_default(const struct lysc_node *snode);
 258
 259 /*
 260  * Get the type structure of a leaf of leaf-list. If the type is a leafref, the
 261  * final (if there is a chain of leafrefs) target's type is found.
 262  *
 263  * snode
 264  *    libyang schema node to operate on.
 265  *
 266  * Returns:
 267  *    The found type if the schema node represents a leaf or a leaf-list, NULL
 268  *    otherwise.
 269  */
 270 extern const struct lysc_type *
 271 yang_snode_get_type(const struct lysc_node *snode);
 272
 273 /*
 274  * Get the number of key nodes for the given list.
 275  *
 276  * snode
 277  *    libyang (LYS_LIST) schema node to operate on.
 278  *
 279  * Returns:
 280  *    The number of key LYS_LEAFs as children of this list node.
 281  */
 282 extern unsigned int yang_snode_num_keys(const struct lysc_node *snode);
 283
 284 #define LY_FOR_KEYS(snode, skey)                                               \
 285         for ((skey) = (const struct lysc_node_leaf *)lysc_node_child((snode)); \
 286              (skey); (skey) = (const struct lysc_node_leaf *)((skey)->next))   \
 287                 if (!lysc_is_key(skey)) {                                      \
 288                         break;                                                 \
 289                 } else
 290
 291
 292 /*
 293  * Build data path of the data node.
 294  *
 295  * dnode
 296  *    libyang data node to be processed.
 297  *
 298  * xpath
 299  *    Pointer to previously allocated buffer.
 300  *
 301  * xpath_len
 302  *    Size of the xpath buffer.
 303  */
 304 extern void yang_dnode_get_path(const struct lyd_node *dnode, char *xpath,
 305                                 size_t xpath_len);
 306
 307 /*
 308  * Return the schema name of the given libyang data node.
 309  *
 310  * dnode
 311  *    libyang data node.
 312  *
 313  * xpath_fmt
 314  *    Optional XPath expression (absolute or relative) to specify a different
 315  *    data node to operate on in the same data tree.
 316  *
 317  * Returns:
 318  *    Schema name of the libyang data node.
 319  */
 320 extern const char *yang_dnode_get_schema_name(const struct lyd_node *dnode,
 321                                               const char *xpath_fmt, ...)
 322         PRINTFRR(2, 3);
 323
 324 /*
 325  * Find a libyang data node by its YANG data path.
 326  *
 327  * dnode
 328  *    Base libyang data node to operate on.
 329  *
 330  * xpath
 331  *    Limited XPath (absolute or relative) string. See Path in libyang
 332  *    documentation for restrictions.
 333  *
 334  * Returns:
 335  *    The libyang data node if found, or NULL if not found.
 336  */
 337 extern struct lyd_node *yang_dnode_get(const struct lyd_node *dnode,
 338                                        const char *xpath);
 339
 340 /*
 341  * Find a libyang data node by its YANG data path.
 342  *
 343  * dnode
 344  *    Base libyang data node to operate on.
 345  *
 346  * xpath_fmt
 347  *    Limited XPath (absolute or relative) format string. See Path in libyang
 348  *    documentation for restrictions.
 349  *
 350  * ...
 351  *    any parameters for xpath_fmt.
 352  *
 353  * Returns:
 354  *    The libyang data node if found, or NULL if not found.
 355  */
 356 extern struct lyd_node *yang_dnode_getf(const struct lyd_node *dnode,
 357                                         const char *path_fmt, ...)
 358         PRINTFRR(2, 3);
 359
 360 /*
 361  * Check if a libyang data node exists.
 362  *
 363  * dnode
 364  *    Base libyang data node to operate on.
 365  *
 366  * xpath
 367  *    Limited XPath (absolute or relative) string. See Path in libyang
 368  *    documentation for restrictions.
 369  *
 370  * Returns:
 371  *    true if a libyang data node was found, false otherwise.
 372  */
 373 extern bool yang_dnode_exists(const struct lyd_node *dnode, const char *xpath);
 374
 375 /*
 376  * Check if a libyang data node exists.
 377  *
 378  * dnode
 379  *    Base libyang data node to operate on.
 380  *
 381  * xpath_fmt
 382  *    Limited XPath (absolute or relative) format string. See Path in
 383  *    libyang documentation for restrictions.
 384  *
 385  * ...
 386  *    any parameters for xpath_fmt.
 387  *
 388  * Returns:
 389  *    true if a libyang data node was found, false otherwise.
 390  */
 391 extern bool yang_dnode_existsf(const struct lyd_node *dnode,
 392                                const char *xpath_fmt, ...) PRINTFRR(2, 3);
 393
 394 /*
 395  * Iterate over all libyang data nodes that satisfy an XPath query.
 396  *
 397  * cb
 398  *    Function to call with each data node.
 399  *
 400  * arg
 401  *    Arbitrary argument passed as the second parameter in each call to 'cb'.
 402  *
 403  * dnode
 404  *    Base libyang data node to operate on.
 405  *
 406  * xpath_fmt
 407  *    XPath expression (absolute or relative).
 408  *
 409  * ...
 410  *    any parameters for xpath_fmt.
 411  */
 412 void yang_dnode_iterate(yang_dnode_iter_cb cb, void *arg,
 413                         const struct lyd_node *dnode, const char *xpath_fmt,
 414                         ...) PRINTFRR(4, 5);
 415
 416 /*
 417  * Check if the libyang data node contains a default value. Non-presence
 418  * containers are assumed to always contain a default value.
 419  *
 420  * dnode
 421  *    Base libyang data node to operate on.
 422  *
 423  * xpath
 424  *    Optional XPath expression (absolute or relative) to specify a different
 425  *    data node to operate on in the same data tree.
 426  *
 427  * Returns:
 428  *    true if the data node contains the default value, false otherwise.
 429  */
 430 extern bool yang_dnode_is_default(const struct lyd_node *dnode,
 431                                   const char *xpath);
 432
 433 /*
 434  * Check if the libyang data node contains a default value. Non-presence
 435  * containers are assumed to always contain a default value.
 436  *
 437  * dnode
 438  *    Base libyang data node to operate on.
 439  *
 440  * xpath
 441  *    Optional limited XPath (absolute or relative) format string. See Path in
 442  *    libyang documentation for restrictions.
 443  *
 444  * ...
 445  *    any parameters for xpath_fmt.
 446  *
 447  * Returns:
 448  *    true if the data node contains the default value, false otherwise.
 449  */
 450 extern bool yang_dnode_is_defaultf(const struct lyd_node *dnode,
 451                                    const char *xpath_fmt, ...) PRINTFRR(2, 3);
 452
 453 /*
 454  * Check if the libyang data node and all of its children contain default
 455  * values. Non-presence containers are assumed to always contain a default
 456  * value.
 457  *
 458  * dnode
 459  *    libyang data node to operate on.
 460  *
 461  * Returns:
 462  *    true if the data node and all of its children contain default values,
 463  *    false otherwise.
 464  */
 465 extern bool yang_dnode_is_default_recursive(const struct lyd_node *dnode);
 466
 467 /*
 468  * Change the value of a libyang leaf node.
 469  *
 470  * dnode
 471  *    libyang data node to operate on.
 472  *
 473  * value
 474  *    String representing the new value.
 475  */
 476 extern void yang_dnode_change_leaf(struct lyd_node *dnode, const char *value);
 477
 478 /*
 479  * Create a new libyang data node.
 480  *
 481  * ly_ctx
 482  *    libyang context to operate on.
 483  *
 484  * config
 485  *    Specify whether the data node will contain only configuration data (true)
 486  *    or both configuration data and state data (false).
 487  *
 488  * Returns:
 489  *    Pointer to newly created libyang data node.
 490  */
 491 extern struct lyd_node *yang_dnode_new(struct ly_ctx *ly_ctx, bool config_only);
 492
 493 /*
 494  * Duplicate a libyang data node.
 495  *
 496  * dnode
 497  *    libyang data node to duplicate.
 498  *
 499  * Returns:
 500  *    Pointer to duplicated libyang data node.
 501  */
 502 extern struct lyd_node *yang_dnode_dup(const struct lyd_node *dnode);
 503
 504 /*
 505  * Delete a libyang data node.
 506  *
 507  * dnode
 508  *    Pointer to the libyang data node that is going to be deleted along with
 509  *    the entire tree it belongs to.
 510  */
 511 extern void yang_dnode_free(struct lyd_node *dnode);
 512
 513 /*
 514  * Create a new yang_data structure.
 515  *
 516  * xpath
 517  *    Data path of the YANG data.
 518  *
 519  * value
 520  *    String representing the value of the YANG data.
 521  *
 522  * Returns:
 523  *    Pointer to newly created yang_data structure.
 524  */
 525 extern struct yang_data *yang_data_new(const char *xpath, const char *value);
 526
 527 /*
 528  * Delete a yang_data structure.
 529  *
 530  * data
 531  *    yang_data to delete.
 532  */
 533 extern void yang_data_free(struct yang_data *data);
 534
 535 /*
 536  * Create a new linked list of yang_data structures. The list 'del' callback is
 537  * initialized appropriately so that the entire list can be deleted safely with
 538  * list_delete_and_null().
 539  *
 540  * Returns:
 541  *    Pointer to newly created linked list.
 542  */
 543 extern struct list *yang_data_list_new(void);
 544
 545 /*
 546  * Find the yang_data structure corresponding to an XPath in a list.
 547  *
 548  * list
 549  *    list of yang_data structures to operate on.
 550  *
 551  * xpath_fmt
 552  *    XPath to search for (format string).
 553  *
 554  * Returns:
 555  *    Pointer to yang_data if found, NULL otherwise.
 556  */
 557 extern struct yang_data *yang_data_list_find(const struct list *list,
 558                                              const char *xpath_fmt, ...)
 559         PRINTFRR(2, 3);
 560
 561 /*
 562  * Create and set up a libyang context (for use by the translator)
 563  *
 564  * embedded_modules
 565  *    Specify whether libyang should attempt to look for embedded YANG modules.
 566  *
 567  * explicit_compile
 568  *    True if the caller will later call ly_ctx_compile to compile all loaded
 569  *    modules at once.
 570  */
 571 extern struct ly_ctx *yang_ctx_new_setup(bool embedded_modules,
 572                                          bool explicit_compile);
 573
 574 /*
 575  * Enable or disable libyang verbose debugging.
 576  *
 577  * enable
 578  *    When set to true, enable libyang verbose debugging, otherwise disable it.
 579  */
 580 extern void yang_debugging_set(bool enable);
 581
 582 /*
 583  * Print libyang error messages into the provided buffer.
 584  *
 585  * ly_ctx
 586  *    libyang context to operate on.
 587  *
 588  * buf
 589  *    Buffer to store the libyang error messages.
 590  *
 591  * buf_len
 592  *    Size of buf.
 593  *
 594  * Returns:
 595  *    The provided buffer.
 596  */
 597 extern const char *yang_print_errors(struct ly_ctx *ly_ctx, char *buf,
 598                                      size_t buf_len);
 599
 600 /*
 601  * Initialize the YANG subsystem. Should be called only once during the
 602  * daemon initialization process.
 603  *
 604  * embedded_modules
 605  *    Specify whether libyang should attempt to look for embedded YANG modules.
 606  * defer_compile
 607  *    Hold off on compiling modules until yang_init_loading_complete is called.
 608  */
 609 extern void yang_init(bool embedded_modules, bool defer_compile);
 610
 611 /*
 612  * Should be called after yang_init and all yang_module_load()s have been done,
 613  * compiles all modules loaded into the yang context.
 614  */
 615 extern void yang_init_loading_complete(void);
 616
 617 /*
 618  * Finish the YANG subsystem gracefully. Should be called only when the daemon
 619  * is exiting.
 620  */
 621 extern void yang_terminate(void);
 622
 623 /*
 624  * API to return the parent dnode having a given schema-node name
 625  * Use case: One has to access the parent dnode's private pointer
 626  * for a given child node.
 627  * For that there is a need to find parent dnode first.
 628  *
 629  * dnode The starting node to work on
 630  *
 631  * name  The name of container/list schema-node
 632  *
 633  * Returns The dnode matched with the given name
 634  */
 635 extern const struct lyd_node *
 636 yang_dnode_get_parent(const struct lyd_node *dnode, const char *name);
 637
 638
 639 /*
 640  * In some cases there is a need to auto delete the parent nodes
 641  * if the given node is last in the list.
 642  * It tries to delete all the parents in a given tree in a given module.
 643  * The use case is with static routes and route maps
 644  * example : ip route 1.1.1.1/32 ens33
 645  *           ip route 1.1.1.1/32 ens34
 646  * After this no ip route 1.1.1.1/32 ens34 came, now staticd
 647  * has to find out upto which level it has to delete the dnodes.
 648  * For this case it has to send delete nexthop
 649  * After this no ip route 1.1.1.1/32 ens33 came, now staticd has to
 650  * clear nexthop, path and route nodes.
 651  * The same scheme is required for routemaps also
 652  * dnode The starting node to work on
 653  *
 654  * Returns The final parent node selected for deletion
 655  */
 656 extern const struct lyd_node *
 657 yang_get_subtree_with_no_sibling(const struct lyd_node *dnode);
 658
 659 /* To get the relative position of a node in list */
 660 extern uint32_t yang_get_list_pos(const struct lyd_node *node);
 661
 662 /* To get the number of elements in a list
 663  *
 664  * dnode : The head of list
 665  * Returns : The number of dnodes present in the list
 666  */
 667 extern uint32_t yang_get_list_elements_count(const struct lyd_node *node);
 668
 669 /* API to check if the given node is last node in the list */
 670 bool yang_is_last_list_dnode(const struct lyd_node *dnode);
 671
 672 /* API to check if the given node is last node in the data tree level */
 673 bool yang_is_last_level_dnode(const struct lyd_node *dnode);
 674
 675 #ifdef __cplusplus
 676 }
 677 #endif
 678
 679 #endif /* _FRR_YANG_H_ */