diff --git a/doc/Makefile b/doc/Makefile index 36d1ee5..c67ded7 100644 --- a/doc/Makefile +++ b/doc/Makefile @@ -59,7 +59,7 @@ DOC_C_MODULES := fmimcl fmimodelc fmu fmigateway .PHONY: examples examples: cd ..;mkdir -p doc/content/apis/fmi/examples/fmu - cd ..;cp dse/examples/fmu/counter/fmu.c doc/content/apis/fmi/examples/fmu/fmu.c + cd ..;cp dse/examples/fmu/counter/counter.c doc/content/apis/fmi/examples/fmu/fmu.c .PHONY: index index: diff --git a/doc/content/apis/fmi/examples/fmu/fmu.c b/doc/content/apis/fmi/examples/fmu/fmu.c index b6363eb..e2b23c3 100644 --- a/doc/content/apis/fmi/examples/fmu/fmu.c +++ b/doc/content/apis/fmi/examples/fmu/fmu.c @@ -2,34 +2,36 @@ // // SPDX-License-Identifier: Apache-2.0 -#include -#include #include -#define UNUSED(x) ((void)x) -#define VR_COUNTER "1" +typedef struct { + double counter; +} VarTable; int fmu_create(FmuInstanceData* fmu) { - UNUSED(fmu); + VarTable* v = malloc(sizeof(VarTable)); + *v = (VarTable){ + .counter = fmu_register_var(fmu, 1, false, offsetof(VarTable, counter)), + }; + fmu_register_var_table(fmu, v); return 0; } int fmu_init(FmuInstanceData* fmu) { - hashmap_set_double(&(fmu->variables.scalar.output), VR_COUNTER, 0.0); + UNUSED(fmu); return 0; } -int fmu_step( - FmuInstanceData* fmu, double CommunicationPoint, double stepSize) +int fmu_step(FmuInstanceData* fmu, double CommunicationPoint, double stepSize) { UNUSED(CommunicationPoint); UNUSED(stepSize); + VarTable* v = fmu_var_table(fmu); /* Increment the counter. */ - double* counter = hashmap_get(&fmu->variables.scalar.output, VR_COUNTER); - if (counter) *counter += 1; + v->counter += 1; return 0; } diff --git a/doc/content/apis/fmi/fmigateway/index.md b/doc/content/apis/fmi/fmigateway/index.md index 42402f5..ac8d000 100644 --- a/doc/content/apis/fmi/fmigateway/index.md +++ b/doc/content/apis/fmi/fmigateway/index.md @@ -2,21 +2,6 @@ title: FMI Gateway FMU API Reference linkTitle: Gateway FMU --- -## fmu_signals_reset - - -Resets the binary signals of the gateway to a length of 0, if the signals have -not been reseted yet. - -> Required by FMU. - -### Parameters - -fmu (FmuInstanceData*) -: The FMU Descriptor object representing an instance of the FMU Model. - - - ## fmu_signals_setup @@ -155,14 +140,37 @@ fmu (FmuInstanceData*) +## fmu_signals_reset + + +Resets the binary signals of the gateway to a length of 0, if the signals have +not been reseted yet. + +> Required by FMU. + +### Parameters + +fmu (FmuInstanceData*) +: The FMU Descriptor object representing an instance of the FMU Model. + + + ## Typedefs ### FmiGateway ```c typedef struct FmiGateway { - int * model; - struct (anonymous struct at dse/fmigateway/fmigateway.h:75:5) settings; + int* model; + struct { + int* doc_list; + const char** yaml_files; + double step_size; + double end_time; + int log_level; + const char* log_location; + FmiGatewaySession* session; + } settings; int binary_signals_reset; } ``` @@ -171,9 +179,19 @@ typedef struct FmiGateway { ```c typedef struct FmiGatewaySession { - WindowsModel * w_models; - struct (anonymous struct at dse/fmigateway/fmigateway.h:61:5) init; - struct (anonymous struct at dse/fmigateway/fmigateway.h:65:5) shutdown; + const char* model_stack; + int* model_stack_file; + WindowsModel* w_models; + WindowsModel* simbus; + WindowsModel* transport; + struct { + int models; + int simbus; + int transport; + } visibility; + const char* init_cmd; + const char* shutdown_cmd; + int envar; double last_step; } ``` @@ -182,17 +200,15 @@ typedef struct FmiGatewaySession { ```c typedef struct WindowsModel { - const char * path; - const char * file; - int show_process; - const char * name; + const char* exe; + const char* name; double step_size; double end_time; int log_level; - const char * yaml; + char* yaml; double current_step; double timeout; - void * w_process; + void* w_process; } ``` diff --git a/doc/content/apis/fmi/fmimcl/index.md b/doc/content/apis/fmi/fmimcl/index.md index c1055cd..8f4880e 100644 --- a/doc/content/apis/fmi/fmimcl/index.md +++ b/doc/content/apis/fmi/fmimcl/index.md @@ -243,7 +243,10 @@ model (ModelDesc*) typedef struct FmuData { int count; const char** name; - uint32_t* binary_len; + struct { + double* scalar; + void** binary; + } binary_len; int* kind; int* mg_table; } @@ -265,7 +268,12 @@ typedef struct FmuModel { void* m_doc; void* adapter; FmuData data; - struct (anonymous struct at dse/fmimcl/fmimcl.h:266:5) measurement; + struct { + char* file_name; + void* file; + int* cg; + int mdf; + } measurement; } ``` diff --git a/doc/content/apis/fmi/fmimodelc/index.md b/doc/content/apis/fmi/fmimodelc/index.md index 3a41067..b03c774 100644 --- a/doc/content/apis/fmi/fmimodelc/index.md +++ b/doc/content/apis/fmi/fmimodelc/index.md @@ -2,53 +2,6 @@ title: FMI ModelC FMU API Reference linkTitle: ModelC FMU --- -## FMI ModelC FMU - - -The FMI ModelC FMU is and FMU which is capable of loading and running a -DSE Simulation (e.g. a ModelC Simulation Stack). All capabilites of the ModelC -Runtime are supported, including the exchange of binary signals (e.g. CAN) and -realisation of bus topologies (e.g. multi-node CAN Networks). - - -### Component Diagram - - - -![](fmimodelc-component.png) - - - - -## fmi2Instantiate - - -Create an instance of this FMU, allocate/initialise a Fmu2InstanceData -object which should be used for subsequent calls to FMI methods (as parameter -`fmi2Component c`). - -> Note: This implementation __does not__ use memory related callbacks provided - by the Importer (e.g. `malloc()` or `free()`). - -### Returns - -fmi2Component (pointer) -: An Fmu2InstanceData object which represents this FMU instance. - - - ## fmi2ExitInitializationMode @@ -70,7 +23,19 @@ fmi2OK (fmi2Status) -## fmi2GetReal +## fmi2FreeInstance + + +Free memory and resources related to the provided FMU instance. + +### Parameters + +c (fmi2Component*) +: An Fmu2InstanceData object representing an instance of this FMU. + + + +## fmi2GetString Get values for the provided list of value references. @@ -86,7 +51,7 @@ vr (fmi2ValueReference[]) nvr (int) : The number of value references to retrieve. -value (fmi2Real[]) +value (fmi2String[]) : Storage for the retrieved values. ### Returns @@ -96,10 +61,10 @@ fmi2OK (fmi2Status) -## fmi2GetString +## fmi2SetReal -Get values for the provided list of value references. +Set values for the provided list of value references and values. ### Parameters @@ -107,25 +72,30 @@ c (fmi2Component*) : An Fmu2InstanceData object representing an instance of this FMU. vr (fmi2ValueReference[]) -: List of value references to retrieve. +: List of value references to set. nvr (int) -: The number of value references to retrieve. +: The number of value references to set. -value (fmi2String[]) -: Storage for the retrieved values. +value (fmi2Real[]) +: Storage for the values to be set. ### Returns fmi2OK (fmi2Status) -: The requested variables are retrieved (where available). +: The requested variables have been set (where available). -## fmi2SetReal +## fmi2SetString -Set values for the provided list of value references and values. +Set values for the provided list of value references and values. String/Binary +variables are always appended to the ModelC Binary Signal. + +> Note: If several variables are indexed against the same ModelC Binary Signal, + for instance in a Bus Topology, then each variable will be appended to that + ModelC Binary Signal. ### Parameters @@ -138,7 +108,7 @@ vr (fmi2ValueReference[]) nvr (int) : The number of value references to set. -value (fmi2Real[]) +value (fmi2String[]) : Storage for the values to be set. ### Returns @@ -182,27 +152,57 @@ fmi2Error (fmi2Status) -## fmi2FreeInstance +## FMI ModelC FMU -Free memory and resources related to the provided FMU instance. +The FMI ModelC FMU is and FMU which is capable of loading and running a +DSE Simulation (e.g. a ModelC Simulation Stack). All capabilites of the ModelC +Runtime are supported, including the exchange of binary signals (e.g. CAN) and +realisation of bus topologies (e.g. multi-node CAN Networks). -### Parameters -c (fmi2Component*) -: An Fmu2InstanceData object representing an instance of this FMU. +### Component Diagram + + +![](fmimodelc-component.png) + + + + +## fmi2Instantiate + + +Create an instance of this FMU, allocate/initialise a Fmu2InstanceData +object which should be used for subsequent calls to FMI methods (as parameter +`fmi2Component c`). + +> Note: This implementation __does not__ use memory related callbacks provided + by the Importer (e.g. `malloc()` or `free()`). + +### Returns + +fmi2Component (pointer) +: An Fmu2InstanceData object which represents this FMU instance. + + + +## fmi2GetReal + + +Get values for the provided list of value references. ### Parameters @@ -210,18 +210,18 @@ c (fmi2Component*) : An Fmu2InstanceData object representing an instance of this FMU. vr (fmi2ValueReference[]) -: List of value references to set. +: List of value references to retrieve. nvr (int) -: The number of value references to set. +: The number of value references to retrieve. -value (fmi2String[]) -: Storage for the values to be set. +value (fmi2Real[]) +: Storage for the retrieved values. ### Returns fmi2OK (fmi2Status) -: The requested variables have been set (where available). +: The requested variables are retrieved (where available). diff --git a/doc/content/apis/fmi/fmu/index.md b/doc/content/apis/fmi/fmu/index.md index a7b6ae0..1573b94 100644 --- a/doc/content/apis/fmi/fmu/index.md +++ b/doc/content/apis/fmi/fmu/index.md @@ -7,21 +7,31 @@ linkTitle: FMU The FMU API provides a simplified FMU inteface with an abstracted varaible interface (indexing and storage). The FMU Interface includes the methods: -* `[fmu_create()]({{< ref "#fmu_create" >}})` -* `[fmu_init()]({{< ref "#fmu_init" >}})` -* `[fmu_step()]({{< ref "#fmu_step" >}})` -* `[fmu_destroy()]({{< ref "#fmu_destroy" >}})` +* Implemented by FMU developer: + * `[fmu_create()]({{< ref "#fmu_create" >}})` + * `[fmu_init()]({{< ref "#fmu_init" >}})` + * `[fmu_step()]({{< ref "#fmu_step" >}})` + * `[fmu_destroy()]({{< ref "#fmu_destroy" >}})` +* Additional provided functions: + * `[fmu_log()]({{< ref "#fmu_log" >}})` - logging function +* Supporting Variable Table mechanism: + * `[fmu_register_var()]({{< ref "#fmu_register_var" >}})` + * `[fmu_register_var_table()]({{< ref "#fmu_register_var_table" >}})` + * `[fmu_var_table()]({{< ref "#fmu_var_table" >}})` + An additional FMU Signal Interface is available for more complex integrations: * `[fmu_signals_reset()]({{< ref "#fmu_signals_reset" >}})` * `[fmu_signals_setup()]({{< ref "#fmu_signals_setup" >}})` * `[fmu_signals_remove()]({{< ref "#fmu_signals_remove" >}})` + FMUs imlemented using this simplified FMU API can be built for both FMI 2 and FMI 3 standards by linking to the relevant implementations: * `fmi2fmu.c` for and FMI 2 FMU * `fmi3fmu.c` for and FMI 3 FMU + Binary variables are supported for FMI 3 and FMI 2 standards. In FMUs built to the FMI 2 standard, binary variables are implemented via FMI String Variables and an associated encoding. @@ -105,9 +115,41 @@ counter. ```c typedef struct FmuInstanceData { - struct (anonymous struct at dse/fmu/fmu.h:175:5) instance; - struct (anonymous struct at dse/fmu/fmu.h:188:5) variables; + struct { + char* name; + int type; + int version; + char* resource_location; + char* guid; + bool log_enabled; + void* logger; + char* save_resource_location; + } instance; + struct { + struct { + int input; + int output; + } scalar; + struct { + int input; + int output; + } string; + struct { + int rx; + int tx; + int encode_func; + int decode_func; + int free_list; + } binary; + FmuSignalVTable vtable; + bool signals_reset; + } variables; void* data; + struct { + void* table; + int var_list; + FmuVarTableMarshalItem* marshal_list; + } var_table; } ``` @@ -156,6 +198,15 @@ typedef struct FmuVTable { } ``` +### FmuVarTableMarshalItem + +```c +typedef struct FmuVarTableMarshalItem { + double* variable; + double* signal; +} +``` + ## Functions ### fmu_create @@ -186,8 +237,8 @@ It is called in the `FreeInstance()` Method of the FMU. #### Parameters -model (ModelDesc*) -: Model descriptor object. +fmu (FmuInstanceData*) +: The FMU Descriptor object representing an instance of the FMU Model. #### Returns @@ -215,6 +266,63 @@ fmu (FmuInstanceData*) +### fmu_log + +Write a log message to the logger defined by the FMU. + +#### Parameters + +fmu (FmuInstanceData*) +: The FMU Descriptor object representing an instance of the FMU Model. + +status (const int) +: The status of the message to be logged. + +category (const char*) +: The category the message belongs to. + +message (const char*) +: The message to be logged by the FMU. + + + +### fmu_register_var + +Register a variable with the FMU Variable Table mechanism. + +#### Parameters + +fmu (FmuInstanceData*) +: The FMU Descriptor object representing an instance of the FMU Model. +vref (uint32_t) +: Variable reference of the variable being registered. +input (bool) +: Set `true` for input, and `false` for output variable causality. +offset (size_t) +: Offse of the variable (type double) in the FMU provided variable table. + +#### Returns + +start_value (double) +: The configured FMU Variable start value, or 0. + + + +### fmu_register_var_table + +Register the Variable Table. The previouly registered variables, via calls to +`fmu_register_var`, are configured and the FMU Variable Table mechanism +is enabled. + +#### Parameters + +fmu (FmuInstanceData*) +: The FMU Descriptor object representing an instance of the FMU Model. +table (void*) +: Pointer to the Variable Table being registered. + + + ### fmu_signals_remove This method will reomve any buffers used to provide storage for FMU variables. @@ -287,3 +395,19 @@ step_size (double) +### fmu_var_table + +Return a reference to the previously registered Variable Table. + +#### Parameters + +fmu (FmuInstanceData*) +: The FMU Descriptor object representing an instance of the FMU Model. + +#### Returns + +table (void*) +: Pointer to the Variable Table. + + +