blob: 687e760adc4d141d5b611c73c3d0f4f20ee661df [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
Michal Vasko03fbaed2021-07-15 09:18:32 +020026/**
27 * @brief LYB format parser context
28 */
Radek Krejci1798aae2020-07-14 13:26:06 +020029struct lylyb_ctx {
30 const struct ly_ctx *ctx;
31 uint64_t line; /* current line */
32 struct ly_in *in; /* input structure */
33
34 const struct lys_module **models;
35
aPiecek570d7ed2021-09-10 07:15:35 +020036 struct lyd_lyb_sibling {
Michal Vasko60ea6352020-06-29 13:39:39 +020037 size_t written;
38 size_t position;
aPiecek6828a312021-09-17 15:53:18 +020039 uint16_t inner_chunks;
aPiecek570d7ed2021-09-10 07:15:35 +020040 } *siblings;
41 LY_ARRAY_COUNT_TYPE sibling_size;
Michal Vasko60ea6352020-06-29 13:39:39 +020042
Michal Vasko60ea6352020-06-29 13:39:39 +020043 /* LYB printer only */
44 struct lyd_lyb_sib_ht {
45 struct lysc_node *first_sibling;
46 struct hash_table *ht;
47 } *sib_hts;
48};
49
50/**
Radek Krejci1798aae2020-07-14 13:26:06 +020051 * @brief Destructor for the lylyb_ctx structure
52 */
53void lyd_lyb_ctx_free(struct lyd_ctx *lydctx);
54
55/**
Michal Vasko60ea6352020-06-29 13:39:39 +020056 * LYB format
57 *
58 * Unlike XML or JSON, it is binary format so most data are represented in similar way but in binary.
59 * Some notable differences:
60 *
61 * - schema nodes are identified based on their hash instead of their string name. In case of collisions
62 * an array of hashes is created with each next hash one bit shorter until a unique sequence of all these
63 * hashes is found and then all of them are stored.
64 *
aPiecek570d7ed2021-09-10 07:15:35 +020065 * - tree structure is represented as individual strictly bounded "siblings". Each "siblings" begins
66 * with its metadata, which consist of 1) the whole "sibling" length in bytes and 2) number
67 * of included metadata chunks of nested "siblings".
Michal Vasko60ea6352020-06-29 13:39:39 +020068 *
aPiecek570d7ed2021-09-10 07:15:35 +020069 * - since length of a "sibling" is not known before it is printed, holes are first written and
70 * after the "sibling" is printed, they are filled with actual valid metadata. As a consequence,
Michal Vasko60ea6352020-06-29 13:39:39 +020071 * LYB data cannot be directly printed into streams!
72 *
73 * - data are preceded with information about all the used modules. It is needed because of
74 * possible augments and deviations which must be known beforehand, otherwise schema hashes
75 * could be matched to the wrong nodes.
76 */
77
78/* just a shortcut */
aPiecek570d7ed2021-09-10 07:15:35 +020079#define LYB_LAST_SIBLING(lybctx) lybctx->siblings[LY_ARRAY_COUNT(lybctx->siblings) - 1]
Michal Vasko60ea6352020-06-29 13:39:39 +020080
aPiecek570d7ed2021-09-10 07:15:35 +020081/* struct lyd_lyb_sibling allocation step */
82#define LYB_SIBLING_STEP 4
Michal Vasko60ea6352020-06-29 13:39:39 +020083
84/* current LYB format version */
aPiecek20127bf2021-09-10 11:24:58 +020085#define LYB_VERSION_NUM 0x02
Michal Vasko60ea6352020-06-29 13:39:39 +020086
87/* LYB format version mask of the header byte */
aPiecek20127bf2021-09-10 11:24:58 +020088#define LYB_VERSION_MASK 0x0F
Michal Vasko60ea6352020-06-29 13:39:39 +020089
90/**
91 * LYB schema hash constants
92 *
93 * Hash is divided to collision ID and hash itself.
94 *
Michal Vasko11f76c82021-04-15 14:36:14 +020095 * @anchor collisionid
96 *
Michal Vasko60ea6352020-06-29 13:39:39 +020097 * First bits are collision ID until 1 is found. The rest is truncated 32b hash.
98 * 1xxx xxxx - collision ID 0 (no collisions)
99 * 01xx xxxx - collision ID 1 (collision ID 0 hash collided)
100 * 001x xxxx - collision ID 2 ...
Michal Vasko11f76c82021-04-15 14:36:14 +0200101 *
102 * When finding a match for a unique schema (siblings) hash (sequence of hashes with increasing collision ID), the highest
103 * collision ID can be read from the last hash (LYB parser).
104 *
105 * To learn what is the highest collision ID of a hash that must be included in a unique schema (siblings) hash,
106 * collisions with all the preceding sibling schema hashes must be checked (LYB printer).
Michal Vasko60ea6352020-06-29 13:39:39 +0200107 */
108
109/* Number of bits the whole hash will take (including hash collision ID) */
110#define LYB_HASH_BITS 8
111
112/* Masking 32b hash (collision ID 0) */
113#define LYB_HASH_MASK 0x7f
114
115/* Type for storing the whole hash (used only internally, publicly defined directly) */
116#define LYB_HASH uint8_t
117
118/* Need to move this first >> collision number (from 0) to get collision ID hash part */
119#define LYB_HASH_COLLISION_ID 0x80
120
121/* How many bytes are reserved for one data chunk SIZE (8B is maximum) */
aPiecek6828a312021-09-17 15:53:18 +0200122#define LYB_SIZE_BYTES 2
Michal Vasko60ea6352020-06-29 13:39:39 +0200123
124/* Maximum size that will be written into LYB_SIZE_BYTES (must be large enough) */
aPiecek6828a312021-09-17 15:53:18 +0200125#define LYB_SIZE_MAX UINT16_MAX
Michal Vasko60ea6352020-06-29 13:39:39 +0200126
127/* How many bytes are reserved for one data chunk inner chunk count */
aPiecek6828a312021-09-17 15:53:18 +0200128#define LYB_INCHUNK_BYTES 2
Michal Vasko60ea6352020-06-29 13:39:39 +0200129
130/* Maximum size that will be written into LYB_INCHUNK_BYTES (must be large enough) */
aPiecek6828a312021-09-17 15:53:18 +0200131#define LYB_INCHUNK_MAX UINT16_MAX
Michal Vasko60ea6352020-06-29 13:39:39 +0200132
133/* Just a helper macro */
134#define LYB_META_BYTES (LYB_INCHUNK_BYTES + LYB_SIZE_BYTES)
Radek Krejcif13b87b2020-12-01 22:02:17 +0100135
136/* model revision as XXXX XXXX XXXX XXXX (2B) (year is offset from 2000)
137 * YYYY YYYM MMMD DDDD */
138#define LYB_REV_YEAR_OFFSET 2000
139#define LYB_REV_YEAR_MASK 0xfe00U
140#define LYB_REV_YEAR_SHIFT 9
141#define LYB_REV_MONTH_MASK 0x01E0U
142#define LYB_REV_MONTH_SHIFT 5
143#define LYB_REV_DAY_MASK 0x001fU
Michal Vasko60ea6352020-06-29 13:39:39 +0200144
Michal Vasko11f76c82021-04-15 14:36:14 +0200145/**
146 * @brief Get single hash for a schema node to be used for LYB data. Read from cache, if possible.
147 *
148 * @param[in] node Node to hash.
149 * @param[in] collision_id Collision ID of the hash to generate, see @ref collisionid.
150 * @return Generated hash.
151 */
152LYB_HASH lyb_get_hash(const struct lysc_node *node, uint8_t collision_id);
153
154/**
155 * @brief Fill the hash cache of all the schema nodes of a module.
156 *
157 * @param[in] mod Module to process.
158 */
159void lyb_cache_module_hash(const struct lys_module *mod);
160
161/**
162 * @brief Check whether a node's module is in a module array.
163 *
164 * @param[in] node Node to check.
165 * @param[in] models Modules in a sized array.
166 * @return Boolean value whether @p node's module was found in the given @p models array.
167 */
168ly_bool lyb_has_schema_model(const struct lysc_node *node, const struct lys_module **models);
169
Michal Vasko60ea6352020-06-29 13:39:39 +0200170#endif /* LY_LYB_H_ */