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 matlabroot folder). If you place your folder under matlabroot you 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_tool1, dev_tool2, and so on represent subfolders containing files associated with development environments or tools. This document describes an example structure where the folder mytarget contains subfolders for mytarget, blocks, dev_tool1, dev_tool2. The top level folder mytarget is the target root folder.

Overview

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.
Control files:
- 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.xml file 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.

Code Components

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

You Provide...	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)
Device drivers	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 rt_OneStep function.
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).
Device drivers. Drivers communicate with I/O devices on your target hardware. In production code, device drivers are normally implemented as inlined S-functions.
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.

Control Files

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.m.

Note

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.

The 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 custom code. 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 (model.rtw). The Target Language Compiler reads model.rtw 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 make utility.

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 (matlabroot/rtw/c/ert/ert.tlc).

The detailed structure of the system target file is described in Customize System Target Files.

Note

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 matlabroot/toolbox/coder/compile/tmf. The standard TMFs are described in Template Makefiles and Make Options.

The detailed structure of the TMF is described in Customize Template Makefiles.

Note

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)
Target Folder (mytarget/mytarget)
Target Block Folder (mytarget/blocks)
Development Tools Folder (mytarget/dev_tool1, mytarget/dev_tool2)
Target Source Code Folder (mytarget/src)

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.

Note

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. mytarget/blocks contains

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)

Note

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 MATLAB path.

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.

mytarget/blocks/slblocks.m. This file allows a group of blocks to be integrated into the Simulink Library and Simulink Library Browser.

Example 1. Example slblocks.m File

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.

Example 2. Example demos.xml File

<?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_tool1, 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)

Introduction
mytarget.tlc
mytarget.tmf
mytarget_genfiles.tlc
mytarget_main.c
STF_make_rtw_hook.m
info.xml
mytarget_overview.html

Introduction

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

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

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.

mytarget_genfiles.tlc

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.

mytarget_main.c

A main program module is required for your target. To provide a main module, you can either

Modify the rt_main.c or rt_cppclass_main.cpp module provided by the software
Generate mytarget_main.c or .cpp during 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.

STF_make_rtw_hook.m

STF_make_rtw_hook.m is an optional hook file that you can use to invoke target-specific functions or executables at specified points in the build process. STF_make_rtw_hook.m implements a function that dispatches to a specific action depending on the method argument that is passed into it.

Customize Build Process with STF_make_rtw_hook File describes the operation of the STF_make_rtw_hook.m hook file in detail.

info.xml

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.

mytarget_overview.html

By convention, this file serves as home page for the target examples.

The <description> field in demos.xml 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

Introduction
mytarget/mytarget/mytarget_setup.m
mytarget/mytarget/doc

Introduction

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 within mytarget/mytarget, for the convenience of your users. The following sections describe the required materials and where to place them.

mytarget/mytarget/mytarget_setup.m

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 mytarget_setup.m file.

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.');

mytarget/mytarget/doc

You should put the documentation related to your target in the folder mytarget/mytarget/doc.

Target Development and the Build Process

About the Build Process
Build Process Phases and Information Passing
Additional Information Passing Techniques

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

The model.rtw file, which provides information about the generating model. The information in model.rtw 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 rtwoptions data 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 (model.rtw)
Generation of the target code by the TLC compiler
Compilation of the generated code with make or 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)
Simulink
Target Language Compiler execution environment
makefile
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, the makevariable is passed in on the command line when make is invoked. Thus, in either case, the makevariable is available to the makefile.

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 example:

getenv ('MSDEVDIR')

ans =

D:\Applications\Microsoft Visual Studio\Common\MSDev98

To access the same information from TLC, use the FEVAL directive to invoke getenv.

%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 setappdata and getappdata.

The following code examples illustrates the use of application data to pass information to TLC.

This file, tlc2appdata.m, stores the data passed in as application data under the name passed in (appDataName).

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 z80.

%% test.tlc
%%
%assign myApp = "z80"
%assign myData = "314159"
%assign dummy = FEVAL("tlc2appdata",myApp,myData)

To test this technique:

Create the tlc2appdata.m file as shown. Check that tlc2appdata.m is stored in a folder on the MATLAB path.
Create the TLC file as shown. Save it as test.tlc.
Enter the following command at the MATLAB prompt to execute the TLC file:
```
tlc test.tlc
```
Get the application data at the MATLAB prompt:
```
k = getappdata(0,'z80')
```
The function returns the value 314159.
Enter the following command.
```
who
```
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 model.rtw 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.