How to make your own blocks with code! (Introduction to S-Functions)10

Posted by Guy Rouleau,

I have to admit... before joining MathWorks, I was afraid of S-Functions.

Now this makes me laugh, because I know that writing an S-Function is very powerful and not that complicated.

In my opinion, understanding S-Functions is the best way to understand how Simulink works.

When looking at the previous posts on this blog, I realized that I wrote a few posts about advanced usage of s-functions (Variable Size Signals and Unit Delay and Scheduling Future Events), but I never covered the basic of how S-Functions work.

Getting Started with S-Functions

For most MATLAB users, I recommend starting by writing S-Functions in MATLAB (in opposite to C or C++). MATLAB S-Functions have some limitations compared to C or C++, but debugging is easier.

sfundemos

This will launch a library containing links to many examples. In this collection, the simplest model to start with is msfcndemo_timestwo.mdl.

In this model, click on the annotation to open the source code of the S-Function.

Basic structure of an S-Function

If you look at the code, you will find that the S-Function is in fact just a MATLAB function, taking as input a variable block and passing it to another function using the line setup(block).

The block variable

This block variable is an instance of the Simulink.MSFcnRunTimeBlock class. We call it the S-Function run-time object.

Using the run-time object, the S-Function can exchange information with the Simulink engine.

The setup(block) function

In the setup function, the run-time object allows you to specify and obtain information about various characteristics of the block, including ports, parameters, states, work vectors, etc.

In our example msfcn_times_two.m, the properties of ports are set using lines like:

Also, the setup function is responsible for registering a set of callback methods that the Simulink solver will call during different phases of the simulation.

In the times two example, we register only one method, the output function:

If you are interested to see the list of available methods and when they are called, I recommend going through the documentation section How the Simulink Engine Interacts with C S-Functions

Registered Methods

Every time the Simulink engine calls a method of an S-Function, it passes to it the run-time object.

In msfcn_times_two.m, we access the data of the input port and use it to compute the value that will be written to the output port:

Conclusion

This is it for this simple s-function example.

Of course, if you need to multiply a signal by two in Simulink, I recommend using a Gain block, and not an S-Function. But hopefully this simple example gives you an idea of how MATLAB S-functions work.

Do you use S-Functions? Are there S-Functions related topics you would like to be covered in a future post? Leave a comment here.

James Myatt replied on : 1 of 10

I totally agree with your statement that understanding S-Functions is the best way to understand how Simulink actually works. However, since MATLAB S-Functions run in the MATLAB interpreter, they cause a significant decrease in performance and they should never be used in a production environment, and C S-Functions are significantly more complicated. Therefore, in terms of Getting Things Done, S-Functions have limited usefulness. If it were possible to run MATLAB S-Functions compiled like “(Embedded) MATLAB Function” blocks, then I think that this conclusion would probably be reversed.

Guy Rouleau replied on : 2 of 10

@ James, Thank you for the comment. I agree with all the points you mention.

A version of MATLAB S-Function that would be compiled like the MATLAB Function block is definitely something to be considered for the future.

Allan Baker replied on : 3 of 10

Many times we use MATLAB based S-Functions to add our own interactive graphics to Simulation runs. When are capabilities such as Java or .NET interfaces to Simulink going to be added so we can make things faster? Are these things under consideration?

Zhichang replied on : 4 of 10

I have searched many materials about S-Function. However, they are all very difficult to understand. Today, I am so luckly to meet your blog here. I have studied S-Function for weeks and I have met some questions about it. I am using the SIMULINK & QUARC soft to do an experiment, and I have created a model with S-Function(leval 1). We need use the QUARC soft to build this model to C. In the build process, the matlab told us we need a TLC file of the M-file in the S-Function. I have soved this problem using the S-Function Builder. However,this is only a way the matlab told me. Another one is to creat a TLC file related to the M file. It so difficulit for me. Maybe you can told me the method about how to creat a TLC file. Thanks!

Praveen Suvarna replied on : 5 of 10

hi,
The model on which im working, the requirement is such that i have to write a s fuction which recieves the single input and directly executes the model. Its like when i enter the input value in command window, my output window shoud open and show the response…how to go about it?

Matt Pollock replied on : 6 of 10

I’m writing an s-function for an adaptive controller and I’m looking for some 2-dimension functionality out of the Dwork object, does this exist? Would I just have to use multiple Dwork vectors or reshape one large vector to accomplish? Thanks!

cK replied on : 7 of 10

Well, I doubt if this article provides anything more than what the times-two built-in demo function does. The demo helps understand some structure of s-functions, but doesn’t take you anywhere near doing other tasks, even simpler. Of all the help topics in Matlab & Simulink, I think those of s-function are the worst compiled stuff. They dont take you anywhere only end up confusing a beginner.

jabbar replied on : 8 of 10

thank u for prosperous post big Guy!
i want to make an S-function which is capable to read from file! help me for god’s sake!