Documentation

legacy_code

Use 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('rtwmakecfg_generate', specs)
legacy_code('backward_compatibility')

Description

The legacy_code function creates a MATLAB® structure for registering the specification for existing C or C++ code and the S-function being generated. In addition, the function can generate, compile and link, and create a masked block for the specified S-function. Other options include generating

  • A TLC file for simulation in Accelerator mode or code generation

  • An rtwmakecfg.m file that you can customize to specify dependent source and header files that reside in a different directory than that of the generated S-function

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 might 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 in Simulink software to use the TLC inlining code of the generated S-function. See the description of the ssSetOptions SimStruct function and 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 Build S-Function With Legacy Code Tool.

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. This option is relevant only if you use Simulink Coder software to generate code from your Simulink model. For more information, see Use rtwmakecfg.m API to Customize Generated Makefiles and Build S-Function With Legacy Code Tool in the Simulink Coder documentation.

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.

Input Arguments

specs

A structure with the following fields:

Name the S-function

SFunctionName (Required) — A character vector specifying a name for the S-function to be generated by the Legacy Code Tool.

Define Legacy Code Tool Function Specifications

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

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

  • StartFcnSpec — A character vector specifying the function that the S-function calls when it begins execution. This function can access S-function parameter arguments only. You must declare this function by using tokens that Simulink software can interpret as explained in Declaring Legacy Code Tool Function Specifications.

  • TerminateFcnSpec — A character vector specifying the function that the S-function calls when it terminates execution. This function can access S-function parameter arguments only. 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 — A cell array of character vectors specifying the file names of header files required for compilation.

  • SourceFiles — A cell array of character vectors specifying source files required for compilation. You can specify the source files using absolute or relative path names.

  • HostLibFiles — A cell array of character vectors specifying library files required for host compilation. You can specify the library files using absolute or relative path names.

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

  • IncPaths — A cell array of character vectors specifying directories containing header files. You can specify the directories using absolute or relative path names.

  • SrcPaths — A cell array of character vectors specifying directories containing source files. You can specify the directories using absolute or relative path names.

  • LibPaths — A cell array of character vectors specifying directories containing host and target library files. 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 — A structure that controls S-function options. The structure's fields include:

  • isMacro — A logical value specifying whether the legacy code is a C macro. By default, the value is false (0).

  • isVolatile — A logical value specifying the setting of the S-function SS_OPTION_NONVOLATILE option. By default, the value is true (1).

  • canBeCalledConditionally — A logical value specifying the setting of the S-function SS_OPTION_CAN_BE_CALLED_CONDITIONALLY option. By default, the value is true (1).

  • useTlcWithAccel — A logical value specifying the setting of the S-function SS_OPTION_USE_TLC_WITH_ACCELERATOR option. By default, the value is true (1).

  • language — A character vector specifying either 'C' or 'C++' as the target language of the S-function that Legacy Code Tool will produce. 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.

  • singleCPPMexFile — A logical value that, if true, specifies that 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.

    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— A logical value specifying whether to include a call to the ssSupportsMultipleExecInstances function. By default, the value is false (0).

  • convert2DMatrixToRowMajor— A logical value specifying the automatic conversion of a matrix between a 2–D column-major format and a row-major format. The 2-D 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).

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

  • supportCoverage— A logical value specifying whether the generated S-function must be compatible with Model Coverage. By default, the value is false (0).

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

  • outputsConditionallyWritten— A logical value specifying whether the legacy code conditionally writes the output ports. 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.

modelname

The name of a Simulink model into which Legacy Code Tool is to insert the masked S-function block generated when you specify legacy_code with the action character vector 'slblock_generate'. If you omit this argument, the block appears in an empty model editor window.

Introduced in R2006b

Was this topic helpful?