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         /*
  73          * Schema information (necessary to interpret certain values like
  74          * enums).
  75          */
  76         const struct lys_node *snode;
  77
  78         /* Value encoded as a raw string. */
  79         char *value;
  80 };
  81
  82 struct yang_list_keys {
  83         /* Number os keys (max: LIST_MAXKEYS). */
  84         uint8_t num;
  85
  86         struct {
  87                 /*
  88                  * Schema information (necessary to interpret certain values
  89                  * like enums).
  90                  */
  91                 struct lys_node *snode;
  92
  93                 /* Value encoded as a raw string. */
  94                 char value[LIST_MAXKEYLEN];
  95         } key[LIST_MAXKEYS];
  96 };
  97
  98 enum yang_path_type {
  99         YANG_PATH_SCHEMA = 0,
 100         YANG_PATH_DATA,
 101 };
 102
 103 /* Filter non-presence containers. */
 104 #define YANG_ITER_FILTER_NPCONTAINERS 0x0001
 105 /* Filter list keys (leafs). */
 106 #define YANG_ITER_FILTER_LIST_KEYS 0x0002
 107 /* Filter RPC input/output nodes. */
 108 #define YANG_ITER_FILTER_INPUT_OUTPUT 0x0004
 109 /* Filter implicitely created nodes. */
 110 #define YANG_ITER_FILTER_IMPLICIT 0x0008
 111
 112 /* Global libyang context for native FRR models. */
 113 extern struct ly_ctx *ly_native_ctx;
 114
 115 /* Tree of all loaded YANG modules. */
 116 extern struct yang_modules yang_modules;
 117
 118 /*
 119  * Create a new YANG module and load it using libyang. If the YANG module is not
 120  * found in the YANG_MODELS_PATH directory, the program will exit with an error.
 121  * Once loaded, a YANG module can't be unloaded anymore.
 122  *
 123  * module_name
 124  *    Name of the YANG module.
 125  *
 126  * Returns:
 127  *    Pointer to newly created YANG module.
 128  */
 129 extern struct yang_module *yang_module_load(const char *module_name);
 130
 131 /*
 132  * Find a YANG module by its name.
 133  *
 134  * module_name
 135  *    Name of the YANG module.
 136  *
 137  * Returns:
 138  *    Pointer to YANG module if found, NULL otherwise.
 139  */
 140 extern struct yang_module *yang_module_find(const char *module_name);
 141
 142 /*
 143  * Register a YANG module embedded in the binary file.  Should be called
 144  * from a constructor function.
 145  *
 146  * embed
 147  *    YANG module embedding structure to register.  (static global provided
 148  *    by caller.)
 149  */
 150 extern void yang_module_embed(struct yang_module_embed *embed);
 151
 152 /*
 153  * Iterate over all libyang schema nodes from the given YANG module.
 154  *
 155  * module
 156  *    YANG module to operate on.
 157  *
 158  * func
 159  *    Function to call with each schema node.
 160  *
 161  * flags
 162  *    YANG_ITER_FILTER_* flags to specify node types that should be filtered.
 163  *
 164  * arg1
 165  *    Arbitrary argument passed as the second parameter in each call to 'func'.
 166  *
 167  * arg2
 168  *    Arbitrary argument passed as the third parameter in each call to 'func'.
 169  */
 170 extern void yang_module_snodes_iterate(const struct lys_module *module,
 171                                        void (*func)(const struct lys_node *,
 172                                                     void *, void *),
 173                                        uint16_t flags, void *arg1, void *arg2);
 174
 175 /*
 176  * Iterate over all libyang schema nodes from all loaded YANG modules.
 177  *
 178  * func
 179  *    Function to call with each schema node.
 180  *
 181  * flags
 182  *    YANG_ITER_FILTER_* flags to specify node types that should be filtered.
 183  *
 184  * arg1
 185  *    Arbitrary argument passed as the second parameter in each call to 'func'.
 186  *
 187  * arg2
 188  *    Arbitrary argument passed as the third parameter in each call to 'func'.
 189  */
 190 extern void yang_all_snodes_iterate(void (*func)(const struct lys_node *,
 191                                                  void *, void *),
 192                                     uint16_t flags, void *arg1, void *arg2);
 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 lys_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 lys_node *yang_snode_real_parent(const struct lys_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 lys_node *yang_snode_parent_list(const struct lys_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 lys_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 lys_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 lys_type *yang_snode_get_type(const struct lys_node *snode);
 271
 272 /*
 273  * Build data path of the data node.
 274  *
 275  * dnode
 276  *    libyang data node to be processed.
 277  *
 278  * xpath
 279  *    Pointer to previously allocated buffer.
 280  *
 281  * xpath_len
 282  *    Size of the xpath buffer.
 283  */
 284 extern void yang_dnode_get_path(const struct lyd_node *dnode, char *xpath,
 285                                 size_t xpath_len);
 286
 287 /*
 288  * Return the schema name of the given libyang data node.
 289  *
 290  * dnode
 291  *    libyang data node.
 292  *
 293  * xpath_fmt
 294  *    Optional XPath expression (absolute or relative) to specify a different
 295  *    data node to operate on in the same data tree.
 296  *
 297  * Returns:
 298  *    Schema name of the libyang data node.
 299  */
 300 extern const char *yang_dnode_get_schema_name(const struct lyd_node *dnode,
 301                                               const char *xpath_fmt, ...);
 302
 303 /*
 304  * Find a libyang data node by its YANG data path.
 305  *
 306  * dnode
 307  *    Base libyang data node to operate on.
 308  *
 309  * xpath_fmt
 310  *    XPath expression (absolute or relative).
 311  *
 312  * Returns:
 313  *    The libyang data node if found, or NULL if not found.
 314  */
 315 extern struct lyd_node *yang_dnode_get(const struct lyd_node *dnode,
 316                                        const char *xpath_fmt, ...);
 317
 318 /*
 319  * Check if a libyang data node exists.
 320  *
 321  * dnode
 322  *    Base libyang data node to operate on.
 323  *
 324  * xpath_fmt
 325  *    XPath expression (absolute or relative).
 326  *
 327  * Returns:
 328  *    true if the libyang data node was found, false otherwise.
 329  */
 330 extern bool yang_dnode_exists(const struct lyd_node *dnode,
 331                               const char *xpath_fmt, ...);
 332
 333 /*
 334  * Check if the libyang data node contains a default value. Non-presence
 335  * containers are assumed to always contain a default value.
 336  *
 337  * dnode
 338  *    Base libyang data node to operate on.
 339  *
 340  * xpath_fmt
 341  *    Optional XPath expression (absolute or relative) to specify a different
 342  *    data node to operate on in the same data tree.
 343  *
 344  * Returns:
 345  *    true if the data node contains the default value, false otherwise.
 346  */
 347 extern bool yang_dnode_is_default(const struct lyd_node *dnode,
 348                                   const char *xpath_fmt, ...);
 349
 350 /*
 351  * Check if the libyang data node and all of its children contain default
 352  * values. Non-presence containers are assumed to always contain a default
 353  * value.
 354  *
 355  * dnode
 356  *    libyang data node to operate on.
 357  *
 358  * Returns:
 359  *    true if the data node and all of its children contain default values,
 360  *    false otherwise.
 361  */
 362 extern bool yang_dnode_is_default_recursive(const struct lyd_node *dnode);
 363
 364 /*
 365  * Change the value of a libyang leaf node.
 366  *
 367  * dnode
 368  *    libyang data node to operate on.
 369  *
 370  * value
 371  *    String representing the new value.
 372  */
 373 extern void yang_dnode_change_leaf(struct lyd_node *dnode, const char *value);
 374
 375 /*
 376  * Set the libyang private pointer to a user pointer. Can only be used on YANG
 377  * lists and containers.
 378  *
 379  * dnode
 380  *    libyang data node to operate on.
 381  *
 382  * entry
 383  *    Arbitrary user-specified pointer.
 384  */
 385 extern void yang_dnode_set_entry(const struct lyd_node *dnode, void *entry);
 386
 387 /*
 388  * Find the user pointer associated to the given libyang data node.
 389  *
 390  * The data node is traversed by following the parent pointers until an user
 391  * pointer is found or until the root node is reached.
 392  *
 393  * dnode
 394  *    libyang data node to operate on.
 395  *
 396  * abort_if_not_found
 397  *    When set to true, abort the program if no user pointer is found.
 398  *
 399  *    As a rule of thumb, this parameter should be set to true in the following
 400  *    scenarios:
 401  *    - Calling this function from any northbound configuration callback during
 402  *      the NB_EV_APPLY phase.
 403  *    - Calling this function from a 'delete' northbound configuration callback
 404  *      during any phase.
 405  *
 406  *    In both the above cases, the libyang data node should contain an user
 407  *    pointer except when there's a bug in the code, in which case it's better
 408  *    to abort the program right away and eliminate the need for unnecessary
 409  *    NULL checks.
 410  *
 411  *    In all other cases, this parameter should be set to false and the caller
 412  *    should check if the function returned NULL or not.
 413  *
 414  * Returns:
 415  *    User pointer if found, NULL otherwise.
 416  */
 417 extern void *yang_dnode_get_entry(const struct lyd_node *dnode,
 418                                   bool abort_if_not_found);
 419
 420 /*
 421  * Create a new libyang data node.
 422  *
 423  * ly_ctx
 424  *    libyang context to operate on.
 425  *
 426  * Returns:
 427  *    Pointer to newly created libyang data node.
 428  */
 429 extern struct lyd_node *yang_dnode_new(struct ly_ctx *ly_ctx);
 430
 431 /*
 432  * Duplicate a libyang data node.
 433  *
 434  * dnode
 435  *    libyang data node to duplicate.
 436  *
 437  * Returns:
 438  *    Pointer to duplicated libyang data node.
 439  */
 440 extern struct lyd_node *yang_dnode_dup(const struct lyd_node *dnode);
 441
 442 /*
 443  * Delete a libyang data node.
 444  *
 445  * dnode
 446  *    Pointer to the libyang data node that is going to be deleted.
 447  */
 448 extern void yang_dnode_free(struct lyd_node *dnode);
 449
 450 /*
 451  * Create a new yang_data structure.
 452  *
 453  * xpath
 454  *    Data path of the YANG data.
 455  *
 456  * value
 457  *    String representing the value of the YANG data.
 458  *
 459  * Returns:
 460  *    Pointer to newly created yang_data structure.
 461  */
 462 extern struct yang_data *yang_data_new(const char *xpath, const char *value);
 463
 464 /*
 465  * Delete a yang_data structure.
 466  *
 467  * data
 468  *    yang_data to delete.
 469  */
 470 extern void yang_data_free(struct yang_data *data);
 471
 472 /*
 473  * Create a new linked list of yang_data structures. The list 'del' callback is
 474  * initialized appropriately so that the entire list can be deleted safely with
 475  * list_delete_and_null().
 476  *
 477  * Returns:
 478  *    Pointer to newly created linked list.
 479  */
 480 extern struct list *yang_data_list_new(void);
 481
 482 /*
 483  * Initialize the YANG subsystem. Should be called only once during the
 484  * daemon initialization process.
 485  */
 486 extern void yang_init(void);
 487
 488 /*
 489  * Finish the YANG subsystem gracefully. Should be called only when the daemon
 490  * is exiting.
 491  */
 492 extern void yang_terminate(void);
 493
 494 #endif /* _FRR_YANG_H_ */