Target Development Folders, Files, and Builds
Target development mechanics work with a number of folder and file types. The following topics provide the information to develop custom targets, configure folder usage, and use custom targets in the build process.
Folder and File Naming Conventions
You can use a single folder for your custom target files, or if desired you can use subfolders, for example containing files associated with specific development environments or tools.
For a custom target implementation, the recommended folder and file naming conventions are
Use only lowercase in folder names, filenames, and extensions.
Do not embed spaces in folder names. Spaces in folder names cause errors with many third-party development environments.
Include desired folders in the MATLAB® path
Do not place your custom target folder anywhere in the MATLAB folder tree (that is, in or under the
folder). If you place your folder under
matlabrootyou risk losing your work if you install a new MATLAB version (or reinstall the current version).
The following sections explain how to organize your target folders and files and add them to your MATLAB path. They also provide high-level descriptions of the files.
In this document,
mytarget is a placeholder name that represents
folders and files that use the target's name. The names
dev_tool2, and so on represent subfolders containing files associated
with development environments or tools. This document describes an example structure where
mytarget contains subfolders for
top level folder
mytarget is the target root
Components of a Custom Target
The components of a custom target are files located in a hierarchy of folders. The top-level folder in this structure is called the target root folder. The target root folder and its contents are named, organized, and located on the MATLAB path according to conventions described in Folder and File Naming Conventions.
The components of a custom target include
Code components: C source code that supervises and supports execution of generated model code.
A system target file to control the code generation process.
File(s) to control the building of an executable from the generated code. In a traditional make-based environment, a template makefile (TMF) generates a makefile for this purpose. Another approach is to generate project files in support of a modern integrated development environment (IDE) such as the Freescale® Semiconductor CodeWarrior® IDE.
Hook files: Optional TLC and MATLAB program files that can be invoked at well-defined stages of the build process. Hook files let you customize the build process and communicate information between various phases of the process.
Other target files: Files that let you integrate your target into the MATLAB environment. For example, you can provide an
info.xmlfile to make your target block libraries and examples available from a MATLAB session.
The next sections introduce key concepts and terminology you need to know to develop each component. References to more detailed information sources are provided.
An executable program containing code generated from a Simulink® model consists of a number of code modules and data structures. These fall into two categories: application components and execution support files.
Application Components. Application components are those which are specific to a particular model; they implement the functions represented by the blocks in the model. Application components are not specific to the target. Application components include
Modules generated from the model
User-written blocks (S-functions)
Parameters of the model that are visible, and can be interfaced to, external code
Execution Support Files. A number of code modules and data structures, referred to collectively as the execution support files, are responsible for managing and supporting the execution of the generated program. The execution support files modules are not automatically generated. Depending on the requirements of your target, you must implement certain parts of the execution support files. Execution Support Files summarizes the execution support files.
Execution Support Files
|The Code Generator Provides...
Customized main program
Generic main program
Timer interrupt handler to run model
Execution engine and integration solver (called by timer interrupt handler)
Other interrupt handlers
Example interrupt handlers (Asynchronous Interrupt blocks)
Example device drivers
Data logging, parameter tuning, signal monitoring, and external mode support
Data logging, parameter tuning, signal monitoring, and external mode APIs
User-Written Execution Support Files. The code generator provides most of the execution support files. Depending on the requirements of your target, you must implement some or all of the following elements:
A timer interrupt service routine (ISR). The timer runs at the program's base sample rate. The timer ISR is responsible for operations that must be completed within a single clock period, such as computing the current output sample. The timer ISR usually calls the
If you are targeting a real-time operating system (RTOS), your generated code usually executes under control of the timing and task management mechanisms provided by the RTOS. In this case, you may not have to implement a timer ISR.
The main program. Your main program initializes the blocks in the model, installs the timer ISR, and executes a background task or loop. The timer periodically interrupts the main loop. If the main program is designed to run for a finite amount of time, it is also responsible for cleanup operations — such as memory deallocation and masking the timer interrupt — before terminating the program.
If you are targeting a real-time operating system (RTOS), your main program most likely spawns tasks (corresponding to the sample rates used in the model) whose execution is timed and controlled by the RTOS.
Your main program typically is based on a generated or static main program. For details on the structure of the execution support files, code execution, and guidelines for customizing main programs, see Deploy Applications to Target Hardware (Embedded Coder).
Other interrupt handlers. If your models need to support asynchronous events, such as hardware generated interrupts and asynchronous read and write operations, you must supply interrupt handlers. The Interrupt Templates library provides examples.
Data logging, parameter tuning, signal monitoring, and external mode support. It is atypical to implement rapid prototyping features such as external mode support in an embedded target. However, it is possible to support these features by using standard code generator APIs. See Generated Code Interfacing for details.
The code generation and build process is directed by a number of TLC and MATLAB files collectively called control files. This section introduces and summarizes the main control files.
Top-Level Control File (make_rtw). The build process is initiated when you press Ctrl+B.
At this point, the build process parses the Make
command field of the Code Generation pane of the
Configuration Parameters dialog box, expecting to find the name of a MATLAB command that controls the build process (as well as optional arguments to
that command). The default command is
make_rtw, and the default
top-level control file for the build process is
make_rtw is an internal MATLAB command used by the build process. Normally, target developers do not
need detailed knowledge of how
make_rtw works. (The details for
target developers are described in Target Development and the Build Process.) You should not invoke
make_rtw directly from MATLAB code, and you should not customize
make_rtw.m file contains the logic required to execute your
target-specific control files, including a number of hook points for execution of your
make_rtw does the following:
Passes optional arguments in to the build process
Performs required preprocessing before code generation
Executes the system target file to perform code generation (and optional HTML report generation)
Processes the TMF to generate a makefile
Invokes a make utility to execute the makefile and build an executable
Performs required post-processing (such as generating calibration data files or downloading the generated executable to the target)
System Target File. The Target Language Compiler (TLC) generates target-specific C or C++ code from a
partial description of your Simulink block diagram (
The Target Language Compiler reads
and executes a program
consisting of several target files (
.tlc files.) The system target
file, at the top level of this program, controls the code generation process. The output
of this process is a number of source files, which are fed to your development system's
You need to create a customized system target file to set code generation parameters
for your target. You should copy, rename, and modify the standard ERT system target file
The detailed structure of the system target file is described in Customize System Target Files.
The system target file selects whether the target supports the toolchain approach or template makefile approach for code generation. See Customize System Target Files.
Template Makefile (TMF). A TMF provides information about your model and your development system. The build
process uses this information to create a makefile (
.mk file) that
builds an executable program.
Some targets implement more than one TMF, in order to support multiple development environments (for example, two or more cross-compilers) or multiple modes of code generation (for example, generating a binary executable versus generating a project file for your compiler).
The Embedded Coder® software provides a large number of TMFs suitable for different types of
development computer systems. These TMFs are located in
The standard TMFs are described in Template Makefiles and Make Options.
The detailed structure of the TMF is described in Customize Template Makefiles.
The system target file selects whether the target supports the toolchain approach or template makefile approach for code generation. See Customize System Target Files.
Hook Files. The build process allows you to supply optional hook files that are executed at specified points in the code generation and make process. You can use hook files to add target-specific actions to the build process.
The hook files must follow well-defined naming and location requirements. Folder and File Naming Conventions describes these requirements.
Key Folders Under Target Root (mytarget)
Target Root Folder (mytarget)
This folder contains the key subfolders for the target (see Folder and File Naming Conventions). You can also locate miscellaneous files
(such as a
readme file) in the target root folder. The following
sections describe required and optional subfolders and their contents.
Target Folder (mytarget/mytarget)
This folder contains files that are central to the target, such as the system target
file (STF) and template makefile (TMF). Key Files in Target Folder (mytarget/mytarget) summarizes the files that should be stored in
mytarget/mytarget, and provides pointers to detailed information
about these files.
mytarget/mytarget should be on the MATLAB path.
Target Block Folder (mytarget/blocks)
If your target includes device drivers or other blocks, locate the block
implementation files in this folder.
Compiled block MEX-files
Source code for the blocks
TLC inlining files for the blocks
Library models for the blocks (if you provide your blocks in one or more libraries)
mytarget/blocks should be on the MATLAB path.
You can also store example models and supporting files in
mytarget/blocks. Alternatively, you can create a
mytarget/mytargetdemos folder, which should also be on the
To display your blocks in the standard Simulink Library Browser and/or integrate your example models into the MATLAB session environment
you can create the files described below and store them in
mytarget/blocks/slblocks.m. This file allows a group of blocks to be integrated into the Simulink Library and Simulink Library Browser.
function blkStruct = slblocks % Information for "Blocksets and Toolboxes" subsystem blkStruct.Name = sprintf('Embedded Target\n for MYTARGET'); blkStruct.OpenFcn = 'mytargetlib'; blkStruct.MaskDisplay = 'disp(''MYTARGET'')'; % Information for Simulink Library Browser Browser(1).Library = 'mytargetlib'; Browser(1).Name = 'Embedded Target for MYTARGET'; Browser(1).IsFlat = 1;% Is this library "flat" (i.e. no subsystems)? blkStruct.Browser = Browser;
mytarget/blocks/demos.xml. This file provides information about the components, organization, and location of example models. MATLAB software uses this information to place the example in the MATLAB session environment.
<?xml version="1.0" encoding="utf-8"?> <demos> <name>Embedded Target for MYTARGET</name> <type>simulink</type> <icon>$toolbox/matlab/icons/boardicon.gif</icon> <description source = "file">mytarget_overview.html</description> <demosection> <label>Multirate model</label> <demoitem> <label>MYTARGET demo</label> <file>mytarget_overview.html</file> <callback>mytarget_model</callback> </demoitem> </demosection> </demos>
Development Tools Folder (mytarget/dev_tool1, mytarget/dev_tool2)
These folders contain files associated with specific development environments or tools
dev_tool2, etc.). Normally, your
target supports at least one such development environment and invokes its compiler,
linker, and other utilities during the build process.
mytarget/dev_tool1 includes linker command files, startup code, hook
functions, and other files required to support this process.
For each development environment, you should provide a separate folder.
Target Source Code Folder (mytarget/src)
This folder is optional. If the complexity of your target requires it, you can use
mytarget/src to store common source code and configuration code (such
as boot and startup code).
Key Files in Target Folder (mytarget/mytarget)
The target folder
mytarget/mytarget contains key files in your
target implementation. These include the system target file, template makefile, main
program module, and optional M and TLC hook files that let you add target-specific actions
to the build process. The following sections describe the key target folder files.
mytarget.tlc is the system target file. Functions of the system
target file include
Making the target visible in the System Target File Browser
Definition of code generation options for the target (inherited and target-specific)
Providing an entry point for the top-level control of the TLC code generation process
You should base your system target file on
ert.tlc, the system
target file provided by Embedded Coder software.
Customize System Target Files gives detailed information on the structure of the system target file, and also gives instructions on how to customize a system target file to
Display your target in the System Target File Browser
Add your own target options to the Configuration Parameters dialog box
Tailor the code generation and build process to the requirements of your target
mytarget.tmf is the template makefile for building an executable
for your target.
For basic information on the structure and operation of template makefiles, see Customize Template Makefiles.
This file is optional.
mytarget_genfiles.tlc is useful as a central
file from which to invoke target-specific TLC files that generate additional files as part
of your target build process. For example, your target may create sub-makefiles or project
files for a development environment, or command scripts for a debugger to do automatic
downloads. See Using mytarget_genfiles.tlc for details.
A main program module is required for your target. To provide a main module, you can either
rt_cppclass_main.cppmodule provided by the software
.cppduring the build process
For a description of the operation of main programs, see Deploy Applications to Target Hardware (Embedded Coder). The section also contains guidelines for generating and modifying a main program module.
is an optional hook
file that you can use to invoke target-specific functions or executables at specified
points in the build process.
implements a function
that dispatches to a specific action depending on the
that is passed into it.
Customize Build Process with STF_make_rtw_hook File describes the operation of
hook file in
This file provides information to MATLAB software that specifies where to display the target toolbox in the MATLAB session environment. For more information, see Display Custom Documentation.
By convention, this file serves as home page for the target examples.
<description> field in
should point to
mytarget_overview.html (see mytarget/blocks/demos.xml).
Example mytarget_overview.html File
<html> <head><title>Embedded Target for MYTARGET</title></head><body> <p style="color:#990000; font-weight:bold; font-size:x-large">Embedded Target for MYTARGET Example Model</p> <p>This example provides a simple model that allows you to generate an executable for a supported target board. You can then download and run the executable and set breakpoints to study and monitor the execution behavior.</p> </body> </html>
Additional Files for Externally Developed Targets
If you are developing an embedded target that is not installed into the MATLAB tree, you should provide a target setup script and target documentation
mytarget/mytarget, for the convenience of your users. The
following sections describe the required materials and where to place them.
This file script adds paths for your target to the MATLAB path. Your documentation should instruct users to run the script when installing the target.
You should include a call to the MATLAB function
savepath in your
mytarget_setup.m script. This function saves the added paths, so
users need to run
mytarget_setup.m only once.
The following code is an example
function mytarget_setup() curpath = pwd; tgtpath = curpath(1:end-length('\mytarget')); addpath(fullfile(tgtpath, 'mytarget')); addpath(fullfile(tgtpath, 'dev_tool1')); addpath(fullfile(tgtpath, 'blocks')); addpath(fullfile(tgtpath, 'mytargetdemos')); savepath; disp('MYTARGET Target Path Setup Complete.');
You should put the documentation related to your target in the folder
Target Development and the Build Process
About the Build Process
To develop an embedded target, you need a thorough understanding of the build process. Your embedded target uses the build process and might require you to modify or customize the process. A general overview of code generation and the build process is given in Source Code Generation.
This section supplements that overview with a description of the build process as customized by the Embedded Coder software. The emphasis is on points in the process where customization hooks are available and on passing information between different phases of the process.
This section concludes with Additional Information Passing Techniques, describing assorted tips and tricks for passing information during the build process.
Build Process Phases and Information Passing
It is important to understand where (and when) the build process obtains required information. Sources of information include
file, which provides information about the generating model. The information in
is available to target TLC files.
The code generation panes of the Configuration Parameters dialog box. Options (both general and target-specific) are provided through check boxes, menus, and edit fields. You can associate options with TLC variables in the
rtwoptionsdata structure. Use the Configuration Parameters > Code Generation > Custom Code > Code information > Defines field to define makefile tokens .
The selected toolchain (for toolchain approach builds) or selected template makefile
.tmf(for template makefile approach builds); these generate the model-specific makefile.
Environment variables on the host computer. Environment variables provide additional information about installed development tools.
Other target-specific files such as target-related TLC files, linker command files, or project files.
It is also important to understand the several phases of the build process and how to pass information between the phases. The build process comprises several high-level phases:
Execution of the top-level file (
slbuild.m) to sequence through the build process for a target
Conversion of the model into the TLC input file (
Generation of the target code by the TLC compiler
Compilation of the generated code with
makeor other utilities
Transmission of the final generated executable to the target hardware with a debugger or download utility
It is helpful to think of each phase of the process as a different “environment” that maintains its own data. These environments include
MATLAB code execution environment (MATLAB)
Target Language Compiler execution environment
Development environments such as and IDE or debugger
In each environment, you might get information from the various sources mentioned above. For example, during the TLC phase, execute MATLAB file might execute to obtain information from the MATLAB environment. Also, a given phase may generate information for a subsequent phase.
See Key Files in Target Folder (mytarget/mytarget) for details on the available MATLAB file and TLC hooks for information passing, with code examples.
Additional Information Passing Techniques
This section describes a number of useful techniques for passing information among different phases of the build process.
tlcvariable Field in rtwoptions Structure. Parameters on the code generation panes of the Configuration Parameters dialog box
can be associated with a TLC variable, and specified in the
tlcvariable field of the option's entry in the
rtwoptions structure. The variable value is passed on the command
line when TLC is invoked. This provides a way to make code generation parameters and
their values available in the TLC phase.
See System Target File Structure for further information.
makevariable Field in rtwoptions Structure. You can associate code generation parameters with a template makefile token, that
you specify in the
makevariable field of the option's entry in the
rtwoptions structure. If a token of the same name as the
makevariable name exists in the TMF, the token is updated with the
option value when the final makefile is created. If the token does not exist in the TMF,
makevariable is passed in on the command line when make is
invoked. Thus, in either case, the
makevariable is available to the
See System Target File Structure for further information.
Accessing Host Environment Variables. You can access host shell environment variables at the MATLAB command line by entering the
getenv command. For
getenv ('MSDEVDIR') ans = D:\Applications\Microsoft Visual Studio\Common\MSDev98
To access the same information from TLC, use the
%assign eVar = FEVAL("getenv","<varname>")
Supplying Development Environment Information to Your Template Makefile. An embedded target must tie the build process to target-specific development tools installed on a host computer. For the make process to run these tools, the TMF must be able to determine the name of the tools, the path to the compiler, linker, and other utilities, and possibly the host operating system environment variable settings.
Require the end user to modify the target TMF. The user enters path information (such as the location of a compiler executable), and possibly host operating system environment variables, as make variables. This allows the TMF to be tailored to specific needs.
Using MATLAB Application Data. Application data provides a way for applications to save and retrieve data stored
with the GUI. This technique enables you to create what is essentially a user-defined
property for an object, and use this property to store data for use in the build
process. For more information, see
The following code examples illustrates the use of application data to pass information to TLC.
tlc2appdata.m, stores the
passed in as application data under the name passed in
function k = tlc2appdata(appDataName,data) disp([mfilename,': ',appDataName,' ', data]); setappdata(0,appDataName,data); k = 0; % TLC expects a return value for FEVAL.
The following sample TLC file uses the
FEVAL directive to invoke
tlc2appdata.m to store arbitrary application data, under the name
%% test.tlc %% %assign myApp = "z80" %assign myData = "314159" %assign dummy = FEVAL("tlc2appdata",myApp,myData)
To test this technique:
tlc2appdata.mfile as shown. Check that
tlc2appdata.mis stored in a folder on the MATLAB path.
Create the TLC file as shown. Save it as
Enter the following command at the MATLAB prompt to execute the TLC file:
Get the application data at the MATLAB prompt:
k = getappdata(0,'z80')
The function returns the value 314159.
Enter the following command.
Note that application data is not stored in the MATLAB workspace. Also observe that the z80 data is not visible. Using application data in this way has the advantage that it does not clutter the MATLAB workspace. Also, it helps prevent you from accidentally deleting your data, since it is not stored directly in your workspace.
A real-world use of application data might be to collect information from the
file and store it for use
later in the build process.
Adding Block-Specific Information to the Makefile. The
rtwmakecfg mechanism provides a method for inlined
S-functions such as driver blocks to add information to the makefile. This mechanism is
described in Use rtwmakecfg.m API to Customize Generated Makefiles.