From 1eedc23ebb4748aebd58e2240f8dff5288db22dd Mon Sep 17 00:00:00 2001 From: OLSSON Hans Date: Tue, 7 Jun 2022 14:04:23 +0200 Subject: [PATCH 1/2] Propose complete handling of records in external functions. --- chapters/functions.tex | 27 +++++++++++++++++++++++++++ 1 file changed, 27 insertions(+) diff --git a/chapters/functions.tex b/chapters/functions.tex index 2f6788449..dfa9a31c2 100644 --- a/chapters/functions.tex +++ b/chapters/functions.tex @@ -2220,6 +2220,11 @@ \subsubsection{Records}\label{records} \begin{itemize} \item The record class is represented by a struct in C. +\item + If the record has \lstinline!annotation(CStructName="CName")! the struct has the name CName, \cref{annotations-for-records-in-external-functions}. +\item + If the record has \lstinline!annotation(Include="includeDirective")! it is assumed that the include directive will declare the struct, \cref{annotations-for-records-in-external-functions}. + Without \lstinline!annotation(CStructName="CName")! it is assumed that the name of the struct is the same as the record-class. \item Each component of the Modelica record is mapped to its corresponding C representation. A nested record component is mapped to a nested struct component. @@ -2562,6 +2567,28 @@ \subsection{Annotations for External Functions}\label{annotations-for-external-l The \lstinline!Library! name and the \lstinline!LibraryDirectory! name in the function annotation are mapped to a linkage directive in a compiler-dependent way thereby selecting the object library suited for the respective computer platform. +\subsection{Annotations for Records in External Functions}\label{annotations-for-records-in-external-functions} +Records used in external functions may have the following annotations. + +The following annotations are useful in the context of records used in calling external functions from Modelica. +The first two can specify either a scalar value or an array of values: +\begin{itemize} +\item + The \lstinline!annotation(Include="includeDirective")!\annotationindex{Include}, used to include source files needed for declaring the struct in C. + The included code should be valid C89 code. + \begin{nonnormative} + Examples of files that can be included are header files or source files that contain the struct declaration corresponding to the Modelica record. + \end{nonnormative} +\item + The + \lstinline!annotation(IncludeDirectory="modelica://ModelicaLibraryName/Resources/Include")!\annotationindex{IncludeDirectory}, used to specify a location for header files. + The preceding one is the default and need not be specified; but another location could be specified by using an URI name for the include directory, see \cref{external-resources}. +\item + The \lstinline!annotation(CStructName="CName")!\annotationindex{CStructName} gives the name of the struct in C. + It requires that the name of the struct-members in C are the same as in Modelica. +\end{itemize} +The includeDirective is only included if the record is used in an external function call used in the simulation model. +If multiple record definitions used in this way have the same \lstinline!CName! it is an error unless the records are type compatible. \subsection{Examples}\label{examples1} \subsubsection{Input Parameters, Function Value}\label{input-parameters-function-value} From beaefc2d6980a63453d1cf2f2419fd162a759266 Mon Sep 17 00:00:00 2001 From: OLSSON Hans Date: Fri, 10 Jun 2022 10:00:00 +0200 Subject: [PATCH 2/2] Clarify further, and add example. --- chapters/functions.tex | 35 +++++++++++++++++++++++++++++++++++ 1 file changed, 35 insertions(+) diff --git a/chapters/functions.tex b/chapters/functions.tex index dfa9a31c2..c6238e4d2 100644 --- a/chapters/functions.tex +++ b/chapters/functions.tex @@ -2576,8 +2576,10 @@ \subsection{Annotations for Records in External Functions}\label{annotations-for \item The \lstinline!annotation(Include="includeDirective")!\annotationindex{Include}, used to include source files needed for declaring the struct in C. The included code should be valid C89 code. + It should declare the struct-members in C, but they may be aligned differently, they may be in a different order, and additional padding or fields may exist. \begin{nonnormative} Examples of files that can be included are header files or source files that contain the struct declaration corresponding to the Modelica record. + In this case the consistency is ensured by including the correct definition and thus the contents is freer, whereas the struct generated by tools must be restricted to ensure consistency. \end{nonnormative} \item The @@ -2680,6 +2682,39 @@ \subsubsection{Both Function Value and Output Variable}\label{external-function- \end{lstlisting} \end{example} +\subsubsection{Record example}\label{record-example} + +\begin{example} +The following external function illustrates the annotations in \cref{annotations-for-records-in-external-functions}. +It assumes that the external code uses \lstinline!MyComp_! as a prefix for declarations to avoid namespace collisions. +\begin{lstlisting}[language=modelica] +record R + Real x; + Integer y; + annotation(CStructName="MyComp_R"); +end R; +record R2 + Real z; + Real w; + annotation(Include="struct MyComp_R2 {double a,w,z;}"); + // Note different order and a is unused. +end R2; +function foo + input R r; + input output R2 r2; +external "C" + MyComp_foo(r, r2); + annotation(Include="void MyComp_foo(const struct MyComp_R*r, struct MyComp_R2*r2);"); +end foo; +\end{lstlisting} +This will generate C-code along these lines: +\begin{lstlisting}[language=C] +struct MyComp_R2 {double a,w,z;} +struct MyComp_R {double x;int y;} +void MyComp_foo(const struct MyComp_R*r, struct MyComp_R2*r2); +\end{lstlisting} +\end{example} + \subsection{Utility Functions}\label{utility-functions} This section describes the utility functions declared in \filename{ModelicaUtilities.h}, which can be called in external Modelica functions written in C.