Learn more about Real-Time Workshop

Build Support for S-Functions

On this page…
Introduction Implicit Build Support Specifying Additional Source Files for an S-Function Using TLC Library Functions Using the rtwmakecfg.m API to Customize Generated Makefiles

Introduction

User-written S-Function blocks provide a powerful way to incorporate legacy and custom code into the Simulink and Real-Time Workshop development environment. In most cases, you should use S-functions to integrate existing code with Real-Time Workshop generated code. Several approaches to writing S-functions are available as discussed in

• Writing Noninlined S-Functions

• Writing Wrapper S-Functions

• Writing Fully Inlined S-Functions

• Writing Fully Inlined S-Functions with the mdlRTW Routine

• Writing S-Functions That Support Code Reuse

• Writing S-Functions for Multirate Multitasking Environments

S-functions also provide the most flexible and capable way of including build information for legacy and custom code files in the Real-Time Workshop build process.

This section discusses the different ways of adding S-functions to the Real-Time Workshop build process.

Back to Top

Implicit Build Support

When building models with S-functions, the Real-Time Workshop code generator automatically adds the appropriate rules, include paths, and source filenames to the generated makefile. For this to occur, the source files (.h, .c, and .cpp) for the S-function must be in the same directory as the S-function MEX-file. The code generator propagates this information through the token expansion mechanism of converting a template makefile (TMF) to a makefile. The propagation requires the TMF to support the appropriate tokens.

Details of the implicit build support follow:

• If the file sfcnname.h exists in the same directory as the S-function MEX-file (for example, sfcnname.mexext), the directory is added to the include path.

• If the file sfcnname.c or sfcnname.cpp exists in the same directory as the S-function MEX-file, the Real-Time Workshop code generator adds a makefile rule for compiling files from that directory.

• When an S-function is not inlined with a TLC file, the Real-Time Workshop code generator must compile the S-function's source file. To determine the name of the source file to add to the list of files to compile, the code generator searches for sfcnname.cpp on the MATLAB path. If the source file is found, the code generator adds the source filename to the makefile. If sfcnname.cpp is not found on the path, the code generator adds the filename sfcnname.c to the makefile, whether or not it is on the MATLAB path.

  Note   For the Simulink engine to find the MEX-file for simulation and code generation, it must exist on the MATLAB path or be in your current MATLAB working directory.

Back to Top

Specifying Additional Source Files for an S-Function

If your S-function has additional source file dependencies, you must add the names of the additional modules to the build process. You can do this by specifying the filenames

• In the S-function modules field of the S-Function block parameter dialog box

• With the SFunctionModules parameter in a call to the set_param function

For example, suppose you build your S-function with multiple modules, as in

mex sfun_main.c sfun_module1.c sfun_module2.c

You can then add the modules to the build process by doing one of the following:

• Specifying sfun_main, sfun_module1, and sfun_module2 in the S-function modules field in the S-Function block dialog box

• Entering the following command at the MATLAB command prompt:

  set_param(sfun_block,'SFunctionModules','sfun_module1 sfun_module2')

  Alternatively, you can define a variable to represent the parameter value.

  modules = 'sfun_module1 sfun_module2'
            set_param(sfun_block,'SFunctionModules', modules)
  

Note   The S-function modules field and SFunctionsModules parameter do not support complete source file path specifications. To use the parameter, the Real-Time Workshop software must be able to find the additional source files when executing the makefile. To ensure that the Real-Time Workshop software can locate the additional files, place them in the same directory as the S-function MEX-file. This will enable you to leverage the implicit build support discussed in Implicit Build Support.

For more complicated S-function file dependencies, such as specifying source files in other locations or specifying libraries or object files, use the rtwmakecfg.m API, as explained in Using the rtwmakecfg.m API to Customize Generated Makefiles.

Back to Top

Using TLC Library Functions

If you inline your S-function by writing a TLC file, you can add source filenames to the build process by using the TLC library function LibAddToModelSources. For details, see LibAddSourceFileCustomSection(file, builtInSection, newSection) in the Target Language Compiler documentation.

Note   This function does not support complete source file path specifications and assumes the Real-Time Workshop software can find the additional source files when executing the makefile.

Another useful TLC library function is LibAddToCommonIncludes. Use this function in a #include statement to include S-function header files in the generated model.h header file. For details, see LibAddToCommonIncludes(incFileName) in the Target Language Compiler documentation.

For more complicated S-function file dependencies, such as specifying source files in other locations or specifying libraries or object files, use the rtwmakecfg.m API, as explained in Using the rtwmakecfg.m API to Customize Generated Makefiles.

Back to Top

Using the rtwmakecfg.m API to Customize Generated Makefiles

• Overview

• Creating the rtwmakecfg.m M-File Function

• Modifying the Template Makefile

• Precompiling S-Function Libraries

Overview

Real-Time Workshop TMFs provide tokens that let you add the following items to generated makefiles:

• Source directories

• Include directories

• Run-time library names

• Run-time module objects

S-functions can add this information to the makefile by using an rtwmakecfg.m M-file function. This function is particularly useful when building a model that contains one or more of your S-Function blocks, such as device driver blocks.

To add information pertaining to an S-function to the makefile,

1. Create the M-file function rtwmakecfg in a file rtwmakecfg.m. The Real-Time Workshop software associates this file with your S-function based on its directory location. Creating the rtwmakecfg.m M-File Function discusses the requirements for the rtwmakecfg function and the data it should return.

2. Modify your target's TMF such that it supports macro expansion for the information returned by rtwmakecfg functions. Modifying the Template Makefile discusses the required modifications.

After the TLC phase of the build process, when generating a makefile from the TMF, the Real-Time Workshop code generator searches for an rtwmakecfg.m file in the directory that contains the S-function component. If it finds the file, the code generator calls the rtwmakecfg function.

Creating the rtwmakecfg.m M-File Function

Create the rtwmakecfg.m M-file function in the same directory as your S-function component (sfcname.mexext on a Microsoft Windows system and sfcname and a platform-specific extension on The Open Group UNIX system). The function must return a structured array that contains the following fields:

Field	Description
makeInfo.includePath	A cell array that specifies additional include directory names, organized as a row vector. The Real-Time Workshop code generator expands the directory names into include instructions in the generated makefile.
makeInfo.sourcePath	A cell array that specifies additional source directory names, organized as a row vector. You must include the directory names of files entered into the S-function modules field on the S-Function Block Parameters dialog box or into the block's SFunctionModules parameter if they are not in the same directory as the S-function. The Real-Time Workshop code generator expands the directory names into make rules in the generated makefile.
makeInfo.sources	A cell array that specifies additional source filenames (C or C++), organized as a row vector. Do not include the name of the S-function or any files entered into the S-function modules field on the S-Function Block Parameters dialog box or into the block's SFunctionModules parameter. The Real-Time Workshop code generator expands the filenames into make variables that contain the source files. You should specify only filenames (with extension). Specify path information with the sourcePath field.
makeInfo.linkLibsObjs	A cell array that specifies additional, fully qualified paths to object or library files against which the Real-Time Workshop generated code should link. The Real-Time Workshop code generator does not compile the specified objects and libraries. However, it includes them when linking the final executable. This can be useful for incorporating libraries that you do not want the Real-Time Workshop code generator to recompile or for which the source files are not available. You might also use this element to incorporate source files from languages other than C and C++. This is possible if you first create a C compatible object file or library outside of the Real-Time Workshop build process.
makeInfo.precompile	A Boolean flag that indicates whether the libraries specified in the rtwmakecfg.m file exist in a specified location (precompile==1) or if the libraries need to be created in the build directory during the Real-Time Workshop build process (precompile==0).
makeInfo.library	A structure array that specifies additional run-time libraries and module objects, organized as a row vector. The Real-Time Workshop code generator expands the information into make rules in the generated makefile. See the next table for a list of the library fields.

The makeInfo.library field consists of the following elements:

Element	Description
makeInfo.library(n).Name	A character array that specifies the name of the library (without an extension).
makeInfo.library(n).Location	A character array that specifies the directory in which the library is located when precompiled. See the description of makeInfo.precompile in the preceding table for more information. A target can use the TargetPreCompLibLocation parameter to override this value. See Specifying the Location of Precompiled Libraries for details.
makeInfo.library(n).Modules	A cell array that specifies the C or C++ source file base names (without an extension) that comprise the library. Do not include the file extension. The makefile appends the appropriate object extension.

Note   The makeInfo.library field must fully specify each library and how to build it. The modules list in the makeInfo.library(n).Modules element cannot be empty. If you need to specify a link-only library, use the makeInfo.linkLibsObjs field instead.

Example:

 disp(['Running rtwmakecfg from directory: ',pwd]);
    makeInfo.includePath = { fullfile(pwd, 'somedir2') };
    makeInfo.sourcePath = {fullfile(pwd, 'somedir2'), fullfile(pwd, 'somedir3')};
    makeInfo.sources  = { 'src1.c', 'src2.cpp'};
    makeInfo.linkLibsObjs = { fullfile(pwd, 'somedir3', 'src3.object'),...
                              fullfile(pwd, 'somedir4', 'mylib.library')};
    makeInfo.precompile = 1;
    makeInfo.library(1).Name     = 'myprecompiledlib';
    makeInfo.library(1).Location = fullfile(pwd,'somdir2','lib');
    makeInfo.library(1).Modules  = {'srcfile1' 'srcfile2' 'srcfile3' };

Note   If a path that you specify in the rtwmakecfg.m API contains spaces, the Real-Time Workshop code generator does not automatically convert the path to its non-space equivalent. If the build environments you intend to support do not support spaces in paths, refer to Enabling the Real-Time Workshop Software to Build When Path Names Contain Spaces.

Modifying the Template Makefile

To expand the information generated by an rtwmakecfg function, you can modify the following sections of your target's TMF:

• Include Path

• C Flags and/or Additional Libraries

• Rules

The TMF code examples below may not be appropriate for your make utility. For additional examples, see the GRT or ERT TMFs located in matlabroot/rtw/c/grt/*.tmf or matlabroot/rtw/c/ert/*.tmf.

Example — Adding Directory Names to the Makefile Include Path.   The following TMF code example adds directory names to the include path in the generated makefile:

ADD_INCLUDES = \
|>START_EXPAND_INCLUDES<|   -I|>EXPAND_DIR_NAME<| \
|>END_EXPAND_INCLUDES<|

Additionally, the ADD_INCLUDES macro must be added to the INCLUDES line, as shown below.

INCLUDES = -I. -I.. $(MATLAB_INCLUDES) $(ADD_INCLUDES) $(USER_INCLUDES)

Example — Adding Library Names to the Makefile.   The following TMF code example adds library names to the generated makefile.

LIBS =
|>START_PRECOMP_LIBRARIES<|
LIBS += |>EXPAND_LIBRARY_NAME<|.a |>END_PRECOMP_LIBRARIES<|
|>START_EXPAND_LIBRARIES<|
LIBS += |>EXPAND_LIBRARY_NAME<|.a |>END_EXPAND_LIBRARIES<|

For more information on how to use configuration parameters to control library names and location during the build process, see Controlling the Location and Naming of Libraries During the Build Process.

Example — Adding Rules to the Makefile.   The following TMF code example adds rules to the generated makefile.

|>START_EXPAND_RULES<|
$(BLD)/%.o: |>EXPAND_DIR_NAME<|/%.c $(SRC)/$(MAKEFILE) rtw_proj.tmw
    @$(BLANK)
    @echo ### "|>EXPAND_DIR_NAME<|\$*.c"
    $(CC) $(CFLAGS) $(APP_CFLAGS) -o $(BLD)$(DIRCHAR)$*.o \
    |>EXPAND_DIR_NAME<|$(DIRCHAR)$*.c > $(BLD)$(DIRCHAR)$*.lst
|>END_EXPAND_RULES<|

|>START_EXPAND_LIBRARIES<|MODULES_|>EXPAND_LIBRARY_NAME<| = \
|>START_EXPAND_MODULES<|    |>EXPAND_MODULE_NAME<|.o \
|>END_EXPAND_MODULES<|

|>EXPAND_LIBRARY_NAME<|.a : $(MAKEFILE) rtw_proj.tmw
$(MODULES_|>EXPAND_LIBRARY_NAME<|:%.o=$(BLD)/%.o)
    @$(BLANK)
    @echo ### Creating $@
    $(AR) -r $@ $(MODULES_|>EXPAND_LIBRARY_NAME<|:%.o=$(BLD)/%.o)
|>END_EXPAND_LIBRARIES<|

|>START_PRECOMP_LIBRARIES<|MODULES_|>EXPAND_LIBRARY_NAME<| = \
|>START_EXPAND_MODULES<|    |>EXPAND_MODULE_NAME<|.o \
|>END_EXPAND_MODULES<|

|>EXPAND_LIBRARY_NAME<|.a : $(MAKEFILE) rtw_proj.tmw
$(MODULES_|>EXPAND_LIBRARY_NAME<|:%.o=$(BLD)/%.o)
    @$(BLANK)
    @echo ### Creating $@
    $(AR) -r $@ $(MODULES_|>EXPAND_LIBRARY_NAME<|:%.o=$(BLD)/%.o)
|>END_PRECOMP_LIBRARIES<|

Precompiling S-Function Libraries

You can precompile new or updated S-function libraries (MEX-files) for a model by using the M-file function rtw_precompile_libs. Using a specified model and a library build specification, this function builds and places the libraries in a precompiled library directory.

By precompiling S-function libraries, you can optimize system builds. Once your precompiled libraries exist, the Real-Time Workshop code generator can omit library compilation from subsequent builds. For models that use numerous libraries, the time savings for build processing can be significant.

To use rtw_precompile_libs,

1. Set the library file suffix, including the file type extension, based on the platform in use.

2. Set the precompiled library directory.

3. Define a build specification.

4. Issue a call to rtw_precompile_libs.

The following procedure explains these steps in more detail.

1. Set the library file suffix, including the file type extension, based on the platform in use.

   Consider checking for the type of platform in use and then using the TargetLibSuffix parameter to set the library suffix accordingly. For example, you might set the suffix to .a for a UNIX platform and _vc.lib otherwise.

     if isunix
       suffix = '.a';
     else
       suffix = '_vc.lib';
     end
   
   set_param(my_model,'TargetLibSuffix', suffix);

2. Set the precompiled library directory.

   Use one of the following methods to set the precompiled library directory.

   • Set the TargetPreCompLibLocation parameter, as explained in Specifying the Location of Precompiled Libraries.

   • Set the makeInfo.precompile field in an rtwmakecfg M-file function.

   If you set both TargetPreCompLibLocation and makeInfo.precompile, the setting for TargetPreCompLibLocation takes precedence.

   The following command sets the precompiled library directory for model my_model to directory lib under the current working directory.

    set_param(my_model,'TargetPreCompLibLocation', fullfile(pwd,'lib'));
   

   Note   If you set both the target directory for the precompiled library files and a target library file suffix, the Real-Time Workshop code generator automatically detects whether any precompiled library files are missing while processing builds.

3. Define a build specification.

   Set up a structure that defines a build specification. The following table describes fields you can define in the structure. All fields except rtwmakecfgDirs are optional.

   Field	Description
   rtwmakecfgDirs	A cell array of strings that name the directories containing rtwmakecfg files for libraries to be precompiled. The function uses the Name and Location elements of makeInfo.library, as returned by rtwmakecfg, to specify the name and location of the precompiled libraries. If you set the TargetPreCompLibLocation parameter to specify the library directory, that setting overrides the makeInfo.library.Location setting. Note: The specified model must contain blocks that use precompiled libraries specified by the rtwmakecfg files. This is necessary because the TMF-to-makefile conversion generates the library rules only if the libraries are needed.
   libSuffix	A string that specifies the suffix, including the file type extension, to be appended to the name of each library (for example, .a or _vc.lib). The string must include a period (.). You must set the suffix with either this field or the TargetLibSuffix parameter. If you specify a suffix with both mechanisms, the TargetLibSuffix setting overrides the setting of this field.
   intOnlyBuild	A Boolean flag. When set to true, the flag indicates the libraries are to be optimized such that they are compiled from integer code only. This field applies to ERT targets only.
   makeOpts	A string that specifies an option to be included in the rtwMake command line.
   addLibs	A cell array of structures that specify libraries to be built that are not specified by an rtwmakecfg function. Each structure must be defined with two fields that are character arrays: libName — the name of the library without a suffix libLoc — the location for the precompiled library The TMF can specify other libraries and how those libraries are to be built. Use this field if you need to precompile those libraries.

   The following commands set up build specification build_spec, which indicates that the files to be compiled are in directory src under the current working directory.

   build_spec = [];
   build_spec.rtwmakecfgDirs = {fullfile(pwd,'src')};
   

4. Issue a call to rtw_precompile_libs.

   Issue a call to rtw_precompile_libs that specifies the model for which you want to build the precompiled libraries and the build specification. For example:

   rtw_precompile_libs(my_model,build_spec);

Back to Top

Writing S-Functions for Multirate Multitasking Environments

Setting Up Generated Code To Interface With Components in the Run-Time Environment

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