Real-Time Workshop User's Guide

Tutorial: Creating a Custom Target Configuration

This tutorial walks through the task of creating a skeletal rapid prototyping target. This exercise illustrates several tasks that are usually required when creating a custom target:

• Incorporating a noninlined S-function into a model for use in simulation.
• Inlining the S-function in the generated code, using a corresponding TLC file.

In a real-world application, you would incorporate inlined and noninlined device driver S-functions into the model and the generated code. In this tutorial, we inline a simple S-function that multiplies its input by two.

• Making minor modifications to a standard system target file and template makefile.
• Generating code from the model by invoking your customized system target file and template makefile.

You can use this process as a starting point for your own projects.

This example uses the LCC compiler under Windows. LCC is distributed with Real-Time Workshop. If you use a different compiler, you can set up LCC temporarily as your default compiler by typing the MATLAB command

mex -setup

A command prompt window will open; follow the prompts and select LCC.

Note    On UNIX systems, make sure that you have a C compiler installed. You can then do this exercise substituting appropriate UNIX directory syntax.

In this example, the code is generated from targetModel.mdl, a very simple fixed-step model (see Figure 17-1). The resultant program behaves exactly as if it had been built for the generic real-time target.

Figure 17-1: targetModel.mdl

The S-Function block will use the source code from the timestwo example. See the Writing S-Functions manual for a complete discussion of this S-function. The Target Language Compiler Reference Guide discusses timestwo.tlc, the inlined version of timestwo.

To create the skeletal target system:

1. Create a directory to store your C source files and .tlc and .tmf files. We refer to this directory as d:/work/mytarget.
2. Add d:/work/mytarget to your MATLAB path.

   addpath d:/work/mytarget
   

3. Make d:/work/mytarget your working directory. Real-Time Workshop writes the output files of the code generation process into a build directory within the working directory.
4. Copy the timestwo S-function C source code from matlabroot/toolbox/rtw/rtwdemos/tlctutorial/timestwo/solutions/timestwo.c to
   d:/work/mytarget.
5. Build the timestwo MEX-file in d:/work/mytarget.

   mex timestwo.c
   

6. Create the model as illustrated in Figure 17-1. Use an S-Function block from the Simulink Functions & Tables library in the Library Browser. Set the solver options to fixed-step and ode4.
7. Double-click the S-Function block to open the Block Parameters dialog. Enter the S-function name timestwo. The block is now bound to the timestwo MEX-file. Click OK.
8. Open the Scope and run the simulation. Verify that the timestwo S-function multiplies its input by 2.0.
9. In order to generate inlined code from the timestwo S-Function block, you must have a corresponding TLC file in the working directory. If the Target Language Compiler detects a C-code S-function and a TLC file with the same name in the working directory, it generates inline code from the TLC file. Otherwise, it generates a function call to the external S-function.

To ensure that the build process generates inlined code from the timestwo block, copy the timestwo TLC source code from matlabroot/toolbox/rtw/ rtwdemos/tlctutorial/timestwo/solutions/timestwo.tlc to
d:/work/mytarget.

10. Make local copies of the main program and system target files. matlabroot/rtw/c/grt contains the main program (grt_main.c) and the system target file (grt.tlc) for the generic real-time target. Copy grt_main.c and grt.tlc to d:/work/mytarget. Rename them to mytarget_main.c and mytarget.tlc.
11. Remove the initial comment lines from mytarget.tlc. The lines to remove are shown below.

    %% SYSTLC: Generic Real-Time Target \
    %%    TMF: grt_default_tmf MAKE: make_rtw EXTMODE: ext_comm 
    %% SYSTLC: Visual C/C++ Project Makefile only for the "grt" target \
    %%    TMF: grt_msvc.tmf MAKE: make_rtw EXTMODE: ext_comm
    

The initial comment lines have significance only if you want to add my_target to the System Target File Browser. For now you should remove them.

12. Real-Time Workshop creates a build directory in your working directory to store files created during the code generation process. The build directory is given the name of the model, followed by a suffix. This suffix is specified in the rtwgensettings structure in the system target file.

To set the suffix to a more appropriate string, change the line

rtwgensettings.BuildDirSuffix = '_grt_rtw'

to

rtwgensettings.BuildDirSuffix = '_mytarget_rtw'

Your build directory will be named targetModel__mytarget_rtw.

13. Make a local copy of the template makefile. matlabroot/rtw/c/grt contains several compiler-specific template makefiles for the generic real-time target. The appropriate template makefile for the LCC compiler is grt_lcc.tmf. Copy grt_lcc.tmf to d:/work/mytarget, and rename it to mytarget.tmf.

Note    Some of the template makefile modifications described in the next step are specific to the LCC template makefile. If you are using a different compiler and template makefile, the rules for the source (REQ_SRCS) and object file (%.obj :) lists may differ slightly.

14. Modify mytarget.tmf. The SYS_TARGET FILE parameter must be changed so that the correct file reference is generated in the make file. Change the line

    SYS_TARGET FILE = grt.tlc
    

to

SYS_TARGET FILE = mytarget.tlc

Also, change the source file list to include mytarget_main.c instead of grt_main.c.

REQ_SRCS = $(MODEL).c $(MODULES) mytarget_main.c...

Finally, change the line

%.obj : $(MATLAB_ROOT)/rtw/c/grt/%.c

to

%.obj : d:/work/mytarget/%.c

15. This exercise requires no changes to mytarget_main.c. In an actual application, you would modify mytarget_main.c to execute your model code under the control of a timer interrupt, and make other changes.
16. Open the Real-Time Workshop page in the Simulation Parameters dialog. Select Target configuration from the Category menu. Enter the system target file, template makefile, and Make command parameters as below.
    
    
17. Click the Apply button.
18. Click the Build button. If the build is successful, MATLAB will display the message below.

    ### Created executable: targetModel.exe 
    ### Successful completion of Real-Time Workshop build procedure 
    for model: targetModel
    

Your working directory will contain the targetModel.exe file and the build directory, targetModel_mytarget_rtw.

19. Edit the generated file d:/work/mytarget/targetModel_mytarget_rtw/targetModel.c and locate the MdlOutputs function. Observe the inlined code.

    /* S-Function Block: <Root>/S-Function (timestwo) */
    rtB.S_Function = 2.0 * rtB.Sine_Wave;
    

Because the working directory contained a TLC file (timestwo.tlc) with the same name as the timestwo S-Function block, the Target Language Compiler generated inline code instead of a function call to the external C- code S-function.

20. As an optional final step to this exercise, you may want to add your custom target configuration to the System Target File Browser. See Adding a Custom Target to the System Target File Browser to learn how to do this.

Control Files

Customizing the Build Process