Documentation

Comparison of Custom Block Functionality

When creating a custom block, consider:

This table shows how each custom block type addresses the three concerns.

Modelling Considerations

Custom Block TypeModel State DynamicsSimulation Performance Code Generation
FcnNoVery fastSupported
Interpreted MATLAB FunctionNo Less fastNot supported
Level-2 MATLAB S-functionYesLess fastRequires a TLC file
MATLAB FunctionNoFastSupported with exceptions
MATLAB SystemYesFastSupported with exceptions
YesFastRequires a TLC file or non-inline S-Function support
YesFastSupported
Simulink FunctionYesFastSupported
YesFastSupported

For detailed design of custom blocks, consider:

Block Type Flowchart

This diagram helps to decide which block to use. First, determine whether you need the block for a function or a system. A function defines the relationship between a set of inputs and outputs. A system defines the relationship between a set of states as well as a set of inputs and outputs, parameters, System object™ processing methods for initialization, output, update, termination, and so forth.

Note

In the flowchart, Legacy stands for the existing code or models.

Model State Behavior

You need to model the state behavior for a block that requires some or all of its previous outputs to compute its current outputs. See Modeling Dynamic Systems for more information.

Custom Block TypeNotes
Fcn, Interpreted MATLAB FunctionDoes not allow you to model state behavior.
MATLAB FunctionAllows you to model a discrete state using persistent variables.
Level-2 MATLAB® S-FunctionAllows you to model both continuous and discrete state behavior using the ContStates or Dwork run-time object methods in combination with block callback methods. For a list of supported methods, see Level-2 MATLAB S-Function Callback Methods in Write Level-2 MATLAB S-Functions.
MATLAB SystemAllows you to model discrete state behavior using DiscreteState properties of the System object, in combination with block callback methods. This block uses System object methods for callback methods: mdlOutputs (stepImpl, outputImpl), mdlUpdate (updateImpl), mdlInitializeConditions (resetImpl), mdlStart (setupImpl), mdlTerminate (releaseImpl). For more information see What Are System Objects? (MATLAB).
C MEX S-Function, S-Function BuilderAllows you to model both continuous and discrete state behavior in combination with block callback methods. For more information, see Callback Methods for C MEX S-Functions
Simulink FunctionCommunicates directly with the engine. You can model the state behavior using appropriate blocks from the continuous and discrete Simulink block libraries. When multiple calls to this function originate from different callers, the state values are also persistent between these calls. For more information, see Call a Simulink Function Block from Multiple Sites.
SubsystemCommunicates directly with the engine. You can model the state behavior using appropriate blocks from the continuous and discrete Simulink block libraries.

Simulation Performance

For most applications, all custom block types provide satisfactory simulation performance. Use the Simulink profiler to get the actual performance indication. See How Profiler Captures Performance Data for more information.

The two categories of performance indication are the interface cost and the algorithm cost. The interface cost is the time it takes to move data from the Simulink engine into the block. The algorithm cost is the time it takes to perform the algorithm that the block implements.

Custom Block TypeNotes
FcnHas the highest simulation performance. The block is tightly integrated with the Simulink engine and optimized for simulation and code generation.
Interpreted MATLAB FunctionHas a slower performance due to the interface, but has the same algorithm cost as a MATLAB function.
When block data (such as inputs and outputs) is accessed or returned from an Interpreted MATLAB Function block, the Simulink engine packages this data into MATLAB arrays. This packaging takes additional time and causes a temporary increase in memory during communication. If you pass large amounts of data across this interface, such as frames or arrays, the performance can be substantially slow.
Once the data has been converted, the MATLAB execution engine executes the algorithm. As a result, the algorithm cost is the same as for MATLAB function.
Level-2 MATLAB S-FunctionIncurs the same algorithm costs as the Interpreted MATLAB Function block, but with a slightly higher interface cost. Since MATLAB S-Functions can handle multiple inputs and outputs, the packaging is more complicated than for the Interpreted MATLAB Function block. In addition, the Simulink engine calls the MATLAB execution engine for each block method you implement, whereas the Interpreted MATLAB Function block calls the MATLAB execution engine only for the Outputs method.
MATLAB FunctionPerforms simulation through code generation and incurs the same interface cost as other Simulink built-in blocks.
The algorithm cost of this block is harder to analyze because of the block's implementation. On average, a function for this block and theMATLAB function run at about the same speed.
If the MATLAB Function block has code that uses coder.extrinsic to call out to the MATLAB execution engine, it incurs all the costs that the MATLAB S-Function or Interpreted MATLAB Function block incur. Calling out to the MATLAB execution engine from a MATLAB Function block produces a warning to prevent you from doing so unintentionally.
To reduce the algorithm cost, you can disable debugging for all MATLAB Function blocks.
MATLAB SystemIn the interpreted execution mode, performance is similar to that of the Level-2 MATLAB S-Function because the model simulates the block using the MATLAB execution engine. In the code generation mode, performance is similar to that of the MATLAB Function because the model simulates the block using the generated code. For more information, see the MATLAB Function entry in this table.
C MEX S-FunctionSimulates via the compiled code and incurs the same interface cost as Simulink built-in blocks. The algorithm cost depends on the complexity of the S-Function.
S-Function BuilderThis block only builds an S-Function from the specifications and C code you supply. You can also use this block as a wrapper for the generated S-Function in models. The algorithm cost of this block compared to C MEX S-Function is incurred only from the wrapper.
Simulink Function, SubsystemIf included in a library, introduces no interface or algorithm costs beyond what would normally be incurred if the block existed as a regular subsystem in the model.
Performance is proportional to the complexity of the algorithm implemented in the subsystem. If the subsystem is contained in a library, some cost is incurred when Simulink loads any unloaded libraries the first time the diagram is updated or readied for simulation. If all referenced library blocks remain unchanged, Simulink does not subsequently reload the library. Compiling the model becomes faster than if the model did not use libraries.

Code Generation

You need code generation if your model is part of a bigger system. Not all custom block types support code generation with Simulink Coder™.

Custom Block TypeNotes
FcnSupports code generation.
Interpreted MATLAB FunctionDoes not support code generation.
Level-2 MATLAB S-FunctionGenerates code only if you implement the algorithm using a Target Language Compiler (TLC) function. In accelerated and external mode simulations, you can choose to execute the S-Function in the interpretive mode by calling back to the MATLAB execution engine without implementing the algorithm in TLC. If the MATLAB S-Function is SimViewingDevice, the Simulink Coder product automatically omits the block during code generation.
MATLAB Function, MATLAB SystemSupports code generation. However, if your block calls out to the MATLAB execution engine, it will build with the Simulink Coder product only if the calls to the MATLAB execution engine do not affect the block outputs. Under this condition, the Simulink Coder product omits these calls from the generated C code. This feature allows you to leave visualization code in place, even when generating embedded code.
C MEX S-Function, S-Function Builder

Both supports code generation.

  • For non-inlined S-Functions, the Simulink Coder product uses the C MEX function during code generation.

  • In the case of C MEX S-Functions, if you need to either inline the S-Function or create a wrapper for handwritten code, you must write a TLC file for the S-Function.

  • In the case of S-Function Builder, you can choose the Generate wrapper TLC option to automatically generate a TLC file.

See S-Functions and Code Generation (Simulink Coder) for more information.

Simulink FunctionSupports code generation.
SubsystemSupports code generation as long as the blocks contained within the subsystem support code generation. For more information, see Code Generation of Subsystems (Embedded Coder)

Multiple Input and Output Ports

These types of custom blocks support multiple input and output ports.

Custom Block TypeNotes
Fcn, Interpreted MATLAB FunctionSupports only a single input and a single output port.
MATLAB FunctionSupports multiple input and output ports, including bus signals. See How Structure Inputs and Outputs Interface with Bus Signals for more information.
MATLAB SystemSupports multiple input and output ports, including bus signals. In addition, you can modify the number of input and output ports based on system object properties using the getNumInputs and getNumOutputs methods.
Level-2 MATLAB S-Function, C MEX S-Function, S-Function BuilderSupports multiple input and output ports. In addition, you can modify the number of input and output ports based on user-defined parameters. The C MEX S-Function and S-Function Builder support bus signals.
Simulink FunctionSupports multiple input and output ports, including bus signals.
SubsystemSupports multiple input and output ports, including bus signals. In addition, you can modify the number of input and output ports based on user-defined parameters. See Self-Modifiable Linked Subsystems for more information.

Speed of Updating the Simulink Diagram

Simulink updates the diagram before every simulation and when requested by the user. Every block introduces some overhead into the diagram update process.

Custom Block TypeNotes
Fcn, Interpreted MATLAB FunctionLow diagram update cost.
MATLAB FunctionSimulation is performed through code generation, so this blocks can take a significant amount of time when first updated. However, because code generation is incremental, Simulink does not repeatedly update the block if the block and the signals connected to it have not changed.
MATLAB SystemFaster than MATLAB Function because code is not generated to update the diagram. Since, code generation is incremental, Simulink does not repeatedly update the block if the block and the signals connected to it have not changed.
C MEX S-Function, Level-2 MATLAB S-FunctionIncurs greater costs than other Simulink blocks only if it overrides methods executed when updating the diagram. If these methods become complex, they can contribute significantly to the time it takes to update the diagram. For a list of methods executed when updating the diagram, see the process view in Simulink Engine Interaction with C S-Functions. When updating the diagram, Simulink invokes all relevant methods in the model initialization phase up to, but not including, mdlStart.
Simulink Function, SubsystemThe speed is proportional to the complexity of the algorithm implemented in the subsystem. If the subsystem is contained in a library, some cost is incurred when Simulink loads any unloaded libraries the first time the diagram is updated or readied for simulation. If all referenced library blocks remain unchanged, Simulink does not subsequently reload the library. Compiling the model becomes faster than if the model does not use libraries.

Callback Methods

Simulink blocks communicate with the Simulink engine through block callback methods, which fully specify the behavior of blocks (except the Simulink Function block). Each custom block type allows you to implement a different set of callback methods. To learn how blocks interact with Simulink engine, see Simulink Engine Interaction with C S-Functions. This table uses S-Function Callback Methods names as equivalents.

Custom Block TypeNotes
Fcn, Interpreted MATLAB Function, MATLAB FunctionAll create a mdlOutputs method to calculate the value of outputs given the value of inputs. You cannot implement any other callback methods using one of these blocks and, therefore, cannot model state behavior.
Level-2 MATLAB S-FunctionAllows implementation of a larger subset of callback methods, including methods you can use to model continuous and discrete states. For a list of supported methods, see Level-2 MATLAB S-Function Callback Methods in Write Level-2 MATLAB S-Functions.
MATLAB SystemUses System object methods for callback methods: mdlOutputs (stepImpl, outputImpl), mdlUpdate (updateImpl), mdlInitializeConditions (resetImpl), mdlStart (setupImpl), mdlTerminate (releaseImpl). For more information, see Simulink Engine Interaction with System Object Methods
C MEX S-FunctionAllows implementation of a complete set of callback methods.
S-Function BuilderAllows implementation of mdlOutputs, mdlDerivatives and mdlUpdate.
Simulink FunctionPackaged as a standalone function. Any caller to this function becomes part of one of the callback methods based on the caller’s location.
SubsystemCommunicates directly with the engine. You can model state behaviors using appropriate blocks from the continuous and discrete Simulink block libraries.

See Also

| | | | | | | |

Related Topics

Was this topic helpful?