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 256
  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 *data;
  52         LYS_INFORMAT format;
  53 };
  54
  55 struct yang_module {
  56         RB_ENTRY(yang_module) entry;
  57         const char *name;
  58         const struct lys_module *info;
  59 #ifdef HAVE_CONFD
  60         int confd_hash;
  61 #endif
  62 #ifdef HAVE_SYSREPO
  63         sr_subscription_ctx_t *sr_subscription;
  64 #endif
  65 };
  66 RB_HEAD(yang_modules, yang_module);
  67 RB_PROTOTYPE(yang_modules, yang_module, entry, yang_module_compare);
  68
  69 struct yang_data {
  70         /* XPath identifier of the data element. */
  71         char xpath[XPATH_MAXLEN];
  72
  73         /* Value encoded as a raw string. */
  74         char *value;
  75 };
  76
  77 struct yang_list_keys {
  78         /* Number os keys (max: LIST_MAXKEYS). */
  79         uint8_t num;
  80
  81         /* Value encoded as a raw string. */
  82         char key[LIST_MAXKEYS][LIST_MAXKEYLEN];
  83 };
  84
  85 enum yang_path_type {
  86         YANG_PATH_SCHEMA = 0,
  87         YANG_PATH_DATA,
  88 };
  89
  90 enum yang_iter_flags {
  91         /* Filter non-presence containers. */
  92         YANG_ITER_FILTER_NPCONTAINERS = (1<<0),
  93
  94         /* Filter list keys (leafs). */
  95         YANG_ITER_FILTER_LIST_KEYS = (1<<1),
  96
  97         /* Filter RPC input/output nodes. */
  98         YANG_ITER_FILTER_INPUT_OUTPUT = (1<<2),
  99
 100         /* Filter implicitely created nodes. */
 101         YANG_ITER_FILTER_IMPLICIT = (1<<3),
 102
 103         /* Allow iteration over augmentations. */
 104         YANG_ITER_ALLOW_AUGMENTATIONS = (1<<4),
 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 /* 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  * cb
 166  *    Function to call with each schema node.
 167  *
 168  * flags
 169  *    YANG_ITER_* flags to control how the iteration is performed.
 170  *
 171  * arg
 172  *    Arbitrary argument passed as the second parameter in each call to 'cb'.
 173  *
 174  * Returns:
 175  *    The return value of the last called callback.
 176  */
 177 extern int yang_snodes_iterate_subtree(const struct lys_node *snode,
 178                                        yang_iterate_cb cb, uint16_t flags,
 179                                        void *arg);
 180
 181 /*
 182  * Iterate over all libyang schema nodes from the given YANG module.
 183  *
 184  * module
 185  *    YANG module to operate on.
 186  *
 187  * cb
 188  *    Function to call with each schema node.
 189  *
 190  * flags
 191  *    YANG_ITER_* flags to control how the iteration is performed.
 192  *
 193  * arg
 194  *    Arbitrary argument passed as the second parameter in each call to 'cb'.
 195  *
 196  * Returns:
 197  *    The return value of the last called callback.
 198  */
 199 extern int yang_snodes_iterate_module(const struct lys_module *module,
 200                                       yang_iterate_cb cb, uint16_t flags,
 201                                       void *arg);
 202
 203 /*
 204  * Iterate over all libyang schema nodes from all loaded YANG modules.
 205  *
 206  * cb
 207  *    Function to call with each schema node.
 208  *
 209  * flags
 210  *    YANG_ITER_* flags to control how the iteration is performed.
 211  *
 212  * arg
 213  *    Arbitrary argument passed as the second parameter in each call to 'cb'.
 214  *
 215  * Returns:
 216  *    The return value of the last called callback.
 217  */
 218 extern int yang_snodes_iterate_all(yang_iterate_cb cb, uint16_t flags,
 219                                    void *arg);
 220
 221 /*
 222  * Build schema path or data path of the schema node.
 223  *
 224  * snode
 225  *    libyang schema node to be processed.
 226  *
 227  * type
 228  *    Specify whether a schema path or a data path should be built.
 229  *
 230  * xpath
 231  *    Pointer to previously allocated buffer.
 232  *
 233  * xpath_len
 234  *    Size of the xpath buffer.
 235  */
 236 extern void yang_snode_get_path(const struct lys_node *snode,
 237                                 enum yang_path_type type, char *xpath,
 238                                 size_t xpath_len);
 239
 240 /*
 241  * Find first parent schema node which is a presence-container or a list
 242  * (non-presence containers are ignored).
 243  *
 244  * snode
 245  *    libyang schema node to operate on.
 246  *
 247  * Returns:
 248  *    The parent libyang schema node if found, or NULL if not found.
 249  */
 250 extern struct lys_node *yang_snode_real_parent(const struct lys_node *snode);
 251
 252 /*
 253  * Find first parent schema node which is a list.
 254  *
 255  * snode
 256  *    libyang schema node to operate on.
 257  *
 258  * Returns:
 259  *    The parent libyang schema node (list) if found, or NULL if not found.
 260  */
 261 extern struct lys_node *yang_snode_parent_list(const struct lys_node *snode);
 262
 263 /*
 264  * Check if the libyang schema node represents typeless data (e.g. containers,
 265  * leafs of type empty, etc).
 266  *
 267  * snode
 268  *    libyang schema node to operate on.
 269  *
 270  * Returns:
 271  *    true if the schema node represents typeless data, false otherwise.
 272  */
 273 extern bool yang_snode_is_typeless_data(const struct lys_node *snode);
 274
 275 /*
 276  * Get the default value associated to a YANG leaf or leaf-list.
 277  *
 278  * snode
 279  *    libyang schema node to operate on.
 280  *
 281  * Returns:
 282  *    The default value if it exists, NULL otherwise.
 283  */
 284 extern const char *yang_snode_get_default(const struct lys_node *snode);
 285
 286 /*
 287  * Get the type structure of a leaf of leaf-list. If the type is a leafref, the
 288  * final (if there is a chain of leafrefs) target's type is found.
 289  *
 290  * snode
 291  *    libyang schema node to operate on.
 292  *
 293  * Returns:
 294  *    The found type if the schema node represents a leaf or a leaf-list, NULL
 295  *    otherwise.
 296  */
 297 extern const struct lys_type *yang_snode_get_type(const struct lys_node *snode);
 298
 299 /*
 300  * Build data path of the data node.
 301  *
 302  * dnode
 303  *    libyang data node to be processed.
 304  *
 305  * xpath
 306  *    Pointer to previously allocated buffer.
 307  *
 308  * xpath_len
 309  *    Size of the xpath buffer.
 310  */
 311 extern void yang_dnode_get_path(const struct lyd_node *dnode, char *xpath,
 312                                 size_t xpath_len);
 313
 314 /*
 315  * Return the schema name of the given libyang data node.
 316  *
 317  * dnode
 318  *    libyang data node.
 319  *
 320  * xpath_fmt
 321  *    Optional XPath expression (absolute or relative) to specify a different
 322  *    data node to operate on in the same data tree.
 323  *
 324  * Returns:
 325  *    Schema name of the libyang data node.
 326  */
 327 extern const char *yang_dnode_get_schema_name(const struct lyd_node *dnode,
 328                                               const char *xpath_fmt, ...);
 329
 330 /*
 331  * Find a libyang data node by its YANG data path.
 332  *
 333  * dnode
 334  *    Base libyang data node to operate on.
 335  *
 336  * xpath_fmt
 337  *    XPath expression (absolute or relative).
 338  *
 339  * Returns:
 340  *    The libyang data node if found, or NULL if not found.
 341  */
 342 extern struct lyd_node *yang_dnode_get(const struct lyd_node *dnode,
 343                                        const char *xpath_fmt, ...);
 344
 345 /*
 346  * Check if a libyang data node exists.
 347  *
 348  * dnode
 349  *    Base libyang data node to operate on.
 350  *
 351  * xpath_fmt
 352  *    XPath expression (absolute or relative).
 353  *
 354  * Returns:
 355  *    true if the libyang data node was found, false otherwise.
 356  */
 357 extern bool yang_dnode_exists(const struct lyd_node *dnode,
 358                               const char *xpath_fmt, ...);
 359
 360 /*
 361  * Check if the libyang data node contains a default value. Non-presence
 362  * containers are assumed to always contain a default value.
 363  *
 364  * dnode
 365  *    Base libyang data node to operate on.
 366  *
 367  * xpath_fmt
 368  *    Optional XPath expression (absolute or relative) to specify a different
 369  *    data node to operate on in the same data tree.
 370  *
 371  * Returns:
 372  *    true if the data node contains the default value, false otherwise.
 373  */
 374 extern bool yang_dnode_is_default(const struct lyd_node *dnode,
 375                                   const char *xpath_fmt, ...);
 376
 377 /*
 378  * Check if the libyang data node and all of its children contain default
 379  * values. Non-presence containers are assumed to always contain a default
 380  * value.
 381  *
 382  * dnode
 383  *    libyang data node to operate on.
 384  *
 385  * Returns:
 386  *    true if the data node and all of its children contain default values,
 387  *    false otherwise.
 388  */
 389 extern bool yang_dnode_is_default_recursive(const struct lyd_node *dnode);
 390
 391 /*
 392  * Change the value of a libyang leaf node.
 393  *
 394  * dnode
 395  *    libyang data node to operate on.
 396  *
 397  * value
 398  *    String representing the new value.
 399  */
 400 extern void yang_dnode_change_leaf(struct lyd_node *dnode, const char *value);
 401
 402 /*
 403  * Create a new libyang data node.
 404  *
 405  * ly_ctx
 406  *    libyang context to operate on.
 407  *
 408  * config
 409  *    Specify whether the data node will contain only configuration data (true)
 410  *    or both configuration data and state data (false).
 411  *
 412  * Returns:
 413  *    Pointer to newly created libyang data node.
 414  */
 415 extern struct lyd_node *yang_dnode_new(struct ly_ctx *ly_ctx, bool config_only);
 416
 417 /*
 418  * Duplicate a libyang data node.
 419  *
 420  * dnode
 421  *    libyang data node to duplicate.
 422  *
 423  * Returns:
 424  *    Pointer to duplicated libyang data node.
 425  */
 426 extern struct lyd_node *yang_dnode_dup(const struct lyd_node *dnode);
 427
 428 /*
 429  * Delete a libyang data node.
 430  *
 431  * dnode
 432  *    Pointer to the libyang data node that is going to be deleted.
 433  */
 434 extern void yang_dnode_free(struct lyd_node *dnode);
 435
 436 /*
 437  * Create a new yang_data structure.
 438  *
 439  * xpath
 440  *    Data path of the YANG data.
 441  *
 442  * value
 443  *    String representing the value of the YANG data.
 444  *
 445  * Returns:
 446  *    Pointer to newly created yang_data structure.
 447  */
 448 extern struct yang_data *yang_data_new(const char *xpath, const char *value);
 449
 450 /*
 451  * Delete a yang_data structure.
 452  *
 453  * data
 454  *    yang_data to delete.
 455  */
 456 extern void yang_data_free(struct yang_data *data);
 457
 458 /*
 459  * Create a new linked list of yang_data structures. The list 'del' callback is
 460  * initialized appropriately so that the entire list can be deleted safely with
 461  * list_delete_and_null().
 462  *
 463  * Returns:
 464  *    Pointer to newly created linked list.
 465  */
 466 extern struct list *yang_data_list_new(void);
 467
 468 /*
 469  * Find the yang_data structure corresponding to an XPath in a list.
 470  *
 471  * list
 472  *    list of yang_data structures to operate on.
 473  *
 474  * xpath_fmt
 475  *    XPath to search for (format string).
 476  *
 477  * Returns:
 478  *    Pointer to yang_data if found, NULL otherwise.
 479  */
 480 extern struct yang_data *yang_data_list_find(const struct list *list,
 481                                              const char *xpath_fmt, ...);
 482
 483 /*
 484  * Create and set up a libyang context (for use by the translator)
 485  */
 486 extern struct ly_ctx *yang_ctx_new_setup(void);
 487
 488 /*
 489  * Enable or disable libyang verbose debugging.
 490  *
 491  * enable
 492  *    When set to true, enable libyang verbose debugging, otherwise disable it.
 493  */
 494 extern void yang_debugging_set(bool enable);
 495
 496 /*
 497  * Initialize the YANG subsystem. Should be called only once during the
 498  * daemon initialization process.
 499  */
 500 extern void yang_init(void);
 501
 502 /*
 503  * Finish the YANG subsystem gracefully. Should be called only when the daemon
 504  * is exiting.
 505  */
 506 extern void yang_terminate(void);
 507
 508 #ifdef __cplusplus
 509 }
 510 #endif
 511
 512 #endif /* _FRR_YANG_H_ */