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 DECLARE_MTYPE(YANG_MODULE)
  33 DECLARE_MTYPE(YANG_DATA)
  34
  35 /* Maximum XPath length. */
  36 #define XPATH_MAXLEN 256
  37
  38 /* Maximum list key length. */
  39 #define LIST_MAXKEYS 8
  40
  41 /* Maximum list key length. */
  42 #define LIST_MAXKEYLEN 128
  43
  44 /* Maximum string length of an YANG value. */
  45 #define YANG_VALUE_MAXLEN 1024
  46
  47 struct yang_module_embed {
  48         struct yang_module_embed *next;
  49         const char *mod_name, *mod_rev;
  50         const char *data;
  51         LYS_INFORMAT format;
  52 };
  53
  54 struct yang_module {
  55         RB_ENTRY(yang_module) entry;
  56         const char *name;
  57         const struct lys_module *info;
  58 #ifdef HAVE_CONFD
  59         int confd_hash;
  60 #endif
  61 #ifdef HAVE_SYSREPO
  62         sr_subscription_ctx_t *sr_subscription;
  63 #endif
  64 };
  65 RB_HEAD(yang_modules, yang_module);
  66 RB_PROTOTYPE(yang_modules, yang_module, entry, yang_module_compare);
  67
  68 struct yang_data {
  69         /* XPath identifier of the data element. */
  70         char xpath[XPATH_MAXLEN];
  71
  72         /* Value encoded as a raw string. */
  73         char *value;
  74 };
  75
  76 struct yang_list_keys {
  77         /* Number os keys (max: LIST_MAXKEYS). */
  78         uint8_t num;
  79
  80         /* Value encoded as a raw string. */
  81         char key[LIST_MAXKEYS][LIST_MAXKEYLEN];
  82 };
  83
  84 enum yang_path_type {
  85         YANG_PATH_SCHEMA = 0,
  86         YANG_PATH_DATA,
  87 };
  88
  89 enum yang_iter_flags {
  90         /* Filter non-presence containers. */
  91         YANG_ITER_FILTER_NPCONTAINERS = (1<<0),
  92
  93         /* Filter list keys (leafs). */
  94         YANG_ITER_FILTER_LIST_KEYS = (1<<1),
  95
  96         /* Filter RPC input/output nodes. */
  97         YANG_ITER_FILTER_INPUT_OUTPUT = (1<<2),
  98
  99         /* Filter implicitely created nodes. */
 100         YANG_ITER_FILTER_IMPLICIT = (1<<3),
 101
 102         /* Allow iteration over augmentations. */
 103         YANG_ITER_ALLOW_AUGMENTATIONS = (1<<4),
 104 };
 105
 106 /* Callback used by the yang_snodes_iterate_*() family of functions. */
 107 typedef int (*yang_iterate_cb)(const struct lys_node *snode, void *arg);
 108
 109 /* Return values of the 'yang_iterate_cb' callback. */
 110 #define YANG_ITER_CONTINUE 0
 111 #define YANG_ITER_STOP -1
 112
 113 /* Global libyang context for native FRR models. */
 114 extern struct ly_ctx *ly_native_ctx;
 115
 116 /* Tree of all loaded YANG modules. */
 117 extern struct yang_modules yang_modules;
 118
 119 /*
 120  * Create a new YANG module and load it using libyang. If the YANG module is not
 121  * found in the YANG_MODELS_PATH directory, the program will exit with an error.
 122  * Once loaded, a YANG module can't be unloaded anymore.
 123  *
 124  * module_name
 125  *    Name of the YANG module.
 126  *
 127  * Returns:
 128  *    Pointer to newly created YANG module.
 129  */
 130 extern struct yang_module *yang_module_load(const char *module_name);
 131
 132 /*
 133  * Load all FRR native YANG models.
 134  */
 135 extern void yang_module_load_all(void);
 136
 137 /*
 138  * Find a YANG module by its name.
 139  *
 140  * module_name
 141  *    Name of the YANG module.
 142  *
 143  * Returns:
 144  *    Pointer to YANG module if found, NULL otherwise.
 145  */
 146 extern struct yang_module *yang_module_find(const char *module_name);
 147
 148 /*
 149  * Register a YANG module embedded in the binary file.  Should be called
 150  * from a constructor function.
 151  *
 152  * embed
 153  *    YANG module embedding structure to register.  (static global provided
 154  *    by caller.)
 155  */
 156 extern void yang_module_embed(struct yang_module_embed *embed);
 157
 158 /*
 159  * Iterate recursively over all children of a schema node.
 160  *
 161  * snode
 162  *    YANG schema node to operate on.
 163  *
 164  * cb
 165  *    Function to call with each schema node.
 166  *
 167  * flags
 168  *    YANG_ITER_* flags to control how the iteration is performed.
 169  *
 170  * arg
 171  *    Arbitrary argument passed as the second parameter in each call to 'cb'.
 172  *
 173  * Returns:
 174  *    The return value of the last called callback.
 175  */
 176 extern int yang_snodes_iterate_subtree(const struct lys_node *snode,
 177                                        yang_iterate_cb cb, uint16_t flags,
 178                                        void *arg);
 179
 180 /*
 181  * Iterate over all libyang schema nodes from the given YANG module.
 182  *
 183  * module
 184  *    YANG module to operate on.
 185  *
 186  * cb
 187  *    Function to call with each schema node.
 188  *
 189  * flags
 190  *    YANG_ITER_* flags to control how the iteration is performed.
 191  *
 192  * arg
 193  *    Arbitrary argument passed as the second parameter in each call to 'cb'.
 194  *
 195  * Returns:
 196  *    The return value of the last called callback.
 197  */
 198 extern int yang_snodes_iterate_module(const struct lys_module *module,
 199                                       yang_iterate_cb cb, uint16_t flags,
 200                                       void *arg);
 201
 202 /*
 203  * Iterate over all libyang schema nodes from all loaded YANG modules.
 204  *
 205  * cb
 206  *    Function to call with each schema node.
 207  *
 208  * flags
 209  *    YANG_ITER_* flags to control how the iteration is performed.
 210  *
 211  * arg
 212  *    Arbitrary argument passed as the second parameter in each call to 'cb'.
 213  *
 214  * Returns:
 215  *    The return value of the last called callback.
 216  */
 217 extern int yang_snodes_iterate_all(yang_iterate_cb cb, uint16_t flags,
 218                                    void *arg);
 219
 220 /*
 221  * Build schema path or data path of the schema node.
 222  *
 223  * snode
 224  *    libyang schema node to be processed.
 225  *
 226  * type
 227  *    Specify whether a schema path or a data path should be built.
 228  *
 229  * xpath
 230  *    Pointer to previously allocated buffer.
 231  *
 232  * xpath_len
 233  *    Size of the xpath buffer.
 234  */
 235 extern void yang_snode_get_path(const struct lys_node *snode,
 236                                 enum yang_path_type type, char *xpath,
 237                                 size_t xpath_len);
 238
 239 /*
 240  * Find first parent schema node which is a presence-container or a list
 241  * (non-presence containers are ignored).
 242  *
 243  * snode
 244  *    libyang schema node to operate on.
 245  *
 246  * Returns:
 247  *    The parent libyang schema node if found, or NULL if not found.
 248  */
 249 extern struct lys_node *yang_snode_real_parent(const struct lys_node *snode);
 250
 251 /*
 252  * Find first parent schema node which is a list.
 253  *
 254  * snode
 255  *    libyang schema node to operate on.
 256  *
 257  * Returns:
 258  *    The parent libyang schema node (list) if found, or NULL if not found.
 259  */
 260 extern struct lys_node *yang_snode_parent_list(const struct lys_node *snode);
 261
 262 /*
 263  * Check if the libyang schema node represents typeless data (e.g. containers,
 264  * leafs of type empty, etc).
 265  *
 266  * snode
 267  *    libyang schema node to operate on.
 268  *
 269  * Returns:
 270  *    true if the schema node represents typeless data, false otherwise.
 271  */
 272 extern bool yang_snode_is_typeless_data(const struct lys_node *snode);
 273
 274 /*
 275  * Get the default value associated to a YANG leaf or leaf-list.
 276  *
 277  * snode
 278  *    libyang schema node to operate on.
 279  *
 280  * Returns:
 281  *    The default value if it exists, NULL otherwise.
 282  */
 283 extern const char *yang_snode_get_default(const struct lys_node *snode);
 284
 285 /*
 286  * Get the type structure of a leaf of leaf-list. If the type is a leafref, the
 287  * final (if there is a chain of leafrefs) target's type is found.
 288  *
 289  * snode
 290  *    libyang schema node to operate on.
 291  *
 292  * Returns:
 293  *    The found type if the schema node represents a leaf or a leaf-list, NULL
 294  *    otherwise.
 295  */
 296 extern const struct lys_type *yang_snode_get_type(const struct lys_node *snode);
 297
 298 /*
 299  * Build data path of the data node.
 300  *
 301  * dnode
 302  *    libyang data node to be processed.
 303  *
 304  * xpath
 305  *    Pointer to previously allocated buffer.
 306  *
 307  * xpath_len
 308  *    Size of the xpath buffer.
 309  */
 310 extern void yang_dnode_get_path(const struct lyd_node *dnode, char *xpath,
 311                                 size_t xpath_len);
 312
 313 /*
 314  * Return the schema name of the given libyang data node.
 315  *
 316  * dnode
 317  *    libyang data node.
 318  *
 319  * xpath_fmt
 320  *    Optional XPath expression (absolute or relative) to specify a different
 321  *    data node to operate on in the same data tree.
 322  *
 323  * Returns:
 324  *    Schema name of the libyang data node.
 325  */
 326 extern const char *yang_dnode_get_schema_name(const struct lyd_node *dnode,
 327                                               const char *xpath_fmt, ...);
 328
 329 /*
 330  * Find a libyang data node by its YANG data path.
 331  *
 332  * dnode
 333  *    Base libyang data node to operate on.
 334  *
 335  * xpath_fmt
 336  *    XPath expression (absolute or relative).
 337  *
 338  * Returns:
 339  *    The libyang data node if found, or NULL if not found.
 340  */
 341 extern struct lyd_node *yang_dnode_get(const struct lyd_node *dnode,
 342                                        const char *xpath_fmt, ...);
 343
 344 /*
 345  * Check if a libyang data node exists.
 346  *
 347  * dnode
 348  *    Base libyang data node to operate on.
 349  *
 350  * xpath_fmt
 351  *    XPath expression (absolute or relative).
 352  *
 353  * Returns:
 354  *    true if the libyang data node was found, false otherwise.
 355  */
 356 extern bool yang_dnode_exists(const struct lyd_node *dnode,
 357                               const char *xpath_fmt, ...);
 358
 359 /*
 360  * Check if the libyang data node contains a default value. Non-presence
 361  * containers are assumed to always contain a default value.
 362  *
 363  * dnode
 364  *    Base libyang data node to operate on.
 365  *
 366  * xpath_fmt
 367  *    Optional XPath expression (absolute or relative) to specify a different
 368  *    data node to operate on in the same data tree.
 369  *
 370  * Returns:
 371  *    true if the data node contains the default value, false otherwise.
 372  */
 373 extern bool yang_dnode_is_default(const struct lyd_node *dnode,
 374                                   const char *xpath_fmt, ...);
 375
 376 /*
 377  * Check if the libyang data node and all of its children contain default
 378  * values. Non-presence containers are assumed to always contain a default
 379  * value.
 380  *
 381  * dnode
 382  *    libyang data node to operate on.
 383  *
 384  * Returns:
 385  *    true if the data node and all of its children contain default values,
 386  *    false otherwise.
 387  */
 388 extern bool yang_dnode_is_default_recursive(const struct lyd_node *dnode);
 389
 390 /*
 391  * Change the value of a libyang leaf node.
 392  *
 393  * dnode
 394  *    libyang data node to operate on.
 395  *
 396  * value
 397  *    String representing the new value.
 398  */
 399 extern void yang_dnode_change_leaf(struct lyd_node *dnode, const char *value);
 400
 401 /*
 402  * Set the libyang private pointer to a user pointer. Can only be used on YANG
 403  * lists and containers.
 404  *
 405  * dnode
 406  *    libyang data node to operate on.
 407  *
 408  * entry
 409  *    Arbitrary user-specified pointer.
 410  */
 411 extern void yang_dnode_set_entry(const struct lyd_node *dnode, void *entry);
 412
 413 /*
 414  * Find the user pointer associated to the given libyang data node.
 415  *
 416  * The data node is traversed by following the parent pointers until an user
 417  * pointer is found or until the root node is reached.
 418  *
 419  * dnode
 420  *    libyang data node to operate on.
 421  *
 422  * abort_if_not_found
 423  *    When set to true, abort the program if no user pointer is found.
 424  *
 425  *    As a rule of thumb, this parameter should be set to true in the following
 426  *    scenarios:
 427  *    - Calling this function from any northbound configuration callback during
 428  *      the NB_EV_APPLY phase.
 429  *    - Calling this function from a 'delete' northbound configuration callback
 430  *      during any phase.
 431  *
 432  *    In both the above cases, the libyang data node should contain an user
 433  *    pointer except when there's a bug in the code, in which case it's better
 434  *    to abort the program right away and eliminate the need for unnecessary
 435  *    NULL checks.
 436  *
 437  *    In all other cases, this parameter should be set to false and the caller
 438  *    should check if the function returned NULL or not.
 439  *
 440  * Returns:
 441  *    User pointer if found, NULL otherwise.
 442  */
 443 extern void *yang_dnode_get_entry(const struct lyd_node *dnode,
 444                                   bool abort_if_not_found);
 445
 446 /*
 447  * Create a new libyang data node.
 448  *
 449  * ly_ctx
 450  *    libyang context to operate on.
 451  *
 452  * config
 453  *    Specify whether the data node will contain only configuration data (true)
 454  *    or both configuration data and state data (false).
 455  *
 456  * Returns:
 457  *    Pointer to newly created libyang data node.
 458  */
 459 extern struct lyd_node *yang_dnode_new(struct ly_ctx *ly_ctx, bool config_only);
 460
 461 /*
 462  * Duplicate a libyang data node.
 463  *
 464  * dnode
 465  *    libyang data node to duplicate.
 466  *
 467  * Returns:
 468  *    Pointer to duplicated libyang data node.
 469  */
 470 extern struct lyd_node *yang_dnode_dup(const struct lyd_node *dnode);
 471
 472 /*
 473  * Delete a libyang data node.
 474  *
 475  * dnode
 476  *    Pointer to the libyang data node that is going to be deleted.
 477  */
 478 extern void yang_dnode_free(struct lyd_node *dnode);
 479
 480 /*
 481  * Create a new yang_data structure.
 482  *
 483  * xpath
 484  *    Data path of the YANG data.
 485  *
 486  * value
 487  *    String representing the value of the YANG data.
 488  *
 489  * Returns:
 490  *    Pointer to newly created yang_data structure.
 491  */
 492 extern struct yang_data *yang_data_new(const char *xpath, const char *value);
 493
 494 /*
 495  * Delete a yang_data structure.
 496  *
 497  * data
 498  *    yang_data to delete.
 499  */
 500 extern void yang_data_free(struct yang_data *data);
 501
 502 /*
 503  * Create a new linked list of yang_data structures. The list 'del' callback is
 504  * initialized appropriately so that the entire list can be deleted safely with
 505  * list_delete_and_null().
 506  *
 507  * Returns:
 508  *    Pointer to newly created linked list.
 509  */
 510 extern struct list *yang_data_list_new(void);
 511
 512 /*
 513  * Initialize the YANG subsystem. Should be called only once during the
 514  * daemon initialization process.
 515  */
 516 extern void yang_init(void);
 517
 518 /*
 519  * Finish the YANG subsystem gracefully. Should be called only when the daemon
 520  * is exiting.
 521  */
 522 extern void yang_terminate(void);
 523
 524 #endif /* _FRR_YANG_H_ */