Defining Custom Block Replacements

On this page…
Basic Workflow for Defining Custom Block Replacements Specifying Replacement Blocks Writing Block Replacement Rules Example: Replacing Multiport Switch Blocks

Basic Workflow for Defining Custom Block Replacements

To replace certain blocks in your model in a way that the factory-default block replacement rules do not handle, create custom block replacement rules by completing the following tasks:

• Specifying Replacement Blocks

• Writing Block Replacement Rules

Back to Top

Specifying Replacement Blocks

A replacement block can be one of the built-in blocks in the Simulink model library or a block in a user-created library.

In the Simulink Design Verifier software, replacement blocks have the following restrictions:

• They must be built-in blocks or subsystems.

• They cannot be Model blocks, nor can they include any Model blocks.

  Note   A Model block cannot be a replacement block, but you can replace Model blocks with built-in blocks or subsystems.

• They must reside in a block library that is available on your MATLAB search path.

• If the replacement block is a subsystem, any Inport and Outport blocks must have the default names (In1 and Out1).

After constructing your replacement block, write a custom block replacement rule.

Back to Top

Writing Block Replacement Rules

Block replacement rules have the following restrictions:

• The function that represents a block replacement rule must include particular callbacks. Use the block replacement rule template as a starting point for writing a custom rule. (See Template for Block Replacement Rules.)

• The function that represents a block replacement rule must be on the MATLAB search path.

Back to Top

Example: Replacing Multiport Switch Blocks

• Why Replace Multiport Switch Blocks?

• Creating the Library and Replacement Block

• Writing the Rule for the Replacement Block

Why Replace Multiport Switch Blocks?

A Multiport Switch block has one control input port and one or more data input ports; the default number of data inputs is 3.

A model may have test objectives on some blocks whose output is directly or indirectly connected to the Multiport Switch block. For example, a Saturation block may send data to the control input port. In this case, the analysis may create test cases that satisfy those objectives. However, those test cases may create values that are out of range for the control input port, regardless of whether the Multiport Switch block uses zero-based indexing or one-based indexing. This causes the simulation to fail.

In this example, you create a rule to replace all Multiport Switch blocks that have two data inputs and do not use zero-based indexing. The replacement block is a subsystem that has a Test Condition block that constrains the value of the control input to 1 or 2, so that the analysis does not create out-of-range data input values. This allows the analysis to satisfy the objectives on blocks that are connected to the control input port of the Multiport Switch block.

Creating the Library and Replacement Block

Create a user library and specify the replacement block as a masked subsystem:

1. In the Simulink Library Browser, select File > New > Library.

2. In your library, create a subsystem named myReplacementBlock to represent your replacement block. It should look like the following graphic, with several parameters set:

   • In the Multiport Switch block, set the Number of data ports parameter to 2.

   • In the Test Condition block, set the Values parameter to {[1, 2]}.

   

3. To create a mask for your subsystem, select the subsystem, right-click, and select Edit mask from the context menu.

   Specify the following information in the Mask Editor:

   • In the Parameters pane, click the Add button to define a mask parameter named InputSameDT as shown.

     This parameter replicates the behavior of the Require all data port inputs to have the same data type parameter of the underlying Multiport Switch block.

     

     Note   When you create mask parameters that control the behavior of parameters associated with their underlying blocks, specify actual parameter names as dialog box variables in the Mask Editor. For instance, InputSameDT is the actual parameter name that controls the Require all data port inputs to have the same data type parameter of the Multiport Switch block; therefore, it specifies the name of the dialog box variable in this example.

   • In the Initialization pane, in the Initialization commands field, enter commands to specify that the subsystem inherit the InputSameDT parameter value of the top-level model:

     maskInputSameDT = get_param(gcb,'InputSameDT');
     blkName = sprintf('/Multiport\nSwitch');
     targetBlock = [gcb, blkName];
     set_param(targetBlock,'InputSameDT',maskInputSameDT);

4. Save your block library as custom_rule.mdl in a folder on your MATLAB search path.

Writing the Rule for the Replacement Block

To write a rule for the replacement block:

1. Open the block replacement rule template

   matlabroot/toolbox/sldv/sldv/sldvblockreplacetemplate.m

2. Make a copy of the file and save it as custom_rule_switch.m in a folder on your MATLAB search path.

   Note   Execute steps 3 through 11 for the copy of the template that you saved.

3. To declare a function custom_rule_switch and modify its help, modify the first few lines of the template:

   function rule = custom_rule_switch
   %CUSTOM_RULE_SWITCH Custom block replacement rule for
   %the Simulink Design Verifier software
   %
   %   This block replacement rule identifies Multiport
   %   Switch blocks whose "Number of inputs" parameter
   %   specifies '2' and "Use zero-based indexing" parameter
   %   specifies 'off'. It replaces such blocks with an
   %   implementation that includes a Test Condition block
   %   on the control input signal.

   The function name must match its file name, without the .m extension. The comments that follow the function declaration create help for this rule.

4. Specify the type of block that you want to replace in your model by specifying its BlockType parameter as the rule.blockType object. For this example, change the rule.blockType object to 'MultiPortSwitch':

   %% Target Block Type
   %
   rule.BlockType = 'MultiPortSwitch';

   Note   You can use the get_param function to obtain the value of the BlockType parameter for the block that you want to replace.

5. Specify the full block path name for the replacement block as the rule.ReplacementPath object. For this example, to replace Multiport Switch blocks with the replacement block developed in Specifying Replacement Blocks, modify therule.ReplacementPath object using the full block path name:

   %% Replacement Library 
   %
   rule.ReplacementPath = sprintf('custom_rule/myReplacementBlock');

   Note   To get the full block path name, use the gcb function.

6. To specify the type of subsystem that the software uses when replacing blocks, specify a value for the rule.ReplacementMode object. Valid values are:

   • Normal — The software replaces blocks with a copy of the subsystem specified by the rule.ReplacementPath object. This is the default.

   • ConfigurableSubSystem — The software replaces blocks with a Configurable Subsystem block. With the Configurable Subsystem block, you can choose whether it represents the subsystem specified by the rule.ReplacementPath object, or the original block before its replacement.

   For this example, set rule.ReplacementMode to Normal:

   %% Replacement Mode
   %
   rule.ReplacementMode = 'Normal';

7. Specify parameter values that the replacement blocks inherit from the blocks being replaced. You achieve inheritance by mapping the parameter names in a structure. Each field of the structure represents a parameter that the replacement block inherits. Specify the value of each field using the token $original.parameter$. parameter is the name of the parameter that belongs to the original block.

   To define a structure named parameter that maps the InputSameDT parameter from the original Multiport Switch blocks to their replacement blocks, change the content of the Parameter Handling section as follows:

   %% Parameter Handling
   %
   parameter.InputSameDT = '$original.InputSameDT$';
   
   % Register the parameter mapping for the rule
   rule.ParameterMap = parameter;

   Note   To determine block parameter names, refer to Model and Block Parameters in the Simulink Reference.

8. To define the callback functions, keep the following lines in the file:

   %% Replacement Test Callback
   % Customize the subfunction 'replacementTestFunction' to specify the
   % conditions under which Simulink Design Verifier replaces blocks when
   % using this rule. Simulink Design Verifier replaces blocks only when this
   % subfunction returns true. 
   %
   rule.IsReplaceableCallBack = @replacementTestFunction;
   
   %% Post Replacement Callback
   % Customize the subfunction 'postReplacementFunction' to specify actions
   % that will be performed after a block is replaced. 
   %
   % The usage of this callback in replacement rules is optional. Simulink
   % design verifier does not enforce its existence in the rule definition. 
   %
   rule.PostReplacementCallBack = @postReplacementFunction;

9. Customize replacementTestFunction by specifying conditions under which the Simulink Design Verifier software replaces blocks in your model.

   To instruct the software to replace only the Multiport Switch blocks whose NumInputPorts parameter is 2 and whose zeroIdx parameter is off, replace the existing replacementTestFunction with the following:

   function out = replacementTestFunction(blockH)
   % Specify the logic that determines when the Simulink Design
   % Verifier software replaces a block in your model. For example,
   % restrict replacements to only the blocks whose parameters
   % specify particular values.
   %
   out = false;
   numInputPorts = eval(get_param(blockH,'NumInputPorts'));
   zeroIdx = get_param(blockH,'zeroIdx');
   if numInputPorts==2 && strcmp(zeroIdx,'off')
      out = true; 
   end   

   Because replacementTestFunction executes after the model has been compiled, you can access parameters such as CompiledPortDataTypes or CompiledPortDimensions from replacementTestFunction.

   For an example of a replacementTestFunction that accesses these parameters, open the following file:

   matlabroot/toolbox/sldv/sldv/private/blkrep_rule_switch_normal.m

10. Optionally, you can customize postReplacementFunction to specify the actions the software performs after a block has been replaced.

    For an example of a postReplacementFunction, open the following file:

    matlabroot/toolbox/sldv/sldv/private/blkrep_rule_selectorIndexVecPort_normal.m

11. Save the edited file and continue to the next section, Executing Block Replacements, to execute your replacement rule.

Back to Top

Template for Block Replacement Rules

Executing Block Replacements

© 1984-2012- The MathWorks, Inc.    -   Site Help   -   Patents   -   Trademarks   -   Privacy Policy   -   Preventing Piracy   -   RSS