blob: 67f76c7d43d167635449819228d47e1ba21fbbe8 [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
Michal Vasko60ea6352020-06-29 13:39:39 +020023struct ly_ctx;
Michal Vasko60ea6352020-06-29 13:39:39 +020024struct lysc_node;
25
aPiecek3cd6abe2021-09-30 13:31:54 +020026/*
27 * LYB format
28 *
29 * Unlike XML or JSON, it is binary format so most data are represented in similar way but in binary.
30 * Some notable differences:
31 *
32 * - schema nodes are identified based on their hash instead of their string name. In case of collisions
33 * an array of hashes is created with each next hash one bit shorter until a unique sequence of all these
34 * hashes is found and then all of them are stored.
35 *
36 * - tree structure is represented as individual strictly bounded "siblings". Each "siblings" begins
37 * with its metadata, which consist of 1) the whole "sibling" length in bytes and 2) number
38 * of included metadata chunks of nested "siblings".
39 *
40 * - since length of a "sibling" is not known before it is printed, holes are first written and
41 * after the "sibling" is printed, they are filled with actual valid metadata. As a consequence,
42 * LYB data cannot be directly printed into streams!
43 *
44 * - data are preceded with information about all the used modules. It is needed because of
45 * possible augments and deviations which must be known beforehand, otherwise schema hashes
46 * could be matched to the wrong nodes.
47 *
48 * This is a short summary of the format:
49 * @verbatim
50
51 sb = siblings_start
52 se = siblings_end
53 siblings = zero-LYB_SIZE_BYTES | (sb instance+ se)
Michal Vasko9883a3e2022-03-31 12:16:00 +020054 instance = node_type model hash node
aPiecek3cd6abe2021-09-30 13:31:54 +020055 model = 16bit_zero | (model_name_length model_name revision)
56 node = opaq | leaflist | list | any | inner | leaf
57 opaq = opaq_data siblings
58 leaflist = sb leaf+ se
59 list = sb (node_header siblings)+ se
60 any = node_header anydata_data
61 inner = node_header siblings
62 leaf = node_header term_value
63 node_header = metadata node_flags
64
65 @endverbatim
66 */
67
Michal Vasko03fbaed2021-07-15 09:18:32 +020068/**
Michal Vasko9883a3e2022-03-31 12:16:00 +020069 * @brief LYB data node type
70 */
71enum lylyb_node_type {
72 LYB_NODE_TOP, /**< top-level node */
73 LYB_NODE_CHILD, /**< child node with a parent */
74 LYB_NODE_OPAQ, /**< opaque node */
75 LYB_NODE_EXT /**< nested extension data node */
76};
77
78/**
Michal Vasko03fbaed2021-07-15 09:18:32 +020079 * @brief LYB format parser context
80 */
Radek Krejci1798aae2020-07-14 13:26:06 +020081struct lylyb_ctx {
82 const struct ly_ctx *ctx;
83 uint64_t line; /* current line */
84 struct ly_in *in; /* input structure */
85
86 const struct lys_module **models;
87
aPiecek570d7ed2021-09-10 07:15:35 +020088 struct lyd_lyb_sibling {
Michal Vasko60ea6352020-06-29 13:39:39 +020089 size_t written;
90 size_t position;
aPiecek6828a312021-09-17 15:53:18 +020091 uint16_t inner_chunks;
aPiecek570d7ed2021-09-10 07:15:35 +020092 } *siblings;
93 LY_ARRAY_COUNT_TYPE sibling_size;
Michal Vasko60ea6352020-06-29 13:39:39 +020094
Michal Vasko60ea6352020-06-29 13:39:39 +020095 /* LYB printer only */
96 struct lyd_lyb_sib_ht {
97 struct lysc_node *first_sibling;
98 struct hash_table *ht;
99 } *sib_hts;
100};
101
102/**
Radek Krejci1798aae2020-07-14 13:26:06 +0200103 * @brief Destructor for the lylyb_ctx structure
104 */
105void lyd_lyb_ctx_free(struct lyd_ctx *lydctx);
106
Michal Vasko60ea6352020-06-29 13:39:39 +0200107/* just a shortcut */
aPiecek570d7ed2021-09-10 07:15:35 +0200108#define LYB_LAST_SIBLING(lybctx) lybctx->siblings[LY_ARRAY_COUNT(lybctx->siblings) - 1]
Michal Vasko60ea6352020-06-29 13:39:39 +0200109
aPiecek570d7ed2021-09-10 07:15:35 +0200110/* struct lyd_lyb_sibling allocation step */
111#define LYB_SIBLING_STEP 4
Michal Vasko60ea6352020-06-29 13:39:39 +0200112
113/* current LYB format version */
Michal Vasko9883a3e2022-03-31 12:16:00 +0200114#define LYB_VERSION_NUM 0x04
Michal Vasko60ea6352020-06-29 13:39:39 +0200115
116/* LYB format version mask of the header byte */
aPiecek20127bf2021-09-10 11:24:58 +0200117#define LYB_VERSION_MASK 0x0F
Michal Vasko60ea6352020-06-29 13:39:39 +0200118
119/**
120 * LYB schema hash constants
121 *
122 * Hash is divided to collision ID and hash itself.
123 *
Michal Vasko11f76c82021-04-15 14:36:14 +0200124 * @anchor collisionid
125 *
Michal Vasko60ea6352020-06-29 13:39:39 +0200126 * First bits are collision ID until 1 is found. The rest is truncated 32b hash.
127 * 1xxx xxxx - collision ID 0 (no collisions)
128 * 01xx xxxx - collision ID 1 (collision ID 0 hash collided)
129 * 001x xxxx - collision ID 2 ...
Michal Vasko11f76c82021-04-15 14:36:14 +0200130 *
131 * When finding a match for a unique schema (siblings) hash (sequence of hashes with increasing collision ID), the highest
132 * collision ID can be read from the last hash (LYB parser).
133 *
134 * To learn what is the highest collision ID of a hash that must be included in a unique schema (siblings) hash,
135 * collisions with all the preceding sibling schema hashes must be checked (LYB printer).
Michal Vasko60ea6352020-06-29 13:39:39 +0200136 */
137
138/* Number of bits the whole hash will take (including hash collision ID) */
139#define LYB_HASH_BITS 8
140
141/* Masking 32b hash (collision ID 0) */
142#define LYB_HASH_MASK 0x7f
143
144/* Type for storing the whole hash (used only internally, publicly defined directly) */
145#define LYB_HASH uint8_t
146
147/* Need to move this first >> collision number (from 0) to get collision ID hash part */
148#define LYB_HASH_COLLISION_ID 0x80
149
150/* How many bytes are reserved for one data chunk SIZE (8B is maximum) */
aPiecek6828a312021-09-17 15:53:18 +0200151#define LYB_SIZE_BYTES 2
Michal Vasko60ea6352020-06-29 13:39:39 +0200152
153/* Maximum size that will be written into LYB_SIZE_BYTES (must be large enough) */
aPiecek6828a312021-09-17 15:53:18 +0200154#define LYB_SIZE_MAX UINT16_MAX
Michal Vasko60ea6352020-06-29 13:39:39 +0200155
156/* How many bytes are reserved for one data chunk inner chunk count */
aPiecek6828a312021-09-17 15:53:18 +0200157#define LYB_INCHUNK_BYTES 2
Michal Vasko60ea6352020-06-29 13:39:39 +0200158
159/* Maximum size that will be written into LYB_INCHUNK_BYTES (must be large enough) */
aPiecek6828a312021-09-17 15:53:18 +0200160#define LYB_INCHUNK_MAX UINT16_MAX
Michal Vasko60ea6352020-06-29 13:39:39 +0200161
162/* Just a helper macro */
163#define LYB_META_BYTES (LYB_INCHUNK_BYTES + LYB_SIZE_BYTES)
Radek Krejcif13b87b2020-12-01 22:02:17 +0100164
165/* model revision as XXXX XXXX XXXX XXXX (2B) (year is offset from 2000)
166 * YYYY YYYM MMMD DDDD */
167#define LYB_REV_YEAR_OFFSET 2000
168#define LYB_REV_YEAR_MASK 0xfe00U
169#define LYB_REV_YEAR_SHIFT 9
170#define LYB_REV_MONTH_MASK 0x01E0U
171#define LYB_REV_MONTH_SHIFT 5
172#define LYB_REV_DAY_MASK 0x001fU
Michal Vasko60ea6352020-06-29 13:39:39 +0200173
Michal Vasko11f76c82021-04-15 14:36:14 +0200174/**
175 * @brief Get single hash for a schema node to be used for LYB data. Read from cache, if possible.
176 *
177 * @param[in] node Node to hash.
178 * @param[in] collision_id Collision ID of the hash to generate, see @ref collisionid.
179 * @return Generated hash.
180 */
181LYB_HASH lyb_get_hash(const struct lysc_node *node, uint8_t collision_id);
182
183/**
184 * @brief Fill the hash cache of all the schema nodes of a module.
185 *
186 * @param[in] mod Module to process.
187 */
188void lyb_cache_module_hash(const struct lys_module *mod);
189
190/**
191 * @brief Check whether a node's module is in a module array.
192 *
193 * @param[in] node Node to check.
194 * @param[in] models Modules in a sized array.
195 * @return Boolean value whether @p node's module was found in the given @p models array.
196 */
197ly_bool lyb_has_schema_model(const struct lysc_node *node, const struct lys_module **models);
198
Michal Vasko60ea6352020-06-29 13:39:39 +0200199#endif /* LY_LYB_H_ */