Skip to content

Latest commit

 

History

History
114 lines (76 loc) · 7.39 KB

binary_variables.adoc

File metadata and controls

114 lines (76 loc) · 7.39 KB
Raw

../_config.adoc = Binary variables

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].

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] (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 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.

<prefix>.base.hi

Higher, meaning the most 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. Note that this variable is only used for 64-bit platforms. For 32-bit platforms, it shall still be present but will always be 0 to support FMUs with 32-bit and 64-bit implementations.

<prefix>.size

Size of the binary data buffer to be passed into or out of the model as a signed 32-bit integer. This restricts the maximum size of binary data buffers being passed around to a size less than 2 GB.

The three actual variables shall have matching causality and variability, which will be the causality and variability of the notional binary variable.

The variables shall have a start value of 0, indicating that no valid binary data buffer is available. The variables 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 values of 0 for the merged base address or the size to indicate that no valid binary data buffer is available. Models FMUs shall handle this case safely.

The three actual variables shall contain an annotation of the following form in the <Annotations> child element of their <ScalarVariable> element of the modelDescription.xml:

<Tool name="net.pmsf.osmp" xmlns:osmp="http://xsd.pmsf.net/OSISensorModelPackaging"><osmp:osmp-binary-variable name="<prefix>" role="<role>" mime-type="<mime-type>"/></Tool>

<prefix> is the prefix as defined above, and @role is either base.lo, base.hi, or size, depending on the variable.

It is an error if there is not exactly one variable of each role for the same name.

The MIME type given in @mime-type shall be a valid MIME type specification.

It is an error if the MIME types specified in the annotations for one notional binary variable differ.

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:

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 buffer pointer transported through the actual variables is defined for each kind of variable, as specified in the following sections.

Generally the lifetime for inputs is from the time they are set to the time the corresponding co-simulation step calculation finishes. For outputs the lifetime is extended from the point the output is provided at the end of a co-simulation step until the end of the next co-simulation step.

This convention allows the use of FMUs in simulation engines that have no special support for the protocol buffer pointers: 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:

<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. It shall be identical to the MIME type specification given in the @mimeType attribute of the binary variable element.

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:

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.