1zcbor 2===== 3 4zcbor is a low footprint [CBOR](https://en.wikipedia.org/wiki/CBOR) library in the C language (C++ compatible), tailored for use in microcontrollers. 5It comes with a schema-driven script tool that can validate your data, or even generate code. 6The schema language (CDDL) allows creating very advanced and detailed schemas. 7 8The validation and conversion part of the tool works with YAML and JSON data, in addition to CBOR. 9It can for example validate a YAML file against a schema and convert it into CBOR. 10 11The code generation part of the tool generates C code based on the given schema. 12The generated code performs CBOR encoding and decoding using the C library, while also validating the data against all the rules in the schema. 13 14The schema language used by zcbor is CDDL (Concise Data Definition Language) which is a powerful human-readable data description language defined in [IETF RFC 8610](https://datatracker.ietf.org/doc/rfc8610/). 15 16 17Features 18======== 19 20Here are some possible ways zcbor can be used: 21 22 - C code: 23 - As a low-footprint CBOR decoding/encoding library similar to TinyCBOR/QCBOR/NanoCBOR. The library can be used independently of the Python script. ([More information](#cbor-decodingencoding-library)) 24 - To generate C code (using the Python script) for validating and decoding or encoding CBOR, for use in optimized or constrained environments, such as microcontrollers. ([More information](#code-generation)) 25 - Python script and module ([More information](#python-script-and-module)): 26 - Validate a YAML/JSON file and translate it into CBOR e.g. for transmission. 27 - Validate a YAML/JSON/CBOR file before processing it with some other tool 28 - Decode and validate incoming CBOR data into human-readable YAML/JSON. 29 - As part of a python script that processes YAML/JSON/CBOR files. 30 - Uses the same internal representation used by the PyYAML/json/cbor2 libraries. 31 - Do validation against a CDDL schema. 32 - Create a read-only representation via named tuples (with names taken from the CDDL schema). 33 34 35Getting started 36=============== 37 38There are samples in the [samples](samples) directory that demonstrate different ways to use zcbor, both the script tool and the C code. 39 401. The [hello_world sample](samples/hello_world/README.md) is a minimum examples of encoding and decoding using the C library. 412. The [pet sample](samples/pet/README.md) shows a how to use the C library together with generated code, and how to use the script tool to do code generation and data conversion. 42 43The [tests](tests) also demonstrate how to use zcbor in different ways. The [encoding](tests/encode), [decoding](tests/decode), and [unit](tests/unit) tests run using [Zephyr](https://github.com/zephyrproject-rtos/zephyr) (the samples do not use Zephyr). 44 45Should I use code generation or the library directly? 46----------------------------------------------------- 47 48The benefit of using code generation is greater for decoding than encoding. 49This is because decoding is generally more complex than encoding, since when decoding you have to gracefully handle all possible payloads. 50The code generation will provide a number of checks that are tedious to write manually. 51These checks ensure that the payload is well-formed. 52 53 54CBOR decoding/encoding library 55============================== 56 57The CBOR library can be found in [include/](include) and [src/](src) and can be used directly, by including the files in your project. 58If using zcbor with Zephyr, the library will be available when the [CONFIG_ZCBOR](https://docs.zephyrproject.org/latest/kconfig.html#CONFIG_ZCBOR) config is enabled. 59 60The library is also used by generated code. See the [Code generation](#code-generation) section for more info about code generation. 61 62The C library is C++ compatible. 63 64The zcbor state object 65---------------------- 66 67To do encoding or decoding with the library, instantiate a `zcbor_state_t` object, which is most easily done using the `ZCBOR_STATE_*()` macros, look below or in the [hello_world](samples/hello_world/src/main.c) sample for example code. 68 69The `elem_count` member refers to the number of encoded objects in the current list or map. 70`elem_count` starts again when entering a nested list or map, and is restored when exiting. 71 72`elem_count` is one reason for needing "backup" states (the other is to allow rollback of the payload). 73Backups are needed for _decoding_ if there are any lists, maps, or CBOR-encoded strings (`zcbor_bstr_*_decode`) in the data. 74Backups are needed for _encoding_ if there are any lists or maps *and* you are using canonical encoding (`ZCBOR_CANONICAL`), or when using the `zcbor_bstr_*_encode` functions. 75 76```c 77/** Initialize a decoding state (could include an array of backup states). 78 * After calling this, decode_state[0] is ready to be used with the decoding APIs. */ 79ZCBOR_STATE_D(decode_state, n, payload, payload_len, elem_count, n_flags); 80 81/** Initialize an encoding state (could include an array of backup states). 82 * After calling this, encode_state[0] is ready to be used with the encoding APIs. */ 83ZCBOR_STATE_E(encode_state, n, payload, payload_len, 0); 84``` 85 86Configuration 87------------- 88 89The C library has a few compile-time configuration options. 90These configuration options can be enabled by adding them as compile definitions to the build. 91If using zcbor with Zephyr, use the [Kconfig options](https://github.com/zephyrproject-rtos/zephyr/blob/main/modules/zcbor/Kconfig) instead. 92 93Name | Description 94------------------------- | ----------- 95`ZCBOR_CANONICAL` | Assume canonical encoding (AKA "deterministically encoded CBOR"). When encoding lists and maps, do not use indefinite length encoding. Enabling `ZCBOR_CANONICAL` increases code size and makes the encoding library more often use state backups. When decoding, ensure that the incoming data conforms to canonical encoding, i.e. no indefinite length encoding, and always using minimal length encoding (e.g. not using 16 bits to encode a value < 256). Note: the map ordering constraint in canonical encoding is not checked. 96`ZCBOR_VERBOSE` | Print log messages on encoding/decoding errors (`zcbor_log()`), and also a trace message (`zcbor_trace()`) for each decoded value, and in each generated function (when using code generation). 97`ZCBOR_ASSERTS` | Enable asserts (`zcbor_assert()`). When they fail, the assert statements instruct the current function to return a `ZCBOR_ERR_ASSERTION` error. If `ZCBOR_VERBOSE` is enabled, a message is printed. 98`ZCBOR_STOP_ON_ERROR` | Enable the `stop_on_error` functionality. This makes all functions abort their execution if called when an error has already happened. 99`ZCBOR_BIG_ENDIAN` | All decoded values are returned as big-endian. The default is little-endian. 100`ZCBOR_MAP_SMART_SEARCH` | Applies to decoding of unordered maps. When enabled, a flag is kept for each element in an array, ensuring it is not processed twice. If disabled, a count is kept for map as a whole. Enabling increases code size and memory usage, and requires the state variable to possess the memory necessary for the flags. 101 102 103Python script and module 104======================== 105 106The zcbor.py script can directly read CBOR, YAML, or JSON data and validate it against a CDDL description. 107It can also freely convert the data between CBOR/YAML/JSON. 108It can also output the data to a C file formatted as a byte array. 109 110Invoking zcbor.py from the command line 111--------------------------------------- 112 113zcbor.py can be installed via [`pip`](https://pypi.org/project/zcbor/), or alternatively invoked directly from its location in this repo. 114 115Following are some generalized examples for validating, and for converting (which also validates) data from the command line. 116The script infers the data format from the file extension, but the format can also be specified explicitly. 117See `zcbor validate --help` and `zcbor convert --help` for more information. 118 119```sh 120zcbor validate -c <CDDL description file> -t <which CDDL type to expect> -i <input data file> 121zcbor convert -c <CDDL description file> -t <which CDDL type to expect> -i <input data file> -o <output data file> 122``` 123 124Or directly from within the repo. 125 126```sh 127python3 <zcbor base>/zcbor/zcbor.py validate -c <CDDL description file> -t <which CDDL type to expect> -i <input data file> 128python3 <zcbor base>/zcbor/zcbor.py convert -c <CDDL description file> -t <which CDDL type to expect> -i <input data file> -o <output data file> 129``` 130 131Importing zcbor in a Python script 132---------------------------------- 133 134Importing zcbor gives access to the DataTranslator class which is used to implement the command line conversion features. 135DataTranslator can be used to programmatically perform the translations, or to manipulate the data. 136When accessing the data, you can choose between two internal formats: 137 138 1. The format provided by the [cbor2](https://pypi.org/project/cbor2/), [yaml (PyYAML)](https://pypi.org/project/PyYAML/), and [json](https://docs.python.org/3/library/json.html) packages. 139 This is a format where the serialization types (map, list, string, number etc.) are mapped directly to the corresponding Python types. 140 This format is common between these packages, which makes translation very simple. 141 When returning this format, DataTranslator hides the idiomatic representations for bytestrings, tags, and non-text keys described above. 142 2. A custom format which allows accessing the data via the names from the CDDL description file. 143 This format is implemented using named tuples, and is immutable, meaning that it can be used for inspecting data, but not for changing or creating data. 144 145Making CBOR YAML-/JSON-compatible 146--------------------------------- 147 148Since CBOR supports more data types than YAML and JSON, zcbor can optionally use a bespoke format when converting to/from YAML/JSON. 149This is controlled with the `--yaml-compatibility` option to `convert` and `validate`. 150This is relevant when handling YAML/JSON conversions of data that uses the unsupported features. 151The following data types are supported by CBOR, but not by YAML (or JSON which is a subset of YAML): 152 153 1. bytestrings: YAML supports only text strings. In YAML, bytestrings are represented as `{"zcbor_bstr": "<hex-formatted bytestring>"}`, or as `{"zcbor_bstr": <any type>}` if the CBOR bytestring contains CBOR-formatted data, in which the data is decoded into `<any type>`. 154 2. map keys other than text string: In YAML, such key value pairs are represented as `{"zcbor_keyval<unique int>": {"key": <key, not text>, "val": <value>}}`. 155 3. tags: In cbor2, tags are represented by a special type, `cbor2.CBORTag`. In YAML, these are represented as `{"zcbor_tag": <tag number>, "zcbor_tag_val": <tagged data>}`. 156 4. undefined: In cbor2, undefined has its own value `cbor2.types.undefined`. In YAML, undefined is represented as: `["zcbor_undefined"]`. 157 158You can see an example of the conversions in [tests/cases/yaml_compatibility.yaml](tests/cases/yaml_compatibility.yaml) and its CDDL file [tests/cases/yaml_compatibility.cddl](tests/cases/yaml_compatibility.cddl). 159 160 161Code generation 162=============== 163 164Code generation is invoked with the `zcbor code` command: 165 166```sh 167zcbor code <--decode or --encode or both> -c <CDDL description file(s)> -t <which CDDL type(s) to expose in the API> --output-cmake <path to place the generated CMake file at> 168zcbor code <--decode or --encode or both> -c <CDDL description file(s)> -t <which CDDL type(s) to expose in the API> --oc <path to the generated C file> --oh <path to the generated header file> --oht <path to the generated types header> 169``` 170 171When you call this, zcbor reads the CDDL files and creates C struct types to match the types described in the CDDL. 172It then creates code that uses the C library to decode CBOR data into the structs, and/or encode CBOR from the data in the structs. 173Finally, it takes the "entry types" (`-t`) and creates a public API function for each of them. 174While doing these things, it will make a number of optimizations, e.g. inlining code for small types and removing unused functions. 175It outputs the generated code into header and source files and optionally creates a CMake file to build them. 176 177The `zcbor code` command reads one or more CDDL file(s) and generates some or all of these files: 178 - A header file with types (always) 179 - A header file with declarations for decoding functions (if `--decode`/`-d` is specified) 180 - A C file with decoding functions (if `--decode`/`-d` is specified) 181 - A header file with declarations for encoding functions (if `--encode`/`-e` is specified) 182 - A C file with encoding functions (if `--encode`/`-e` is specified) 183 - A CMake file that creates a library with the generated code and the C library (if `--output-cmake` is specified). 184 185CDDL allows placing restrictions on the members of your data. 186Restrictions can be on type (int/string/list/bool etc.), on content (e.g. values/sizes of ints or strings), and repetition (e.g. the number of members in a list). 187The generated code will validate the input, which means that it will check all the restriction set in the CDDL description, and fail if a restriction is broken. 188 189There are tests for the code generation in [tests/decode](tests/decode) and [tests/encode](tests/encode). 190The tests require [Zephyr](https://github.com/zephyrproject-rtos/zephyr) (if your system is set up to build Zephyr samples, the tests should also build). 191 192The generated C code is C++ compatible. 193 194Build system 195------------ 196 197When calling zcbor with the argument `--output-cmake <file path>`, a CMake file will be created at that location. 198The generated CMake file creates a target library and adds the generated and non-generated source files as well as required include directories to it. 199This CMake file can then be included in your project's `CMakeLists.txt` file, and the target can be linked into your project. 200This is demonstrated in the tests, e.g. at [tests/decode/test3_simple/CMakeLists.txt](tests/decode/test3_simple/CMakeLists.txt). 201zcbor can be instructed to copy the non-generated sources to the same location as the generated sources with `--copy-sources`. 202 203 204Usage Example 205============= 206 207There are buildable examples in the [samples](samples) directory. 208 209To see how to use the C library directly, see the [hello_world](samples/hello_world/src/main.c) sample, or the [pet](samples/pet/src/main.c) sample (look for calls to functions prefixed with `zcbor_`). 210 211To see how to use code generation, see the [pet](samples/pet/src/main.c) sample. 212 213Look at the [CMakeLists.txt](samples/pet/CMakeLists.txt) file to see how zcbor is invoked for code generation (and for conversion). 214 215To see how to do conversion, see the [pet](samples/pet/CMakeLists.txt) sample. 216 217Below are some additional examples of how to invoke zcbor for code generation and for converting/validating 218 219Code generation 220--------------- 221 222```sh 223python3 <zcbor base>/zcbor/zcbor.py code -c pet.cddl -d -t Pet --oc pet_decode.c --oh pet_decode.h 224# or 225zcbor code -c pet.cddl -d -t Pet --oc pet_decode.c --oh pet_decode.h 226``` 227 228Converting 229---------- 230 231Here is an example call for converting from YAML to CBOR: 232 233```sh 234python3 <zcbor base>/zcbor/zcbor.py convert -c pet.cddl -t Pet -i mypet.yaml -o mypet.cbor 235# or 236zcbor convert -c pet.cddl -t Pet -i mypet.yaml -o mypet.cbor 237``` 238 239Which takes a yaml structure from mypet.yaml, validates it against the Pet type in the CDDL description in pet.cddl, and writes binary CBOR data to mypet.cbor. 240 241Validating 242---------- 243 244Here is an example call for validating a JSON file: 245 246```sh 247python3 <zcbor base>/zcbor/zcbor.py validate -c pet.cddl -t Pet --yaml-compatibility -i mypet.json 248# or 249zcbor validate -c pet.cddl -t Pet --yaml-compatibility -i mypet.json 250``` 251 252Which takes the json structure in mypet.json, converts any [yaml-compatible](#making-cbor-yaml-json-compatible) values to their original form, and validates that against the Pet type in the CDDL description in pet.cddl. 253 254 255Running tests 256============= 257 258The tests for the generated code are based on the Zephyr ztest library. 259These tests can be found in [tests/decode](tests/decode) and [tests/encode](tests/encode). 260To set up the environment to run the ztest tests, follow [Zephyr's Getting Started Guide](https://docs.zephyrproject.org/latest/getting_started/index.html), or see the workflow in the [`.github`](.github) directory. 261 262Tests for `convert` and `verify` are implemented with the unittest module. 263These tests can be found in [tests/scripts/test_zcbor.py](tests/scripts/test_zcbor.py). 264In this file there are also tests for code style of all python scripts, using the `pycodestyle` library. 265 266Tests for the docs, samples, etc. can be found in [tests/scripts/test_repo_files.py](tests/scripts/test_repo_files.py). 267 268For running the tests locally, there is [`tests/test.sh`](tests/test.sh) which runs all above tests. 269 270 271Introduction to CDDL 272==================== 273 274In CDDL you define types from other types. 275Types can be defined from base types, or from other types you define. 276Types are declared with '`=`', e.g. `Foo = int` which declares the type `Foo` to be an integer, analogous to `typedef int Foo;` in C. 277CDDL defines the following base types (this is not an exhaustive list): 278 279 - `int`: Positive or negative integer 280 - `uint`: Positive integer 281 - `bstr`: Byte string 282 - `tstr`: Text string 283 - `bool`: Boolean 284 - `nil`: Nil/Null value 285 - `float`: Floating point value 286 - `any`: Any single element 287 288CDDL allows creating aggregate types: 289 290 - `[]`: List. Elements don't need to have the same type. 291 - `{}`: Map. Key/value pairs as are declared as `<key> => <value>` or `<key>: <value>`. Note that `:` is also used for labels. 292 - `()`: Groups. Grouping with no enclosing type, which means that e.g. `Foo = [(int, bstr)]` is equivalent to `Foo = [int, bstr]`. 293 - `/`: Unions. Analogous to unions in C. E.g. `Foo = int/bstr/Bar` where Foo is either an int, a bstr, or Bar (some custom type). 294 295Literals can be used instead of the base type names: 296 297 - Number: `Foo = 3`, where Foo is a uint with the additional requirement that it must have the value 3. 298 - Number range: `Foo = -100..100`, where Foo is an int with value between -100 and 100. 299 - Text string: `Foo = "hello"`, where Foo is a tstr with the requirement that it must be "hello". 300 - True/False: `Foo = false`, where Foo is a bool which is always false. 301 302Base types can also be restricted in other ways: 303 304 - `.size`: Works for integers and strings. E.g. `Foo = uint .size 4` where Foo is a uint exactly 4 bytes long. 305 - `.cbor`/`.cborseq`: E.g. `Foo = bstr .cbor Bar` where Foo is a bstr whose contents must be CBOR data decodable as the Bar type. 306 307An element can be repeated: 308 309 - `?`: 0 or 1 time. E.g. `Foo = [int, ?bstr]`, where Foo is a list with an int possibly followed by a bstr. 310 - `*`: 0 or more times. E.g. `Foo = [*tstr]`, where Foo is a list containing 0 or more tstrs. 311 - `+`: 1 or more times. E.g. `Foo = [+Bar]`. 312 - `x*y`: Between x and y times, inclusive. E.g. `Foo = {4*8(int => bstr)}` where Foo is a map with 4 to 8 key/value pairs where each key is an int and each value is a bstr. 313 314Note that in the zcbor script and its generated code, the number of entries supported via `*` and `+` is affected by the default_max_qty value. 315 316Any element can be labeled with `:`. 317The label is only for readability and does not impact the data structure in any way. 318E.g. `Foo = [name: tstr, age: uint]` is equivalent to `Foo = [tstr, uint]`. 319 320See [pet.cddl](tests/cases/pet.cddl) for CDDL example code. 321 322 323Introduction to CBOR 324==================== 325 326CBOR's format is described well on [Wikipedia](https://en.wikipedia.org/wiki/CBOR), but here's a synopsis: 327 328Encoded CBOR data elements look like this. 329 330``` 331| Header | Value | Payload | 332| 1 byte | 0, 1, 2, 4, or 8 bytes | 0 - 2^64-1 bytes/elements | 333| 3 bits | 5 bits | 334| Major Type | Additional Info | 335``` 336 337The available major types can be seen in `zcbor_major_type_t`. 338 339For all major types, Values 0-23 are encoded directly in the _Additional info_, meaning that the _Value_ field is 0 bytes long. 340If _Additional info_ is 24, 25, 26, or 27, the _Value_ field is 1, 2, 4, or 8 bytes long, respectively. 341 342Major types `pint` (0), `nint` (1), `tag` (6), and `simple` (7) elements have no payload, only _Value_. 343 344 * `pint`: Interpret the _Value_ as a positive integer. 345 * `nint`: Interpret the _Value_ as a positive integer, then multiply by -1 and subtract 1. 346 * `tag`: The _Value_ says something about the next non-tag element. 347 See the [CBOR tag documentation](https://www.iana.org/assignments/cbor-tags/cbor-tags.xhtml) for details. 348 * `simple`: Different _Additional info_ mean different things: 349 * 0-19: Unassigned simple values. 350 * 20: `false` simple value 351 * 21: `true` simple value 352 * 22: `null` simple value 353 * 23: `undefined` simple value 354 * 24: Interpret the _Value_ as a 1 byte simple value. These simple values are currently unassigned. 355 * 25: Interpret the _Value_ as an IEEE 754 float16. 356 * 26: Interpret the _Value_ as an IEEE 754 float32. 357 * 27: Interpret the _Value_ as an IEEE 754 float64. 358 * 31: End of an indefinite-length `list` or `map`. 359 360For `bstr` (2), `tstr` (3), `list` (4), and `map` (5), the _Value_ describes the length of the _Payload_. 361For `bstr` and `tstr`, the length is in bytes, for `list`, the length is in number of elements, and for `map`, the length is in number of key/value element pairs. 362 363For `list` and `map`, sub elements are regular CBOR elements with their own _Header_, _Value_ and _Payload_. `list`s and `map`s can be recursively encoded. 364If a `list` or `map` has _Additional info_ 31, it is "indefinite-length", which means it has an "unknown" number of elements. 365Instead, its end is marked by a `simple` with _Additional info_ 31 (byte value 0xFF). 366 367 368History 369======= 370 371zcbor (then "cddl-gen") was initially conceived as a code generation project. 372It was inspired by the need to securely decode the complex manifest data structures in the [IETF SUIT specification](https://datatracker.ietf.org/doc/draft-ietf-suit-manifest/). 373This is reflected in the fact that there are multiple zcbor tests that use the CDDL and examples from various revisions of that specification. 374Decoding/deserializing data securely requires doing some quite repetitive checks on each data element, to be sure that you are not decoding gibberish. 375This is where code generation could pull a lot of weight. 376Later it was discovered that the CBOR library that was designed to used by generated code could be useful by itself. 377The script was also expanded so it could directly manipulate CBOR data. 378Since CBOR, YAML, and JSON are all represented in roughly the same way internally in Python, it was easy to expand that data manipulation to support YAML and JSON. 379 380Some places where zcbor is currently used: 381- [MCUboot's serial recovery mechanism](https://github.com/mcu-tools/mcuboot/blob/main/boot/boot_serial/src/boot_serial.c) 382- [Zephyr's mcumgr](https://github.com/zephyrproject-rtos/zephyr/blob/main/subsys/mgmt/mcumgr/grp/img_mgmt/src/img_mgmt.c) 383- [Zephyr's LwM2M SenML](https://github.com/zephyrproject-rtos/zephyr/blob/main/subsys/net/lib/lwm2m/lwm2m_rw_senml_cbor.c) 384- [nRF Connect SDK's full modem update mechanism](https://github.com/nrfconnect/sdk-nrf/blob/main/subsys/mgmt/fmfu/src/fmfu_mgmt.c) 385- [nRF Connect SDK's nrf_rpc](https://github.com/nrfconnect/sdk-nrfxlib/blob/main/nrf_rpc/nrf_rpc_cbor.c) 386 387 388Command line documentation 389========================== 390 391Added via `add_helptext.py` 392 393zcbor --help 394------------ 395 396``` 397usage: zcbor [-h] [--version] {code,validate,convert} ... 398 399Parse a CDDL file and validate/convert between YAML, JSON, and CBOR. Can also 400generate C code for validation/encoding/decoding of CBOR. 401 402positional arguments: 403 {code,validate,convert} 404 405options: 406 -h, --help show this help message and exit 407 --version show program's version number and exit 408 409``` 410 411zcbor code --help 412----------------- 413 414``` 415usage: zcbor code [-h] -c CDDL [--no-prelude] [-v] 416 [--default-max-qty DEFAULT_MAX_QTY] [--output-c OUTPUT_C] 417 [--output-h OUTPUT_H] [--output-h-types OUTPUT_H_TYPES] 418 [--copy-sources] [--output-cmake OUTPUT_CMAKE] -t 419 ENTRY_TYPES [ENTRY_TYPES ...] [-d] [-e] [--time-header] 420 [--git-sha-header] [-b {32,64}] 421 [--include-prefix INCLUDE_PREFIX] [-s] 422 [--file-header FILE_HEADER] 423 424Parse a CDDL file and produce C code that validates and xcodes CBOR. 425The output from this script is a C file and a header file. The header file 426contains typedefs for all the types specified in the cddl input file, as well 427as declarations to xcode functions for the types designated as entry types when 428running the script. The c file contains all the code for decoding and validating 429the types in the CDDL input file. All types are validated as they are xcoded. 430 431Where a `bstr .cbor <Type>` is specified in the CDDL, AND the Type is an entry 432type, the xcoder will not xcode the string, only provide a pointer into the 433payload buffer. This is useful to reduce the size of typedefs, or to break up 434decoding. Using this mechanism is necessary when the CDDL contains self- 435referencing types, since the C type cannot be self referencing. 436 437This script requires 'regex' for lookaround functionality not present in 're'. 438 439options: 440 -h, --help show this help message and exit 441 -c CDDL, --cddl CDDL Path to one or more input CDDL file(s). Passing 442 multiple files is equivalent to concatenating them. 443 --no-prelude Exclude the standard CDDL prelude from the build. The 444 prelude can be viewed at zcbor/prelude.cddl in the 445 repo, or together with the script. 446 -v, --verbose Print more information while parsing CDDL and 447 generating code. 448 --default-max-qty DEFAULT_MAX_QTY, --dq DEFAULT_MAX_QTY 449 Default maximum number of repetitions when no maximum 450 is specified. This is needed to construct complete C 451 types. The default_max_qty can usually be set to a 452 text symbol if desired, to allow it to be configurable 453 when building the code. This is not always possible, 454 as sometimes the value is needed for internal 455 computations. If so, the script will raise an 456 exception. 457 --output-c OUTPUT_C, --oc OUTPUT_C 458 Path to output C file. If both --decode and --encode 459 are specified, _decode and _encode will be appended to 460 the filename when creating the two files. If not 461 specified, the path and name will be based on the 462 --output-cmake file. A 'src' directory will be created 463 next to the cmake file, and the C file will be placed 464 there with the same name (except the file extension) 465 as the cmake file. 466 --output-h OUTPUT_H, --oh OUTPUT_H 467 Path to output header file. If both --decode and 468 --encode are specified, _decode and _encode will be 469 appended to the filename when creating the two files. 470 If not specified, the path and name will be based on 471 the --output-cmake file. An 'include' directory will 472 be created next to the cmake file, and the C file will 473 be placed there with the same name (except the file 474 extension) as the cmake file. 475 --output-h-types OUTPUT_H_TYPES, --oht OUTPUT_H_TYPES 476 Path to output header file with typedefs (shared 477 between decode and encode). If not specified, the path 478 and name will be taken from the output header file 479 (--output-h), with '_types' added to the file name. 480 --copy-sources Copy the non-generated source files (zcbor_*.c/h) into 481 the same directories as the generated files. 482 --output-cmake OUTPUT_CMAKE 483 Path to output CMake file. The filename of the CMake 484 file without '.cmake' is used as the name of the CMake 485 target in the file. The CMake file defines a CMake 486 target with the zcbor source files and the generated 487 file as sources, and the zcbor header files' and 488 generated header files' folders as 489 include_directories. Add it to your project via 490 include() in your CMakeLists.txt file, and link the 491 target to your program. This option works with or 492 without the --copy-sources option. 493 -t ENTRY_TYPES [ENTRY_TYPES ...], --entry-types ENTRY_TYPES [ENTRY_TYPES ...] 494 Names of the types which should have their xcode 495 functions exposed. 496 -d, --decode Generate decoding code. Either --decode or --encode or 497 both must be specified. 498 -e, --encode Generate encoding code. Either --decode or --encode or 499 both must be specified. 500 --time-header Put the current time in a comment in the generated 501 files. 502 --git-sha-header Put the current git sha of zcbor in a comment in the 503 generated files. 504 -b {32,64}, --default-bit-size {32,64} 505 Default bit size of integers in code. When integers 506 have no explicit bounds, assume they have this bit 507 width. Should follow the bit width of the architecture 508 the code will be running on. 509 --include-prefix INCLUDE_PREFIX 510 When #include'ing generated files, add this path 511 prefix to the filename. 512 -s, --short-names Attempt to make most generated struct member names 513 shorter. This might make some names identical which 514 will cause a compile error. If so, tweak the CDDL 515 labels or layout, or disable this option. This might 516 also make enum names different from the corresponding 517 union members. 518 --file-header FILE_HEADER 519 Header to be included in the comment at the top of 520 generated C files, e.g. copyright. 521 522``` 523 524zcbor validate --help 525--------------------- 526 527``` 528usage: zcbor validate [-h] -c CDDL [--no-prelude] [-v] -i INPUT 529 [--input-as {yaml,json,cbor,cborhex}] -t ENTRY_TYPE 530 [--default-max-qty DEFAULT_MAX_QTY] 531 [--yaml-compatibility] 532 533Read CBOR, YAML, or JSON data from file or stdin and validate it against a 534CDDL schema file. 535 536options: 537 -h, --help show this help message and exit 538 -c CDDL, --cddl CDDL Path to one or more input CDDL file(s). Passing 539 multiple files is equivalent to concatenating them. 540 --no-prelude Exclude the standard CDDL prelude from the build. The 541 prelude can be viewed at zcbor/prelude.cddl in the 542 repo, or together with the script. 543 -v, --verbose Print more information while parsing CDDL and 544 generating code. 545 -i INPUT, --input INPUT 546 Input data file. The option --input-as specifies how 547 to interpret the contents. Use "-" to indicate stdin. 548 --input-as {yaml,json,cbor,cborhex} 549 Which format to interpret the input file as. If 550 omitted, the format is inferred from the file name. 551 .yaml, .yml => YAML, .json => JSON, .cborhex => CBOR 552 as hex string, everything else => CBOR 553 -t ENTRY_TYPE, --entry-type ENTRY_TYPE 554 Name of the type (from the CDDL) to interpret the data 555 as. 556 --default-max-qty DEFAULT_MAX_QTY, --dq DEFAULT_MAX_QTY 557 Default maximum number of repetitions when no maximum 558 is specified. It is only relevant when handling data 559 that will be decoded by generated code. If omitted, a 560 large number will be used. 561 --yaml-compatibility Whether to convert CBOR-only values to YAML-compatible 562 ones (when converting from CBOR), or vice versa (when 563 converting to CBOR). When this is enabled, all CBOR 564 data is guaranteed to convert into YAML/JSON. JSON and 565 YAML do not support all data types that CBOR/CDDL 566 supports. bytestrings (BSTR), tags, undefined, and 567 maps with non-text keys need special handling. See the 568 zcbor README for more information. 569 570``` 571 572zcbor convert --help 573-------------------- 574 575``` 576usage: zcbor convert [-h] -c CDDL [--no-prelude] [-v] -i INPUT 577 [--input-as {yaml,json,cbor,cborhex}] -t ENTRY_TYPE 578 [--default-max-qty DEFAULT_MAX_QTY] 579 [--yaml-compatibility] -o OUTPUT 580 [--output-as {yaml,json,cbor,cborhex,c_code}] 581 [--c-code-var-name C_CODE_VAR_NAME] 582 [--c-code-columns C_CODE_COLUMNS] 583 584Parse a CDDL file and validate/convert between CBOR and YAML/JSON. The script 585decodes the CBOR/YAML/JSON data from a file or stdin and verifies that it 586conforms to the CDDL description. The script fails if the data does not 587conform. 'zcbor validate' can be used if only validate is needed. 588 589options: 590 -h, --help show this help message and exit 591 -c CDDL, --cddl CDDL Path to one or more input CDDL file(s). Passing 592 multiple files is equivalent to concatenating them. 593 --no-prelude Exclude the standard CDDL prelude from the build. The 594 prelude can be viewed at zcbor/prelude.cddl in the 595 repo, or together with the script. 596 -v, --verbose Print more information while parsing CDDL and 597 generating code. 598 -i INPUT, --input INPUT 599 Input data file. The option --input-as specifies how 600 to interpret the contents. Use "-" to indicate stdin. 601 --input-as {yaml,json,cbor,cborhex} 602 Which format to interpret the input file as. If 603 omitted, the format is inferred from the file name. 604 .yaml, .yml => YAML, .json => JSON, .cborhex => CBOR 605 as hex string, everything else => CBOR 606 -t ENTRY_TYPE, --entry-type ENTRY_TYPE 607 Name of the type (from the CDDL) to interpret the data 608 as. 609 --default-max-qty DEFAULT_MAX_QTY, --dq DEFAULT_MAX_QTY 610 Default maximum number of repetitions when no maximum 611 is specified. It is only relevant when handling data 612 that will be decoded by generated code. If omitted, a 613 large number will be used. 614 --yaml-compatibility Whether to convert CBOR-only values to YAML-compatible 615 ones (when converting from CBOR), or vice versa (when 616 converting to CBOR). When this is enabled, all CBOR 617 data is guaranteed to convert into YAML/JSON. JSON and 618 YAML do not support all data types that CBOR/CDDL 619 supports. bytestrings (BSTR), tags, undefined, and 620 maps with non-text keys need special handling. See the 621 zcbor README for more information. 622 -o OUTPUT, --output OUTPUT 623 Output data file. The option --output-as specifies how 624 to interpret the contents. Use "-" to indicate stdout. 625 --output-as {yaml,json,cbor,cborhex,c_code} 626 Which format to interpret the output file as. If 627 omitted, the format is inferred from the file name. 628 .yaml, .yml => YAML, .json => JSON, .c, .h => C code, 629 .cborhex => CBOR as hex string, everything else => 630 CBOR 631 --c-code-var-name C_CODE_VAR_NAME 632 Only relevant together with '--output-as c_code' or .c 633 files. 634 --c-code-columns C_CODE_COLUMNS 635 Only relevant together with '--output-as c_code' or .c 636 files. The number of bytes per line in the variable 637 instantiation. If omitted, the entire declaration is a 638 single line. 639 640``` 641
