legacy_code - Use Legacy Code Tool

Syntax

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 any compiler options that you might specify. The following examples show how to specify no options, one option, and multiple options:

legacy_code('compile', s);
legacy_code('compile', s, '-DCOMPILE_VALUE1=1');
legacy_code('compile', s,...
        {'-DCOMPILE_VALUE1=1', '-DCOMPILE_VALUE2=2',...
 '-DCOMPILE_VALUE3=3'});

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. See Integrate External Code Using Legacy Code Tool for more information.

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. See Use rtwmakecfg.m API to Customize Generated Makefiles and Integrate External Code Using Legacy Code Tool in the Simulink Coder documentation for more information.

legacy_code('backward_compatibility') automatically updates syntax for using Legacy Code Tool, as made available from MATLAB Central in releases before R2006b, to the supported syntax described in this reference page and in Integrating Existing C Functions into Simulink Models with the Legacy Code Tool in Developing S-Functions.

Input Arguments

specs

A structure with the following fields:

Name the S-function

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

Define Legacy Code Tool Function Specifications

• InitializeConditionsFcnSpec — A nonempty string 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 string 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 string 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 string 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 strings specifying the file names of header files required for compilation.

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

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

• TargetLibFiles — A cell array of strings 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 strings specifying directories containing header files. You can specify the directories using absolute or relative path names.

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

• LibPaths — A cell array of strings 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 How to Specify the 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 string 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).

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 string 'slblock_generate'. If you omit this argument, the block appears in an empty model editor window.

How To

• Integrating Existing C Functions into Simulink Models with the Legacy Code Tool
• Integrate External Code Using Legacy Code Tool

Related Products & Applications

• Simulink
• Control Design
• Signal Processing & Communications
• Model-Based Design
• Physical Modeling
• Verification & Validation

Get Simulink trial software

Learn more about Simulink through this collection of videos, articles, technical literature and the Getting Started with Simulink Guide.

Get this Simulink Kit