Learn more about Real-Time Workshop

Automating the Generation of Files for Fully Inlined S-Functions Using Legacy Code Tool

On this page…
Legacy Code Tool and Code Generation Generating Inlined S-Function Files for Code Generation Support Applying Model Code Style Settings to Legacy Functions Addressing Dependencies on Files in Different Locations Deploying Generated S-Functions for Simulation and Code Generation

Legacy Code Tool and Code Generation

The Simulink Legacy Code Tool provides a way to automatically generate fully inlined C MEX S-functions for legacy or custom code that is optimized for embedded components such as device drivers and lookup tables, that call existing C or C++ functions.

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.

In addition, you can use the tool to

• Compile and build the generated S-function for simulation

• Generate a masked S-Function block that is configured to call the existing external code

If you want to include such S-functions in models for which you intend to generate code, you must use the tool to generate a TLC block file for the generated S-function. The TLC block file specifies how the generated code for a model calls the existing C or C++ function.

If the S-function depends on files in directories other than the directory containing the S-function dynamically loadable executable file and you want to maintain those dependencies for building a model that includes the S-function, you need the tool to also generate an rtwmakecfg.m file for the S-function. For example, for some applications, such as custom targets, it might be preferable to locate files in a target-specific location. The Real-Time Workshop build process looks for the generated rtwmakecfg.m file in the same directory as the S-function's dynamically loadable executable and calls the rtwmakecfg function if the file is found.

For background information and to get started using the Legacy Code Tool, see Integrating Existing C Functions into Simulink Models with the Legacy Code Tool in the Simulink Writing S-Functions documentation.

Back to Top

Generating Inlined S-Function Files for Code Generation Support

Depending on your application's code generation needs, you can choose to do either of the following to generate code for a model that uses the S-function:

• Generate one .cpp file for the inlined S-function by setting the value of the Options.singleCPPMexFile field of the Legacy Code Tool data structure to true (1) before generating the S-function source file from your existing C function. For example,

  def.Options.singleCPPMexFile = 1;
  legacy_code('sfcn_cmex_generate', def);

• Generate a source file and TLC block file for the inlined S-function. For example,

  def.Options.singleCPPMexFile
  
  ans =
  
  0
  legacy_code('sfcn_cmex_generate', def);
  legacy_code('sfcn_tlc_generate', def);

singleCPPMexFile Limitations

You cannot set the singleCPPMexFile field to true (1) if

• Options.language='C++'

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

  • 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

Back to Top

Applying Model Code Style Settings to Legacy Functions

To apply the code style specified by a model's configuration parameters to a legacy function,

1. Initialize the Legacy Code Tool data structure. For example,

   def = legacy_code('initialize');
   

2. Set the value of the Options.singleCPPMexFile field of the data structure to true (1). For example,

   def.Options.singleCPPMexFile = 1;

To verify the setting, enter

def.Options.singleCPPMexFile

singleCPPMexFile Limitations

You cannot set the singleCPPMexFile field to true (1) if

• Options.language='C++'

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

  • 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

Back to Top

Addressing Dependencies on Files in Different Locations

By default, the Legacy Code Tool assumes that all files on which an S-function depends reside in the same directory as the S-function's dynamically loadable executable file. If your S-function depends on files that reside elsewhere and you are using the Real-Time Workshop template makefile build process, you must generate an rtwmakecfg.m file for the S-function. For example, it is likely that you need to generate this file if your Legacy Code Tool data structure defines compilation resources as path names.

To generate the rtwmakecfg.m file, call the legacy_code function with 'rtwmakecfg_generate' as the first argument and the name of the Legacy Code Tool data structure as the second argument.

legacy_code('rtwmakecfg_generate', lct_spec);

If you use multiple registration files in the same directory and generate an S-function for each file with a single call to legacy_code, as explained in Handling Multiple Registration Files in the Simulink Writing S-Functions documentation, the call to legacy_code that specifies 'rtwmakecfg_generate' must be common to all registration files.

For example, if defs is defined as an array of Legacy Code Tool structures, you call legacy_code with 'rtwmakecfg_generate' once.

defs = [defs1(:);defs2(:);defs3(:)];
legacy_code('rtwmakecfg_generate', defs);

For more information, see Build Support for S-Functions.

Back to Top

Deploying Generated S-Functions for Simulation and Code Generation

You can deploy the S-functions that you generate with the Legacy Code Tool for use by others. To deploy an S-function for simulation and code generation, you need to share the following files:

• Registration file

• Compiled dynamically loadable executable

• TLC block file

• rtwmakecfg.m file

• All header, source, and include files on which the generated S-function depends

Users of the deployed files might need to:

• Add the directory that contains the S-function files to the MATLAB path before using them in a Simulink model.

• Regenerate the rtwmakecfg.m file if the Legacy Code Tool data structure registers any required files as absolute paths and the location of the files changes.

Back to Top

Writing Fully Inlined S-Functions

Writing Fully Inlined S-Functions with the mdlRTW Routine

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