Who shall define the prefix for source code FMUs?

[modelica-trac-importer]

Reported by cbertsch on 5 Jun 2017 15:26 UTC
I have a perhaps naive question regarding the prefixing of FMI-Functions in source code FMUs.

Citing from the FMI 2.0 Standard p.14:

The goal is that both textual and binary representations of FMUs are supported and that several FMUs
might be present at the same time in an executable (for example FMU A may use an FMU B). In order
for this to be possible, the names of the functions in different FMUs must be different or function pointers
must be used. To support the first variant macros are provided in “fmi2Functions.h” to build the actual
function names by using a function prefix that depends on how the FMU is shipped. Typically, FMU
functions are used as follows:
// FMU is shipped with C source code, or with static link library
#define FMI2_FUNCTION_PREFIX MyModel_
#include "fmi2Functions.h"
< usage of the FMU functions >

I am wondering, if the prefix shall be defined in the source code (as I have done it in the reference FMUs now) or by the importing tool in the compile command with something like

cl ... /DFMI2_FUNCTION_PREFIX=MyModel_ source_file.c ...

(Visual Studio specific: (https://msdn.microsoft.com/en-us/library/aa235412%28v=vs.60%29.aspx) or -D for gcc https://gcc.gnu.org/onlinedocs/gcc/Preprocessor-Options.html)

The advantage of this solution would be, that multiple instances of the same source-code FMU could be compiled and that the same C-Code code could also be used to create a dynamic link library (e.g. for a different OS)

Or do I get something wrong?

---

Migrated-From: https://trac.fmi-standard.org/ticket/420

[modelica-trac-importer]

Comment by andreas.junghanns on 5 Jun 2017 15:31 UTC
I agree that both versions should be possible from the same source code FMU.
We have so far failed to define exactly how this can be accomplished and it takes looking at the sources and figuring it out.

This is something to be clarified/defined for the next standard version.

[KarlWernersson]

The specification states that the function prefix must be the modelIdentifier in the xml

FMU is shipped with C source code, or with static link library:
The constructed function name is “MyModel_fmi2GetReal”, in other words the function name is
prefixed with the model name and an “”. As FMI2_FUNCTION_PREFIX the “modelIdentifier”
”attribute defined in , or
is used, together with “” at the end (see sections 3.3.1
and 4.3.1). A simulation environment can therefore construct the relevant function names by
generating code for the actual function call. In case of a static link library, the name of the library is
MyModel.lib on Windows, and libMyModel.a on Linux, in other words the “modelIdentifier”
attribute is used as library name.

This partially contradicts the second options.
For 2.01. i would prefer to leave it as is to be as little intrusive as possible.
If a clarification is needed maybe a recommendation that the source guard defines it
#if !defined FMI2_FUNCTION_PREFIX
#define FMI2_FUNCTION_PREFIX ...
#endif

[masoud-najafi]

My question is what is the usage of the FMU with Source code. What I interpret is if an FMU contains the C source code, the importer tool can compile the source code on the fly and generate the DLL (if the tool does not find the appropriate DLL inside the FMU).
Currently, if we define FMI2_FUNCTION_PREFIX and compile the FMU on the fly, no symbol will be exported in the DLL, and the dLL is useless.
Of course the other usage is for embedded applications, where FMI2_FUNCTION_PREFIX is needed.

[KarlWernersson]

decision
move to 3.0

[chrbertsch]

Design meeting in Regensburg:

Discussion:
one should use custom header file to change the header file.
See. p 14 and 66 of FMI 2.0 Spec

Problem occured:
How can one get rid of prefix? By using other header files.

Will be clarified (by Masoud and Torsten S.)

[chrbertsch]

Changed milestone to 2.0.1 as this is only a clarification of FMI 2.0 behaviour. Shall be merged also to fmi 3.0

[chrbertsch]

Summary for FMI Design meeting in Renningen

The discussion is split between:

• Clarify that a modified macro may be used #549
• Who shall define the prefix for source code FMUs? #420

Current problems in FMI 2.0:

• Different interpretations of where to define the prefix by tool vendors lead possibly incompatible source code FMUs or problems with imort of source code FMUS
• Currently nothing really requires the FMU source code to actually use the macros from fmi2Functions.h to define its exported symbols. If we now want unspecific changes to those macros to have a defined effect, we will have to specify this in much more detail.
• Parts of how to handle the prefix is described as a comment in the header file “fmi2Functions.h” and not in the standard document. Are comments in a header file normative?

Use cases:

• Create static link library
• Create dynamic link library

What can be fixed/clarifieid in FMI 2.0.1, what shall be changed FMI 3?

For FMI 2.0.1: describe the current situation (with different interpretations and how an importing tool can handle FMUs with or without an internally defined prefix.

Proposals for Polling for FMI 3:

1. (Derived from comments from Pierre):
   State that FMU source code MUST not define FMI3_FUNCTION_PREFIX internally, and MUST not otherwise hard-code prefixes, but MUST respect an external FMI3_FUNCTION_PREFIX definition and use the appropriate resulting symbol names (without requiring it to use fmi3Functions.h or the name mechanisms therein).
   This allows an implementation to compile a source code FMU to a static library using a prefix of its choice (if we losen the restriction that the provided prefix must be identical to the model identifier in the case that an FMU is being compiled by the importing implementation), and it can compile the same source FMU to a shared object/DLL FMU without a prefix by just not defining the FMI3_FUNCTION_PREFIX.

2. (Derived from comments from Irina)
   FMU source code MUST define FMI3_FUNCTION_PREFIX internally before including fmi3Functions.h. As FMI3_FUNCTION_PREFIX, the "modelIdentifier" attribute defined in or must be used, together with "_" at the end.
   FMU source code MUST not use FMI3_FUNCTION_PREFIX internally, i.e. the function names used in the FMU source code always begin with "fmi3", e.g. "fmi3GetFloat32". The actual names are defined by the definitions in fmi3Functions.h and are therefore given by the importer.

Questions to 2:

• Does an FMU have to include fmi3Functions.h? (see comments in Clarify that a modified macro may be used #549 )

@pmai, @IZacharias and others: please comment and improve the wording of the alternatives to decide on.

[chrbertsch]

Decision at Design Meeting (copy from the meeting minutes https://github.com/modelica/fmi-design/blob/master/Meetings/2019-06-25_FMI-Design-Meeting-Renningen/MeetingMinutes.adoc )

---

#420: Prefixes for FMI functions:

Proposals:

1. Source code FMUs must not define FMU3_FUNCTION_PREFIX (Pierre)
2. Source code FMUs must define FMU3_FUNCTION_PREFIX (this is as it is in FMI 2.0) (Irina)

Irina: According to our experience with FMI 2.0, tools which generate source code FMUs do it in a correct way.
Torsten S: We need to clarify in FMI 2.0.1 that fmi2Functions.h needs to be included.
Pierre: We have to define very clearly what needs to be done if we use version 2. Tools can make many mistakes. It needs to ensured that a modified fmi2Functions.h can be included and everything still works.
Andreas: I still dont get the problem.

Torsten S: Proposal: make it explicit in FMI 2.0.1, this is the default solution for 3.0. If anyone wants to have a different solution, he must explain why.

Andreas: Poll: 1. I don’t care, if it is solution 1 or 2 from above: 12

Solution 2: Leave it as it is as in FMI 2.0, but make description more explicit: 5

Solution 1: Find a better solution: 3

Decision: We go for solution 2!

---

We can fix this in 2.0.1, right?

[chrbertsch]

Closing as included in merged PR #549