legacy_code

Integrate existing C/C++ code using Legacy Code Tool

Syntax

legacy_code("help")

specs = legacy_code("initialize")

legacy_code("sfcn_cmex_generate",specs)

legacy_code("compile",specs,compilerOptions)

legacy_code("generate_for_sim",specs,modelname)

legacy_code("slblock_generate",specs,modelname)

legacy_code("sfcn_tlc_generate",specs)

legacy_code("sfcn_makecfg_generate",specs)

legacy_code("rtwmakecfg_generate",specs)

legacy_code("backward_compatibility")

Description

legacy_code("help") displays instructions for using Legacy Code Tool.

specs = legacy_code("initialize") initializes the Legacy Code Tool data structure, specs, which registers characteristics of existing C or C++ code and properties of the S-function that the Legacy Code Tool generates.

legacy_code("sfcn_cmex_generate",specs) generates an S-function source file as specified by the Legacy Code Tool data structure, specs.

legacy_code("compile",specs,compilerOptions) compiles and links the S-function generated by the Legacy Code Tool based on the data structure, specs and compiler options that you specify. The compiler options must be supported by the mex function.

legacy_code("generate_for_sim",specs,modelname) generates, compiles, and links the S-function in a single step. If the Options.useTlcWithAccel field of the Legacy Code Tool data structure is set to logical 1 (true), the function also generates a TLC file for accelerated simulations.

legacy_code("slblock_generate",specs,modelname) generates a masked S-Function block for the S-function generated by the Legacy Code Tool based on the data structure, specs. The block appears in the Simulink^® model specified by modelname. If you omit modelname, the block appears in an empty model editor window.

legacy_code("sfcn_tlc_generate",specs) generates a TLC file for the S-function generated by the Legacy Code Tool based on the data structure, specs. This option is relevant if you want to:

• Force accelerator mode simulation to use the TLC inlining code of the generated S-function. See the description of the ssSetOptions SimStruct function and the SS_OPTION_USE_TLC_WITH_ACCELERATOR S-function option for more information.

• Use Simulink Coder™ software to generate code from your Simulink model. For more information, see Import Calls to External Code into Generated Code with Legacy Code Tool (Simulink Coder).

legacy_code("sfcn_makecfg_generate",specs) generates an sFunction_makecfg.m file for the S-function generated by the Legacy Code Tool based on the data structure, specs. If you use Simulink Coder to generate code from your Simulink model, you can use this option to specify additional items for the S-function build process such as source folders, preprocessor macros, and link objects. For example, you can specify source files that the S-function depends on that are in folders other than the folder containing the generated S-function executable. For more information, see Use makecfg to Customize Generated Makefiles for S-Functions (Simulink Coder) and Import Calls to External Code into Generated Code with Legacy Code Tool (Simulink Coder).

legacy_code("rtwmakecfg_generate",specs) generates an rtwmakecfg.m file for the S-function generated by the Legacy Code Tool based on the data structure, specs. If you use Simulink Coder to generate code from your Simulink model, you can use this option to specify additional items for the S-function build process such as source folders, preprocessor macros, and link objects. For example, you can specify source files that the S-function depends on that are in folders other than the folder containing the generated S-function executable. For more information, see Use rtwmakecfg.m API to Customize Generated Makefiles (Simulink Coder) and Import Calls to External Code into Generated Code with Legacy Code Tool (Simulink Coder).

legacy_code("backward_compatibility") automatically updates syntax for using Legacy Code Tool to the supported syntax described in this reference page and in Integrate C Functions Using Legacy Code Tool.

Examples

Inputs Passed by Value or Address to Legacy Functions

This example shows you how to use the Legacy Code Tool to integrate legacy C functions that pass their input arguments by value versus address.

The Legacy Code Tool allows you to:

• Provide the legacy function specification,

• Generate a C-MEX S-function that is used during simulation to call the legacy code, and

• Compile and build the generated S-function for simulation.

Providing the Legacy Function Specification

Functions provided with the Legacy Code Tool take a specific data structure or array of structures as the argument. The data structure is initialized by calling the function legacy_code() using initialize as the first input. After initializing the structure, you have to assign its properties to values corresponding to the legacy code being integrated. The prototypes of the legacy functions being called in this example are:

• FLT filterV1(const FLT signal, const FLT prevSignal, const FLT gain)

• FLT filterV2(const FLT* signal, const FLT prevSignal, const FLT gain)

where FLT is a typedef to float. The legacy source code is found in the files your_types.h, myfilter.h, filterV1.c, and filterV2.c.

Note the difference in the OutputFcnSpec defined in the two structures; the first case specifies that the first input argument is passed by value, while the second case specifies pass by pointer.

defs = [];

% sldemo_sfun_filterV1
def = legacy_code('initialize');
def.SFunctionName = 'sldemo_sfun_filterV1';
def.OutputFcnSpec = 'single y1 = filterV1(single u1, single u2, single p1)';
def.HeaderFiles   = {'myfilter.h'};
def.SourceFiles   = {'filterV1.c'};
def.IncPaths      = {'sldemo_lct_src'};
def.SrcPaths      = {'sldemo_lct_src'};
defs = [defs; def];

% sldemo_sfun_filterV2
def = legacy_code('initialize');
def.SFunctionName = 'sldemo_sfun_filterV2';
def.OutputFcnSpec = 'single y1 = filterV2(single u1[1], single u2, single p1)';
def.HeaderFiles   = {'myfilter.h'};
def.SourceFiles   = {'filterV2.c'};
def.IncPaths      = {'sldemo_lct_src'};
def.SrcPaths      = {'sldemo_lct_src'};
defs = [defs; def];

Generating and Compiling an S-Function for Use During Simulation

The function legacy_code() is called again with the first input set to generate_for_sim in order to automatically generate and compile the C-MEX S-function according to the description provided by the input argument defs. This S-function is used to call the legacy functions in simulation. The source code for the S-function is found in the files sldemo_sfun_filterV1.c and sldemo_sfun_filterV2.c.

legacy_code('generate_for_sim', defs);

### Start Compiling sldemo_sfun_filterV1
    mex('-I/tmp/Bdoc24b_2855429_856617/tpa47e5a6e/simulink_features-ex08075368/sldemo_lct_src', '-I/tmp/Bdoc24b_2855429_856617/tpa47e5a6e/simulink_features-ex08075368', '-c', '-outdir', '/tmp/Bdoc24b_2855429_856617/tpa89fb5a6_605a_4689_a0a7_1f4fe2d8a8a0', '/tmp/Bdoc24b_2855429_856617/tpa47e5a6e/simulink_features-ex08075368/sldemo_lct_src/filterV1.c')
Building with 'gcc'.
MEX completed successfully.
    mex('sldemo_sfun_filterV1.c', '-I/tmp/Bdoc24b_2855429_856617/tpa47e5a6e/simulink_features-ex08075368/sldemo_lct_src', '-I/tmp/Bdoc24b_2855429_856617/tpa47e5a6e/simulink_features-ex08075368', '/tmp/Bdoc24b_2855429_856617/tpa89fb5a6_605a_4689_a0a7_1f4fe2d8a8a0/filterV1.o')
Building with 'gcc'.
MEX completed successfully.
### Finish Compiling sldemo_sfun_filterV1
### Exit

### Start Compiling sldemo_sfun_filterV2
    mex('-I/tmp/Bdoc24b_2855429_856617/tpa47e5a6e/simulink_features-ex08075368/sldemo_lct_src', '-I/tmp/Bdoc24b_2855429_856617/tpa47e5a6e/simulink_features-ex08075368', '-c', '-outdir', '/tmp/Bdoc24b_2855429_856617/tp0294ed39_221e_41cc_a018_0742cd7f9861', '/tmp/Bdoc24b_2855429_856617/tpa47e5a6e/simulink_features-ex08075368/sldemo_lct_src/filterV2.c')
Building with 'gcc'.
MEX completed successfully.
    mex('sldemo_sfun_filterV2.c', '-I/tmp/Bdoc24b_2855429_856617/tpa47e5a6e/simulink_features-ex08075368/sldemo_lct_src', '-I/tmp/Bdoc24b_2855429_856617/tpa47e5a6e/simulink_features-ex08075368', '/tmp/Bdoc24b_2855429_856617/tp0294ed39_221e_41cc_a018_0742cd7f9861/filterV2.o')
Building with 'gcc'.
MEX completed successfully.
### Finish Compiling sldemo_sfun_filterV2
### Exit

Generating an rtwmakecfg.m File for Code Generation

After the TLC block file is created, the function legacy_code() can be called again with the first input set to rtwmakecfg_generate in order to generate an rtwmakecfg.m file to support code generation through Simulink® Coder™. Generate the rtwmakecfg.m file if the required source and header files for the S-functions are not in the same directory as the S-functions, and you want to add these dependencies in the makefile produced during code generation.

Note: Complete this step only if you are going to simulate the model in accelerated mode.

legacy_code('rtwmakecfg_generate', def);

Generating Masked S-Function Blocks for Calling the Generated S-Functions

After the C-MEX S-function source is compiled, the function legacy_code() can be called again with the first input set to slblock_generate in order to generate masked S-function blocks which are configured to call those S-functions. The blocks are placed in a new model and can be copied to an existing model.

legacy_code('slblock_generate', defs);

Integrate the Legacy Code

The model sldemo_lct_filter shows integration with the legacy code. The subsystem TestFilter serves as a harness for the calls to the legacy C functions via the generate S-functions, with unit delays serving to store the previous output values.

open_system('sldemo_lct_filter')
open_system('sldemo_lct_filter/TestFilter')
sim('sldemo_lct_filter');

Input Arguments

specs — Specification for existing C or C++ code and S-function

structure

Specification for existing C or C++ code and the S-function being generated, specified as a struct with these fields:

Name the S-function

SFunctionName (required) — Name for the S-function to be generated by the Legacy Code Tool, specified as a character vector or string.

Define Legacy Code Tool Function Specifications

• InitializeConditionsFcnSpec — Function that the S-function calls to initialize and reset states, specified as a nonempty character vector or string. You must declare this function by using tokens that Simulink software can interpret as explained in Declaring Legacy Code Tool Function Specifications.

• OutputFcnSpec — Function that the S-function calls at each time step, specified as a nonempty character vector or string. You must declare this function by using tokens that Simulink software can interpret as explained in Declaring Legacy Code Tool Function Specifications.

• StartFcnSpec — Function that the S-function calls when it begins execution, specified as a character vector or string. This function can access S-function parameter arguments and work data. You must declare this function by using tokens that Simulink software can interpret as explained in Declaring Legacy Code Tool Function Specifications.

• TerminateFcnSpec — Function that the S-function calls when it terminates execution, specified as a character vector or string. This function can access S-function parameter arguments and work data. You must declare this function by using tokens that Simulink software can interpret as explained in Declaring Legacy Code Tool Function Specifications.

Define Compilation Resources

• HeaderFiles — File names of header files required for compilation, specified as a cell array of character vectors or string array.

• SourceFiles — Source files required for compilation, specified as a cell array of character vectors or string array. You can specify the source files using absolute or relative path names.

• HostLibFiles — Library files required for host compilation, specified as a cell array of character vectors or string array. You can specify the library files using absolute or relative path names.

• TargetLibFiles — Library files required for target (that is, standalone) compilation, specified as a cell array of character vectors or string array. You can specify the library files using absolute or relative path names.

• IncPaths — Directories containing header files, specified as a cell array of character vectors or string array. You can specify the directories using absolute or relative path names.

• SrcPaths — Directories containing source files, specified as a cell array of character vectors or string array. You can specify the directories using absolute or relative path names.

• LibPaths — Directories containing host and target library files, specified as a cell array of character vectors or string array. You can specify the directories using absolute or relative path names.

Specify a Sample Time

SampleTime — One of the following:

• 'inherited' (default) — Sample time is inherited from the source block.

• 'parameterized' — Sample time is represented as a tunable parameter. Generated code can access the parameter by calling MEX API functions, such as mxGetPr or mxGetData.

• Fixed — Sample time that you explicitly specify. For information on how to specify sample time, see Specify Sample Time.

If you specify this field, you must specify it last.

Define S-Function Options

Options — S-function options, specified as a structure. The structure's fields include:

• canBeCalledConditionally — Setting of the S-function SS_OPTION_CAN_BE_CALLED_CONDITIONALLY option, specified as a logical. By default, the value is true (1).

• convertNDArrayToRowMajor— Automatic conversion of a matrix between a column-major format and a row-major format, specified as a logical. The column-major format is used by MATLAB^®, Simulink, and the generated code. The row-major format is used by C. By default, the value is false (0). If you currently specify the previous version of the option, convert2DMatrixToRowMajor, the function automatically specifies the new convertNDArrayToRowMajor option.

  Note

  This option does not support a 2–D matrix of complex data.

• isMacro — Whether the legacy code is a C macro, specified as a logical. By default, the value is false (0).

• isVolatile — Setting of the S-function SS_OPTION_NONVOLATILE option, specified as a logical. By default, the value is true (1).

• language — Target language of the S-function that Legacy Code Tool will produce, specified as either 'C' or 'C++'. By default, the value is 'C'.

  Note

  The Legacy Code Tool can interface with C++ functions, but not C++ objects. For a work around, see Legacy Code Tool Limitations in the Simulink documentation.

• outputsConditionallyWritten— Whether the legacy code conditionally writes the output ports, specified as a logical. If true, the generated S-function specifies that the memory associated with each output port cannot be overwritten and is global (SS_NOT_REUSABLE_AND_GLOBAL). If false, the memory associated with each output port is reusable and is local (SS_REUSABLE_AND_LOCAL). By default, the value is false (0). For more information, see ssSetOutputPortOptimOpts.

• singleCPPMexFile — Whether generated code:

  • Requires you to generate and manage an inlined S-function as only one file (.cpp) instead of two (.c and .tlc).

  • Maintains model code style (level of parentheses usage and preservation of operand order in expressions and condition expressions in if statements) as specified by model configuration parameters.

  Specified as a logical. By default, the value is false.

  Limitations

  You cannot set the singleCPPMexFile field to true if

  • Options.language='C++'

  • You use one of the following Simulink objects with the IsAlias property set to true:

    • Simulink.Bus

    • Simulink.AliasType

    • Simulink.NumericType

  • The Legacy Code Tool function specification includes a void* or void** to represent scalar work data for a state argument

  • HeaderFiles field of the Legacy Code Tool structure specifies multiple header files

• supportsMultipleExecInstances— Option to include a call to the ssSupportsMultipleExecInstances function, specified as a logical. By default, the value is false (0).

• supportCodeReuseAcrossModels— Whether the generated S-function can be reused across the model reference hierarchy, specified as a logical. If true, the generated S-function includes the ssSetSupportedForCodeReuseAcrossModels function call. The code generator produces the code for the S-functions in the slprj\ert\_sharedutils folder.

• supportCoverage— Whether the generated S-function must be compatible with Model Coverage, specified as a logical. By default, the value is false (0).

• supportCoverageAndDesignVerifier— Whether the generated S-function must be compatible with Model Coverage and Simulink Design Verifier™, specified as a logical. By default, the value is false (0).

• useTlcWithAccel — Setting of the S-function SS_OPTION_USE_TLC_WITH_ACCELERATOR option, specified as a logical. By default, the value is true (1).

Data Types: struct

modelname — Model name

string | character vector

The name of a Simulink model, specified as a string or character vector. When you specify legacy_code with the action 'slblock_generate', Legacy Code Tool inserts the generated masked S-function block into the specified model. If you omit this argument, the block appears in an empty model editor window.

Data Types: char | string

compilerOptions — Compiler options

string | character vector

Compiler options to include when you specify legacy_code with the action 'compile', specified as a string or a character vector. The compiler options must be supported by the mex function.

Data Types: char | string

Version History

Introduced in R2006b