Create an S Function - AD-EYE/AD-EYE_Core GitHub Wiki

An S-function is a computer language description of a Simulink block written in MATLAB, C, C++, or Fortran. S-functions are dynamically linked subroutines that the MATLAB execution engine can automatically load and execute.

S-functions define how a block works during different parts of simulation, such as initialization, update, derivatives, outputs and termination. In every step of a simulation, a method is invoked by the simulation engine to fulfill a specific task.

Creating an S function

To create an S function, open a blank Simulink model and add the S-Function Builder block from the Library Browser.

The S-Function Builder integrates new or existing C or C++ code and creates a C MEX S-function from specifications you provide. Instances of the S-Function Builder block also serve as wrappers for generated S-functions in Simulink models. When simulating a model containing instances of an S-Function Builder block, Simulink software invokes the generated S-function in order to call your C or C++ code in the instance's mdlStart, mdlOutputs, mdlDerivatives, mdlUpdate and mdlTerminate methods.

Double click to open the S-Function Builder-

Specify a name for your S-Function that explains what it does, for example "sim_time_calc" for an S function that calculates the wall time of a simulation. Note that when you name an S-function, all functions in the S-Function Builder editor changes and the S-function name becomes a prefix to all wrapper functions.

The code is written in the S-Function Builder under the different tabs such as Libraries, Start, Outputs and Terminate and then Build generates the code that we want to run at different stages of simulation in the different functions.

Explaining the different parts of an S-Function using the example of an S-Function that calculates the wall time of a simulation

1. Libraries

Here you can enter any library/object or source files used by the S-Function. You can also specify any necessary include files or define global variables that will be used in the Start, Output and Terminate methods.

In our example, we specify the header files for printing on Windows and Linux as well as the global variables that will be used in the other wrapper functions.

2. Start

This tab can be used for one-time initialization and memory allocation.

In our example, we obtain the simulation start time using the gettimeofday() function. We also set the values of the variables that should be set at the start of the simulation such as the total duration, previous step duration, maximum and minimum step duration.

3. Outputs

Here you enter the C-code that does the computation or call your algorithm.

In our example, we obtain the simulation end time using gettimeofday() function and then calculate the simulation time by subtracting end time and start time. We also calculate the step duration between 2 iterations and also the maximum and minimum step duration.

4. Terminate

This section is used to perform operations required at the end of the simulation.

In our example, we print the different values that we have calculated in the Outputs tab.

5. Build

Once you write the code in the different tabs you can generate the code in the wrapper files by clicking on Build on the top right corner. Build generates the following files-

  1. s_function_name.c

This file consists of the different mdl functions such as mdlStart(), mdlOutputs() and mdlTerminate(). Inside these mdl functions the wrapper functions such as s_function_name_Start_wrapper(), s_function_name_Outputs_wrapper() and s_function_name_Terminate_wrapper() are called.

  1. s_function_name_wrapper.c

This files contains the code generated from the S-Function Builder. Hence, it also contains the function definitions of s_function_name_Start_wrapper(), s_function_name_Outputs_wrapper() and s_function_name_Terminate_wrapper() functions.

  1. s_function_name.tlc

This file consists of the functions that will be used during code generation.

Adding an S_Function to your Experiment

To do this, you simply have to copy paste the S-Function from the model that contains the S-Function into your model. When you run your simulation, the S-Function will also run during the different stages that it has been called in.

Code generation

To generate code and run the S-Function on Linux, follow this link.

If you face any issues regarding Prescanrun, refer to this link