From 2ccfcd8cfc032d9c3f4da325a61f40cf2698891c Mon Sep 17 00:00:00 2001 From: Erik Jaegervall Date: Fri, 1 Nov 2024 10:28:39 +0100 Subject: [PATCH] Minor documentation update * Fixing Binary Table * Adding Binary to exporter list * Changing to alphabetical order in exporter list * Fixing some broken links Signed-off-by: Erik Jaegervall --- binary/README.md | 57 +++++++++++++++++++++++----------------------- docs/vspec.md | 7 +++--- docs/vspec_arch.md | 6 ++--- 3 files changed, 36 insertions(+), 34 deletions(-) diff --git a/binary/README.md b/binary/README.md index 8e0cbfb1..972a3611 100644 --- a/binary/README.md +++ b/binary/README.md @@ -1,6 +1,6 @@ # Binary Toolset The binary toolset consists of a tool that translates the VSS YAML specification to the binary file format (see below), -and two libraries that provides methods that are likely to be needed by a server that manages the VSS tree, one written in C, and one in Go.
+and two libraries that provides methods that are likely to be needed by a server that manages the VSS tree, one written in C, and one in Go. ## Binary Parser Usage @@ -70,35 +70,36 @@ and assuming a binary tree file has been created in the VSS parent directory: ## Encoding -The binary node file format is as follows:
- Name | Datatype | #bytes
- ---------------------------------------
- NameLen | uint8 | 1
- Name | chararray | NameLen
- NodeTypeLen | uint8 | 1
- NodeType | chararray | NodeTypeLen
- UuidLen | uint8 | 1
- Uuid | chararray | UuidLen
- DescrLen | uint8 | 1
- Description | chararray | DescrLen
- DatatypeLen | uint8 | 1
- Datatype | chararray | DatatypeLen
- MinLen | uint8 | 1
- Min | chararray | MinLen
- MaxLen | uint8 | 1
- Max | chararray | MaxLen
- UnitLen | uint8 | 1
- Unit | chararray | UnitLen
- AllowedLen | uint8 | 1
- Allowed | chararray | AllowedLen
- DefaultLen | uint8 | 1
- Default | chararray | AllowedLen
- ValidateLen | uint8 | 1
- Validate | chararray | ValidateLen
- Children | uint8 | 1

+The binary node file format is as follows: + +Name | Datatype | #bytes +------------|-----------|-------------- +NameLen | uint8 | 1 +Name | chararray | NameLen +NodeTypeLen | uint8 | 1 +NodeType | chararray | NodeTypeLen +UuidLen | uint8 | 1 +Uuid | chararray | UuidLen +DescrLen | uint8 | 1 +Description | chararray | DescrLen +DatatypeLen | uint8 | 1 +Datatype | chararray | DatatypeLen +MinLen | uint8 | 1 +Min | chararray | MinLen +MaxLen | uint8 | 1 +Max | chararray | MaxLen +UnitLen | uint8 | 1 +Unit | chararray | UnitLen +AllowedLen | uint8 | 1 +Allowed | chararray | AllowedLen +DefaultLen | uint8 | 1 +Default | chararray | AllowedLen +ValidateLen | uint8 | 1 +Validate | chararray | ValidateLen +Children | uint8 | 1 The Allowed string contains an array of allowed, each Allowed is preceeded by two characters holding the size of the Allowed sub-string. -The size is in hex format, with values from "01" to "FF". An example is "03abc0A012345678902cd" which contains the three Alloweds "abc", "0123456789", and "cd".

+The size is in hex format, with values from "01" to "FF". An example is "03abc0A012345678902cd" which contains the three Alloweds "abc", "0123456789", and "cd". The nodes are written into the file in the order given by a recursive method as shown in the following pseudocode: diff --git a/docs/vspec.md b/docs/vspec.md index b4761081..de88138c 100644 --- a/docs/vspec.md +++ b/docs/vspec.md @@ -43,16 +43,17 @@ vspec export json --vspec spec/VehicleSignalSpecification.vspec --output vss.jso INFO Serializing compact JSON... json.py:148 ``` -## Exporter docs +## Exporter Specific Documentation - [apigear](./apigear.md) -- [tree](./tree.md) +- [binary](../binary/README.md) - [ddsidl](./ddsidl.md) +- [go](./go.md) - [graphql](./graphql.md) - [id](./id.md) - [protobuf](./protobuf.md) - [samm](./samm.md) -- [go](./go.md) +- [tree](./tree.md) ## Argument Explanations diff --git a/docs/vspec_arch.md b/docs/vspec_arch.md index ab0ccbeb..a2ad7fa5 100644 --- a/docs/vspec_arch.md +++ b/docs/vspec_arch.md @@ -134,13 +134,13 @@ branch. The command line interface is designed with [click](https://click.palletsprojects.com/). We are making use of subcommands and evaluating them lazy. That means that we can define the cli interface of subcommands in their own files. -The main cli entrypoint for `vspec` is defined in [vspec.py](../src/vss_tools/vspec/vspec.py). +The main cli entrypoint for `vspec` is defined in [cli.py](../src/vss_tools/cli.py). There you can also see all the subcommands referenced. When building a new exporter tool, this is the place that needs to be adapted as well -as creating a new file similar to the other exporters in [exporters](../src/vss_tools/vspec/exporters). +as creating a new file similar to the other exporters in [exporters](../src/vss_tools/exporters). It is also possible to build a complete different script entrypoint and not hook into the current interface. -All cli options can be imported and used via [cli_options.py](../src/vss_tools/vspec/cli_options.py). +All cli options can be imported and used via [cli_options.py](../src/vss_tools/cli_options.py). Only a few are left out which are defined on the toplevel command just as `--log-level`, `--log-file` and `--version`. ## Linters and Static Code Checkers