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         /* Filter implicitely created nodes. */
 104         YANG_ITER_FILTER_IMPLICIT = (1<<3),
 105 };
 106
 107 /* Callback used by the yang_snodes_iterate_*() family of functions. */
 108 typedef int (*yang_iterate_cb)(const struct lys_node *snode, void *arg);
 109
 110 /* Callback used by the yang_dnode_iterate() function. */
 111 typedef int (*yang_dnode_iter_cb)(const struct lyd_node *dnode, 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  * module
 169  *    When set, iterate over all nodes of the specified module only.
 170  *
 171  * cb
 172  *    Function to call with each schema node.
 173  *
 174  * flags
 175  *    YANG_ITER_* flags to control how the iteration is performed.
 176  *
 177  * arg
 178  *    Arbitrary argument passed as the second parameter in each call to 'cb'.
 179  *
 180  * Returns:
 181  *    The return value of the last called callback.
 182  */
 183 extern int yang_snodes_iterate_subtree(const struct lys_node *snode,
 184                                        const struct lys_module *module,
 185                                        yang_iterate_cb cb, uint16_t flags,
 186                                        void *arg);
 187
 188 /*
 189  * Iterate over all libyang schema nodes from the given YANG module.
 190  *
 191  * module
 192  *    YANG module to operate on.
 193  *
 194  * cb
 195  *    Function to call with each schema node.
 196  *
 197  * flags
 198  *    YANG_ITER_* flags to control how the iteration is performed.
 199  *
 200  * arg
 201  *    Arbitrary argument passed as the second parameter in each call to 'cb'.
 202  *
 203  * Returns:
 204  *    The return value of the last called callback.
 205  */
 206 extern int yang_snodes_iterate_module(const struct lys_module *module,
 207                                       yang_iterate_cb cb, uint16_t flags,
 208                                       void *arg);
 209
 210 /*
 211  * Iterate over all libyang schema nodes from all loaded YANG modules.
 212  *
 213  * cb
 214  *    Function to call with each schema node.
 215  *
 216  * flags
 217  *    YANG_ITER_* flags to control how the iteration is performed.
 218  *
 219  * arg
 220  *    Arbitrary argument passed as the second parameter in each call to 'cb'.
 221  *
 222  * Returns:
 223  *    The return value of the last called callback.
 224  */
 225 extern int yang_snodes_iterate_all(yang_iterate_cb cb, uint16_t flags,
 226                                    void *arg);
 227
 228 /*
 229  * Build schema path or data path of the schema node.
 230  *
 231  * snode
 232  *    libyang schema node to be processed.
 233  *
 234  * type
 235  *    Specify whether a schema path or a data path should be built.
 236  *
 237  * xpath
 238  *    Pointer to previously allocated buffer.
 239  *
 240  * xpath_len
 241  *    Size of the xpath buffer.
 242  */
 243 extern void yang_snode_get_path(const struct lys_node *snode,
 244                                 enum yang_path_type type, char *xpath,
 245                                 size_t xpath_len);
 246
 247 /*
 248  * Find first parent schema node which is a presence-container or a list
 249  * (non-presence containers are ignored).
 250  *
 251  * snode
 252  *    libyang schema node to operate on.
 253  *
 254  * Returns:
 255  *    The parent libyang schema node if found, or NULL if not found.
 256  */
 257 extern struct lys_node *yang_snode_real_parent(const struct lys_node *snode);
 258
 259 /*
 260  * Find first parent schema node which is a list.
 261  *
 262  * snode
 263  *    libyang schema node to operate on.
 264  *
 265  * Returns:
 266  *    The parent libyang schema node (list) if found, or NULL if not found.
 267  */
 268 extern struct lys_node *yang_snode_parent_list(const struct lys_node *snode);
 269
 270 /*
 271  * Check if the libyang schema node represents typeless data (e.g. containers,
 272  * leafs of type empty, etc).
 273  *
 274  * snode
 275  *    libyang schema node to operate on.
 276  *
 277  * Returns:
 278  *    true if the schema node represents typeless data, false otherwise.
 279  */
 280 extern bool yang_snode_is_typeless_data(const struct lys_node *snode);
 281
 282 /*
 283  * Get the default value associated to a YANG leaf or leaf-list.
 284  *
 285  * snode
 286  *    libyang schema node to operate on.
 287  *
 288  * Returns:
 289  *    The default value if it exists, NULL otherwise.
 290  */
 291 extern const char *yang_snode_get_default(const struct lys_node *snode);
 292
 293 /*
 294  * Get the type structure of a leaf of leaf-list. If the type is a leafref, the
 295  * final (if there is a chain of leafrefs) target's type is found.
 296  *
 297  * snode
 298  *    libyang schema node to operate on.
 299  *
 300  * Returns:
 301  *    The found type if the schema node represents a leaf or a leaf-list, NULL
 302  *    otherwise.
 303  */
 304 extern const struct lys_type *yang_snode_get_type(const struct lys_node *snode);
 305
 306 /*
 307  * Build data path of the data node.
 308  *
 309  * dnode
 310  *    libyang data node to be processed.
 311  *
 312  * xpath
 313  *    Pointer to previously allocated buffer.
 314  *
 315  * xpath_len
 316  *    Size of the xpath buffer.
 317  */
 318 extern void yang_dnode_get_path(const struct lyd_node *dnode, char *xpath,
 319                                 size_t xpath_len);
 320
 321 /*
 322  * Return the schema name of the given libyang data node.
 323  *
 324  * dnode
 325  *    libyang data node.
 326  *
 327  * xpath_fmt
 328  *    Optional XPath expression (absolute or relative) to specify a different
 329  *    data node to operate on in the same data tree.
 330  *
 331  * Returns:
 332  *    Schema name of the libyang data node.
 333  */
 334 extern const char *yang_dnode_get_schema_name(const struct lyd_node *dnode,
 335                                               const char *xpath_fmt, ...);
 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_fmt
 344  *    XPath expression (absolute or relative).
 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_fmt, ...);
 351
 352 /*
 353  * Check if a libyang data node exists.
 354  *
 355  * dnode
 356  *    Base libyang data node to operate on.
 357  *
 358  * xpath_fmt
 359  *    XPath expression (absolute or relative).
 360  *
 361  * Returns:
 362  *    true if the libyang data node was found, false otherwise.
 363  */
 364 extern bool yang_dnode_exists(const struct lyd_node *dnode,
 365                               const char *xpath_fmt, ...);
 366
 367 /*
 368  * Iterate over all libyang data nodes that satisfy an XPath query.
 369  *
 370  * cb
 371  *    Function to call with each data node.
 372  *
 373  * arg
 374  *    Arbitrary argument passed as the second parameter in each call to 'cb'.
 375  *
 376  * dnode
 377  *    Base libyang data node to operate on.
 378  *
 379  * xpath_fmt
 380  *    XPath expression (absolute or relative).
 381  */
 382 void yang_dnode_iterate(yang_dnode_iter_cb cb, void *arg,
 383                         const struct lyd_node *dnode, const char *xpath_fmt,
 384                         ...);
 385
 386 /*
 387  * Check if the libyang data node contains a default value. Non-presence
 388  * containers are assumed to always contain a default value.
 389  *
 390  * dnode
 391  *    Base libyang data node to operate on.
 392  *
 393  * xpath_fmt
 394  *    Optional XPath expression (absolute or relative) to specify a different
 395  *    data node to operate on in the same data tree.
 396  *
 397  * Returns:
 398  *    true if the data node contains the default value, false otherwise.
 399  */
 400 extern bool yang_dnode_is_default(const struct lyd_node *dnode,
 401                                   const char *xpath_fmt, ...);
 402
 403 /*
 404  * Check if the libyang data node and all of its children contain default
 405  * values. Non-presence containers are assumed to always contain a default
 406  * value.
 407  *
 408  * dnode
 409  *    libyang data node to operate on.
 410  *
 411  * Returns:
 412  *    true if the data node and all of its children contain default values,
 413  *    false otherwise.
 414  */
 415 extern bool yang_dnode_is_default_recursive(const struct lyd_node *dnode);
 416
 417 /*
 418  * Change the value of a libyang leaf node.
 419  *
 420  * dnode
 421  *    libyang data node to operate on.
 422  *
 423  * value
 424  *    String representing the new value.
 425  */
 426 extern void yang_dnode_change_leaf(struct lyd_node *dnode, const char *value);
 427
 428 /*
 429  * Create a new libyang data node.
 430  *
 431  * ly_ctx
 432  *    libyang context to operate on.
 433  *
 434  * config
 435  *    Specify whether the data node will contain only configuration data (true)
 436  *    or both configuration data and state data (false).
 437  *
 438  * Returns:
 439  *    Pointer to newly created libyang data node.
 440  */
 441 extern struct lyd_node *yang_dnode_new(struct ly_ctx *ly_ctx, bool config_only);
 442
 443 /*
 444  * Duplicate a libyang data node.
 445  *
 446  * dnode
 447  *    libyang data node to duplicate.
 448  *
 449  * Returns:
 450  *    Pointer to duplicated libyang data node.
 451  */
 452 extern struct lyd_node *yang_dnode_dup(const struct lyd_node *dnode);
 453
 454 /*
 455  * Delete a libyang data node.
 456  *
 457  * dnode
 458  *    Pointer to the libyang data node that is going to be deleted.
 459  */
 460 extern void yang_dnode_free(struct lyd_node *dnode);
 461
 462 /*
 463  * Create a new yang_data structure.
 464  *
 465  * xpath
 466  *    Data path of the YANG data.
 467  *
 468  * value
 469  *    String representing the value of the YANG data.
 470  *
 471  * Returns:
 472  *    Pointer to newly created yang_data structure.
 473  */
 474 extern struct yang_data *yang_data_new(const char *xpath, const char *value);
 475
 476 /*
 477  * Delete a yang_data structure.
 478  *
 479  * data
 480  *    yang_data to delete.
 481  */
 482 extern void yang_data_free(struct yang_data *data);
 483
 484 /*
 485  * Create a new linked list of yang_data structures. The list 'del' callback is
 486  * initialized appropriately so that the entire list can be deleted safely with
 487  * list_delete_and_null().
 488  *
 489  * Returns:
 490  *    Pointer to newly created linked list.
 491  */
 492 extern struct list *yang_data_list_new(void);
 493
 494 /*
 495  * Find the yang_data structure corresponding to an XPath in a list.
 496  *
 497  * list
 498  *    list of yang_data structures to operate on.
 499  *
 500  * xpath_fmt
 501  *    XPath to search for (format string).
 502  *
 503  * Returns:
 504  *    Pointer to yang_data if found, NULL otherwise.
 505  */
 506 extern struct yang_data *yang_data_list_find(const struct list *list,
 507                                              const char *xpath_fmt, ...);
 508
 509 /*
 510  * Create and set up a libyang context (for use by the translator)
 511  *
 512  * embedded_modules
 513  *    Specify whether libyang should attempt to look for embedded YANG modules.
 514  */
 515 extern struct ly_ctx *yang_ctx_new_setup(bool embedded_modules);
 516
 517 /*
 518  * Enable or disable libyang verbose debugging.
 519  *
 520  * enable
 521  *    When set to true, enable libyang verbose debugging, otherwise disable it.
 522  */
 523 extern void yang_debugging_set(bool enable);
 524
 525 /*
 526  * Print libyang error messages into the provided buffer.
 527  *
 528  * ly_ctx
 529  *    libyang context to operate on.
 530  *
 531  * buf
 532  *    Buffer to store the libyang error messages.
 533  *
 534  * buf_len
 535  *    Size of buf.
 536  *
 537  * Returns:
 538  *    The provided buffer.
 539  */
 540 extern const char *yang_print_errors(struct ly_ctx *ly_ctx, char *buf,
 541                                      size_t buf_len);
 542
 543 /*
 544  * Initialize the YANG subsystem. Should be called only once during the
 545  * daemon initialization process.
 546  *
 547  * embedded_modules
 548  *    Specify whether libyang should attempt to look for embedded YANG modules.
 549  */
 550 extern void yang_init(bool embedded_modules);
 551
 552 /*
 553  * Finish the YANG subsystem gracefully. Should be called only when the daemon
 554  * is exiting.
 555  */
 556 extern void yang_terminate(void);
 557
 558 /*
 559  * API to return the parent dnode having a given schema-node name
 560  * Use case: One has to access the parent dnode's private pointer
 561  * for a given child node.
 562  * For that there is a need to find parent dnode first.
 563  *
 564  * dnode The starting node to work on
 565  *
 566  * name  The name of container/list schema-node
 567  *
 568  * Returns The dnode matched with the given name
 569  */
 570 extern const struct lyd_node *
 571 yang_dnode_get_parent(const struct lyd_node *dnode, const char *name);
 572
 573
 574 /*
 575  * In some cases there is a need to auto delete the parent nodes
 576  * if the given node is last in the list.
 577  * It tries to delete all the parents in a given tree in a given module.
 578  * The use case is with static routes and route maps
 579  * example : ip route 1.1.1.1/32 ens33
 580  *           ip route 1.1.1.1/32 ens34
 581  * After this no ip route 1.1.1.1/32 ens34 came, now staticd
 582  * has to find out upto which level it has to delete the dnodes.
 583  * For this case it has to send delete nexthop
 584  * After this no ip route 1.1.1.1/32 ens33 came, now staticd has to
 585  * clear nexthop, path and route nodes.
 586  * The same scheme is required for routemaps also
 587  * dnode The starting node to work on
 588  *
 589  * Returns The final parent node selected for deletion
 590  */
 591 extern const struct lyd_node *
 592 yang_get_subtree_with_no_sibling(const struct lyd_node *dnode);
 593
 594 /* To get the relative position of a node in list */
 595 extern uint32_t yang_get_list_pos(const struct lyd_node *node);
 596
 597 /* To get the number of elements in a list
 598  *
 599  * dnode : The head of list
 600  * Returns : The number of dnodes present in the list
 601  */
 602 extern uint32_t yang_get_list_elements_count(const struct lyd_node *node);
 603
 604
 605 /* To get the immediate child of a dnode */
 606 const struct lyd_node *yang_dnode_get_child(const struct lyd_node *dnode);
 607
 608
 609 #ifdef __cplusplus
 610 }
 611 #endif
 612
 613 #endif /* _FRR_YANG_H_ */