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         PRINTFRR(2, 3);
 336
 337 /*
 338  * Find a libyang data node by its YANG data path.
 339  *
 340  * dnode
 341  *    Base libyang data node to operate on.
 342  *
 343  * xpath
 344  *    Limited XPath (absolute or relative) string. See Path in libyang
 345  *    documentation for restrictions.
 346  *
 347  * Returns:
 348  *    The libyang data node if found, or NULL if not found.
 349  */
 350 extern struct lyd_node *yang_dnode_get(const struct lyd_node *dnode,
 351                                        const char *xpath);
 352
 353 /*
 354  * Find a libyang data node by its YANG data path.
 355  *
 356  * dnode
 357  *    Base libyang data node to operate on.
 358  *
 359  * xpath_fmt
 360  *    Limited XPath (absolute or relative) format string. See Path in libyang
 361  *    documentation for restrictions.
 362  *
 363  * ...
 364  *    any parameters for xpath_fmt.
 365  *
 366  * Returns:
 367  *    The libyang data node if found, or NULL if not found.
 368  */
 369 extern struct lyd_node *yang_dnode_getf(const struct lyd_node *dnode,
 370                                         const char *path_fmt, ...)
 371         PRINTFRR(2, 3);
 372
 373 /*
 374  * Check if a libyang data node exists.
 375  *
 376  * dnode
 377  *    Base libyang data node to operate on.
 378  *
 379  * xpath
 380  *    Limited XPath (absolute or relative) string. See Path in libyang
 381  *    documentation for restrictions.
 382  *
 383  * Returns:
 384  *    true if a libyang data node was found, false otherwise.
 385  */
 386 extern bool yang_dnode_exists(const struct lyd_node *dnode, const char *xpath);
 387
 388 /*
 389  * Check if a libyang data node exists.
 390  *
 391  * dnode
 392  *    Base libyang data node to operate on.
 393  *
 394  * xpath_fmt
 395  *    Limited XPath (absolute or relative) format string. See Path in
 396  *    libyang documentation for restrictions.
 397  *
 398  * ...
 399  *    any parameters for xpath_fmt.
 400  *
 401  * Returns:
 402  *    true if a libyang data node was found, false otherwise.
 403  */
 404 extern bool yang_dnode_existsf(const struct lyd_node *dnode,
 405                                const char *xpath_fmt, ...) PRINTFRR(2, 3);
 406
 407 /*
 408  * Iterate over all libyang data nodes that satisfy an XPath query.
 409  *
 410  * cb
 411  *    Function to call with each data node.
 412  *
 413  * arg
 414  *    Arbitrary argument passed as the second parameter in each call to 'cb'.
 415  *
 416  * dnode
 417  *    Base libyang data node to operate on.
 418  *
 419  * xpath_fmt
 420  *    XPath expression (absolute or relative).
 421  *
 422  * ...
 423  *    any parameters for xpath_fmt.
 424  */
 425 void yang_dnode_iterate(yang_dnode_iter_cb cb, void *arg,
 426                         const struct lyd_node *dnode, const char *xpath_fmt,
 427                         ...) PRINTFRR(4, 5);
 428
 429 /*
 430  * Check if the libyang data node contains a default value. Non-presence
 431  * containers are assumed to always contain a default value.
 432  *
 433  * dnode
 434  *    Base libyang data node to operate on.
 435  *
 436  * xpath
 437  *    Optional XPath expression (absolute or relative) to specify a different
 438  *    data node to operate on in the same data tree.
 439  *
 440  * Returns:
 441  *    true if the data node contains the default value, false otherwise.
 442  */
 443 extern bool yang_dnode_is_default(const struct lyd_node *dnode,
 444                                   const char *xpath);
 445
 446 /*
 447  * Check if the libyang data node contains a default value. Non-presence
 448  * containers are assumed to always contain a default value.
 449  *
 450  * dnode
 451  *    Base libyang data node to operate on.
 452  *
 453  * xpath
 454  *    Optional limited XPath (absolute or relative) format string. See Path in
 455  *    libyang documentation for restrictions.
 456  *
 457  * ...
 458  *    any parameters for xpath_fmt.
 459  *
 460  * Returns:
 461  *    true if the data node contains the default value, false otherwise.
 462  */
 463 extern bool yang_dnode_is_defaultf(const struct lyd_node *dnode,
 464                                    const char *xpath_fmt, ...) PRINTFRR(2, 3);
 465
 466 /*
 467  * Check if the libyang data node and all of its children contain default
 468  * values. Non-presence containers are assumed to always contain a default
 469  * value.
 470  *
 471  * dnode
 472  *    libyang data node to operate on.
 473  *
 474  * Returns:
 475  *    true if the data node and all of its children contain default values,
 476  *    false otherwise.
 477  */
 478 extern bool yang_dnode_is_default_recursive(const struct lyd_node *dnode);
 479
 480 /*
 481  * Change the value of a libyang leaf node.
 482  *
 483  * dnode
 484  *    libyang data node to operate on.
 485  *
 486  * value
 487  *    String representing the new value.
 488  */
 489 extern void yang_dnode_change_leaf(struct lyd_node *dnode, const char *value);
 490
 491 /*
 492  * Create a new libyang data node.
 493  *
 494  * ly_ctx
 495  *    libyang context to operate on.
 496  *
 497  * config
 498  *    Specify whether the data node will contain only configuration data (true)
 499  *    or both configuration data and state data (false).
 500  *
 501  * Returns:
 502  *    Pointer to newly created libyang data node.
 503  */
 504 extern struct lyd_node *yang_dnode_new(struct ly_ctx *ly_ctx, bool config_only);
 505
 506 /*
 507  * Duplicate a libyang data node.
 508  *
 509  * dnode
 510  *    libyang data node to duplicate.
 511  *
 512  * Returns:
 513  *    Pointer to duplicated libyang data node.
 514  */
 515 extern struct lyd_node *yang_dnode_dup(const struct lyd_node *dnode);
 516
 517 /*
 518  * Delete a libyang data node.
 519  *
 520  * dnode
 521  *    Pointer to the libyang data node that is going to be deleted along with
 522  *    the entire tree it belongs to.
 523  */
 524 extern void yang_dnode_free(struct lyd_node *dnode);
 525
 526 /*
 527  * Create a new yang_data structure.
 528  *
 529  * xpath
 530  *    Data path of the YANG data.
 531  *
 532  * value
 533  *    String representing the value of the YANG data.
 534  *
 535  * Returns:
 536  *    Pointer to newly created yang_data structure.
 537  */
 538 extern struct yang_data *yang_data_new(const char *xpath, const char *value);
 539
 540 /*
 541  * Delete a yang_data structure.
 542  *
 543  * data
 544  *    yang_data to delete.
 545  */
 546 extern void yang_data_free(struct yang_data *data);
 547
 548 /*
 549  * Create a new linked list of yang_data structures. The list 'del' callback is
 550  * initialized appropriately so that the entire list can be deleted safely with
 551  * list_delete_and_null().
 552  *
 553  * Returns:
 554  *    Pointer to newly created linked list.
 555  */
 556 extern struct list *yang_data_list_new(void);
 557
 558 /*
 559  * Find the yang_data structure corresponding to an XPath in a list.
 560  *
 561  * list
 562  *    list of yang_data structures to operate on.
 563  *
 564  * xpath_fmt
 565  *    XPath to search for (format string).
 566  *
 567  * Returns:
 568  *    Pointer to yang_data if found, NULL otherwise.
 569  */
 570 extern struct yang_data *yang_data_list_find(const struct list *list,
 571                                              const char *xpath_fmt, ...)
 572         PRINTFRR(2, 3);
 573
 574 /*
 575  * Create and set up a libyang context (for use by the translator)
 576  *
 577  * embedded_modules
 578  *    Specify whether libyang should attempt to look for embedded YANG modules.
 579  *
 580  * explicit_compile
 581  *    True if the caller will later call ly_ctx_compile to compile all loaded
 582  *    modules at once.
 583  */
 584 extern struct ly_ctx *yang_ctx_new_setup(bool embedded_modules,
 585                                          bool explicit_compile);
 586
 587 /*
 588  * Enable or disable libyang verbose debugging.
 589  *
 590  * enable
 591  *    When set to true, enable libyang verbose debugging, otherwise disable it.
 592  */
 593 extern void yang_debugging_set(bool enable);
 594
 595 /*
 596  * Print libyang error messages into the provided buffer.
 597  *
 598  * ly_ctx
 599  *    libyang context to operate on.
 600  *
 601  * buf
 602  *    Buffer to store the libyang error messages.
 603  *
 604  * buf_len
 605  *    Size of buf.
 606  *
 607  * Returns:
 608  *    The provided buffer.
 609  */
 610 extern const char *yang_print_errors(struct ly_ctx *ly_ctx, char *buf,
 611                                      size_t buf_len);
 612
 613 /*
 614  * Initialize the YANG subsystem. Should be called only once during the
 615  * daemon initialization process.
 616  *
 617  * embedded_modules
 618  *    Specify whether libyang should attempt to look for embedded YANG modules.
 619  * defer_compile
 620  *    Hold off on compiling modules until yang_init_loading_complete is called.
 621  */
 622 extern void yang_init(bool embedded_modules, bool defer_compile);
 623
 624 /*
 625  * Should be called after yang_init and all yang_module_load()s have been done,
 626  * compiles all modules loaded into the yang context.
 627  */
 628 extern void yang_init_loading_complete(void);
 629
 630 /*
 631  * Finish the YANG subsystem gracefully. Should be called only when the daemon
 632  * is exiting.
 633  */
 634 extern void yang_terminate(void);
 635
 636 /*
 637  * API to return the parent dnode having a given schema-node name
 638  * Use case: One has to access the parent dnode's private pointer
 639  * for a given child node.
 640  * For that there is a need to find parent dnode first.
 641  *
 642  * dnode The starting node to work on
 643  *
 644  * name  The name of container/list schema-node
 645  *
 646  * Returns The dnode matched with the given name
 647  */
 648 extern const struct lyd_node *
 649 yang_dnode_get_parent(const struct lyd_node *dnode, const char *name);
 650
 651
 652 /*
 653  * In some cases there is a need to auto delete the parent nodes
 654  * if the given node is last in the list.
 655  * It tries to delete all the parents in a given tree in a given module.
 656  * The use case is with static routes and route maps
 657  * example : ip route 1.1.1.1/32 ens33
 658  *           ip route 1.1.1.1/32 ens34
 659  * After this no ip route 1.1.1.1/32 ens34 came, now staticd
 660  * has to find out upto which level it has to delete the dnodes.
 661  * For this case it has to send delete nexthop
 662  * After this no ip route 1.1.1.1/32 ens33 came, now staticd has to
 663  * clear nexthop, path and route nodes.
 664  * The same scheme is required for routemaps also
 665  * dnode The starting node to work on
 666  *
 667  * Returns The final parent node selected for deletion
 668  */
 669 extern const struct lyd_node *
 670 yang_get_subtree_with_no_sibling(const struct lyd_node *dnode);
 671
 672 /* To get the relative position of a node in list */
 673 extern uint32_t yang_get_list_pos(const struct lyd_node *node);
 674
 675 /* To get the number of elements in a list
 676  *
 677  * dnode : The head of list
 678  * Returns : The number of dnodes present in the list
 679  */
 680 extern uint32_t yang_get_list_elements_count(const struct lyd_node *node);
 681
 682 /* API to check if the given node is last node in the list */
 683 bool yang_is_last_list_dnode(const struct lyd_node *dnode);
 684
 685 /* API to check if the given node is last node in the data tree level */
 686 bool yang_is_last_level_dnode(const struct lyd_node *dnode);
 687
 688 #ifdef __cplusplus
 689 }
 690 #endif
 691
 692 #endif /* _FRR_YANG_H_ */