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