Merge pull request #109 from OpenSimulationInterface/feature/fmi-30-support

Add FMI 3.0 native support

Author: pmai

doc/spec/basic_conventions.adoc

@@ -27,3 +27,15 @@ A simulator can call the FMU `fmi2DoStep` routine at this implied rate.
 If the step size is not supplied, the model communication rate is determined from any input configuration data the model provides, or it must be configured manually.
 
 The model may have inputs, outputs, and parameters that are not specified by OSMP if the model can be run correctly with all of those variables left unconnected and at their default values.
+
+== FMI 3.0
+
+Alternatively a model can be packaged as a valid FMU for co-simulation as specified in the FMI 3.0 standard cite:[fmi3.0].
+In this case, unless otherwise noted, all specifications in the FMI 3.0 cite:[fmi3.0] standard apply as-is.
+
+The rules above for FMI 2.0 apply, with the provision that the annotation shall be placed as an `<Annotation>` element into the `<Annotations>` element of the `modelDescription.xml`:
+
+[source,xml]
+----
+<Annotation type="net.pmsf.osmp" xmlns:osmp="http://xsd.pmsf.net/OSISensorModelPackaging"><osmp:osmp version="1.4.0" osi-version="x.y.z"/></Annotation>
+----

doc/spec/binary_variables.adoc

@@ -6,16 +6,17 @@ endif::[]
 
 FMI 2.0 cite:[fmi2.0] does not directly support the efficient exchange of arbitrary binary data between FMUs.
 OSMP therefore introduces the concept of notional binary variables that are mapped to actual integer variables for use with FMI 2.0 cite:[fmi2.0].
-Future FMI versions will directly support binary variables compatible with this concept.
+
+For FMI 3.0 cite:[fmi3.0] and above these notional binary variables can be directly mapped into actual binary variables as specified below.
 
 A notional binary variable named `<prefix>` is defined using the following conventions:
 
-The name of the notional binary variable given by `<prefix>` shall be a valid structured name according to FMI 2.0 cite:[fmi2.0].
+The name of the notional binary variable given by `<prefix>` shall be a valid structured name according to FMI 2.0 cite:[fmi2.0] (or FMI 3.0 cite:[fmi3.0] for 3.0 FMUs).
 
 The FMU shall not contain any other variable that is named `<prefix>`.
 This restriction ensures that there is no conflict between notional binary variables and actual variables.
 
-For each notional binary variable, three actual FMU integer variables shall be defined:
+For FMI 2.0, for each notional binary variable, three actual FMU integer variables shall be defined:
 
 `<prefix>.base.lo`::
 Lower, meaning the least significant, 32-bit address part of the binary data buffer to be passed into or out of the model, cast into a signed 32-bit integer without changing the bit values.
@@ -71,3 +72,42 @@ This convention allows the use of FMUs in simulation engines that have no specia
 The simulation engine can rely on the provided buffer to remain valid from the moment it is passed out of a model until the end of the next co-simulation calculation cycle.
 Thus, the simulation engine does not need to copy the contents in that case, corresponding to zero-copy output for the simulation engine at the cost of double buffering for the model providing the output data.
 It is possible to daisy-chain FMUs with protocol buffer inputs and outputs in a normal simulation engine supporting FMI, and get valid results.
+
+== FMI 3.0
+
+For FMI 3.0, each notional binary variable is mapped to an actual binary variable with the name `<prefix>` and the causality and variability of the notional binary variable.
+
+The variable shall have a start value of length 0 (i.e. the empty binary), indicating that no valid binary data is available.
+The variable may have a different or no start value if the combination of causality and variability precludes this, for example, for `@variability = fixed` or `@variability = tunable` and `@causality = calculatedParameter`.
+
+Model FMUs shall interpret empty binary values to indicate that no valid binary data is available.
+Model FMUs shall handle this case safely.
+
+The actual binary variable shall contain an annotation of the following form in the `<Annotations>` child element of their `<Binary>` element of the `modelDescription.xml`:
+
+[source,xml]
+----
+<Annotation type="net.pmsf.osmp" xmlns:osmp="http://xsd.pmsf.net/OSISensorModelPackaging"><osmp:osmp-binary-variable name="<prefix>" role="full" mime-type="<mime-type>"/></Annotation>
+----
+
+`<prefix>` is the prefix as defined above.
+
+It is an error if there is not exactly one variable for the same name.
+
+The MIME type given in `@mime-type` shall be a valid MIME type specification.
+
+In the case of OSI-specified data, the MIME type shall have the following form to indicate that the binary content is conformant to the given OSI version and contains a message of the given type:
+
+[source,xml]
+----
+application/x-open-simulation-interface; type=<type>; version=x.y.z
+----
+
+`<type>` shall be the name of an OSI top-level message, excluding the `osi3::` prefix.
+
+The version parameter of the MIME type `application/x-open-simulation-interface` will default to the version specified in the `@osi-version` attribute as part of the top-level `<osmp:osmp>` annotation.
+It is an error if a version number is specified neither as part of the MIME type nor using the `@osi-version` attribute.
+
+The guaranteed lifetime of the binary data transported through the actual variable is defined in the FMI 3.0 standard, **regardless** of any specifications in the following sections.
+
+Alternatively, for specific compatibility or other reasons, it is permissible, though not recommended, for an FMI 3.0 FMU to follow the FMI 2.0 approach as specified above.

osmp.xsd

@@ -23,6 +23,7 @@
                         <xs:enumeration value="base.lo"/>
                         <xs:enumeration value="base.hi"/>
                         <xs:enumeration value="size"/>
+                        <xs:enumeration value="full"/>
                     </xs:restriction>
                 </xs:simpleType>
             </xs:attribute>