blob: bb72f0bff414cf277bc71fdea267796aa23487d4 [file] [log] [blame]
Michal Vasko60ea6352020-06-29 13:39:39 +02001/**
2 * @file lyb.h
3 * @author Michal Vasko <mvasko@cesnet.cz>
4 * @brief Header for LYB format printer & parser
5 *
6 * Copyright (c) 2020 CESNET, z.s.p.o.
7 *
8 * This source code is licensed under BSD 3-Clause License (the "License").
9 * You may not use this file except in compliance with the License.
10 * You may obtain a copy of the License at
11 *
12 * https://opensource.org/licenses/BSD-3-Clause
13 */
14
15#ifndef LY_LYB_H_
16#define LY_LYB_H_
17
18#include <stddef.h>
19#include <stdint.h>
20
Radek Krejci1798aae2020-07-14 13:26:06 +020021#include "parser_internal.h"
Michal Vasko60ea6352020-06-29 13:39:39 +020022#include "set.h"
23#include "tree.h"
24
25struct hash_table;
26struct ly_ctx;
27struct lyd_node;
28struct lysc_node;
29
Radek Krejci1798aae2020-07-14 13:26:06 +020030struct lylyb_ctx {
31 const struct ly_ctx *ctx;
32 uint64_t line; /* current line */
33 struct ly_in *in; /* input structure */
34
35 const struct lys_module **models;
36
Michal Vasko60ea6352020-06-29 13:39:39 +020037 struct lyd_lyb_subtree {
38 size_t written;
39 size_t position;
40 uint8_t inner_chunks;
41 } *subtrees;
Michal Vaskofd69e1d2020-07-03 11:57:17 +020042 LY_ARRAY_COUNT_TYPE subtree_size;
Michal Vasko60ea6352020-06-29 13:39:39 +020043
Michal Vasko60ea6352020-06-29 13:39:39 +020044 /* LYB printer only */
45 struct lyd_lyb_sib_ht {
46 struct lysc_node *first_sibling;
47 struct hash_table *ht;
48 } *sib_hts;
49};
50
51/**
Radek Krejci1798aae2020-07-14 13:26:06 +020052 * @brief Internal structure for LYB parser/printer.
53 *
54 * Note that the structure maps to the lyd_ctx which is common for all the data parsers
55 */
56struct lyd_lyb_ctx {
57 union {
58 struct {
59 uint32_t parse_options; /**< various @ref dataparseroptions. */
60 uint32_t validate_options; /**< various @ref datavalidationoptions. */
61 };
62 uint32_t print_options;
63 };
64 uint32_t int_opts; /**< internal data parser options */
65 uint32_t path_len; /**< used bytes in the path buffer */
66 char path[LYD_PARSER_BUFSIZE]; /**< buffer for the generated path */
67 struct ly_set unres_node_type; /**< set of nodes validated with LY_EINCOMPLETE result */
68 struct ly_set unres_meta_type; /**< set of metadata validated with LY_EINCOMPLETE result */
69 struct ly_set when_check; /**< set of nodes with "when" conditions */
70 struct lyd_node *op_node; /**< if an RPC/action/notification is being parsed, store the pointer to it */
71
72 /* callbacks */
73 lyd_ctx_free_clb free; /* destructor */
Radek Krejci1798aae2020-07-14 13:26:06 +020074
75 struct lylyb_ctx *lybctx; /* lyb format context */
76};
77
78/**
79 * @brief Destructor for the lylyb_ctx structure
80 */
81void lyd_lyb_ctx_free(struct lyd_ctx *lydctx);
82
83/**
Michal Vasko60ea6352020-06-29 13:39:39 +020084 * LYB format
85 *
86 * Unlike XML or JSON, it is binary format so most data are represented in similar way but in binary.
87 * Some notable differences:
88 *
89 * - schema nodes are identified based on their hash instead of their string name. In case of collisions
90 * an array of hashes is created with each next hash one bit shorter until a unique sequence of all these
91 * hashes is found and then all of them are stored.
92 *
93 * - tree structure is represented as individual strictly bounded subtrees. Each subtree begins
94 * with its metadata, which consist of 1) the whole subtree length in bytes and 2) number
95 * of included metadata chunks of nested subtrees.
96 *
97 * - since length of a subtree is not known before it is printed, holes are first written and
98 * after the subtree is printed, they are filled with actual valid metadata. As a consequence,
99 * LYB data cannot be directly printed into streams!
100 *
101 * - data are preceded with information about all the used modules. It is needed because of
102 * possible augments and deviations which must be known beforehand, otherwise schema hashes
103 * could be matched to the wrong nodes.
104 */
105
106/* just a shortcut */
Michal Vaskofd69e1d2020-07-03 11:57:17 +0200107#define LYB_LAST_SUBTREE(lybctx) lybctx->subtrees[LY_ARRAY_COUNT(lybctx->subtrees) - 1]
Michal Vasko60ea6352020-06-29 13:39:39 +0200108
109/* struct lyd_lyb_subtree allocation step */
110#define LYB_SUBTREE_STEP 4
111
112/* current LYB format version */
113#define LYB_VERSION_NUM 0x10
114
115/* LYB format version mask of the header byte */
116#define LYB_VERSION_MASK 0x10
117
118/**
119 * LYB schema hash constants
120 *
121 * Hash is divided to collision ID and hash itself.
122 *
123 * First bits are collision ID until 1 is found. The rest is truncated 32b hash.
124 * 1xxx xxxx - collision ID 0 (no collisions)
125 * 01xx xxxx - collision ID 1 (collision ID 0 hash collided)
126 * 001x xxxx - collision ID 2 ...
127 */
128
129/* Number of bits the whole hash will take (including hash collision ID) */
130#define LYB_HASH_BITS 8
131
132/* Masking 32b hash (collision ID 0) */
133#define LYB_HASH_MASK 0x7f
134
135/* Type for storing the whole hash (used only internally, publicly defined directly) */
136#define LYB_HASH uint8_t
137
138/* Need to move this first >> collision number (from 0) to get collision ID hash part */
139#define LYB_HASH_COLLISION_ID 0x80
140
141/* How many bytes are reserved for one data chunk SIZE (8B is maximum) */
142#define LYB_SIZE_BYTES 1
143
144/* Maximum size that will be written into LYB_SIZE_BYTES (must be large enough) */
145#define LYB_SIZE_MAX UINT8_MAX
146
147/* How many bytes are reserved for one data chunk inner chunk count */
148#define LYB_INCHUNK_BYTES 1
149
150/* Maximum size that will be written into LYB_INCHUNK_BYTES (must be large enough) */
151#define LYB_INCHUNK_MAX UINT8_MAX
152
153/* Just a helper macro */
154#define LYB_META_BYTES (LYB_INCHUNK_BYTES + LYB_SIZE_BYTES)
Radek Krejcif13b87b2020-12-01 22:02:17 +0100155#define LYB_BYTE_MASK 0xff
156
157/* model revision as XXXX XXXX XXXX XXXX (2B) (year is offset from 2000)
158 * YYYY YYYM MMMD DDDD */
159#define LYB_REV_YEAR_OFFSET 2000
160#define LYB_REV_YEAR_MASK 0xfe00U
161#define LYB_REV_YEAR_SHIFT 9
162#define LYB_REV_MONTH_MASK 0x01E0U
163#define LYB_REV_MONTH_SHIFT 5
164#define LYB_REV_DAY_MASK 0x001fU
Michal Vasko60ea6352020-06-29 13:39:39 +0200165
166/* Type large enough for all meta data */
167#define LYB_META uint16_t
168
169#endif /* LY_LYB_H_ */