Block Replacement for Code Optimization

You can configure the code generator to replace the default C/C++ code generated for a Simulink^® block with custom implementation code, such as a library optimized for your target hardware. Customize how and when the code generator replaces the code for Simulink blocks by developing a code replacement library that includes block replacement entries.

How Block Replacement Works

To replace generated code for a block, you create a code replacement library that contains block replacement entries. Each entry defines the conceptual representation of a block and maps it to the implementation code that you want to use to replace the code generated for that block. When the code generator encounters a block that matches the conceptual representation in a code replacement entry, instead of generating the default code for the block, it generates calls to the implementation code that you specify in the entry. The code generator also generates code needed for packaging, initializing, and updating data associated with the implementation. If a block matches multiple code replacement entries in a table, the code generator uses the entry with the higher priority, which you specify when you create the entry. The highest priority is 0 and the lowest priority is 100.

Code replacement for blocks does not change the simulation behavior of the replaced blocks.

Conceptual Information for Matching Blocks

In a block replacement entry, the conceptual representation describes the blocks for which you want to replace the default generated code with your implementation code. The code generator uses conceptual information to match blocks for code replacement. The conceptual representation of a block includes these parts:

• Block key

• Inputs and outputs

• Block property settings

• Block parameter arguments

For more information about what you can specify for an entry, see RTW.TflBlockEntry.

Block Key

The block key indicates the type of block that the entry matches. For example, DiscreteFir is the key for the Discrete FIR filter block.

To find the key for a block, determine the value of the BlockType property for the block. For example, use get_param at the command line and specify the path to the block:

get_param('myModel/Discrete FIR Filter', 'BlockType')

For the Discrete FIR Filter block, this command returns the block type 'DiscreteFir'.

If this command returns 'S-Function' as the block type, you must use the MaskType value as the key for the block instead of the block type. Determine the mask type by calling:

get_param('myModel/Biquad Filter', 'MaskType')

Specify the block key as the Key property of the RTW.TflBlockEntry object.

Block keys for supported blocks are listed in Blocks You Can Replace.

Inputs and Outputs

Specify the data types of the block inputs and outputs by adding conceptual arguments to the block replacement entry. Create an argument handle and add the argument to the entry for each input and output of the block that you want to replace. For an example, see Define the Conceptual Representation.

Block Property Settings

Use block property setting criteria to control the code replacement process so that the code generator matches only blocks that support your implementation code. You can specify settings for the entry to match including block dialog properties and block algorithm properties. For example, when your implementation code uses a specific rounding mode, configure the entry to match only blocks that use the same rounding mode. Specify these settings by creating RTW.BlockProperty objects and adding them to the entry. For an example, see Define the Conceptual Representation.

Some blocks have required properties that you must specify in the block replacement entry. For a list of the required properties, see Blocks You Can Replace.

Block Parameter Arguments

When your implementation code uses block parameter values as arguments, or uses derived parameters that depend on block parameter values, you must specify those block parameters as block parameter arguments in the conceptual representation for the entry. A block parameter argument specifies the data type that the block parameter value must match for code replacement to occur. This specification prevents the code generator from replacing code from a block that uses a data type that is not compatible with the implementation code. Adding the block parameter argument specification also enables you to specify the parameter as an argument for an implementation function. For example, if your implementation code for a Discrete FIR filter block uses the value of the Coefficients parameter, you must add that parameter as a block parameter argument. For more information on using block parameter arguments, see Use Derived Data in Replacement Code Implementations.

Implementation Information for Replacing Block Code

In a block replacement entry, the implementation information describes the custom code that you want the generated code to call instead of the default code for the block. You can specify this information about your custom implementation code:

• Implementation functions that are called by the system functions generated from the block

• Derived parameters that store values calculated from block inputs, outputs, and other block parameters

• Arguments used by the replacement functions, including:

  • Derived parameter arguments.

  • DWork arguments that are accessible to implementation functions.

  • Arguments to use in-place as buffers for both inputs and outputs.

Implementation Functions

When you replace the code generated from a block, you can specify which implementation function is called by each system function. You can specify implementation functions for these system functions:

• initialize － the <model>_initialize function

• output － the system function containing the output code, which is either the <model>_step function or the <model>_output function, depending on the setting of Single output/update function

• update － the system function containing the update code, which is either the <model>_step function or the <model>_update function, depending on the setting of Single output/update function

• terminate － the <model>_terminate function

For each implementation function, you specify properties of the function and arguments for the function signature by using a RTW.CImplementation object. Add the implementation object to the entry by using the addImplementation method.

outImplementation = RTW.CImplementation;
outImplementation.Name = 'MyDiscreteFIR_out';
argIn = getTflArgFromString(hTable,'u1','single*');
addArgument(outImplementation,argIn);
addImplementation(hEntry,'output', outImplementation);

For more information, see Define the Implementation Representation.

Derived Parameters for Implementation Functions

Some custom implementations that you can use for code replacement require data that is derived from the block inputs, outputs, and block parameters. For example, an implementation function could require the dimensions of the input data. Input dimensions are not stored as a block parameter but can be computed from the input data. For block replacement, define this computed data as a derived parameter. For an example that shows how to use derived parameters, see Use Derived Data in Replacement Code Implementations.

DWork Arguments for Implementation Functions

If your implementation function requires states, global data, or other data that is typically generated in a DWork vector, you must create custom DWork vector arguments. Implementation functions can access the DWork vectors that you specify for a block entry. For an example, see Define the Implementation Representation.

Arguments for In-Place Use

If your implementation function uses a buffer for both input and output data storage, configure the buffer by specifying the buffer as an in-place argument. For either the input or output argument, set the property ArgumentForInPlaceUse to the name of the other argument that shares the buffer. Use in-place arguments for only input and output arguments. Do not use in-place arguments for derived parameters or DWork vector arguments.

Blocks You Can Replace

This table indicates the blocks you can replace, the key for each block, block parameter settings that you can specify, and valid block parameter arguments for each block. The table also indicates which block parameter settings and block parameter arguments you are required to set in a block replacement entry for each block. For fixed-point implementations for supported blocks, you must also specify the required data type parameters.

Block	Key	Block Parameters	Block Parameter Arguments	Data Type Block Parameters for Fixed-Point Implementations
Discrete FIR Filter	DiscreteFir	Coefficient source (CoefSource) － Required Filter structure (FilterStructure) － Required Coefficients (Coefficients) Input processing (InputProcessing) － Required Initial states (InitialStates) Show enable port (ShowEnablePort) External reset (ExternalReset) Sample time (SampleTime)	Coefficients (Coefficients) Initial states (InitialStates)	Tap sum (TapSumDataTypeStr) － Required Coefficients (CoefDataTypeStr) － Required Coefficients minimum (CoeffMin) － Not supported. Do not specify this parameter. Coefficients maximum (CoeffMax) － Not supported. Do not specify this parameter. Product output (ProductDataTypeStr)－ Required Accumulator (AccumDataTypeStr)－ Required State (StateDataTypeStr) － Required Output (OutDataTypeStr) － Required Output minimum (OutMin) － Not supported. Do not specify this parameter. Output maximum (OutMax) － Not supported. Do not specify this parameter. Lock data type settings against changes by the fixed-point tools (LockScale) － Required Integer rounding mode (RndMeth) － Required Saturate on integer overflow (SaturateOnIntegerOverflow) － Required
Biquad Filter (DSP System Toolbox)	Biquad Filter	Coefficient source (FilterSource) － Required Filter structure (IIRFiltStruct) － Required SOS Matrix (Mx6) (BiQuadCoeffs) Scale values (ScaleValues) Input processing (InputProcessing) － Required Initial conditions (IC) Initial conditions on zeros side (ICnum) Initial conditions on poles side (ICden) Scale values mode (ScaleValueMode) Action when the a0 values of the SOS matrix are not one (a0Flag) Optimize unity scale values (OptimizeUnityScaleValues)	SOS Matrix (Mx6) (BiQuadCoeffs) Initial conditions (IC) Initial conditions on zeros side (ICnum) Initial conditions on poles side (ICden) Scale values (ScaleValue)	Rounding mode (RoundingMode) － Required Saturate on integer overflow (OverflowMode) － Required Coefficients (firstCoeffMode) － Required Product output (prodOutputMode) － Required Accumulator (accumMode) － Required States (memoryMode) － Required Output (outputMode) － Required Section input (stageInputMode) － Required Section output (stageOutputMode) － Required Multiplicand (multiplicandMode) － Required Lock data type settings against changes by the fixed-point tools (LockScale) － Required
FFT (DSP System Toolbox)	FFT	FFT implementation (FFTImplementation) － Required Output in bit-reversed order (BitRevOrder) － Required Divide output by FFT length (Normalize) － Required Inherit FFT length from input dimensions (InheritFFTLength) － Required FFT length (FFTLength) － Required if InheritFFTLength is off Wrap input data when FFT length is shorter than input length (WrapInput) － Required if InheritFFTLength is off	None	Fixed-point implementations are not supported.
IFFT (DSP System Toolbox)	IFFT	FFT implementation (FFTImplementation) － Required Input is in bit-reversed order (BitRevOrder) － Required Input is conjugate symmetric (cs_in) － Required Divide output by FFT length (Normalize) － Required Inherit FFT length from input dimensions (InheritFFTLength) － Required FFT length (FFTLength) － Required if InheritFFTLength is off Wrap input data when FFT length is shorter than input length (WrapInput) － Required if InheritFFTLength is off	None	Fixed-point implementations are not supported.
FIR Decimation (DSP System Toolbox)	FIR Decimation	Coefficient source (FilterSource) － Required Decimation factor (D) － Required FIR filter coefficients (h) － Required if FilterSource is dialog parameters Filter structure (FiltStruct) － Required Input processing (InputProcessing) － Required Rate options (framing) － Required Filter object (FilterObject) － Required if FilterSource is filter object Output buffer initial conditions (OutputBufInitCond) － Required if framing is allow multirate processing Allow arbitrary frame length for fixed-size input signals (AllowArbitraryInputLength) － Required if framing is enforce single-rate processing	Decimation factor (D) Filter object (FilterObject)	Fixed-point implementations are not supported.
FIR Interpolation (DSP System Toolbox)	FIR Interpolation	Coefficient source (FilterSource) － Required Interpolation factor (L) － Required FIR filter coefficients (h) － Required if FilterSource is dialog parameters Input processing (InputProcessing) － Required Rate options (framing) － Required Filter object (FilterObject) － Required if FilterSource is filter object Output buffer initial conditions (OutputBufInitCond) － Required if framing is allow multirate processing	Interpolation factor (L) Filter object (FilterObject)	Fixed-point implementations are not supported.

Limitations

• Multirate blocks, and blocks inside subsystems that require multiple rates, do not support block replacement. This includes FIR Interpolation and FIR Decimation blocks that have Rate options set to Allow multirate processing or Input processing set to Elements as channels (sample based).

• For fixed-point data types, which you create by calling fixdt, you must specify the scaling.