From f4180a2cbaff6da9750542618ce843e1a0cbe297 Mon Sep 17 00:00:00 2001 From: "Timothy Rule (VM/EMT3)" Date: Wed, 8 Jan 2025 12:47:32 +0100 Subject: [PATCH] New Simulation AST schema. Signed-off-by: Timothy Rule (VM/EMT3) --- Makefile | 8 +- README.md | 12 +- code/go/dse/Makefile | 45 +++- code/go/dse/ast/Simulation.go | 63 +++++ code/go/dse/ast/ast.go | 1 + code/go/dse/ast/config.yaml | 5 + code/go/dse/ast/metadata.go | 9 + doc/content/schemas/yaml/Simulation.md | 360 +++++++++++++++++++++++++ schemas/yaml/Simulation.yaml | 263 ++++++++++++++++++ 9 files changed, 748 insertions(+), 18 deletions(-) create mode 100644 code/go/dse/ast/Simulation.go create mode 100644 code/go/dse/ast/ast.go create mode 100644 code/go/dse/ast/config.yaml create mode 100644 code/go/dse/ast/metadata.go create mode 100644 doc/content/schemas/yaml/Simulation.md create mode 100644 schemas/yaml/Simulation.yaml diff --git a/Makefile b/Makefile index 15b0964..bb97f08 100644 --- a/Makefile +++ b/Makefile @@ -142,11 +142,11 @@ dist: @ls -1sh $(DIST_DIR)/*.* @ls -1sh $(PYTHON_DIST_DIR)/dist/*.* -_generate_clean: +generate_clean: -@rm -rf $(DOC_SCHEMA_YAML_DIR) $(MAKE) -C code/go/dse clean -generate: _generate_clean $(DOC_YAML_SCHEMAS) +generate_doc: for d in $(DOC_YAML_SCHEMAS) ;\ do \ swagger-cli validate $$d ;\ @@ -159,8 +159,11 @@ generate: _generate_clean $(DOC_YAML_SCHEMAS) done; cp doc/templates/yaml/_index.md $(DOC_SCHEMA_YAML_DIR)/_index.md +generate_code: $(MAKE) -C code/go/dse generate +generate: generate_clean generate_code $(DOC_YAML_SCHEMAS) generate_doc + test: install: @@ -173,4 +176,3 @@ clean: -@rm -rf $(DIST_DIR) .PHONY: default build fbs msgpack python dist dist_package clean $(FBS_SCHEMA_SOURCES) $(MPK_SCHEMA_SOURCES) - diff --git a/README.md b/README.md index 593c7df..86f214d 100644 --- a/README.md +++ b/README.md @@ -90,10 +90,20 @@ $ sudo apt install npm # widdershins $ git clone https://github.com/Mermade/widdershins.git $ cd widdershins/ -$ sudo -E npm install -g widdershins``` +$ sudo -E npm install -g widdershins --before=2020-04-01 # swagger-cli $ sudo -E npm install -g @apidevtools/swagger-cli + +# oapi-codegen +$ go install github.com/oapi-codegen/oapi-codegen/v2/cmd/oapi-codegen@latest + +# Audit +$ npm list -g +/usr/local/lib +├── @apidevtools/swagger-cli@4.0.4 +├── nexe@3.0.0 +└── widdershins@4.0.1 ``` diff --git a/code/go/dse/Makefile b/code/go/dse/Makefile index 57355d4..5244229 100644 --- a/code/go/dse/Makefile +++ b/code/go/dse/Makefile @@ -3,27 +3,44 @@ # SPDX-License-Identifier: Apache-2.0 -KIND_YAML_DIR = ../../../schemas/yaml -KIND_YAML_FILES = $(shell ls $(KIND_YAML_DIR)/*.yaml) +YAML_DIR = ../../../schemas/yaml +KIND_YAML_FILES = $(shell cd $(YAML_DIR); ls *.yaml) +KIND_YAML_FILES := $(filter-out Simulation.yaml, $(KIND_YAML_FILES)) +KIND_GO_FILES = $(subst .yaml,.go, $(KIND_YAML_FILES)) +KIND_FILES = $(addprefix kind/, $(KIND_GO_FILES)) +AST_FILES = ast/Simulation.go ast/metadata.go .PHONY: generate -generate: clean kind +generate: clean kind ast -kind: $(KIND_YAML_FILES) + +kind: $(KIND_FILES) @echo "package kind" > kind/kind.go +kind/%.go: $(YAML_DIR)/%.yaml + @echo "$$(basename $<) --> $@" + @~/go/bin/oapi-codegen -config $(@D)/config.yaml $< > $@ + @sed -i '/delete_this_line/d' $@ + @sed -i '/\/\//d' $@ + @sed -i '/./!d' $@ + @sed -i -e 's/externalRef[[:digit:]]*\.//g' $@ + @sed -i -e 's/`json:"/`yaml:"/g' $@ + @go fmt $@ + +ast: $(AST_FILES) + @echo "package ast" > ast/ast.go +ast/%.go: $(YAML_DIR)/%.yaml + @echo "$$(basename $<) --> $@" + @~/go/bin/oapi-codegen -config $(@D)/config.yaml $< > $@ + @sed -i '/delete_this_line/d' $@ + @sed -i '/\/\//d' $@ + @sed -i '/./!d' $@ + @sed -i -e 's/externalRef[[:digit:]]*\.//g' $@ + @sed -i -e 's/`json:"/`yaml:"/g' $@ + @go fmt $@ -.PHONY: $(KIND_YAML_FILES) -$(KIND_YAML_FILES): - @echo $$(basename $@) - @~/go/bin/oapi-codegen -config kind/config.yaml $@ > kind/$$(basename $@ .yaml).go - @sed -i '/delete_this_line/d' kind/$$(basename $@ .yaml).go - @sed -i '/\/\//d' kind/$$(basename $@ .yaml).go - @sed -i '/./!d' kind/$$(basename $@ .yaml).go - @sed -i -e 's/externalRef[[:digit:]]*\.//g' kind/$$(basename $@ .yaml).go - @sed -i -e 's/`json:"/`yaml:"/g' kind/$$(basename $@ .yaml).go - @go fmt kind/$$(basename $@ .yaml).go .PHONY: clean clean: @rm -f kind/*.go + @rm -f ast/*.go diff --git a/code/go/dse/ast/Simulation.go b/code/go/dse/ast/Simulation.go new file mode 100644 index 0000000..2ee0b30 --- /dev/null +++ b/code/go/dse/ast/Simulation.go @@ -0,0 +1,63 @@ +package ast + +import () + +const ( + SimulationKindSimulation SimulationKind = "Simulation" +) + +type Model struct { + Arch *string `yaml:"arch,omitempty"` + Channels []ModelChannel `yaml:"channels"` + Env *[]Var `yaml:"env,omitempty"` + Model string `yaml:"model"` + Name string `yaml:"name"` + Workflows *[]Workflow `yaml:"workflows,omitempty"` +} +type ModelChannel struct { + Alias *string `yaml:"alias,omitempty"` + Name string `yaml:"name"` +} +type Simulation struct { + Kind SimulationKind `yaml:"kind"` + Metadata *ObjectMetadata `yaml:"metadata,omitempty"` + Spec SimulationSpec `yaml:"spec"` +} +type SimulationKind string +type SimulationChannel struct { + Name string `yaml:"name"` + Networks *[]SimulationNetwork `yaml:"networks,omitempty"` +} +type SimulationNetwork struct { + MimeType string `yaml:"mime_type"` + Name string `yaml:"name"` +} +type SimulationSpec struct { + Arch string `yaml:"arch"` + Channels []SimulationChannel `yaml:"channels"` + Stacks []Stack `yaml:"stacks"` + Uses *[]Uses `yaml:"uses,omitempty"` + Vars *[]Var `yaml:"vars,omitempty"` +} +type Stack struct { + Arch *string `yaml:"arch,omitempty"` + Env *[]Var `yaml:"env,omitempty"` + Models []Model `yaml:"models"` + Name string `yaml:"name"` + Stacked *bool `yaml:"stacked,omitempty"` +} +type Uses struct { + Name string `yaml:"name"` + Path *string `yaml:"path,omitempty"` + Url string `yaml:"url"` + Version *string `yaml:"version,omitempty"` +} +type Var struct { + Name string `yaml:"name"` + Value string `yaml:"value"` +} +type Workflow struct { + Name string `yaml:"name"` + Uses *string `yaml:"uses,omitempty"` + Vars *[]Var `yaml:"vars,omitempty"` +} diff --git a/code/go/dse/ast/ast.go b/code/go/dse/ast/ast.go new file mode 100644 index 0000000..bd41296 --- /dev/null +++ b/code/go/dse/ast/ast.go @@ -0,0 +1 @@ +package ast diff --git a/code/go/dse/ast/config.yaml b/code/go/dse/ast/config.yaml new file mode 100644 index 0000000..82de010 --- /dev/null +++ b/code/go/dse/ast/config.yaml @@ -0,0 +1,5 @@ +package: ast +generate: + models: true +import-mapping: + metadata.yaml: delete_this_line diff --git a/code/go/dse/ast/metadata.go b/code/go/dse/ast/metadata.go new file mode 100644 index 0000000..c0d191e --- /dev/null +++ b/code/go/dse/ast/metadata.go @@ -0,0 +1,9 @@ +package ast + +type Annotations map[string]interface{} +type Labels map[string]string +type ObjectMetadata struct { + Annotations *Annotations `yaml:"annotations,omitempty"` + Labels *Labels `yaml:"labels,omitempty"` + Name *string `yaml:"name,omitempty"` +} diff --git a/doc/content/schemas/yaml/Simulation.md b/doc/content/schemas/yaml/Simulation.md new file mode 100644 index 0000000..6008741 --- /dev/null +++ b/doc/content/schemas/yaml/Simulation.md @@ -0,0 +1,360 @@ +--- +title: "Schema: Simulation" +linkTitle: "Simulation" +--- + +(v0.0.1) + +

Simulation

+ + + + + + +```yaml +kind: Simulation +metadata: + name: project + annotations: + input: somefile.json + generator: parse2ast +spec: + simulation: + arch: linux-amd64 + channels: + - name: physical + - name: network + networks: + - name: CAN + mime_type: application/x + uses: + - name: model.linear + url: https://github.com/boschglobal/dse.fmi + version: 1.1.15 + path: model/linear/path + vars: + - name: enable + value: true + stacks: + - name: stack_name + stacked: true + arch: linux-amd64 + models: + - name: linear + model: model.linear + channels: + - name: physical + alias: scalar + env: + - name: SIMBUS_LOGLEVEL + value: 4 + workflows: + - name: generate-fmimcl + vars: + - name: FMU_DIR + value: "{{.PATH}}/fmu" + +``` + +Simulation Abstract Syntax Tree (AST). + +### Properties + +|Name|Type|Required|Description| +|---|---|---|---| +|kind|string|true|none| +|metadata|object|false|Information relating to an object.| +|» name|string|false|The name of the object.| +|» labels|object|false|Identifying information used to identify objects within the system (e.g. giving a specific 'label' to an object).| +|»» **additionalProperties**|string|false|none| +|» annotations|object|false|Non identifying information (i.e. information specific to the object itself).| +|»» **additionalProperties**|any|false|none| +|spec|[SimulationSpec](#schemasimulationspec)|true|none| + +#### Enumerated Values + +|Property|Value| +|---|---| +|kind|Simulation| + +

SimulationSpec

+ + + + + + +```yaml +arch: linux-amd64 +channels: + - name: string + networks: + - name: string + mime_type: string +uses: + - name: string + url: string + version: string + path: string +vars: + - name: string + value: string +stacks: + - name: string + arch: linux-amd64 + stacked: true + env: + - name: string + value: string + models: + - name: string + model: string + arch: linux-amd64 + channels: + - name: string + alias: string + env: + - name: string + value: string + workflows: + - name: string + uses: string + vars: + - name: string + value: string + +``` + +### Properties + +|Name|Type|Required|Description| +|---|---|---|---| +|arch|string|true|The default system architecture for the simulation.| +|channels|[[SimulationChannel](#schemasimulationchannel)]|true|The list of channels available in this simulation.| +|uses|[[Uses](#schemauses)]|false|The list of uses references to external artifacts or repos.| +|vars|[[Var](#schemavar)]|false|The list of variables available to models in this simulation.| +|stacks|[[Stack](#schemastack)]|true|The list of stacks contained within this simulation.| + +

SimulationChannel

+ + + + + + +```yaml +name: string +networks: + - name: string + mime_type: string + +``` + +### Properties + +|Name|Type|Required|Description| +|---|---|---|---| +|name|string|true|The name of this channel.| +|networks|[[SimulationNetwork](#schemasimulationnetwork)]|false|A list of networks associated with a channel.| + +

SimulationNetwork

+ + + + + + +```yaml +name: string +mime_type: string + +``` + +A network definition. + +### Properties + +|Name|Type|Required|Description| +|---|---|---|---| +|name|string|true|The name of the network signal (on the associated channel).| +|mime_type|string|true|MIME type defining the network.| + +

ModelChannel

+ + + + + + +```yaml +name: string +alias: string + +``` + +A model <-> simulation channel mapping. + +### Properties + +|Name|Type|Required|Description| +|---|---|---|---| +|name|string|true|The name of the channel in the simulation.| +|alias|string|false|The name (alias) of the channel in the model.| + +

Uses

+ + + + + + +```yaml +name: string +url: string +version: string +path: string + +``` + +Defines an external resource used by the simulation. + +### Properties + +|Name|Type|Required|Description| +|---|---|---|---| +|name|string|true|The name of uses item (to be used for references).| +|url|string|true|The URL of the uses item.| +|version|string|false|The tag/version of the uses item.| +|path|string|false|A sub-path relative to the uses artefact (URL or ZIP file) where the item is located.| + +

Var

+ + + + + + +```yaml +name: string +value: string + +``` + +A variable definition. + +### Properties + +|Name|Type|Required|Description| +|---|---|---|---| +|name|string|true|A variable name.| +|value|string|true|A coresponding variable value.| + +

Stack

+ + + + + + +```yaml +name: string +arch: linux-amd64 +stacked: true +env: + - name: string + value: string +models: + - name: string + model: string + arch: linux-amd64 + channels: + - name: string + alias: string + env: + - name: string + value: string + workflows: + - name: string + uses: string + vars: + - name: string + value: string + +``` + +A stack definition which composes one or more models as a logical unit of the simulation. + +### Properties + +|Name|Type|Required|Description| +|---|---|---|---| +|name|string|true|The name of the stack.| +|arch|string|false|The architecture of the stack, if different from the simulation default architecture.| +|stacked|boolean|false|Indicate that models in this stack should be run in a 'stacked' configuration (i.e. as a single process).| +|env|[[Var](#schemavar)]|false|Sets environment variables in the runtime of this simulation stack.| +|models|[[Model](#schemamodel)]|true|The list of models belonging to this simulation stack.| + +

Model

+ + + + + + +```yaml +name: string +model: string +arch: linux-amd64 +channels: + - name: string + alias: string +env: + - name: string + value: string +workflows: + - name: string + uses: string + vars: + - name: string + value: string + +``` + +### Properties + +|Name|Type|Required|Description| +|---|---|---|---| +|name|string|true|The name of the model in the simulation (i.e. the model instance name).| +|model|string|true|The name of the model this instance represents.| +|arch|string|false|The architecture of the model, if different from the stack or simulation default architecture.| +|channels|[[ModelChannel](#schemamodelchannel)]|true|An array of model <-> simulaiton channel mappings.| +|env|[[Var](#schemavar)]|false|Sets environmnet variables in the runtime of this model.
Values defined here supersede those set in the simulation stack (of the model).| +|workflows|[[Workflow](#schemaworkflow)]|false|An array of workflows used to construct/process artefacts used by this model instance.| + +

Workflow

+ + + + + + +```yaml +name: string +uses: string +vars: + - name: string + value: string + +``` + +### Properties + +|Name|Type|Required|Description| +|---|---|---|---| +|name|string|true|The name of the workflow.| +|uses|string|false|If a workflow is located in a different repository than the model, indicate that here.| +|vars|[[Var](#schemavar)]|false|Set variable values to be used by the workflow.| + +undefined + diff --git a/schemas/yaml/Simulation.yaml b/schemas/yaml/Simulation.yaml new file mode 100644 index 0000000..fb6555d --- /dev/null +++ b/schemas/yaml/Simulation.yaml @@ -0,0 +1,263 @@ +# Copyright 2023 Robert Bosch GmbH +# +# SPDX-License-Identifier: Apache-2.0 + +--- +openapi: 3.0.0 +info: + title: Simulation AST + version: 0.0.1 +paths: + /Stack: + get: + responses: + '200': + description: 'Simulation object array.' + content: + application/yaml: + schema: + type: array + items: + $ref: '#/components/schemas/Simulation' +components: + schemas: + Simulation: + description: | + Simulation Abstract Syntax Tree (AST). + type: object + required: + - kind + - spec + properties: + kind: + type: string + enum: + - Simulation + metadata: + $ref: 'metadata.yaml#/components/schemas/ObjectMetadata' + spec: + $ref: '#/components/schemas/SimulationSpec' + example: + + kind: Simulation + metadata: + name: project + annotations: + input: somefile.json + generator: parse2ast + spec: + simulation: + arch: linux-amd64 + channels: + - name: physical + - name: network + networks: + - name: CAN + mime_type: application/x + uses: + - name: model.linear + url: https://github.com/boschglobal/dse.fmi + version: 1.1.15 + path: model/linear/path + vars: + - name: enable + value: true + stacks: + - name: stack_name + stacked: true + arch: linux-amd64 + models: + - name: linear + model: model.linear + channels: + - name: physical + alias: scalar + env: + - name: SIMBUS_LOGLEVEL + value: 4 + workflows: + - name: generate-fmimcl + vars: + - name: FMU_DIR + value: '{{.PATH}}/fmu' + + SimulationSpec: + type: object + required: + - arch + - channels + - stacks + properties: + arch: + type: string + description: The default system architecture for the simulation. + example: linux-amd64 + channels: + type: array + description: The list of channels available in this simulation. + items: + $ref: '#/components/schemas/SimulationChannel' + uses: + type: array + description: The list of uses references to external artifacts or repos. + items: + $ref: '#/components/schemas/Uses' + vars: + type: array + description: The list of variables available to models in this simulation. + items: + $ref: '#/components/schemas/Var' + stacks: + type: array + description: The list of stacks contained within this simulation. + items: + $ref: '#/components/schemas/Stack' + SimulationChannel: + type: object + required: + - name + properties: + name: + type: string + description: The name of this channel. + networks: + type: array + description: A list of networks associated with a channel. + items: + $ref: '#/components/schemas/SimulationNetwork' + SimulationNetwork: + type: object + description: A network definition. + required: + - name + - mime_type + properties: + name: + type: string + description: The name of the network signal (on the associated channel). + mime_type: + type: string + description: MIME type defining the network. + ModelChannel: + type: object + description: A model <-> simulation channel mapping. + required: + - name + properties: + name: + type: string + description: The name of the channel in the simulation. + alias: + type: string + description: The name (alias) of the channel in the model. + Uses: + type: object + description: Defines an external resource used by the simulation. + required: + - name + - url + properties: + name: + type: string + description: The name of uses item (to be used for references). + url: + type: string + description: The URL of the uses item. + version: + type: string + description: The tag/version of the uses item. + path: + type: string + description: A sub-path relative to the uses artefact (URL or ZIP file) where the item is located. + Var: + type: object + description: A variable definition. + required: + - name + - value + properties: + name: + type: string + description: A variable name. + value: + type: string + description: A coresponding variable value. + Stack: + type: object + description: A stack definition which composes one or more models as a logical unit of the simulation. + required: + - name + - models + properties: + name: + type: string + description: The name of the stack. + arch: + type: string + description: The architecture of the stack, if different from the simulation default architecture. + example: linux-amd64 + stacked: + type: boolean + description: Indicate that models in this stack should be run in a 'stacked' configuration (i.e. as a single process). + env: + type: array + description: | + Sets environment variables in the runtime of this simulation stack. + items: + $ref: '#/components/schemas/Var' + models: + type: array + description: The list of models belonging to this simulation stack. + items: + $ref: '#/components/schemas/Model' + Model: + type: object + required: + - name + - model + - channels + properties: + name: + type: string + description: The name of the model in the simulation (i.e. the model instance name). + model: + type: string + description: The name of the model this instance represents. + arch: + type: string + description: The architecture of the model, if different from the stack or simulation default architecture. + example: linux-amd64 + channels: + type: array + description: An array of model <-> simulaiton channel mappings. + items: + $ref: '#/components/schemas/ModelChannel' + env: + type: array + description: | + Sets environmnet variables in the runtime of this model. + Values defined here supersede those set in the simulation stack (of the model). + items: + $ref: '#/components/schemas/Var' + workflows: + type: array + description: An array of workflows used to construct/process artefacts used by this model instance. + items: + $ref: '#/components/schemas/Workflow' + Workflow: + type: object + required: + - name + properties: + name: + type: string + description: The name of the workflow. + uses: + type: string + description: If a workflow is located in a different repository than the model, indicate that here. + vars: + type: array + description: | + Set variable values to be used by the workflow. + items: + $ref: '#/components/schemas/Var'