Generation S-Functions from header annotations - vishia Tool

As written in GenSfn_SmlkApproaches.html the best way to use all capabilities of S-Functions are manual written ones. Because: All operations can be used.

But manuel writing is an hi effort. Generally, instead manual writing also generating is possible. The generator can be adapted to use the necessary features. Instead, using a standard ready to use generator for S-Functions, it may not have the required features.

Because of many years of experience with header files and textual code generations I have written a generator which takes informations annotated in header files as input for S-Functions. The tool basic are only one Java jar file with about 1.2 MByte size, nor more is necessary. It uses the ZBNF-Parser to parse the header files, the JZtxtcmd as generator, and some script files.

The script files are the complex ones. They are not open source, but available with a basic fee. You can study generated files using the downloaded zip file, see #example.

The header files uses (should use) Javadoc approaches. The C sources should use an Object Oriented approach, binding operations ("C-functions") to data. Internally C++ can be used, but the interface for the S-Functions is yet C only.

For example the data for a simple T1 FBlock is defined as (see emC/Ctrl/T1_Ctrl_emC.h):

This FBlock has three operations, the constructor, the init routine and the step routine. It is possible to have more as one step routine either to get slightly different functionality with the same data definition (for example a DT1-FBlock) or to get access routines:

Here the Description has a @simulink anotation. This constructor is called after creation of the FBlock in Simulink (mdlStart(…​)), respectively it is created in the startup routine of generated code. It is possible that the routine has non-tunable parameter, given in Simulink by the parameter dialog.

The initialization routine, designated with @simulink init in the comment, is called in the target code in a loop till initialization is done, and in simulink in the first step routines. It is possible to get values from other FBlocks in the model. Hence a loop is necessary to initialize all FBlocks independent of a sophisticated calling order. It is a concept. In this example only non-tunable parameters are used and the initialization can be done in the first call.

This routine is not inline, because it should not be fast executed. It contains some more complex stuff. For example calculate the fTs with an e-function: 1.0f - expf(-Tstep / Ts_param)). Hence it is written in the associated C-File.

This is the step routine to call in manual programming as forward declaration.

The step routine is really inline, hence fast. It is only a simple artithmetic. Inline allows fast execution. Hint: The prototype definition before is necessary to prevent warnings for some compiler.

This is another, an access routine for manual call, access to the differential part of a DT1 usage of the FBlock. Prototype and inline implementation.

This routine determines the FBlock itself, with designation @simulink Object-FB. It uses the ctor and the init and maybe some more other routines inside the FBlock, see

The header contains here also the implementation of the step routine, for this simple functionality. The necessary annotations are shown already, only the @simulink …​ tag is necessary. But Javadoc-style is necessary.

Some informations are gotten from writing style of names: Tstep is always the first step time, not only the name of a parameter. The FBlock gets this determined step time per paramter value.

Names ending with _param are parameters (in dialog field in the S-Function). This parameter are tunable for step routines, and non tunable for parameters in the constructor and the init routine.

The data pointer have to be named thiz (not this which is a keyword in C++, but it has the adequate meaning for Object Orientation in C). The output’s names should end with _y. Unfortunately the return value is not able to use as only one output yet. More as one output should be a reference anytime. But that is the reason of an additonal inline operation. The compiler will be optimized it, it is usual not a disadvantage in runtime.

More informations are not necessary to designate the C data and operations to use as S-Function. Any operation with @simulink Object-FB build one S-Function.

Maybe follow also the video: ../../mp4/GenSfn-C.mp4

As example for generation, the script in

is explained here.

As you can see the first part of the generation script is a matlab script. The matlab script calls firstly a Java process from the operation system which generates the S-Function wrapper.c and tlc files.

Then with the generated files, the mex compiler is invoked, either for debug, or only release, or both. Newly generating for debug is necessary if you want to debug internally in the S-Functions for example with Visual-Studio "Attache to process". For running the S-Functions in Simulink only the release version is necessary. That is independent of an installed compiler, only dependent on the operation system (usual generated for MS-Windows, all 64 bit versions).

The scripts for generating the SFunction second source files and also the vishiaFBcl.jar are not open source. You can use it as 'Shareware' getting the compiled version of the vishiaFBcl.jar which includes also the scripts for generating. If you are interest how does it work, you should offer your name, institute and your approach.

You can also follow to the GenSfnFromHeader_HowDoesItWork.html. There partially it is explained how does the generation works, with showing the script and somewhat from the vishiaFBcl.jar java files to get an impression.

But follow the genration script, which you can use as template or pattern for your own with the 'Shareware' approach:

The rest of the script is commented for Matlab, but it is recognized as JZtxtcmd script. You see an included file for this script. This is the internal script. It can be either loaded from the jar file, or, if you have the original, included as file.

The sub text written above is included in the mex generation file. In this case it contains a line for the matscript to copy a special file necessary for code generation into the mex destination folder.

This is one of the essential statements. A Fileset in JZtxtcmd defines some files which can be handled in subroutines. This Fileset contains only one file, here all header files should be named which are used to control the generation. This Header files should contain the annotations as described in chapter above Definition and Annotations in header files - Principle and first example..

The path is relative starting from the current directory in Simulink, which is the condition of starting this script. The Simulink current directory is in the working tree src where also setupMatlabPath.m is found.

The colon in the path is a special separator, after them starts the 'local path' of the file. The 'local path' is also that one which is used in include statements.

This is the include path used for the mex compiler. The directories for include are also given as Fileset, starting from the Simulink’s current directory, where also all source files should be able to find. It is the whole src tree of the working directory. For this concept you can also refer to ../../../SwEng/html/srcFileTree.html.

Here the base directory for all emC files are named as part of the include path, but also two directories which contains applstdef_emC.h (see ../../../emc/html/Base/applstdef_emC_h.html) and compl_adaption.h (see ../../../emc/html/Base/compl_adaption_h.html) especially for the S-Function mex compilation with Visual Studio.

The part above is a file set with the name srcTlc_ following with exact the name of the header file without extension .h. It means each header (more possible) should have one such entry. It lists the (usual one) source file to the header, which contains the implementation. The same source file should be used also for code generation and for the accelerator mode of Simulink as source for compilation.

Note that it is a good style guide that each user header file has exact one or some inplementation files, or revers: each implementation file should have exact one header associated to it which declares the content as interface. This proven style is presumed here.

This is the file set especially for the S-Function or the mex compilation. The name of the file set should be built with src_ following with the name of the header file, adequate as the srcTlc_…​. It is presumed of course that all S-Functions which are declared in one header uses the same implementation files. Of course some system files are necessary for example to fulfill exception handling, allocation, etc. This files build the mex dll. For code generation this files are also present, but one time for the whole code generation, which is one executable. For the mex dll compilation each mex dll should contain this stuff, because all mex dll are primary independent (concept of dll in Windows).

If you have more as one header file, and some header files needs the same content here, you can build an extra file set src_emC or src_base and include it here. See some other +mkSfn/…​m files.

This is the main routine for JZtxtcmd and also the end of the script which closes the JZtxtcmd part and the mathlab comment.

The main routine contains the shown zmake call. zmake is a statement in ../../../JZtxtcmd/html/JZtxtcmd.html#chapter_7.7. It combines some arguments for a make.

How does it work, please refer to GenSfnFromHeader_HowDoesItWork.html. But the normal user may not know that details. Refer it if you are interest and you have the necessary time.

You should study the generated files to recognize which is generated. For that details you find helps on Mathworks. Especially all ss…​ routines in the S-Function wrapper are explain there, as also the whole S-Function concept.

The possibility to wire some S-Functions with association or aggregation relations (UML) is another possibility of this S-Function approach. It enhances the Function block - Data flow modeling style. It is described for example in "Grafische objektorientierte C-Programmierung mit Simulink" (Fachartikel in Elektronik Praxis in german).

Another example is written right side. The two modules Controller and Parameter Optimizer known one together. Both are aggregated, because the exchange some internal data. But the modules are separated, as an architecture decision. Maybe because there are different responsibilities in development, they run on different cores of a processor or something similar.

The necessary references are handles (32 bit) which are checked and replaces by the correct memory addresses inside the S-Function running Simulink-simulation. For code generation (Simulink Coder) or manual programming the handles are immediately replaced by the real 32-bit addresses for a target controller.

For this approach the data struct should base on a ObjectJc part. This is a core feature of the ../../../emc/index.html (embedded multiplatform C/C++).

An header file content for a more complex FBlock, a PID controller with separated parameter FBlock (can hold the parameter for more as one PID) looks like:

This are the data and routines of the parameter FBlock. Some parameters can be changed in runtime, via wired connections (not only via the parametrizing dialog box). But the parametrizing should use often an own slower step time. It is defined as the Tstep in the constructor.

The important but also simple data property is the base class ObjectJc. This class contains so named 'Reflection' of type ClassJc. The concept is adequate Java. Via the 'Reflection' the type is checked in the startup phase of the simulation. For a target software (well tested) a simple version of ObjectJc maybe without 'Reflection' is possible. It needs only 32 bit, proper for a poor target, for example 16 bit controller with less memory.

But the 'Reflection' property can be used both in Simulink as also in a target for symbolic access to data, using the ../../../Inspc/index.html approach.

The associated FBlock, the PID controller itself, has the following data structure (shortened):

The init routine uses a reference (pointer):

This is matching to the parFactors_y output of the set_Par_PIDf_Ctrl_emC(…​) routine. The FBlock PIDctrl knows a defined part (only the factors) from the Param_PIDctrl FBlock. The connection between both is a simple number in uint32 format, a handle. Only that is able to handle in a model’s connection, and it is understandable from the view of a model owner without deep knowledge of C programming. The immediately address value need 64 bit, and it is a sensible number.

Any SFunctionBlock has the four life cycle phases:

The problematic or interesting thing on init is: aggregation relation. The init phase should clarify ObjectOriented aggregation relation. It is a connection between ports. A Function Block should firstly initialized, than it can offer itself as reference to aggregate. Only if a FBlock has all aggregations and all aggregated blocks are initialized (have its aggregations and initial values), then the init phase is done. It means the init needs more as one steps. It is done in a specific step time, related with the Tinit time. For code generation this is an own step routine which is called only on startup till all is initialized. For the simulation run such multiple called startup is not intended. Hence it is done in a specific Tinit step time which is called cyclically but not used after initialization.

Some Wrapper for SFunction are already generated (see #example). They are necessary if the mex files should be newly created. They are an object of study to see how the system works.

In the example some libraries are contained:

You can find at https://vishia.org/smlk/Download/ some versions of the zipped Simulink source tree. It has the structure of ../SmlkFileTree/SmlkFileTree.html.

tlc files are beside mex, in mex/tlc_c