From a0905147c499737ec9414f2eac45cc239c70d297 Mon Sep 17 00:00:00 2001 From: "Rule Timothy (CC/EMT2)" Date: Wed, 15 May 2024 12:06:46 +0200 Subject: [PATCH] Signal transform documentation. Signed-off-by: Rule Timothy (VM/EMT3) --- doc/content/docs/arch/signalvector/index.md | 126 +++++++++++++++----- 1 file changed, 96 insertions(+), 30 deletions(-) diff --git a/doc/content/docs/arch/signalvector/index.md b/doc/content/docs/arch/signalvector/index.md index 3d212cb..130f5e5 100644 --- a/doc/content/docs/arch/signalvector/index.md +++ b/doc/content/docs/arch/signalvector/index.md @@ -13,34 +13,10 @@ github_subdir: "doc" The Dynamic Simulation Environment (DSE) presents models with a simple vector interface for the exchange of signals. Those signals can be either: -- **scalar** : Internally represented as a 64bit storage container (double). These values are transparently exchanged between models, and those models may cast the values to other types (as required by the simulation designer). -- **binary** : Binary strings (i.e. including embedded NULL characters) can be exchanged between models, and with an associated _MIME type_, complex bus simulations can be realised. - - -An associated API can be used to access signal vectors: - -```c -#include - -int model_function(ModelInstanceSpec* mi) -{ - SignalVector* sv = model_sv_create(mi); - while (sv && sv->name) { - for (uint i = 0; i++; i < sv->count) { - if (sv->is_binary) { - sv->reset(sv, i); - sv->append(sv, i, "hello world", 12); - printf("%s = %f (%s)\n", sv->signal[i], sv->binary[i], sv->mime_type[i]); - } else { - printf("%s = %f\n", sv->signal[i], sv->scalar[i]); - } - } - /* Next signal vector. */ - sv++; - } -} -``` +- **scalar** : Internally represented as a 64bit storage container (double). These values are transparently exchanged between models. Models may cast/convert these scalar values to other types as required. +- **binary** : Binary strings, which may container embedded NULL values, can be exchanged between models. Additionally a binary signal may be annotated with a _MIME type_ which describes the content of a binary signal. +{{% alert title="Tip" color="info" %}} Binary signals with an associated MIME type may be supported by a [Network Codec]({{< relref "docs/devel/modelc_ncodec/index.md" >}}) which has an API that simplifies interactions with binary data and can be used to realise network simulations (e.g. CAN bus messaging). {{% /alert %}} ## Scalar Signal Vector @@ -97,7 +73,7 @@ sv->release(sv, i); /* Free the memory buffer of a binary signal. */ const char* value = sv->annotation(sv, i, "name"); ``` -{{% alert title="Tip" color="info" %}} Generally calling `sv->release()` is not necessary and, if avoided, will result in less memory allocation overhead during model runtime. {{% /alert %}} +{{% alert title="Tip" color="info" %}} Using a Network Codec simplifies operations with binary signals. {{% /alert %}} ### Configuration @@ -126,11 +102,101 @@ spec: +## Transformations + +A scalar signal may be associated with a transformation by the `transform` node located alongside the `signal` node in a `SignalGroup` definition. The following transformations are supported: + +| Transform | Description | +| --------- | ----------- | +| `linear` | S~model~ = S~vector~ * `factor` + `offset` | + + +When signals are set by a model, all defined transformations are applied in the reverse direction _before_ those signal values are exchanged with other models in a simulation. Therefore a transformed signal value is only observable by a model which is associated with such a signal definition. + + +### Configuration + +Transformations are configured for individual signals in a `SignalGroup` YAML document. + +**Scalar Signal Vector with Transformations :** +```yaml +kind: SignalGroup +metadata: + name: scalar +spec: + signals: + - signal: foo + - signal: bar + transform: + linear: + factor: 20 + offset: -100 +``` + + + +## API Examples + +### Using the Model API + +(_definied in [dse/modelc/model.h](https://github.com/boschglobal/dse.modelc/blob/main/dse/modelc/model.h)_) + +Signal vectors are located on the `ModelDesc` object (`model->sv`) as a NTL (Null terminated list) and can be indexed with the `model->index` function of the same object. + +```c +int model_step(ModelDesc* model, double* model_time, double stop_time) +{ + // Find a signal using the index method. + ModelSignalIndex counter = model->index(m, "data", "counter"); + if (counter.scalar == NULL) return -EINVAL; + *(counter.scalar) += 1; + + // Find a signal vector using the index method. + ModelSignalIndex data_sv = model->index(m, "data", NULL); + if (data_sv.sv == NULL) return -EINVAL; + + ... +} +``` + +### Using the Runtime API + +(_definied in [dse/modelc/runtime.h](https://github.com/boschglobal/dse.modelc/blob/main/dse/modelc/runtime.h)_) + +The Runtime API can be used to access signal vectors and is of particular use to tool developers and integrators who need access to runtime objects. + +```c +#include + +int model_function(ModelInstanceSpec* mi) +{ + SignalVector* sv = model_sv_create(mi); + while (sv && sv->name) { + for (uint i = 0; i++; i < sv->count) { + if (sv->is_binary) { + sv->reset(sv, i); + sv->append(sv, i, "hello world", 12); + printf("%s = %f (%s)\n", sv->signal[i], sv->binary[i], sv->mime_type[i]); + } else { + printf("%s = %f\n", sv->signal[i], sv->scalar[i]); + } + } + /* Next signal vector. */ + sv++; + } +} +``` + + + ## References * [dse/modelc/model.h](https://github.com/boschglobal/dse.modelc/blob/main/dse/modelc/model.h) - definition of Signal Vector API. * [SignalGroup](https://github.com/boschglobal/dse.schemas/blob/main/schemas/yaml/SignalGroup.yaml) schema definition. * DSE Model C examples: * [Binary Model](https://github.com/boschglobal/dse.modelc/tree/main/dse/modelc/examples/binary) - * [Gateway Model](https://github.com/boschglobal/dse.modelc/tree/main/dse/modelc/examples/gateway) -* [Frame Stream Interface (Automotive Bus)](https://github.com/boschglobal/automotive-bus-schema/blob/main/schemas/stream/frame.fbs) with [sample](https://github.com/boschglobal/automotive-bus-schema/tree/main/examples/streams) code. + * [NCodec Model](https://github.com/boschglobal/dse.modelc/tree/main/dse/modelc/examples/ncodec) + * [Transform Model](https://github.com/boschglobal/dse.modelc/tree/main/dse/modelc/examples/transform) +* Binary Codecs: + * [Network Codec]({{< relref "docs/devel/modelc_ncodec/index.md" >}}) from DSE Model C which implements a stream interface to the Network Codec API by using binary signals and associated MIME type annotations. + * [Network Codec API](https://github.com/boschglobal/dse.standards/tree/main/dse/ncodec) generalised codec library with an example binary stream implementation.