Embedded Coder Users Guide R2014b PDF
Embedded Coder Users Guide R2014b PDF
User's Guide
R2014b
How to Contact MathWorks
Phone: 508-647-7000
Revision History
April 2011 Online only New for Version 6.0 (Release 2011a)
September 2011 Online only Revised for Version 6.1 (Release 2011b)
March 2012 Online only Revised for Version 6.2 (Release 2012a)
September 2012 Online only Revised for Version 6.3 (Release 2012b)
March 2013 Online only Revised for Version 6.4 (Release 2013a)
September 2013 Online only Revised for Version 6.5 (Release 2013b)
March 2014 Online only Revised for Version 6.6 (Release 2014a)
October 2014 Online only Revised for Version 6.7 (Release 2014b)
Check Bug Reports for Issues and Fixes
Software is inherently complex and is not free of errors. The output of a code generator
might contain bugs, some of which are not detected by a compiler. MathWorks
reports critical known bugs brought to its attention on its Bug Report system at
www.mathworks.com/support/bugreports/. Use the Saved Searches and Watched Bugs
tool with the search phrase "Incorrect Code Generation" to obtain a report of known bugs
that produce code that might compile and execute, but still produce wrong answers.
The bug reports are an integral part of the documentation for each release. Examine
periodically all bug reports for a release, as such reports may identify inconsistencies
between the actual behavior of a release you are using and the behavior described in this
documentation.
In addition to reviewing bug reports, you should implement a verification and validation
strategy to identify potential bugs in your design, code, and tools.
Contents
Modeling Environment
1
Set Up Your Modeling Environment . . . . . . . . . . . . . . . . 1-2
Application Objectives
2
v
ISO 26262 Standard . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-9
Apply Simulink and Embedded Coder to the ISO 26262
Standard . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-9
Check for ISO 26262 Standard Compliance Using the
Model Advisor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-9
Validate Traceability . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-8
vi Contents
Declare a Variable for a Signal using a Data Object . . . 4-10
If-Else . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-23
C Construct . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-23
Modeling Patterns . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-23
Modeling Pattern for If-Else: Switch block . . . . . . . . . 4-23
Modeling Pattern for If-Else: Stateflow Chart . . . . . . . 4-25
Modeling Pattern for If-Else: MATLAB Function Block 4-26
Switch . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-28
C Construct . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-28
Modeling Patterns . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-28
Modeling Pattern for Switch: Switch Case block . . . . . 4-28
vii
Modeling Pattern for Switch: MATLAB Function block 4-31
Convert If-Elseif-Else to Switch statement . . . . . . . . . 4-32
viii Contents
Use a Stateflow Chart to Make Calls to C Functions . . 4-61
Using a MATLAB Function Block to Make Calls to C
Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-62
Typedef . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-69
C Construct . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-69
Procedure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-69
Results . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-70
Bitfields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-80
C Construct . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-80
Procedure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-80
Results . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-81
ix
Results . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-83
Variant Systems
5
About Variant Systems . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-2
x Contents
View Generated Code . . . . . . . . . . . . . . . . . . . . . . . . . 5-13
Scheduling Considerations
6
Use Discrete and Continuous Time . . . . . . . . . . . . . . . . . 6-2
Support for Discrete and Continuous Time Blocks . . . . . 6-2
Support for Continuous Solvers . . . . . . . . . . . . . . . . . . . 6-2
Support for Stop Time . . . . . . . . . . . . . . . . . . . . . . . . . . 6-2
Data Types
7
What are User-Defined Data Types? . . . . . . . . . . . . . . . . 7-2
xi
Location of User-Defined Type Definitions . . . . . . . . . . 7-3
Omit a HeaderFile Value . . . . . . . . . . . . . . . . . . . . . . . 7-3
Specify a HeaderFile Value . . . . . . . . . . . . . . . . . . . . . . 7-3
Buses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-11
About Buses and Code Generation . . . . . . . . . . . . . . . 7-11
Set Bus Diagnostics . . . . . . . . . . . . . . . . . . . . . . . . . . 7-12
Optimize Virtual and Nonvirtual Buses . . . . . . . . . . . 7-12
Use Single-Rate and Multi-Rate Buses . . . . . . . . . . . . 7-15
Set Bus Signal Initial Values . . . . . . . . . . . . . . . . . . . 7-18
Use Buses with Atomic Subsystems . . . . . . . . . . . . . . 7-22
xii Contents
Module Packaging Tool (MPT) Data Objects
8
MPT Data Object Properties . . . . . . . . . . . . . . . . . . . . . . 8-2
xiii
Define Advanced Custom Storage Classes Types . . . . . 9-50
Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-50
Create Your Own Parameter and Signal Classes . . . . . 9-50
Create Custom Attributes Classes for Custom Storage
Classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-50
Write TLC Code for Custom Storage Classes . . . . . . . . 9-51
Register Custom Storage Class Definitions . . . . . . . . . 9-51
xiv Contents
Sample Procedure for Configuring Function
Prototypes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-11
Configure Function Prototypes Programmatically . . . 11-16
Sample Script for Configuring Function Prototypes . . 11-20
Verify Generated Code for Customized Functions . . . 11-20
Function Prototype Control Limitations . . . . . . . . . . 11-21
Memory Sections
12
About Memory Sections . . . . . . . . . . . . . . . . . . . . . . . . . 12-2
What Are Memory Sections? . . . . . . . . . . . . . . . . . . . . 12-2
xv
Specify a Qualifier for Custom Storage Class Data
Definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-7
Specify Comment and Pragma Text . . . . . . . . . . . . . . 12-7
Surround Individual Definitions with Pragmas . . . . . . 12-7
Include Identifier Names in Pragmas . . . . . . . . . . . . . 12-8
Code Generation
Configuration
13
Application Objectives . . . . . . . . . . . . . . . . . . . . . . . . . . 13-2
xvi Contents
Check and Configure Model for Code Generation
Objectives Using Configuration Parameters Dialog
Box . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-10
Wizard . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-32
Configure and Optimize Model with Configuration Wizard
Blocks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-32
Add a Configuration Wizard Block . . . . . . . . . . . . . . 13-33
Use Configuration Wizard Blocks . . . . . . . . . . . . . . . 13-35
Create a Custom Configuration Wizard Block . . . . . . 13-35
xvii
Code Appearance
14
Add Custom Comments to Generated Code . . . . . . . . . 14-3
xviii Contents
Specify Templates For Code Generation . . . . . . . . . . 14-37
xix
Ownership Settings . . . . . . . . . . . . . . . . . . . . . . . . . . 14-85
Memory Section Settings . . . . . . . . . . . . . . . . . . . . . . 14-86
Data Placement Rules . . . . . . . . . . . . . . . . . . . . . . . . 14-86
Settings for a Data Object . . . . . . . . . . . . . . . . . . . . . 14-86
Data Placement Rules and Results . . . . . . . . . . . . . . 14-94
xx Contents
Report Generation
16
Reports for Code Generation . . . . . . . . . . . . . . . . . . . . . 16-2
xxi
Analyze the Generated Code Interface . . . . . . . . . . . . 16-24
Code Interface Report Overview . . . . . . . . . . . . . . . . 16-24
Generating a Code Interface Report . . . . . . . . . . . . . 16-25
Navigating Code Interface Report Subsections . . . . . 16-27
Interpreting the Entry Point Functions Subsection . . 16-28
Interpreting the Inports and Outports Subsections . . 16-31
Interpreting the Interface Parameters Subsection . . . 16-32
Interpreting the Data Stores Subsection . . . . . . . . . . 16-34
Code Interface Report Limitations . . . . . . . . . . . . . . . 16-35
xxii Contents
Math Functions – Simulink Support . . . . . . . . . . . . . . 17-4
Math Functions – Stateflow Support . . . . . . . . . . . . . 17-10
Memory Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . 17-15
Nonfinite Functions . . . . . . . . . . . . . . . . . . . . . . . . . . 17-16
Mutex and Semaphore Functions . . . . . . . . . . . . . . . 17-17
Lookup Table Functions . . . . . . . . . . . . . . . . . . . . . . 17-18
Operators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17-18
Deployment
Desktops
18
Shared Object Libraries . . . . . . . . . . . . . . . . . . . . . . . . . 18-2
About Host-Based Shared Libraries . . . . . . . . . . . . . . 18-2
Generate Shared Library Version of Model Code . . . . . 18-3
Create Application Code to Use Shared Library . . . . . 18-3
Host-Based Shared Library Limitations . . . . . . . . . . . 18-7
xxiii
Real-Time and Embedded Systems
19
Standalone Programs (No Operating System) . . . . . . . 19-2
About Standalone Program Execution . . . . . . . . . . . . . 19-2
Generate a Standalone Program . . . . . . . . . . . . . . . . . 19-2
Standalone Program Components . . . . . . . . . . . . . . . . 19-3
Main Program . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19-3
rt_OneStep and Scheduling Considerations . . . . . . . . . 19-4
Static Main Program Module . . . . . . . . . . . . . . . . . . 19-10
Rate Grouping Compliance and Compatibility Issues . 19-17
xxiv Contents
Code Replacement Customization for Simulink
Models
21
What Is Code Replacement Customization? . . . . . . . . . 21-3
xxv
Register Code Replacement Mappings . . . . . . . . . . . . 21-66
Code Replacement Library Registration . . . . . . . . . . 21-66
Create Registration File Interactively with the Code
Replacement Tool . . . . . . . . . . . . . . . . . . . . . . . . . 21-67
Create Registration File Programmatically . . . . . . . . 21-69
Register a Code Replacement Library . . . . . . . . . . . . 21-71
Registration Files That Define Multiple Code Replacement
Libraries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21-71
Registration Files That Define Code Replacement Library
Hierarchies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21-72
xxvi Contents
Data Alignment for Code Replacement . . . . . . . . . . . 21-125
Code Replacement Data Alignment . . . . . . . . . . . . . 21-125
Specify Data Alignment Requirements for Function
Arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21-125
Provide Data Alignment Specifications for Compilers 21-127
Basic Example of Code Replacement Data Alignment 21-132
xxvii
Customize Matching and Replacement Process for
Operators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21-180
Create the Entry . . . . . . . . . . . . . . . . . . . . . . . . . . . 21-180
Test the Entry . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21-185
xxviii Contents
Code You Can Replace from MATLAB Code . . . . . . . . . 22-4
About Code You Can Replace . . . . . . . . . . . . . . . . . . . 22-4
Math Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22-4
Memory Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22-9
Operators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22-9
xxix
Review and Test Code Replacements . . . . . . . . . . . . . 22-63
Code Replacement Table Validation . . . . . . . . . . . . . 22-63
Validate a Table Definition File . . . . . . . . . . . . . . . . 22-63
Review Table Content . . . . . . . . . . . . . . . . . . . . . . . . 22-64
Verify Library Registration and Content . . . . . . . . . . 22-65
Review and Trace Code Replacements Generated Using a
Code Replacement Library . . . . . . . . . . . . . . . . . . 22-66
Determine Why Code Replacement Functions Are Not
Used . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22-68
xxx Contents
Matrix Multiplication Operation to MathWorks BLAS
Code Replacement . . . . . . . . . . . . . . . . . . . . . . . . . . 22-101
xxxi
Performance
Configuration
23
Configure Code Optimizations . . . . . . . . . . . . . . . . . . . . 23-2
xxxii Contents
Data Type Replacement Support . . . . . . . . . . . . . . . . 24-19
xxxiii
Execution Speed
27
Remove Initialization Code . . . . . . . . . . . . . . . . . . . . . . 27-2
Memory Usage
28
Optimize Generated Code Using Specified Minimum and
Maximum Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28-2
How to Configure Your Model . . . . . . . . . . . . . . . . . . . 28-2
How to Enable Optimization . . . . . . . . . . . . . . . . . . . . 28-3
Optimize Generated Code Using Specified Minimum and
Maximum Values . . . . . . . . . . . . . . . . . . . . . . . . . . 28-3
Limitations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28-6
Verification
Code Tracing
29
About Code Tracing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29-2
xxxiv Contents
Format of Traceability Tags . . . . . . . . . . . . . . . . . . . . . . 29-3
Examples of Tagged Code . . . . . . . . . . . . . . . . . . . . . . 29-3
Component Verification
30
Component Verification in the Target Environment . . 30-2
xxxv
Numerical Equivalence Checking
32
About SIL and PIL Simulations . . . . . . . . . . . . . . . . . . . 32-2
What are SIL and PIL Simulations? . . . . . . . . . . . . . . 32-2
Why Use SIL and PIL . . . . . . . . . . . . . . . . . . . . . . . . . 32-3
How SIL and PIL Simulations Work . . . . . . . . . . . . . . 32-4
Comparison of SIL and PIL Simulation . . . . . . . . . . . . 32-5
xxxvi Contents
PIL Customization for Target Environment . . . . . . . . 32-32
Target Connectivity Configurations for PIL . . . . . . . . 32-32
Target Connectivity API Components . . . . . . . . . . . . 32-32
Communications rtiostream API . . . . . . . . . . . . . . 32-33
xxxvii
Software-in-the-Loop Execution Through Project
Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33-4
Code Coverage
34
Code Coverage in SIL and PIL Simulations . . . . . . . . . 34-2
xxxviii Contents
View Code Coverage Information at the End of SIL or
PIL Simulations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34-5
xxxix
Project and Build Configurations for Embedded
Targets
36
Model Setup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36-2
Block Selection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36-2
Configure Target Hardware Resources . . . . . . . . . . . . 36-3
Configuration Parameters . . . . . . . . . . . . . . . . . . . . . . 36-5
Model Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36-12
xl Contents
Perform Execution Time Profiling for IDE and Toolchain
Targets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37-22
Execution Profiling During Standalone Execution . . . 37-22
Execution Profiling During PIL Simulation . . . . . . . . 37-25
xli
Constructing ticcs Objects . . . . . . . . . . . . . . . . . . . . . 39-42
ticcs Properties and Property Values . . . . . . . . . . . . . 39-43
Overloaded Functions for ticcs Objects . . . . . . . . . . . 39-43
ticcs Object Properties . . . . . . . . . . . . . . . . . . . . . . . . 39-44
Function List . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39-50
xlii Contents
PostCodeGenCommand Commands Do Not Apply to IDE
Projects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39-86
xliii
Reported Limitations and Tips . . . . . . . . . . . . . . . . . . 40-11
Example Programs Do Not Run well with Incorrect GEL
Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40-11
PostCodeGenCommand Commands Do Not Apply to IDE
Projects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40-11
xliv Contents
Generating Code from the Model . . . . . . . . . . . . . . . . 41-26
xlv
Placing Additional Code or Data on Unused Flash
Sectors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41-91
xlvi Contents
Code Replacement for MATLAB Code
43
What Is Code Replacement? . . . . . . . . . . . . . . . . . . . . . . 43-2
xlvii
xlviii
Model Architecture and Design
1
Modeling Environment
1 Modeling Environment
The following table guides you to information and examples that pertain to use of the
Embedded Coder® product to meet goals for specific domains.
1-2
2
Application Objectives
The first step in applying Embedded Coder configuration options to the application
development process is to consider how your application objectives, particularly with
respect to efficiency, traceability, and safety, map to code generation options in a model
configuration set.
Parameters that you set in the Solver, Data Import/Export, Diagnostics, and Code
Generation panes of the Configuration Parameters dialog box affect the behavior of a
model in simulation and the code generated for the model.
1 Define your objectives in the configuration set. For more information, see “High-
Level Code Generation Objectives” on page 13-3.
2 Use the Code Generation Advisor to identify parameter values that are not
configured for the objectives that you selected. For more information, see “Determine
Model Configuration for Specified Objectives” on page 13-5.
2-2
3
If your application has mission-critical development and certification goals, your models
or subsystems and the code generated for them might need to comply with one or more of
the standards and guidelines listed in the following table.
3-2
What Are the Standards and Guidelines?
a. MISRA® and MISRA C are registered trademarks of MISRA Ltd., held on behalf of the MISRA Consortium.
3-3
3 Guidelines and Standards
MAAB Guidelines
The MathWorks Automotive Advisory Board (MAAB) involves major automotive OEMs
and suppliers in the process of evolving MathWorks controls, simulation, and code
generation products, including Simulink, Stateflow, and Simulink Coder. An important
result of the MAAB has been the “MAAB Control Algorithm Modeling” guidelines.
If you have a Simulink Verification and Validation product license, you can check that
your Simulink model or subsystem, and the code that you generate from it, complies
with MAAB guidelines. To check your model or subsystem, open the “Simulink Model
Advisor”. Navigate to By Product > Simulink Verification and Validation >
Modeling Standards > MathWorks Automotive Advisory Board Checks and run
the “MathWorks Automotive Advisory Board checks”.
For more information on using the Model Advisor, see “Run Model Checks” in the
Simulink documentation.
3-4
MISRA C Guidelines
MISRA C Guidelines
The Motor Industry Software Reliability Association (MISRA2) has established
“Guidelines for the Use of the C Language in Critical Systems” (MISRA C). For general
information about MISRA C, see www.misra-c.com.
In 1998, MIRA Ltd. published MISRA C (MISRA C:1998) to provide a restricted subset
of a standardized, structured language that met Safety Integrity Level (SIL) 2 and
higher. A major update based on feedback was published in 2004 (MISRA C:2004),
followed by a minor update in 2007 known as Technical Corrigendum (TC1). In 2007,
MISRA also published the MISRA AC AGC standard, “MISRA AC AGC: Guidelines
for the Application of MISRA-C:2004 in the Context of Automatic Code Generation.”
MISRA AC AGC does not change MISRA C:2004 rules, rather it modifies the adherence
recommendation. For more information about MISRA C, see www.misra-c.com.
Embedded Coder and Simulink offer capabilities to minimize the potential for MISRA C
rule violations, especially rules deemed applicable by MISRA AC AGC.
To configure a model or subsystem so that the code generator is most likely to produce
MISRA C:2004 compliant code, use the Code Generation Advisor. For more information,
refer to:
The “ Model Advisor” also checks that you developed your model or subsystem to increase
the likelihood of generating MISRA C:2004 compliant code. To check your model or
subsystem:
For more information about using the Model Advisor, see “Run Model Checks” in the
Simulink documentation.
2. MISRA and MISRA C are registered trademarks of MIRA Ltd., held on behalf of the MISRA Consortium.
3-5
3 Guidelines and Standards
For information about using Embedded Coder software within MISRA C guidelines, see
Technical Solution 1-1IFP0W on the MathWorks Web site.
3-6
IEC 61508 Standard
In this section...
“Apply Simulink and Embedded Coder to the IEC 61508 Standard” on page 3-7
“Check for IEC 61508 Standard Compliance Using the Model Advisor” on page 3-7
“Validate Traceability” on page 3-8
MathWorks provides an IEC Certification Kit product that you can use to certify
MathWorks code generation and verification tools for projects based on the IEC 61508
standard. For more information, see http://www.mathworks.com/products/iec-61508/.
Check for IEC 61508 Standard Compliance Using the Model Advisor
If you have a Simulink Verification and Validation product license, you can check that
your Simulink model or subsystem and the code that you generate from it complies with
selected aspects of the IEC 61508 standard by running the “Simulink Model Advisor”.
Navigate to By Product > Simulink Verification and Validation > Modeling
Standards > IEC 61508, ISO 26262, and EN 50128 Checks or By Task > Modeling
Standards for IEC 61508 and run the “IEC 61508, ISO 26262, and EN 50128 Checks”.
For more information on using the Model Advisor, see “Run Model Checks” in the
Simulink documentation.
3-7
3 Guidelines and Standards
Validate Traceability
Typically, applications that require certification require some level of traceability
between requirements, models, and corresponding code.
To... Use...
Associate requirements documents The “Requirements Traceability” that is
with objects in Simulink models available if you have a Simulink Verification and
Validation license.
Trace model blocks and subsystems to The “Model-to-code traceability option” when
generated code generating an HTML report during the code
generation or build process.
Trace generated code to model blocks The “Code-to-model traceability option” when
and subsystems generating an HTML report during the code
generation or build process.
3-8
ISO 26262 Standard
MathWorks provides an IEC Certification Kit product that you can use to qualify
MathWorks code generation and verification tools for projects based on the ISO 26262
standard. For more information, see http://www.mathworks.com/products/iso–26262/.
Check for ISO 26262 Standard Compliance Using the Model Advisor
If you have a Simulink Verification and Validation product license, you can check that
your Simulink model or subsystem and the code that you generate from it complies with
selected aspects of the ISO 26262 standard by running the “Simulink Model Advisor”.
Navigate to By Product > Simulink Verification and Validation > Modeling
Standards > IEC 61508, ISO 26262, and EN 50128 Checks or By Task > Modeling
Standards for ISO 26262 and run the “IEC 61508, ISO 26262, and EN 50128 Checks”.
For more information on using the Model Advisor, see “Run Model Checks” in the
Simulink documentation.
Validate Traceability
Typically, applications that require certification require some level of traceability
between requirements, models, and corresponding code.
To... Use...
Associate requirements documents The “Requirements Traceability” that is
with objects in Simulink models available if you have a Simulink Verification and
Validation license.
3-9
3 Guidelines and Standards
To... Use...
Trace model blocks and subsystems to The “Model-to-code traceability option” when
generated code generating an HTML report during the code
generation or build process.
Trace generated code to model blocks The “Code-to-model traceability option” when
and subsystems generating an HTML report during the code
generation or build process.
3-10
EN 50128 Standard
EN 50128 Standard
In this section...
“Apply Simulink and Embedded Coder to the EN 50128 Standard” on page 3-11
“Check for EN 50128 Standard Compliance Using the Model Advisor” on page 3-11
“Validate Traceability” on page 3-8
MathWorks provides an IEC Certification Kit product that you can use to certify
MathWorks code generation and verification tools for projects based on the EN 50128
standard. For more information, see http://www.mathworks.com/products/iec-61508/.
For more information on using the Model Advisor, see “Run Model Checks” in the
Simulink documentation.
Validate Traceability
Typically, applications that require certification require some level of traceability
between requirements, models, and corresponding code.
To... Use...
Associate requirements documents The “Requirements Traceability” that is
with objects in Simulink models available if you have a Simulink Verification and
Validation license.
3-11
3 Guidelines and Standards
To... Use...
Trace model blocks and subsystems to The “Model-to-code traceability option” when
generated code generating an HTML report during the code
generation or build process.
Trace generated code to model blocks The “Code-to-model traceability option” when
and subsystems generating an HTML report during the code
generation or build process.
3-12
DO-178C Standard
DO-178C Standard
In this section...
“Apply Simulink and Embedded Coder to the DO-178C Standard” on page 3-13
“Check for Standard Compliance Using the Model Advisor” on page 3-13
“Validate Traceability” on page 3-8
For information about Model-Based Design and MathWorks support of aerospace and
defense industry standards, see http://www.mathworks.com/aerospace-defense/ .
For more information on using the Model Advisor, see “Run Model Checks” in the
Simulink documentation.
Validate Traceability
Typically, applications that require certification require some level of traceability
between requirements, models, and corresponding code.
3-13
3 Guidelines and Standards
To... Use...
Associate requirements documents The “Requirements Traceability” that is
with objects in Simulink models available if you have a Simulink Verification and
Validation license.
Trace model blocks and subsystems to The “Model-to-code traceability option” when
generated code generating an HTML report during the code
generation or build process.
Trace generated code to model blocks The “Code-to-model traceability option” when
and subsystems generating an HTML report during the code
generation or build process.
3-14
4
4-2
About Modeling Patterns
Input ports are named to reflect the signal names that they propagate.
4-3
4 Patterns for C Code
Configure a Signal
1 Create a model in Simulink. For more information, see “Modeling Basics”.
2 Right-click a signal line. Select Properties. For more information about the Signal
Properties dialog box, see “Signal Properties”.
3 Enter a signal name for the Signal name parameter.
4 On the same Signal Properties dialog box, select the Code Generation tab. Use
the drop down menu for the Storage class parameter to specify a storage class.
Examples in this chapter use Exported Global.
Note: Alternatively, on the Signal Properties dialog box, select Signal name must
resolve to Simulink signal object. Then create a signal data object in the base
workspace with the same name as the signal. See “Create Simulink and mpt Data
Objects” for more information on creating data objects in the base workspace.
(Examples use mpt.Signal and specify the Storage class as ExportedGlobal.
4-4
Prepare a Model for Code Generation
Initialize States
1 Double-click a block.
2 In the Block Parameters dialog box, select the Main tab.
3 Specify the Initial conditions and Sample time. For more information, see “
Specify Sample Time”.
4 Select the State Attributes pane. Specify the state name. See “States”.
5 You can also use the Data Object Wizard for creating data objects. A part of this
process initializes states. See “Create Data Objects with Data Object Wizard”.
4-5
4 Patterns for C Code
Follow this general procedure to create a simple model containing a Stateflow chart.
1 From the Stateflow > Chart library, add a Stateflow chart to your model .
2 Add Inport blocks and Outport blocks according to the example model.
3 Open the Stateflow Editor by performing one of the following:
4-6
Prepare a Model for Code Generation
1 Add the number of Inport and Outport blocks according to a C construct example
included in this chapter.
2 From the Simulink User-defined Functions library drag a MATLAB Function block
into the model.
3 Double-click the block. The MATLAB Function Block Editor opens. Edit the function
to implement your application.
4 Click File > Save and close the MATLAB Function Block Editor.
5 Connect the Inport and Outport blocks to the MATLAB Function block. See
“Configure a Signal” on page 4-4.
6 Save your model.
4-7
4 Patterns for C Code
Data Declaration
C Construct
int32 p1 = 3;
Block Parameter
Constant Value
Gain Value
For Iterator Iteration Limit
• For a model with many parameters, use the Data Object Wizard, which analyzes
your model and finds the unresolved data objects and data types. You can then create
the data objects in the Data Object Wizard. The procedure for using the Data Object
Wizard for a parameter is similar to the procedure for a signal. For an example, see
“Declare a Variable for a Signal using a Data Object” on page 4-10.
• To add, delete, edit, and configure data objects, use the base workspace in the Model
Explorer.
• To create and configure data objects, use the MATLAB command line.
The following example demonstrates how to create a data object using the Model
Explorer. The declaration statement in the generated code is as follows:
int Kp = 3;
4-8
Data Declaration
int32 p1 = 3;
int32 p2 = 5;
Note: Depending on the storage class, the global variable is represented differently in the
generated code. For more information, see “Parameter Objects”.
C Construct
int p1 = 3;
4-9
4 Patterns for C Code
Note: The Storage class alters the data object implementation in the generated code.
For more information, see “Signal Objects”.
4-10
Data Type Conversion
Modeling Patterns
• “Modeling Pattern for Data Type Conversion — Simulink Block” on page 4-11
• “Modeling Pattern for Data Type Conversion — Stateflow Chart” on page 4-12
• “Modeling Pattern for Data Type Conversion — MATLAB Function Block” on page
4-12
ex_data_type_SL
1 From the Commonly Used Blocks library, drag a Data Type Conversion block into
your model and connect to the Inport and Outport blocks.
2 Double-click on the Data Type Conversion block to open the Block Parameters dialog
box.
3 Select the Output data type parameter as double.
4 Press Ctrl+B to build the model and generate code.
void ex_data_type_SL_step(void)
{
y1 = (real_T)u1;
4-11
4 Patterns for C Code
}
The Embedded Coder type definition for double is real_T.
Procedure
1 Follow the steps for “Set Up an Example Model With a Stateflow Chart” on page 4-6 .
This example contains one Inport block and one Outport block.
2 Name the example model ex_data_type_SF.
3 Double-click the Inport block and select the Signal Attributes tab. Specify the
Data Type as int32 from the drop down menu.
4 Double-click the Outport block and select the Signal Attributes tab. Specify the
Data Type as Inherit: auto from the drop down menu.
5 Press Ctrl+B to build the model and generate code.
Results
1 Follow the steps for “Set Up an Example Model With a MATLAB Function Block” on
page 4-7 . This example model contains one Inport block and one Outport block.
4-12
Data Type Conversion
Results
void ex_data_type_ML_func_step(void)
{
y1 = u1;
}
4-13
4 Patterns for C Code
Type Qualifiers
ex_type_qual
Procedure
4-14
Type Qualifiers
Results
Procedure
1 Press Ctrl+H to open the Model Explorer. On the Model Hierarchy pane, select the
base workspace.
2 Select Add > Add Custom to add an mpt parameter object. The parameter is
displayed in the Contents of: Base Workspace pane.
3 Double-click the mpt.Parameter object and change the Name to p1.
4 Click the p1 parameter which displays the data object parameters on the right pane
of the Model Explorer.
5 In the Value field, enter 9.8 for p1. Specify the Data type as auto for 64–bit
double.
6 You can use the different type qualifiers by selecting a custom storage class from the
Storage class list. For this example, select ConstVolatile (custom).
7 In the Configuration Parameters dialog box, on the Optimization > Signals and
Parameters pane, select the Inline parameters.
8 Press Ctrl+B to build the model and generate code.
Results
4-15
4 Patterns for C Code
ex_logical_SL
Procedure
1 From the Logic and Bit Operations library, drag a Logical Operator block into
your model.
2 Double-click the block to configure the logical operation. Set the Operator field to
OR.
3 Name the blocks, as shown in the model ex_logical_SL.
4 Connect the blocks and name the signals, as shown in the model ex_logical_SL.
5 Press Ctrl+B to build the model and generate code.
Note: You can use the above procedure to implement relational operators by replacing
the Logical Operator block with a Relational Operator block.
4-16
Relational and Logical Operators
Results
Procedure
1 Follow the steps for “Set Up an Example Model With a Stateflow Chart” on page 4-6.
This example model contains two Inport blocks and one Outport block.
2 Name the example model ex_logical_SF.
3 In the Stateflow Editor, specify the Data Type for y1 as Boolean.
4 In the Stateflow Editor, create the Stateflow diagram as shown. The relational
or logical operation actions are on the transition from one junction to another.
Relational statements specify conditions to conditionally allow a transition. In that
case, the statement would be within square brackets.
5 Press Ctrl+B to build the model and generate code.
4-17
4 Patterns for C Code
Results
void ex_logical_SF_step(void)
{
y1 = (u1 || u2);
}
Procedure
1 Follow the steps for “Set Up an Example Model With a MATLAB Function Block” on
page 4-7 . This example model contains two Inport blocks and one Outport block.
2 Name the example model ex_rel_operator_ML.
3 In the MATLAB Function Block Editor enter the function, as follows:
function y1 = fcn(u1, u2)
y1 = u1 > u2;
end
4 Press Ctrl+B to build the model and generate code.
Results
void ex_rel_operator_ML_step(void)
4-18
Relational and Logical Operators
{
y = (u1 > u2);
}
4-19
4 Patterns for C Code
Bitwise Operations
ex_bit_logic_SL
Procedure
1 Drag a Bitwise Operator block from the Logic and Bit Operations library into
your model.
2 Double-click the block to open the Block Parameters dialog.
3 Select the type of Operator. In this example, select AND.
4 In order to perform Bitwise operations with a bit-mask, select Use bit mask.
Note: If another input uses Bitwise operations, clear the Use bit mask parameter
and enter the number of input ports.
5 In the Bit Mask field, enter a decimal number. Use bin2dec or hex2dec to convert
from binary or hexadecimal. In this example, enter hex2dec('D9').
6 Name the blocks, as shown in, model ex_bit_logic_SL.
7 Connect the blocks and name the signals, as shown in, model ex_bit_logic_SL.
8 Press Ctrl+B to build the model and generate code.
Results
uint8_T u1;
4-20
Bitwise Operations
uint8_T y1;
void ex_bit_logic_SL_step(void)
{
y1 = (uint8_T)(u1 & 217);
}
Stateflow Chart
Procedure
1 Follow the steps for “Set Up an Example Model With a Stateflow Chart” on page 4-6.
This example contains one Inport block and one Outport block.
2 Name the example model ex_bit_logic_SF.
3 From the Stateflow Editor, select Tools > Explore to open the Model Explorer.
4 In the Model Explorer, on the right pane, select Enable C-bit operations.
5 In the Stateflow Editor, create the Stateflow diagram, ex_bit_logic_SF/
Bit_Logic.
6 Press Ctrl+B to build the model and generate code.
Results
void bit_logic_SF_step(void)
{
y1 = (uint8_T)(u1 & 0xD9);
4-21
4 Patterns for C Code
Procedure
1 Follow the steps for “Set Up an Example Model With a MATLAB Function Block” on
page 4-7. This example model contains two Inport blocks and one Outport block.
2 Name your model ex_bit_logic_ML.
3 In the MATLAB Function Block Editor enter the function, as follows:
function y1 = fcn(u1, u2)
y1 = bitor(u1, u2);
end
4 Press Ctrl+B to build the model and generate code.
Results
uint8_T u1;
uint8_T u2;
uint8_T y1;
void ex_bit_logic_ML_step(void)
{
y1 = (uint8_T)(u1 | u2);
}
4-22
If-Else
If-Else
C Construct
if (u1 > u2)
{
y1 = u1;
}
else
{
y1 = u2;
}
Modeling Patterns
• “Modeling Pattern for If-Else: Switch block” on page 4-23
• “Modeling Pattern for If-Else: Stateflow Chart” on page 4-25
• “Modeling Pattern for If-Else: MATLAB Function Block” on page 4-26
Model ex_if_else_SL
4-23
4 Patterns for C Code
Procedure
1 Drag the Switch block from the Simulink>Signal Routing library into your model.
2 Connect the data inputs and outputs to the block.
3 Drag a Relational Operator block from the Logic & Bit Operations library into your
model.
4 Connect the signals that are used in the if-expression to the Relational Operator
block. The order of connection determines the placement of each signal in the if-
expression.
5 Configure the Relational Operator block to be a greater than operator.
6 Connect the controlling input to the middle input port of the Switch block.
7 Double-click the Switch block and set Criteria for passing first input to u2~=0.
The software selects u1 if u2 is TRUE; otherwise u2 passes.
8 Enter Ctrl+B to build the model and generate code.
Results
The generated code includes the following ex_if_else_SL_step function in the file
ex_if_else_SL.c:
/* External inputs (root inport signals with auto storage) */
ExternalInputs U;
4-24
If-Else
ex_if_else_SF/Chart
Procedure
1 Follow the steps for “Set Up an Example Model With a Stateflow Chart” on page 4-6.
This example model contains two Inport blocks and one Outport block.
2 Name your model ex_if_else_SF.
3 When configuring your Stateflow chart, select Chart > Add Patterns > Decision >
If-Else. The Stateflow Pattern dialog opens. Fill in the fields as follows:
Results
The generated code includes the following ex_if_else_SF_step function in the file
If_Else_SF.c:
/* External inputs (root inport signals with auto storage) */
ExternalInputs U;
4-25
4 Patterns for C Code
void ex_if_else_SF_step(void)
{
/* Stateflow: '<Root>/Chart' incorporates:
* Inport: '<Root>/u1'
* Inport: '<Root>/u2'
* Outport: '<Root>/y1'
*/
/* Gateway: Chart */
/* During: Chart */
/* Transition: '<S1>:14' */
/* If-Else */
if (U.u1 > U.u2) {
/* Transition: '<S1>:13' */
/* Transition: '<S1>:12' */
Y.y1 = U.u1;
/* Transition: '<S1>:11' */
} else {
/* Transition: '<S1>:10' */
Y.y1 = U.u2;
}
/* Transition: '<S1>:9' */
}
1 Follow the steps for “Set Up an Example Model With a MATLAB Function Block” on
page 4-7. This example model contains two Inport blocks and one Outport block.
2 Name your model ex_if_else_ML.
3 In the MATLAB Function Block Editor enter the function, as follows:
function y1 = fcn(u1, u2)
if u1 > u2;
y1 = u1;
else y1 = u2;
end
4 Press Ctrl+B to build the model and generate code.
Results
The generated code includes the following ex_if_else_ML_step function in the file
ex_if_else_ML.c:
/* External inputs (root inport signals with auto storage) */
ExternalInputs U;
4-26
If-Else
4-27
4 Patterns for C Code
Switch
C Construct
switch (u1)
{
case 2:
y1 = u2;
break;
case 3:
y1 = u3;
break;
default:
y1 = u4;
break;
}
Modeling Patterns
• “Modeling Pattern for Switch: Switch Case block” on page 4-28
• “Modeling Pattern for Switch: MATLAB Function block” on page 4-31
• “Convert If-Elseif-Else to Switch statement” on page 4-32
4-28
Switch
Model ex_switch_SL
Procedure
1 Drag a Switch Case block from the Simulink > Ports and Subsystems library into
your model.
2 Double-click the block. In the Block Parameters dialog box, fill in the Case
Conditions parameter. In this example, the two cases are: {2,3}.
3 Select the Show default case parameter. The default case is optional in a switch
statement.
4 Connect the condition input u1 to the input port of the Switch block.
5 Drag Switch Case Action Subsystem blocks from the Simulink>Ports and
Subsystems library to correspond with the number of cases.
6 Configure the “Switch Case Action Subsystem” subsystems.
7 Drag a Merge block from the Simulink > Signal Routing library to merge the
outputs.
8 The Switch Case block takes an integer input, therefore, the input signal u1 is type
cast to an int32.
4-29
4 Patterns for C Code
Results
The generated code includes the following ex_switch_SL_step function in the file
ex_switch_SL.c:
/* Exported block signals */
int32_T u1; /* '<Root>/u1' */
case 3:
/* Inport: '<S2>/u3' incorporates:
* Inport: '<Root>/u3'
* Outport: '<Root>/y1'
*/
Y.y1 = U.u3;
break;
default:
/* Inport: '<S3>/u4' incorporates:
* Inport: '<Root>/u4'
* Outport: '<Root>/y1'
*/
Y.y1 = U.u4;
break;
}
}
4-30
Switch
1 Follow the steps for “Set Up an Example Model With a MATLAB Function Block” on
page 4-7. This example model contains four Inport blocks and one Outport block.
2 Name your model ex_switch_ML.
3 In the MATLAB Function Block Editor enter the function, as follows:
function y1 = fcn(u1, u2, u3, u4)
switch u1
case 2
y1 = u2;
case 3
y1 = u3;
otherwise
y1 = u4;
end
4 Press Ctrl+B to build the model and generate code.
Results
The generated code includes the following ex_switch_ML_step function in the file
ex_switch_ML.c:
/* External inputs (root inport signals with auto storage) */
ExternalInputs U;
4-31
4 Patterns for C Code
case 3:
/* '<S1>:1:8' */
Y.y1 = U.u3;
break;
default:
/* '<S1>:1:10' */
Y.y1 = U.u4;
break;
}
}
4-32
For Loop
For Loop
C Construct
y1 = 0;
for(inx = 0; inx <10; inx++)
{
y1 = u1[inx] + y1;
}
Modeling Patterns:
• “Modeling Pattern for For Loop: For-Iterator Subsystem block” on page 4-33
• “Modeling Pattern for For Loop: Stateflow Chart” on page 4-36
• “Modeling Pattern for For Loop: MATLAB Function block” on page 4-37
Model ex_for_loop_SL
4-33
4 Patterns for C Code
Procedure
1 Drag a “For Iterator Subsystem” block from the Simulink > Ports and
Subsystems library into your model.
2 Connect the data inputs and outputs to the For Iterator Subsystem block.
3 Open the Inport block.
4 In the Block Parameters dialog box, select the Signal Attributes pane and set the
Port dimensions parameter to 10.
5 Double-click the For Iterator Subsystem block to open the subsystem.
6 Drag an Index Vector block from the Signal-Routing library into the subsystem.
7 Open the For Iterator block. In the Block Parameters dialog box set the Index-mode
parameter to Zero-based and the Iteration limit parameter to 10.
8 Connect the controlling input to the topmost input port of the Index Vector block,
and the other input to the second port.
9 Drag an Add block from the Math Operations library into the subsystem.
10 Drag a Unit Delay block from Commonly Used Blocks library into the subsystem.
11 Double-click the Unit Delay block and set the Initial Conditions parameter to 0.
This parameter initializes the state to zero.
12 Connect the blocks as shown in the model diagram.
13 Save the subsystem and the model.
4-34
For Loop
Results
The generated code includes the following ex_for_loop_SL_step function in the file
ex_for_loop_SL.c:
/* External inputs (root inport signals with auto storage) */
ExternalInputs U;
/* Outport: '<Root>/y1' */
Y.y1 = rtb_y1;
}
4-35
4 Patterns for C Code
Procedure
1 Follow the steps for “Set Up an Example Model With a Stateflow Chart” on page 4-6.
This example model contains one Inport block and one Outport block.
2 Name the model ex_for_loop_SF.
3 Enter Ctrl+R to open the Model Explorer.
4 In the Model Explorer, select the output variable, u1, and in the right pane, select
the General tab and set the Initial Value to 0.
5 In the Stateflow Editor, select Chart > Add Patterns > Loop > For. The
Stateflow Pattern dialog opens.
6 Fill in the fields in the Stateflow Pattern dialog box as follows:
4-36
For Loop
Results
The generated code includes the following ex_for_loop_SF_step function in the file
ex_for_loop_SF.c:
/* Block signals (auto storage) */
BlockIO B;
/* Transition: '<S1>:21' */
}
/* Transition: '<S1>:20' */
/* Outport: '<Root>/y1' */
Y.y1 = B.y1;
}
1 Follow the directions for “Set Up an Example Model With a MATLAB Function
Block” on page 4-7. This example model contains one Inport block and one Outport
block.
2 Name your model ex_for_loop_ML.
3 In the MATLAB Function Block Editor enter the function, as follows:
function y1 = fcn(u1)
4-37
4 Patterns for C Code
y1 = 0;
for inx=1:10
y1 = u1(inx) + y1 ;
end
4 Press Ctrl+B to build the model and generate code.
Results
The generated code includes the following ex_for_loop_ML_step function in the file
ex_for_loop_ML.c:
/* Exported block signals */
real_T u1[10]; /* '<Root>/u1' */
real_T y1; /* '<Root>/MATLAB Function' */
4-38
While Loop
While Loop
C Construct
while(flag && (num_iter <= 100)
{
flag = func ();
num_iter ++;
}
Modeling Patterns
• “Modeling Pattern for While Loop: While Iterator Subsystem block” on page 4-39
• “Modeling Pattern for While Loop: Stateflow Chart” on page 4-42
• “Modeling Pattern for While Loop: MATLAB Function Block” on page 4-45
Model ex_while_loop_SL
4-39
4 Patterns for C Code
Procedure
1 Drag a While Iterator Subsystem block from the Simulink > Ports and
Subsystems library into the model.
2 Drag a Constant block from the Simulink > Commonly Used Blocks library
into the model. In this case, set the Initial Condition to 1 and the Data Type to
Boolean. You do not have to set the initial condition to FALSE. The initial condition
can be dependent on the input to the block.
3 Connect the Constant block to the While Iterator Subsystem block.
4 Double-click the While Iterator Subsystem block to open the subsystem.
5 Place a Subsystem block next to the While Iterator block.
6 Right-click the subsystem and select Block Parameters (Subsystem). The Block
Parameters dialog box opens.
7 Select the Treat as atomic unit parameter to configure the subsystem to generate
a function. This enables parameters on the Code Generation tab.
8 Select the Code Generation tab. From the Function packaging list, select the
option, Nonreusable function.
9 From the Function name options list, select the option, User specified. The
Function name parameter is displayed.
10 Specify the name as func.
11 Click Apply.
12 Double-click the func subsystem block. In this example, function func() has an
output flag set to 0 or 1 depending on the result of the algorithm in func( ). Create
the func() algorithm as shown in the following diagram:
4-40
While Loop
func
13 Double-click the While Iterator block to set the Maximum number of iterations to
100.
14 Connect blocks as shown in the model and subsystem diagrams.
Results
The generated code includes the following ex_while_loop_SL_step function in the file
ex_while_loop_SL.c:
/* Exported block signals */
boolean_T IC; /* '<Root>/Initial Condition SET to TRUE' */
boolean_T flag; /* '<S2>/Relational Operator' */
/* Start for atomic system: '<S1>/func( ) Is a function that updates the flag' */
void func_Start(void)
{
/* Start for RandomNumber: '<S2>/Random Number' */
DWork.RandSeed = 1144108930U;
DWork.NextOutput = rt_NormalRand(&DWork.RandSeed) * 1.7320508075688772E+000;
}
4-41
4 Patterns for C Code
void ex_while_loop_SL_step(void)
{
int32_T s1_iter;
boolean_T loopCond;
Model ex_while_loop_SF
4-42
While Loop
Procedure
1 Add a Stateflow Chart to your model from the Stateflow > Chart library.
2 Double-click the chart.
3 Add the input, flag, and output, func, to the chart and specify their data type.
4 Connect the data input and output to the Stateflow chart as shown in the model
diagram.
5 In the Model Explorer, select the output variable, then, in the right pane, select the
General tab and set the Initial Value to 0.
6 Select Chart > Add Patterns > Loop > While. The Stateflow Pattern dialog opens.
7 Fill in the fields for the Stateflow Pattern dialog box as follows:
4-43
4 Patterns for C Code
12 From the Function name options list, select the option, User specified. The
Function name parameter is displayed.
13 Specify the name as func.
14 Click Apply to apply the changes.
15 Double-click the func subsystem block. In this example, function func has an
output flag set to 0 or 1 depending on the result of the algorithm in func( ). The
Trigger block parameter Trigger type is function-call. Create the func()
algorithm, as shown in the following diagram:
Results
The generated code includes the following ex_while_loop_SF_step function in the file
ex_while_loop_SF.c:
/* Exported block signals */
int32_T num_iter; /* '<Root>/Chart Executes the desired while-loop' */
boolean_T flag; /* '<S2>/Relational Operator' */
4-44
While Loop
/* During: Chart
Executes the desired while-loop */
/* Transition: '<S1>:2' */
num_iter = 1;
while (flag && (num_iter <= 100)) {
/* Transition: '<S1>:3' */
/* Transition: '<S1>:4' */
/* Event: '<S1>:12' */
func();
num_iter = num_iter + 1;
/* Transition: '<S1>:5' */
}
/* Transition: '<S1>:1' */
}
Model ex_while_loop_ML
Procedure
1 In the Simulink Library Browser, click Simulink > User Defined Functions, and
drag a MATLAB Function block into your model.
2 Double-click the MATLAB Function block. The MATLAB Function Block Editor
opens.
3 In the MATLAB Function Block Editor enter the function, as follows:
function fcn(func_flag)
flag = true;
num_iter = 1;
4-45
4 Patterns for C Code
func;
flag = func_flag;
num_iter = num_iter + 1;
end
4 Click Save and close the MATLAB Function Block Editor.
5 Place a Subsystem block in your model, right-click the subsystem and select Block
Parameters (Subsystem). The Block Parameters dialog box opens.
6 Select the Treat as atomic unit parameter to configure the subsystem to generate
a function. This enables parameters on the Code Generation tab.
7 Select the Code Generation tab. From the Function packaging list, select the
option, Nonreusable function.
8 From the Function name options list, select the option, User specified. The
Function name parameter is displayed.
9 Specify the name as func.
10 Click Apply.
11 Double-click the func() subsystem block. In this example, function func() has
an output flag set to 0 or 1 depending on the result of the algorithm in func( ).
The Trigger block parameter Trigger type is function-call. Create the func()
algorithm, as shown in the following diagram:
Results
The generated code includes the following while_loop_ML_step function in the file
while_loop_EML.c. In some cases an equivalent for loop might be generated instead
of a while loop.
4-46
While Loop
/* '<S1>:1:4' */
num_iter = 1;
while (flag && (num_iter <= 100);
num_iter++) {
/* '<S1>:1:6' */
/* '<S1>:1:7' */
func();
/* '<S1>:1:8' */
flag = func_flag_0;
/* '<S1>:1:9' */
num_iter++;
}
}
4-47
4 Patterns for C Code
Do While Loop
C Construct
num_iter = 1;
do {
flag = func();
num_iter++;
}
while (flag && num_iter <= 100)
Modeling Patterns
• “Modeling Pattern for Do While Loop: While Iterator Subsystem block” on page
4-48
• “Modeling Pattern for Do While Loop: Stateflow Chart” on page 4-51
ex_do_while_loop_SL
4-48
Do While Loop
Procedure
1 Drag a While Iterator Subsystem block from the Simulink > Ports and
Subsystems library into the model.
2 Double-click the While Iterator Subsystem block to open the subsystem.
3 Place a Subsystem block next to the While Iterator block.
4 Right-click the subsystem and select Block Parameters (Subsystem). The Block
Parameters dialog box opens.
5 Select the Treat as atomic unit parameter to configure the subsystem to generate
a function. This enables parameters on the Code Generation tab.
6 Select the Code Generation tab. From the Function packaging list, select the
option, Nonreusable function.
7 From the Function name options list, select the option, User specified. The
Function name parameter is displayed.
8 Specify the name as func.
9 Click Apply.
10 Double-click the func subsystem block. In this example, function func has an
output flag set to 0 or 1 depending on the result of the algorithm in func. Create the
func algorithm as shown in the following diagram:
4-49
4 Patterns for C Code
Results
void func(void)
{
flag = (DWork.NextOutput > (real_T)P.Constant1_Value);
DWork.NextOutput =
rt_NormalRand(&DWork.RandSeed) * P.RandomNumber_StdDev +
P.RandomNumber_Mean;
}
void ex_do_while_loop_SL_step(void)
{
int32_T s1_iter;
s1_iter = 1;
do {
func();
s1_iter++;
} while (flag && (s1_iter <= 100));
4-50
Do While Loop
ex_do_while_loop_SF
ex_do_while_loop_SF/Chart
1 Add a Stateflow Chart to your model from the Stateflow > Chart library.
2 Double-click the chart to open it.
3 Add the inputs and outputs to the chart and specify their data type.
4 Connect the data input and output to the Stateflow chart.
5 In the Model Explorer, select the output variable, then, in the right pane, select the
General tab and set the Initial Value to 0.
4-51
4 Patterns for C Code
6 Select Chart > Add Patterns > Loop > While. The Stateflow Pattern dialog opens.
7 Fill in the fields for the Stateflow Pattern dialog box as follows:
4-52
Do While Loop
Results
void ex_do_while_loop_SF_step(void)
{
int32_T sf_num_iter;
num_iter = 1;
do {
func();
num_iter++;
} while (flag && (sf_num_iter <= 100));
4-53
4 Patterns for C Code
Function Call
To generate a function call, add a subsystem, which implements the operations that you
want.
C Construct
void add_function(void)
{
y1 = u1 + u2;
}
ex_function_call
Procedure
1 Create a model containing a subsystem. In this example, the subsystem has two
inputs and returns one output.
2 Double-click the subsystem. Create Add_Subsystem, as shown.
ex_function_call/Add_Subsystem
3 Right-click the subsystem and select Block Parameters (Subsystem) to open the
Subsystem Parameters dialog box.
4 Select the Treat as atomic unit parameter. This enables parameters on the Code
Generation tab.
4-54
Function Call
Select the Code Generation tab. For the Function packaging parameter, from
the drop-down list, select Nonreusable function.
5 For the Function name options parameter, from the drop-down list, select User
specified.
6 In the Function name field, enter the subsystem name, add_function.
7 Click Apply and OK.
8 Press Ctrl+B to build and generate code.
Results
In ex_function_call.c, the function is called from ex_function_call_step:
void ex_function_call_step(void)
{
add_function();
}
4-55
4 Patterns for C Code
Function Prototyping
C Construct
double add_function(double u1, double u2)
{
return u1 + u2;
}
Modeling Patterns
• “Function Call Using Graphical Functions” on page 4-56
• “Control Function Prototype of the model_step Function” on page 4-58
1 Follow the steps for “Set Up an Example Model With a Stateflow Chart” on page 4-6.
This example model contains two Inport blocks and one Outport block.
2 Name the example model ex_func_SF.
3
In the Stateflow Editor, create a graphical function by clicking the fx button and
placing a graphical function into the Stateflow chart.
4 Edit the graphical function signature to: output = add_function(u1, u2).
5 Add the transition action, as shown in the following diagram.
4-56
Function Prototyping
ex_func_SF/Chart
Results
ex_func_SF_Y.y1 = ex_func_SF_B.y1;
}
4-57
4 Patterns for C Code
ex_control_step_function
Procedure
Results
4-58
External C Functions
External C Functions
C Construct
#include "add.h"
double add(double u1, double u2)
{
double y1;
y1 = u1 + u2;
return (y1);
}
Modeling Patterns
There are several methods for integrating legacy C functions into the generated code.
These methods either create an S-function or make a call to an external C function. For
more information on S-functions, see “Insert S-Function Code”.
Procedure
1 Create a C header file named add.h that contains the function signature:
extern double add(double, double);
2 Create a C source file named add.c that contains the function body:
double add(double u1, double u2)
4-59
4 Patterns for C Code
{
double y1;
y1 = u1 + u2;
return (y1);
}
3 To build an S-function for use in both simulation and code generation, Run the
following script or execute each of these commands at the MATLAB command line:
4-60
External C Functions
ex_function_call_lct
5 Name and save your model. In this example, the model is named
ex_function_call_lct.
6 Press Ctrl+B to build the model and generate code.
Results
#include "add.h"
1 Create a C header file named add.h that contains the example function signature.
2 Create a C source file named add.c that contains the function body.
3 Follow the steps for “Set Up an Example Model With a Stateflow Chart” on page 4-6.
This example model contains two Inport blocks and one Outport block.
4 Name the example model ex_exfunction_call_SF.
5 Double-click the Stateflow chart and edit the chart as shown. Place the call to the
add function within a transition action.
4-61
4 Patterns for C Code
ex_exfunction_call_SF/Chart
6 On the Stateflow Editor, select Simulation > Model Configuration
Parameters.
7 On the Configuration Parameters dialog box, select Simulation Target > Custom
Code. In the Include custom C code in generated section, on the left pane, select
Header file and in the Header file field, enter the #include statement:
#include "add.h"
8 In the Include list of additional section, select Source files and in the Source
files field, enter add.c.
9 Press Ctrl+B to build the model and generate code.
Results
void exfunction_call_SF_step(void)
{
y1 = (real_T)add(u1, u2);
}
1 Create a C header file named add.h that contains the example function signature.
4-62
External C Functions
2 Create a C source file named add.c that contains the function body.
3 In the Simulink Library Browser, click Simulink > User Defined Functions, and
drag a MATLAB Function block into your model.
4 Double-click the MATLAB Function block. The MATLAB Function Block Editor
opens.
5 Edit the function to include the statement:
end
6 Open the Configuration Parameters dialog box, and select Simulation Target >
Custom Code.
7 In the Include custom C code in generated section, on the left pane, select
Header file and in the Header file field, enter the statement, :
#include "add.h"
8 In the Include list of additional section, select Source files and in the Source
files field, enter add.c.
9 Add two Inport blocks and one Outport block to the model and connect to the
MATLAB Function block.
10 Configure the signals: u1, u2, and y1, as described in “Configure a Signal” on page
4-4.
11 Save the model as ex_exfunction_call_ML.
12 Press Ctrl+B to build the model and generate code.
Results
void ex_exfunction_call_ML_step(void)
{
4-63
4 Patterns for C Code
y1 = add(u1, u2);
}
4-64
Macro Definitions (#define)
C Construct
#define p_1 9.8;
Modeling Patterns
“Use a 'Define' Custom Storage Class” on page 4-65
3 In the Configuration Parameter dialog box, on the Optimization > Signals and
Parameters pane, select Inline parameters.
4 Click Apply and OK.
5 In your model, double-click the Gain block. The Block Parameters dialog box opens.
6 In the Value field, enter a variable name. In this example, the variable name is p1.
7 Press Ctrl+H to open the Model Explorer. On the Model Hierarchy pane, select the
Base Workspace.
8 To add an mpt parameter object, in the menu bar, select Add > Add Custom. The
parameter appears in the Contents of: Base Workspace pane.
9 Double-click the mpt.Parameter object and change its name to p1.
10 Click the p1 parameter. The data object parameters are displayed in the right pane
of the Model Explorer.
4-65
4 Patterns for C Code
11 In the Value field, enter 9.8. In the Code generation options section, click the
Storage Class drop-down list and select Define(Custom).
12 Press Ctrl+B to generate code.
Results
1 Follow steps 1 through 10 of “Use a 'Define' Custom Storage Class” on page 4-65.
2 In the Simulink.Parameter dialog box for p1, in the Value field, enter 9.8. In the
Code generation options section, click the Storage Class drop-down list and
select ImportFromFile(Custom).
3 In the Header file parameter, enter the name of the header file, in this example,
external_params.h.
4 Click Apply and OK.
5 Create the C header file, external_params.h that contains the #define
statement:
#ifndef _EXTERNAL_PARAMS
#define _EXTERNAL_PARAMS
#define p1 9.8
#endif
/* EOF */
Results
4-66
Macro Definitions (#define)
ex_define_data_object_Y.Out1 = p1 * ex_define_data_object_U.In1;
4-67
4 Patterns for C Code
4-68
Typedef
Typedef
To generate a typedef definition, use a Simulink.AliasType data object.
C Construct
typedef double float_64;
Procedure
1 Create the ex_get_typedef model with a Gain block.
2 In the Gain block parameter dialog box, select the Parameter Attributes tab, and
specify the Parameter data type as double.
3 Right-click the u1 signal and select Properties. In the Signal Properties dialog box,
select Signal name must resolve to Simulink signal object.
4 Right-click the y1 signal and select Properties. In the Signal Properties dialog
box, select the Code Generation tab, and specify the Storage class parameter as
ExportedGlobal.
5 Create a new alias type by using a “Simulink.AliasType” data object. At the
MATLAB command line, enter:
float_64 = Simulink.AliasType;
6 In the base workspace, double-click float_64. The Simulink.AliasType dialog box
opens.
7 Specify the Base type parameter as double. Click Apply and OK.
8 Create a data object for the u1 signal. In the base workspace, select Add >
Simulink Signal, and name it u1. Specify the Data type parameter as float_64
and the Storage class parameter as Global(custom).
Note: You can also specify an output data type for Simulink blocks using the new
alias type.
9 Click Apply and OK.
4-69
4 Patterns for C Code
Note: An alternative method for defining a typedef is to import the alias type from a
custom header file. If you want to import all of the typedefs from a C header file, using
this alternative method is useful.
Results
The generated code includes the typedef definition, which is declared within #ifndef
and #endif statements in the ex_get_typedef_types.h file.
#ifndef _DEFINED_TYPEDEF_FOR_float_64_
#define _DEFINED_TYPEDEF_FOR_float_64_
#endif
The generated code also includes the declaration of the Simulink data objects of the alias
type in ex_get_typedef.c.
float_64 y1;
float_64 u1;
4-70
Structures for Parameters
C Construct
typdef struct {
double p1;
double p2;
double p3;
} my_struct_type;
my_struct_type my_struct={1.0,2.0,3.0};
Procedure
1 Create the ex_struct_param model with three Constant blocks and three Outport
blocks.
2 Create a data object for each parameter, p1, p2, and p3. At the MATLAB command
line, enter:
p1 = mpt.Parameter;
p2 = mpt.Parameter;
p3 = mpt.Parameter;
3 In the base workspace, double-click one of the parameter data objects to open the
mpt.Parameter dialog box.
4 Specify a Value parameter for each parameter object.
5 Specify the Storage class parameter as Struct (Custom) for each parameter
object.
4-71
4 Patterns for C Code
6 In the Custom Attributes section, specify the Struct name as my_struct. Click
Apply and OK.
7 Press Ctrl+E to open the Configuration Parameters dialog box.
8 Open the Optimization > Signals and Parameters pane, and select the Inline
parameters parameter.
9 Click Apply and OK.
10 Press Ctrl+B to generate code.
Results
The generated code includes the typedef definition for a structure, which is declared in
the ex_struct_param_types.h file.
/* Type definition for custom storage class: Struct */
typedef struct my_struct_tag {
real_T p1;
real_T p2;
real_T p3;
} my_struct_type;
/* p2 */
2.0,
/* p3 */
3.0
};
4-72
Structures for Signals
C Construct
typedef struct {
double u1;
double u2;
double u3;
} my_signals;
Modeling Patterns
“Structure for Signals Using a 'Struct' Custom Storage Class” on page 4-73
“Structure for Signals Using a Simulink Non-Virtual Bus Object” on page 4-74
1 Create the ex_signal_struct_csc model using the blocks shown and follow the
steps to configure the signals and model.
2 Double-click a Gain block to open the block parameter dialog box. Set the values of
the Gain blocks as shown in the model diagram.
3 Right-click the u1 signal and select Properties. In the Signal Properties dialog box,
select Signal name must resolve to Simulink signal object. Repeat for signals
u2 and u3.
4-73
4 Patterns for C Code
4 At the MATLAB command line, create a mpt.Signal data object for each input
signal.
u1 = mpt.Signal;
u2 = mpt.Signal;
u3 = mpt.Signal;
Note: You can also create a data object in the Model Explorer base workspace, by
selecting Add > Add Custom.
5 In the base workspace, configure each of the data objects, u1, u2, and u3. Double-
click a data object, to open the mpt.Signal parameter dialog box.
6 Specify the Data type parameter as auto and the Storage class parameter as
Struct (custom).
7 Click Apply and OK.
8 Press Ctrl+B to generate code.
Results
The generated code includes the typedef definition for a structure, which is declared in
the ex_signal_struct_csc_types.h file.
/* Type definition for custom storage class: Struct */
typedef struct my_signal_struct_tag {
real_T u1;
real_T u2;
real_T u3;
} my_signal_struct_type;
1 Create the ex_signal_struct_bus model using the blocks shown and follow the
steps to configure the bus object and model.
4-74
Structures for Signals
2 Add the Inport blocks, an Outport block, and a Bus Creator block to your diagram.
3 Double-click the Bus Creator block to open the block parameter dialog box.
4 Specify the Number of inputs parameter as 3. Click Apply.
5 In your model diagram, connect the three Inport blocks to the three inports of the
Bus Creator block. Also, connect the outport of the Bus Creator block to the Outport
block.
6 Label the signals as shown in the model diagram.
7 In the Bus Creator block parameter dialog box, Signals in bus now displays the
signals connected to the Bus Creator block.
8 Create a bus object named MySignals that includes signals u1,u2, and u3. For more
information on creating bus objects, see “Manage Bus Objects with the Bus Editor”.
Once the bus object, MySignals, is created, it appears in the base workspace.
9 In the Bus Creator block parameter dialog box, select the Output as nonvirtual
bus parameter, which specifies that bus signals must be grouped into a structure in
the generated code.
10 Click Apply and OK.
11 Press Ctrl+B to generate code.
Results
The generated code includes the typedef definition for a structure, which is declared in
the signal_struct_bus_types.h file.
typedef struct {
real_T u1;
real_T u2;
real_T u3;
} MySignals;
4-75
4 Patterns for C Code
Nested Structures
One way to create nested structures of signals in the generated code is by using multiple
non-virtual bus objects. When nesting bus objects, all of the bus objects must either be
non-virtual, or all of them must be virtual.
C Construct
typedef struct {
double u1;
double u2;
double u3;
} my_signals123;
typedef struct {
double u4;
double u5;
double u6;
} my_signals456;
typedef struct {
my_signals123 y1;
my_signals456 y2;
} nested_signals;
Procedure
1 Create the ex_nested_structure model using the blocks shown and follow the
steps to configure the bus objects and model.
4-76
Nested Structures
2 For each bus in the model, follow the instructions for “Structure for Signals
Using a Simulink Non-Virtual Bus Object” on page 4-74, creating bus objects
My_Signals_123 and My_Signals_456.
3 Drag a Bus Creator block into your model. Configure the Bus Creator block so that it
takes in signals from different buses.
4 Double-click the Bus Creator block to open the block parameter dialog box.
5 Specify the Number of inputs parameter as 2. Click Apply.
6 In your model diagram, connect the two bus outports to the inports of the new Bus
Creator block.
7 Label the signals as shown in the model diagram.
8 In the Bus Creator block parameter dialog box, Signals in bus now displays the
signals, y1 and y2, connected to the Bus Creator block.
9 Create a bus object named Nested_Signals that includes signals y1 and y2,
where the DataType for y1 is My_Signals_123 and the DataType for y2 is
My_Signals_456.
4-77
4 Patterns for C Code
For more information on creating bus objects, see “Manage Bus Objects with the Bus
Editor”. Once the bus object, Nested_Signals, is created, it appears in the base
workspace.
10 In the Bus Creator block parameter dialog box, select the Output as nonvirtual
bus parameter, which specifies that bus signals must be grouped into a structure in
the generated code.
11 Click Apply and OK.
12 Press Ctrl+B to generate code.
Results
The generated code includes the typedef definitions for structures, which are declared
in the ex_nested_structure_types.h file.
#ifndef _DEFINED_TYPEDEF_FOR_My_Signals_123_
#define _DEFINED_TYPEDEF_FOR_My_Signals_123_
typedef struct {
real_T u1;
real_T u2;
real_T u3;
} My_Signals_123;
#endif
4-78
Nested Structures
#ifndef _DEFINED_TYPEDEF_FOR_My_Signals_456_
#define _DEFINED_TYPEDEF_FOR_My_Signals_456_
typedef struct {
real_T u4;
real_T u5;
real_T u6;
} My_Signals_456;
#endif
#ifndef _DEFINED_TYPEDEF_FOR_Nested_Signals_
#define _DEFINED_TYPEDEF_FOR_Nested_Signals_
typedef struct {
My_Signals_123 y1;
My_Signals_456 y2;
} Nested_Signals;
#endif
4-79
4 Patterns for C Code
Bitfields
One way to create bitfields in the generated code is by using a mpt.Parameter object
with Bitfield (Custom) storage class.
C Construct
typedef struct {
unsigned int p1 : 1;
unsigned int p2 : 1;
unsigned int p3 : 1;
} my_struct_type
Procedure
1 Using the model, ex_struct_param, in “Structures for Parameters” on page 4-71,
rename the model as ex_struct_bitfield_CSC.
2 Create a data object for each parameter, p1, p2, and p3. At the MATLAB command
line, enter:
p1 = mpt.Parameter;
p2 = mpt.Parameter;
p3 = mpt.Parameter;
3 In the base workspace, double-click one of the parameter data objects to open the
mpt.Parameter dialog box.
4 Specify the Value parameter for each parameter object.
5 Specify the Storage class parameter as Bitfield (Custom) for each parameter
object.
6 In the Custom Attributes section, specify the Struct name as my_struct. Click
Apply and OK.
7 Specify the data objects for each parameter.
4-80
Bitfields
Results
The generated code of the model, ex_struct_bitfield_CSC, includes the typedef
definition for a Bitfield, which is declared in the ex_struct_bitfield_CSC_types.h
file.
/* Type definition for custom storage class: BitField */
typedef struct my_struct_tag {
uint_T p1 : 1;
uint_T p2 : 1;
uint_T p3 : 1;
} my_struct_type;
4-81
4 Patterns for C Code
C Construct
int params[5]= {1,2,3,4,5};
Procedure
1 Create a model, ex_array_params, containing the Constant blocks and Outport
blocks and label the blocks as shown in the model diagram.
2 Double-click the Constant1 block and give the Constant value the name of a
parameter, params1.
3 Double-click the Constant2 block and give the Constant value the name of a
parameter, params2.
4 To create the parameters in the base workspace, at the MATLAB command line,
enter:
params1 = [1,2,3,4,5];
params2 = mpt.Parameter;
4-82
Arrays for Parameters
Results
The generated code includes the array, params2, in the ex_array_params.c file:
int16_T params2[5] = { 1, 2, 3, 4, 5 } ;
4-83
4 Patterns for C Code
C Construct
int u1[5];
int y1[5];
Procedure
1 Create the ex_array_signals model using the blocks shown and follow the steps
to configure the signals and model.
2 Double-click the Inport block to open the Inport block parameter dialog box.
3 Select the Signal Attributes tab and specify the Port dimensions parameter as 5,
for an array of length 5.
4 Click OK.
5 Right-click the u1 signal line and select Properties.
6 Select the Code Generation tab and specify the Storage Class parameter as
ExportedGlobal.
7 Repeat steps 5 and 6 for signal y1.
8 Press Ctrl+B to generate code.
Note: Alternatively, you can use Simulink data objects (mpt.Signal) to specify the
storage class and dimensions for the signals, u1 and y1.
Results
The generated code includes arrays for u1 and y1 in the ex_array_signals.c file:
int16_T u1[5];
int16_T y1[5];
4-84
Arrays for Signals
In this case, a for loop is generated to carry out the gain operations on elements of the
input signal.
int32_T i;
for (i = 0; i < 5; i++) {
y1[i] = (int16_T)(5 * u1[i]);
}
However, if the dimension of the array is less than a threshold value (typically 5), code
generation might not include a for loop for array operations.
4-85
4 Patterns for C Code
C Construct
extern double *u1;
Procedure
This is a quick method to obtain pointers in the generated code. You cannot control the
data type, which is decided by the model compilation process.
1 Create the ex_pointer_signal model using the blocks shown and follow the steps
to configure the signals and model.
Results
The generated code includes the extern declaration for the pointer in the
ex_pointer_signal_private.h file.
4-86
Pointers Using Simulink Data Objects
C Construct
extern double *u1;
Procedure
You can use this procedure for either a signal or parameter. To create a pointer for a
parameter, use an mpt.Parameter instead of an mpt.Signal data object described in
step 3.
Results
The generated code includes the extern declaration for the pointer in the
ex_pointer_signal_data_object_private.h file.
extern real_T *u1;
4-87
4-88
5
Variant Systems
Code is generated for different variant choices, the active variant, and the default
variant. To generate code for variants, set the following conditions in theVariant
Subsystem block:
5-2
Why Generate Code for Variant Systems?
• Reuse generated code from a set of application models that share functionality with
minor variations.
• Share generated code with a third party that activates one of the variants in the code.
• Validate the supported variants for a model and then choose to activate one variant
for a particular application, without regenerating and re-validate the code.
• Generate code for the default variant that is selected when an active variant does not
exist.
5-3
5 Variant Systems
1 Open the Model Explorer and select the Base Workspace node.
2 A variant control can be a condition expression, a “Simulink.Variant class” object
specifying a condition expression or a Simulink.Parameter object. In the
Model Explorer, select Add > Simulink Parameter. Specify a name for the new
parameter.
3 On the Simulink.Parameter property dialog box, specify the Value and Data
type.
4 Select one of these Storage class values.
• ImportedDefine(Custom)
• CompilerFlag(Custom)
• A storage class created using the Custom Storage Class Designer. Your storage
class must have the Data initialization parameter set to Macro and the Data
scope parameter set to Imported. See “Use Custom Storage Class Designer” for
more information.
5 Specify the value of the variant control. If the storage class is either
ImportedDefine(Custom) or a custom storage class, do the following:
a Specify the Header File parameter as an external header file in the Custom
Attributes section of the Simulink.Parameter property dialog box.
b Enter the values of the variant controls in the external header file.
If the variant control is a CompilerFlag custom storage class the value of the
variant control is set at compile time. On the Code Generation > General pane
of the Model Configuration Parameters dialog box, add a makefile option to
5-4
Generate Preprocessor Conditionals for Variant Systems
the “Make command” parameter. For example, for variant control, VSSMODE, enter
make_rtw OPTS="-DVSSMODE=1" in the Make command field.
Note: If you want to modify the value of the variant control after generating the
makefile, use a makefile option when compiling your code. For example, at a
command line outside of MATLAB, enter:
makecommand -f model.mk OPTS="-DVSSMODE=1"
6 Follow the instructions in “Configure Model for Generating Preprocessor Conditional
Directives” on page 5-5 to implement variant objects for code generation. Check
that only one variant object is active in the generated code by implementing the
condition expressions of the variant objects such that only one evaluates to true.
The generated code includes a test of the variant objects to determine that there is
only one active variant. If this test fails, your code will not compile.
Note: You can define the variant controls using Simulink.Parameter object of
enumerated type. This approach provides meaningful names and improves the
readability of the conditions. The generated code includes preprocessor conditionals
to check that the variant condition contains valid values of the enumerated type.
5-5
5 Variant Systems
was already open, close and reopen the dialog box to see the enabled Generate
preprocessor conditionals parameter.
7 Clear the parameter, Override variant conditions and use following variant.
5-6
Review Code Variants in Code Generation Report
5-7
5 Variant Systems
After building the model, look at the variants in the generated code.
rtwdemo_preprocessor_types.h includes the following:
• Preprocessor directives defining the variant objects, LINEAR and NONLINEAR. The
values of these macros depend on the value of the variant control variable, VSSMODE.
The condition expression associated with each macro, LINEAR and NONLINEAR,
determine the active variant.
/* Model Code Variants */
#ifndef LINEAR
#define LINEAR (VSSMODE == 0)
#endif
#ifndef NONLINEAR
#define NONLINEAR (VSSMODE == 1)
#endif
Calls to the step and initialization functions are conditionally compiled as shown in a
portion of the step function, rtwdemo_preprocessor_step:
#if LINEAR
#elif NONLINEAR
#endif
and
#if LINEAR
5-8
Generate Code for Model Variants
rtwdemo_linr(&trb_Add, &rtb_RightController_vmerge,
&(rtwdemo_preprocessor_DWork.RightController_1_DWORK1.rtdw));
#elif NONLINEAR
#endif /* LINEAR */
5-9
5 Variant Systems
In this section...
“Open Example Model” on page 5-10
“Define Variant Controls” on page 5-10
“Configure Model for Generating Preprocessor Conditional Directives” on page 5-12
“View Generated Code” on page 5-13
• ImportedDefine(Custom)
5-10
Generate Code for Variant Subsystems
• CompilerFlag(Custom)
5-11
5 Variant Systems
7 For each variant subsystem, open the parameter dialog box and select Treat as
atomic unit.
5-12
Generate Code for Variant Subsystems
If you specify Use local settings, preprocessor conditions are generated only
when you set the block parameter GeneratePreprocessorConditions to on.
After building the model, look at the variants in the generated code.
AutoSSVar_types.h includes the following:
• Preprocessor directives defining the variant objects. The values of these macros
depend on the value of VSSMODE. The condition expression associated with each macro
determine the active variant.
/* Model Code Variants */
#ifndef LINEAR
#define LINEAR (VSSMODE == 0))
#endif
#ifndef NONLINEAR
#define NONLINEAR (VSSMODE == 1)
5-13
5 Variant Systems
#endif
#elif NONLINEAR
#else
/* Output and update for atomic system: '<S2>/LinearModified' */
rtb_VariantMergeForOutportOut1 = look1_binlx(rtb_Add1,...
rtCP_LookupTable_bp01Dat_j, rtCP_LookupTable_tableDa_j, 4U);
#endif
5-14
Restrictions on Variant Subsystem Code Generation
In the figure below, the code generation process makes the following connections and
adds VariantMerge blocks to the sldemo_variant_subsystems model.
When compared to a generic Merge block the VariantMerge block can have only one
parameter which is the number of Inputs. The VariantMerge block is used for code
generation in variant subsystems internally, and is not available externally to be used in
models. The number of inputs for VariantMerge is determined and wired as shown in
the figure below.
5-15
5 Variant Systems
The child subsystems of the Variant Subsystem block must be atomic subsystems.
Select Treat as atomic unit parameter in the Subsystem block parameters dialog, to
make the subsystems atomic. The VariantMerge blocks are inserted at the outport of
the subsystems if more than one child subsystems are present. If the source block of a
VariantMerge block input is nonvirtual, an error message will be displayed during code
generation. You must make the source block contiguous, by inserting Signal Conversion
blocks inside the variant choices. The VariantMerge block does not support variable
dimensions through it, so you cannot have child subsystems with different output signal
dimensions.
5-16
Special Considerations for Generating Preprocessor Conditionals
5-17
5 Variant Systems
5-18
Generated Code Components Not Compiled Conditionally
5-19
5-20
6
Scheduling Considerations
Note that use of certain blocks is not recommended for production code generation
for embedded systems. The Simulink Block Data Type Support table summarizes
characteristics of blocks in the Simulink and Fixed-Point Designer block libraries,
including whether or not they are recommended for use in production code generation. To
view this table, execute the following command and see the “Code Generation Support”
column of the table that appears:
showblockdatatypetable
Note Custom targets must be modified to support continuous time. The required
modifications are described in “Custom Targets” in the Simulink Coder documentation.
6-2
Use Discrete and Continuous Time
• External mode is selected in the Data exchange subpane of the Interface pane
• MAT-file logging is selected on the Interface pane
Note: The ERT target provides both generated and static examples of the ert_main.c
file. The ert_main.c file controls the overall model code execution by calling the
model_step function and optionally checking the ErrorStatus/StopRequested
flags to terminate execution. For a custom target, if you provide your own custom static
main.c, you should consider including support for checking these flags.
6-3
6 Scheduling Considerations
Overview
Using the rtmStepTask macro, targets that employ the task management mechanisms
of an RTOS can eliminate certain redundant scheduling calls during the execution
of tasks in a multirate, multitasking model, thereby improving performance of the
generated code.
To understand the optimization that is available for an RTOS target, consider how the
ERT target schedules tasks for bareboard targets (where RTOS is not present). The
ERT target maintains scheduling counters and event flags for each subrate task. The
scheduling counters are implemented within the real-time model (rtM) data structure as
arrays, indexed on task identifier (tid).
The scheduling counters are updated by the base-rate task. The counters are clock rate
dividers that count up the sample period associated with each subrate task. When a
given subrate counter reaches a value that indicates it has a hit, the sample period for
that rate has elapsed and the counter is reset to zero. When this occurs, the subrate task
must be scheduled for execution.
The event flags indicate whether or not a given task is scheduled for execution. For
a multirate, multitasking model, the event flags are maintained by code in the main
program for the model. For each task, the code maintains a task counter. When the
counter reaches 0, indicating that the task's sample period has elapsed, the event flag for
that task is set.
On each time step, the counters and event flags are updated and the base-rate task
executes. Then, the scheduling flags are checked in tid order, and tasks whose event flag
is set is executed. Therefore, tasks are executed in order of priority.
For bareboard targets that cannot rely on an external RTOS, the event flags are
mandatory to allow overlapping task preemption. However, an RTOS target uses the
6-4
Optimize Multirate Multitasking Operation on RTOS Targets
operating system itself to manage overlapping task preemption, making the maintenance
of the event flags redundant.
Use rtmStepTask
The rtmStepTask macro is defined in model.h and its syntax is as follows:
boolean task_ready = rtmStepTask(rtm, idx);
rtmStepTask returns TRUE if the task's scheduling counter equals zero, indicating that
the task should be scheduled for execution on the current time step. Otherwise, it returns
FALSE.
If your target supports the Generate an example main program parameter, you can
generate calls to rtmStepTask using the TLC function RTMTaskRunsThisBaseStep.
6-5
6 Scheduling Considerations
6-6
Data, Function, and File Definition
7
Data Types
• Simulink.AliasType
• Simulink.Bus
• Simulink.NumericType
You can apply user-defined data types to achieve the following objectives in generated
code.
• Map your own data type definitions to built-in data types, and specify that your data
types are to be used in generated code.
• Optionally, generate #include directives specifying own header files that contain
your data type definitions. This technique allows you to use legacy data types in
generated code.
In general, code generated from user-defined data objects conforms to the properties and
attributes of the objects as defined for use in simulation. When generating code from
user-defined data objects, the name of the object is the name of the data type that is used
in the generated code. For Simulink.NumericType objects whose IsAlias property is
false, the name of the functionally equivalent built-in or fixed-point Simulink data type is
used instead.
See Also
“ Data Objects”
7-2
Location of User-Defined Type Definitions
Example
• The string must be the name of a header file that contains a typedef for the object.
• The generated file model_types.h contains a #include that gives the header file
name.
You can use this technique to include legacy or other externally created typedefs in
generated code. When the generated code compiles, the specified header file must be
accessible on the build process include path.
The HeaderFile property should include the desired preprocessor delimiter ("" or
'<>'), as in the following examples.
7-3
7 Data Types
This example:
myfloat.HeaderFile = '<legacy_types.h>'
This example:
myfloat.HeaderFile = '"legacy_types.h"'
7-4
Create and Apply User-Defined Data Types
7-5
7 Data Types
4 Select the data object for which you want to specify the user-defined data type. Click
its Data Type field and from the drop down select Refresh data types.
This action updates the data type list with the user-defined data type you created.
5 Select the user-defined data type.
7-6
Create and Apply User-Defined Data Types
See Also
“Create Simulink and mpt Data Objects” on page 7-44 | “ Data Objects”
7-7
7 Data Types
Notice also the Signal display level and Parameter tune level fields on the Code
Placement pane of the Configuration Parameters dialog box, as illustrated in the next
figure.
7-8
Specify Persistence Level for Signals and Parameters
The Signal display level field allows you to specify whether or not the code generator
defines a signal data object as global data in the generated code. The number you specify
in this field is relative to the number you specify in the Persistence level field. The
Signal display level number is for mpt (module packaging tool) signal data objects in
the model. The Persistence level number is for a particular mpt signal data object. If
the data object's Persistence level is equal to or less than the Signal display level,
the signal appears in the generated code as global data with the properties (custom
attributes) specified in “Create mpt Data Objects with Data Object Wizard” on page
7-51. For example, this would occur if Persistence level is 2 and Signal display
level is 5.
Otherwise, the code generator automatically determines how the particular signal data
object appears in the generated code. Depending on the settings on the Optimization
pane of the Configuration Parameters dialog box, the signal data object could appear in
the code as local data without the custom attributes you specified for that data object. Or,
7-9
7 Data Types
based on expression folding, the code generator could remove the data object so that it
does not appear in the code. For more information, see “Code Optimization Basics”.
The Parameter tune level field allows you to specify whether or not the code generator
declares a parameter data object as tunable global data in the generated code.
The number you specify in this field is relative to the number you specify in the
Persistence level field. The Parameter tune level number is for mpt parameter
data objects in the model. The Persistence level number is for a particular mpt
parameter data object. If the data object's Persistence level is equal to or less than the
Parameter tune level, the parameter appears in the generated code with the properties
(custom attributes) specified in “Create mpt Data Objects with Data Object Wizard” on
page 7-51, and thus is tunable. For example, this would occur if Persistence level is
2 and Parameter tune level is 5.
Otherwise, the parameter is inlined in the generated code, and the code generation
settings determine its exact form.
Note that, in the initial stages of development, you might be more concerned about
debugging than code size. Or, you might want one or more particular data objects to
appear in the code so that you can analyze intermediate calculations of an equation. In
this case, you might want to specify the Parameter tune level (Signal display level
for signals) to be higher than Persistence level for some mpt parameter (or signal) data
objects. This results in larger code size, because the code generator defines the parameter
(or signal) data objects as global data, which have the custom properties you specified. As
you approach production code generation, however, you might have more concern about
reducing the size of the code and less need for debugging or intermediate analyses. In
this stage of the tradeoff, you could make the Parameter tune level (Signal display
level for signals) greater than Persistence level for one or more data objects, generate
code and observe the results. Repeat until satisfied.
1 With the model open, in the Configuration Parameters dialog box, click Code
Generation > Code Placement.
2 Type the desired number in the Signal display level or Parameter tune level
field, and click Apply.
3 In the Model Explorer, type the desired number in the Persistence field for the
selected signal or parameter, and click Apply.
4 Save the model and generate code.
7-10
Buses
Buses
In this section...
“About Buses and Code Generation” on page 7-11
“Set Bus Diagnostics” on page 7-12
“Optimize Virtual and Nonvirtual Buses” on page 7-12
“Use Single-Rate and Multi-Rate Buses” on page 7-15
“Set Bus Signal Initial Values” on page 7-18
“Use Buses with Atomic Subsystems” on page 7-22
This chapter contains guidelines that you can use to improve the results when you work
with buses. The guidelines describe techniques for:
Some trade-offs inevitably exist among speed, size, and clarity. For example, the code for
nonvirtual buses is easier to read because the buses appear in the code as structures, but
the code for virtual buses is faster because virtual buses do not require copying signal
data. The applicability of some guidelines can therefore depend on where you are in the
application development process.
This chapter focuses on optimizations that are useful for final production code. Before
you read this chapter, read “Composite Signals”. This topic assumes that you understand
7-11
7 Data Types
the concepts and procedures described in that one, including the blocks used for creating
and manipulating buses.
Bus signal treated as vector is enabled only when Mux blocks used to create bus
signals is set to error. See “Prevent Bus and Mux Mixtures” for more information.
Virtual buses are graphical conveniences that do not affect generated code. As a result,
the code generation engine is able to fully optimize the signals in the bus. You should
therefore use virtual rather than nonvirtual buses wherever possible. You can convert
between virtual and nonvirtual buses using Signal Conversion blocks. In many cases,
Simulink automatically converts a virtual bus to a nonvirtual bus when required. For
example, a virtual bus input to a Model block becomes a nonvirtual bus without the need
for explicit conversion. See for more information.
When are Virtual and Nonvirtual Buses Required?
7-12
Buses
• Only virtual buses can be used for bundling function call signals.
Buses can contain subordinate buses. The storage class of a subordinate bus should be
auto, which results in a local signal. Setting a subordinate bus to a non-auto storage
class has two undesirable results:
• Allocation of redundant memory (memory for the subordinate bus object and memory
for the final bus object)
• Additional copy operations (first copying to the subordinate bus and then copying
from the subordinate bus to the final bus)
In the following example, the final bus is created from local scoped subordinate elements.
The resulting assignment operations are relatively efficient:
7-13
7 Data Types
By contrast in the next example the subordinate elements Sub_Bus_1 and Sub_Bus_2
are global in scope. First the assignment to the subordinate bus occurs (lines 54 – 59)
then the copy of the subordinate bus to the main bus (lines 60 – 61). In most cases, this is
not an efficient implementation:
7-14
Buses
Introduction
Nonvirtual buses do not support multiple rates. Virtual buses support multiple rates
as long as the bus does not cross a root level inport or outport. The best techniques for
optimizing a bus that contains signals that initially have different rates can depend on
the type of the bus and the number of signals.
The simplest bus contains only two signals. The next figure shows two examples of two-
element buses. The first example shows a virtual bus created from two signals that have
different rates. The second example shows a nonvirtual bus created from the same two
signals. The Sample Time Legend shows the different signal rates:
7-15
7 Data Types
The signals with different rates in the first example can be combined into a virtual bus,
because virtual buses support multiple rates. However, a multirate virtual bus cannot
connect to a root-level output port. The bus therefore passes through a Rate Transition
block that converts it to a single-rate bus, then connects to the Outport. This technique is
preferable only for virtual buses that contain one or two signals. See “Larger Buses and
Multiple Rates” on page 7-17.
7-16
Buses
The signals with different rates in the second example cannot initially be combined
into a nonvirtual bus, because nonvirtual buses do not support multiple rates. One of
the signals therefore passes through a Rate Transition block, which converts it to have
the same rate as the other signal, then connects to the Bus Creator block. The signals
can then combine into a single-rate nonvirtual bus, which can connect to the root-level
outport without further conversion.
When you create a multirate virtual bus that contains more than two signals, you can
convert the bus to single-rate by applying a Rate Transition block to the output of the
Bus Creator block. Use a Rate Transition block on each input signal to give full control
over the output rate. As the next figure shows, when a single Rate Transition block is
used, the block sets the signals to the fastest rate (D1):
7-17
7 Data Types
Note that the preferred techniques for a virtual bus with more than two signals, and the
required technique for a nonvirtual bus with one or more signals, are the same. Note also
that, in the preceding figure, the blocks that perform rate transition are not actual Rate
Transition blocks, but other blocks that can change the signal rate as part of some other
operation. The identity of the blocks that perform rate transition is not as significant;
what matters is that the signal rates match when required.
The sample time for buses should be specified through the signals that define the bus.
If the sample times do not match, use Rate Transition (or equivalent) blocks to create
a uniform rate, as shown in the previous figures. The signal rates should not be set by
specifying Sample Time values in a Bus Creator block's bus object. Instead, set the
sample time for each signal before inputting it to the Bus Creator, and set each Sample
Time in the corresponding bus object to -1, which indicates the value is inherited.
7-18
Buses
Introduction
Unlike scalar and vector signals, buses do not provide a direct way to initialize signals.
This section describes techniques for initializing bus signals using Simulink, Stateflow,
and MATLAB functions.
In Simulink, you can set initial values on a bus by using a set of conditionally executed
subsystems, such as Function-Call subsystems, and a Merge block, as shown in this
example:
This technique is limited because the StandardUpdate subsystem does not use
the initial values from the InitBus subsystem. If the calculations depend on past
information from the bus, consider using Stateflow or MATLAB functions to initialize bus
signals.
Stateflow and MATLAB functions allow for conditional execution internally. In the
following example, the init and update code are Functions in the Stateflow diagram.
This technique simplifies the presentation in the generated code:
7-19
7 Data Types
In the generated code, you can see that the UpdateCnt function uses the past value of
GlobalCounter.cnt:
The previous example used Stateflow Graphical functions to initialize and update the
buses. Alternatively, you can use MATLAB functions or Simulink subsystems embedded
in a Stateflow diagram. The next figure illustrates this technique:
7-20
Buses
The Simulink subsystems are the same as those used in the earlier Simulink-only
example.
The code for specifying a bus of constant values will appear in either the Init or the
Step function of the model. The code location depends on the configuration of the bus.
In most cases the code appears in the Step function. However if the following conditions
hold the code will be placed in the Init function:
In the next figure, only the bus named Bus_2 meets the requirements:
7-21
7 Data Types
The code for Bus_2 therefore appears in the Init function. The code for the other buses
appears in the Step function:
To avoid repeatedly updating a bus of constants, place the bus code into a function-call
subsystem, as described in “Initialize Bus Signals in Simulink” on page 7-19. When
you use this technique, make sure the function-call subsystem is called at the start of
execution. See “Create a Function-Call Subsystem” for more information.
Selecting signals from a nonvirtual bus can result in unnecessary data copies when those
signals cross an atomic boundary. In the following example the same code, a simple
multiplication of two elements in a vector, is executed three times:
7-22
Buses
In the second instance when the bus signals are selected outside of the atomic subsystem
an unnecessary copy of the bus data is created.
Although this example shows only signals with global scope, both global and local signals
show the same behavior: the selection of the signals outside of the model results in an
unnecessary copy, while the internal selection does not.
Virtual buses that cross atomic boundaries can result in the creation of unnecessary data
copies. The following example shows the data copy that occurs when a virtual bus crosses
an atomic boundary:
7-23
7 Data Types
Lines 25–26 show the signals being selected out of the bus before they are used in the
function on lines 19–20. By comparison the nonvirtual bus does not require the use of
temporary variables.
If the bus passed into an atomic subsystem consists exclusively of constants, using a
virtual bus is more efficient, because Simulink is able to inline the constant values into
the code:
7-24
Buses
7-25
7 Data Types
1 In the Model Editor, set the simulation mode of the open model. From the
Simulation menu, select Normal, Software-in-the-loop (SIL), or
Processor-in-the-loop (PIL).
2 In the Configuration Parameters dialog box, click Code Generation > Data Type
Replacement > Replace data type names in the generated code. A Data type
names table appears. The table lists each Simulink built-in data type name with its
corresponding code generation data type name.
3 Fill in fields in the third column with your replacement data types. Each
replacement data type should be the name of a Simulink.AliasType object
that exists in the base workspace. Replacements may be specified or not for each
individual built-in type.
For each replacement data type you enter, the BaseType property of the associated
Simulink.AliasType object must be consistent with the built-in data type it
replaces.
7-26
Rename Built-In Data Types
• For double, single, int32, int16, int8, uint32, uint16, and uint8, the
replacement data type's BaseType must match the data type.
• For boolean, the replacement data type's BaseType must be either an 8-
bit integer or an integer of the size displayed for Number of bits: int on the
Hardware Implementation pane of the Configuration Parameters dialog box.
• For int, uint, and char, the replacement data type's size must match the size
displayed for Number of bits: int or Number of bits: char on the Hardware
Implementation pane of the Configuration Parameters dialog box.
An error occurs, if
7-27
7 Data Types
In this section...
“Introduction” on page 7-28
“Register mpt User Object Types Using sl_customization.m” on page 7-28
“mpt User Object Type Customization Using sl_customization.m” on page 7-30
Introduction
Embedded Coder software allows you to create custom mpt object types and specify
properties and property values to be associated with them (see “Create mpt Data Objects
with Data Object Wizard” on page 7-51). Once created, a user object type can be
applied to data objects displayed in Model Explorer. When you apply a user object type to
a data object, by selecting a type name in the User object type pull-down list in Model
Explorer, the data object is automatically populated with the properties and property
values that you specified for the user object type.
To register mpt user object type customizations, use the Simulink customization file
sl_customization.m. This file is a mechanism that allows you to use MATLAB code to
perform customizations of the standard Simulink user interface. The Simulink software
reads the sl_customization.m file, if present on the MATLAB path, when it starts
and the customizations specified in the file are applied to the Simulink session. For
more information on the sl_customization.m customization file, see “Registering
Customizations”.
function sl_customization(cm)
As a starting point for your customizations, the sl_customization function must first
get the default (factory) customizations, using the following assignment statement:
7-28
Register mpt User Object Types
hObj = cm.slDataObjectCustomizer;
You then invoke methods to register your customizations. The customization manager
object includes the following methods for registering mpt user object type customizations:
Registers the specified user object type, along with specified values for object
properties, and adds the object type to the top of the user object type list, as displayed
in the User object type pull-down list in the Model Explorer.
Moves the specified user object type to the top of the user object type list, as displayed
in the User object type pull-down list in the Model Explorer.
• moveMPTObjectTypeToEnd(hObj, objectTypeName)
Moves the specified user object type to the end of the user object type list, as displayed
in the User object type pull-down list in the Model Explorer.
• removeMPTObjectType(hObj, objectTypeName)
Removes the specified user object type from the user object type list.
Your instance of the sl_customization function should use these methods to register
mpt object type customizations for your Simulink installation.
The Simulink software reads the sl_customization.m file when it starts. If you
subsequently change the file, to use the changes, you must restart your MATLAB
session.
7-29
7 Data Types
hObj.addMPTObjectType(...
'FuelType','Signal',...
'DataType', 'int16',...
'Min', -12,...
'Max', 3000,...
'DocUnits','mg/hr');
end
If you include the above file on the MATLAB path of the Simulink installation that
you want to customize, the specified customizations will appear in Model Explorer. For
example, you could view the customizations as follows:
7-30
Register mpt User Object Types
6 From the User object type drop-down list, select one of the registered user
signal types, for example, FuelType, and verify that the displayed settings are
consistent with the arguments specified to the addMPTObjectType method in
sl_customization.m.
7-31
7 Data Types
In this section...
“Replace Built-In Data Type Names” on page 7-32
“Replace Built-In Data Type Names with Replacement Data Type Names” on page
7-35
“Programmatically Replace Built-In Data Type Names” on page 7-40
“Replace boolean with an Integer Data Type” on page 7-40
“Data Type Replacement Limitations” on page 7-42
1 In the Model Editor, set the simulation mode of the open model. From the
Simulation > Mode menu, select Normal, Software-in-the-loop (SIL), or
Processor-in-the-loop (PIL).
2 In the Configuration Parameters dialog box, click Code Generation > Data
Type Replacement. Select Replace data type names in the generated code.
The Data type names table lists each Simulink built-in data type name with its
corresponding code generation data type name.
7-32
Data Type Replacement
3 Fill in the Replacement Name column with values to replace the default names in
the Code Generation Name column. Specify one of the following:
7-33
7 Data Types
To specify the data type for Replacement Name in column one of the table, use the
value listed in the column representing the replacement representation.
>> unsigned_integer=Simulink.AliasType;
• Look in the table under Code Generation Name for uint32_T.
>> unsigned_integer.BaseType='uint32';
• In the Data Type Replacement table, in the Replacement Name column, in the
uint32_T row, enterunsigned_integer .
7-34
Data Type Replacement
• A replacement data type specification does not correspond to the Simulink Name
data type.
• The Simulink.AliasType object has the Data scope parameter set to Exported.
Replace Built-In Data Type Names with Replacement Data Type Names
If your application requires you to replace built-in data type names with user-defined
replacement data type names in the generated code, you can do so from the Code
Generation > Data Type Replacement pane of the Configuration Parameters dialog
box.
This pane is available for ERT target-based Simulink models. In addition to providing a
mechanism for mapping built-in data types to user-defined replacement data types, this
feature:
• Performs consistency checks so that your specified data type replacements are
consistent with your model's data types.
• Allows many-to-one data type replacement, the ability to map multiple built-in data
types to one replacement data type in generated code. For example, built-in data
types uint8 and boolean can be replaced in your generated code by a data type U8
that you have previously defined.
Note: For limitations that apply, see “Data Type Replacement Limitations” on page
7-42.
If you select Replace data type names in the generated code, the Data type names
table is displayed.
The table Data type names lists each Simulink built-in data type name along with its
code generation data type name. Selectively fill in fields in the third column with your
replacement data types. You can specify replacements or not for each individual built-in
type. Each replacement data type must be one of the following:
• The name of a Simulink.AliasType object that exists in the base workspace. Set
the BaseType object property value to the corresponding Simulink Name data type.
7-35
7 Data Types
When you use a Simulink.AliasType object, you can replace a data type name with
a valid Simulink.AliasType name.
• The Simulink Name data type. This name replaces the name in the generated code.
Using the Simulink Name, you can replace all values except real_T and real32_T.
For information on how you specify replacement names for boolean_T, int_T,
uint_T, and char_T, see the following table.
• The name of a Simulink.NumericType object that exists in the base workspace. Set
the DataTypeMode object property value to the corresponding Simulink Name data
type. Using Simulink.NumericType, you can define replacement names for real_T,
real32_T, and boolean_T.
7-36
Data Type Replacement
It is not recommended to use data type replacement to work around data type checking.
Do not intentionally replace a data type with a type that has inconsistent characteristics,
such as replacing real_T with a type name that maps to a single-precision data
type (inconsistent size). Remapping to inconsistent types can introduce significant
numerical differences, relative to simulation results, and erroneous behavior. Examples
of inconsistencies include:
For example, suppose that you have previously defined the following replacement data
types, which exist as Simulink.AliasType objects in the base workspace.
You can fill in the Data Type Replacement pane with a one-to-one replacement
mapping, as follows:
7-37
7 Data Types
You can also apply a many-to-one data type replacement mapping. For example, in the
following display:
Note: Many-to-one data type replacement does not support the char (char_T) built-in
data type. Use char only in one-to-one data type replacements.
7-38
Data Type Replacement
The user-defined replacement types you specify appear in your model's generated code
in place of the corresponding built-in data types. For example, if you specify user-defined
data type FLOAT64 to replace built-in data type real_T (double), the original generated
code shown in Generated Code with real_T Built-In Data Type becomes the modified
generated code in Generated Code with FLOAT64 Replacement Data Type.
...
/* Model initialize function */
void sinwave_initialize(void)
{
...
{real_T *dwork_ptr = (real_T *) &sinwave_DWork.lastSin;
...
}
...
...
/* Model initialize function */
void sinwave_initialize(void)
7-39
7 Data Types
{
...
{FLOAT64 *dwork_ptr = (FLOAT64 *) &sinwave_DWork.lastSin;
...
}
...
model = bdroot;
cs = getActiveConfigSet(model);
set_param(cs,'EnableUserReplacementTypes','on');
struc = get_param(cs,'ReplacementTypes');
struc.int8 = 'my_T_S8';
struc.uint8 = 'my_T_U8';
struc.boolean = 'my_T_BOOL';
set_param(cs,'ReplacementTypes',struc);
• int8
• uint8
• intn
n is 8, 16, or 32, matching the integer word size for the production hardware (for
example, int32 for 32-bit hardware).
For example, to map boolean to the int32 data type, perform the following steps.
7-40
Data Type Replacement
mybool = Simulink.AliasType;
mybool.BaseType = 'int32';
2 Open an ERT-based model. In the Data Type Replacement pane of the
Configuration Parameters dialog box, map boolean (boolean_T) to the
replacement data type mybool.
In the resulting generated code, boolean is replaced with mybool. For example,
rtwtypes.h contains:
/* Generic type definitions ... */
...
typedef int boolean_T;
...
/* Define Simulink Coder replacement data types. */
typedef boolean_T mybool; /* User defined replacement datatype for boolean_T */
Boolean data in the generated code is declared with mybool. For example, given a model
with a Boolean output Out1, an Out1 declaration such as:
boolean_T Out1; /* '<Root>/Out1' */
7-41
7 Data Types
7-42
Data Definition and Declaration Management
In this section...
“Overview of Data Objects” on page 7-43
“Create Simulink and mpt Data Objects” on page 7-44
“Create Data Objects for a Model” on page 7-57
“Define Global Data Objects in Separate File” on page 7-63
“Define Global Data Objects in Separate Files” on page 7-64
“Save and Load Data Objects” on page 7-65
“Apply Naming Rules to Identifiers Globally” on page 7-65
The values of data object properties are used to determine where the code generator
places a parameter or signal in the generated file. This is because some property values
are associated with different template symbols. The location of a symbol in a template
determines where the associated parameter or signal is located in the generated file. For
details about templates and symbols, see “Customize Code Organization and Format”.
Simulink uses a hierarchy of terms that are drawn from object-oriented programming.
For details, see “ Data Objects” in the Simulink documentation. The sketch below
summarizes this hierarchy.
7-43
7 Data Types
Package
Class . . . Class
P ... P P ... P
P = Property
PV PV PV PV PV = Property Value
Simulink or mpt is the package. Parameter and Signal are two classes in each of these
packages. Each class has a number of properties associated with it. Sometimes properties
are called attributes. Data objects (the parameters and signals) are the instances of a
package.class. Parameter data objects have a set of properties. Signal data objects
have a different set of properties than that for parameters. For each data object, each
property in the set has its own property value.
The Embedded Coder software provides the mpt (module packaging tool) data object,
which contains the properties of Simulink data objects plus properties that provide
additional control over module packaging. For a comparison of the properties of Simulink
and mpt data objects, see “Simulink and mpt Data Object Comparison” on page 7-51.
There are different ways of creating Simulink and mpt data objects.
7-44
Data Definition and Declaration Management
For Simulink data objects, select Add > Simulink Parameter or Add > Simulink
Signal.
The following sections illustrate how to create Simulink and mpt data objects and
compares their properties as data types.
Data Object Wizard is especially useful for creating multiple data objects for
This procedure creates Simulink data objects using Data Object Wizard.
1 Open the model for which you want to create data objects. For example, open
rtwdemo_mpf (which is located in toolbox/rtw/rtwdemos).
2 Open Data Object Wizard by entering dataobjectwizard at the MATLAB
command line or by selecting Data Object Wizard from the Code > Data Objects
menu in the Simulink editor. The Data Object Wizard dialog box appears:
7-45
7 Data Types
The Model name field displays the name of the model. You could specify a different
model by editing the field or by selecting the model using the adjacent Browse
button. When the Model name field is nonempty, the Find button is enabled.
3 In the Find options pane, select the desired check boxes. For descriptions of
each check box, see “Data Object Wizard” in the Simulink documentation. Be
sure to check the Alias types option. This finds user-registered data types in the
sl_customization.m file plus data type replacements specified for the model in
the Data Type Replacement pane of the Configuration Parameters dialog box. The
Data Object Wizard can create Simulink.AliasType objects from these.
4 Click the Find button. The model's potential data objects appear. This includes the
model's signals (root inputs, root outputs, and block outputs), discrete states, data
stores, and parameters, depending on:
7-46
Data Definition and Declaration Management
Data Object Wizard finds only those signals, parameters, data stores, and states
whose storage class is set to Auto. The Wizard lists each data store and discrete
state that it finds as a signal class.
5 Click Select All. Notice in the Choose package for selected data objects field
that Simulink, the default, is selected. Therefore, the data objects are associated
with the Simulink package, as shown below.
6 Click Create. The data objects are added to the MATLAB workspace, and they
disappear from Data Object Wizard.
7 Click Cancel. The Data Object Wizard dialog box disappears.
Now you can set property values for the data objects.
Most of the property values of data objects are supplied by defaults. A few are from the
model. Note that for Simulink data objects, the default storage class is Auto.
1 Type daexplr on the MATLAB command line, and press Enter. The Model Explorer
appears.
7-47
7 Data Types
2 In the Model Hierarchy (left) pane, select Base Workspace. The Simulink data
objects appear in the Contents (middle) pane, as shown below.
If the objects that you see do not appear in the order shown, click the Name column
header in the middle pane to sort the objects in ascending order by name.
3 To see the properties of a Simulink data object, select a data object in the middle
pane. The right pane displays the property names for that object. These property
names also appear as column headings in the middle pane. For example, if you select
signal data object A in the middle pane, the Model Explorer looks like this:
7-48
Data Definition and Declaration Management
4 You can change the values specified for the properties of the selected object. For
example, with A selected, change its StorageClass property from Auto to Default
(Custom), then click Apply. The property changes as shown below:
7-49
7 Data Types
You can use Control-Right-Click to select multiple objects in the center pane, then edit a
property value. The wizard applies the new value to the selected objects. For descriptions
of object properties and their values, see “Parameter and Signal Property Values”.
Generate and Inspect Code
Data objects for the model have been created. You have specified property values for each
data object's properties. Now you generate and inspect the source code, to see if it needs
correction or modification. If it does, you can change property values and regenerate the
code until it is what you want.
1 In the Configuration Parameters dialog box, click Code Generation in the left
pane.
2 In the Report pane, select the Create code generation report check box.
Note When you select the Create code generation report check box, the code
generation software automatically selects two check boxes on the pane: Launch
report automatically and Code-to-model. For large models, you may find that
HTML report generation (step 4 below) takes longer than you want. In this case,
consider clearing the Code-to-model check box (and the Model-to-code check box
if selected). The report will be generated faster.
7-50
Data Definition and Declaration Management
3 In the Code Generation pane, select the Generate code only check box. The
Build button changes to Generate Code.
Note The generate code process generates the .c/.cpp and .h files. The build
process adds compiling and linking to generate the executable. For details on build,
see “How Executable Programs Are Built From Models” in the Simulink Coder
documentation.
4 Click the Generate Code button. After a moment, the HTML code generation report
appears, listing the generated files on the left pane.
5 Select and review files in the HTML code generation report. See “Traceability in
Code Generation Report” for more information.
Create mpt data objects using Data Object Wizard the same way you did for Simulink
data objects, as explained in “Create Data Objects with Data Object Wizard” on page
7-45, except select mpt as the package instead of Simulink.
Set the property values for the mpt data objects the same way you set them for Simulink
data objects, as explained in “Set Property Values for Data Objects” on page 7-47,
with the following exceptions:
• Accept the default custom storage class for mpt data objects, Global(Custom)
• For data objects A and F1, type mydefinitionfile in the Definition file field on
the Model Explorer.
Note The Alias field is related to “Apply Naming Rules to Identifiers Globally” on page
7-65.
The mpt data object contains the properties of Simulink data objects plus properties that
provide additional control over module packaging. The differences between Simulink and
mpt data objects can be illustrated by comparing
7-51
7 Data Types
• Different custom storage classes displayed in the Model Explorer for mpt data objects
provide more control over the appearance of the generated code.
• Additional custom attributes (owner, definition file, persistence level, memory section)
for mpt data objects provide more control over data packaging in the generated code.
• On the Comments pane of the Configuration Parameters dialog box, the Custom
comments (MPT objects only) option allows you to add a comment just above a
signal or parameter's identifier in the generated code.
• On the Code Placement pane of the Configuration Parameters dialog box, in the
Global data placement (MPT data objects only) subpane:
• The Signal display level parameter allows you to specify whether or not the code
generator declares a signal data object as global data
• The Parameter tune level parameter allows you to specify whether or not the
code generator declares a parameter data object as tunable global data
The properties that appear in Model Explorer when mpt is the package include the
properties that appear when Simulink is the package plus additional properties. Notice
this by comparing the next two figures. (For descriptions of properties in Model Explorer,
see “Parameter and Signal Property Values”.)
7-52
Data Definition and Declaration Management
Configuration Parameters
7-53
7 Data Types
when the system target file selected for a Simulink model is ert.tlc (or a system target
file derived from an ert.tlc):
• Custom comments (MPT objects only) option on the Code Generation >
Comments pane
• In the Global data placement (MPT data objects only) subpane on the Code
Generation > Code Placement pane:
Generated Code
In the example used in “Set Property Values for Data Objects” on page 7-47, you
selected Default (Custom) in the Storage class field for signal A and parameter F1.
You selected the default Auto in the Storage class field for the remaining data objects.
But for the mpt data objects you used the default Global (Custom) in the Storage
class field. When you generated code, these selections resulted in the definitions and
declarations shown in the table below.
Simulink Data Object with Auto Simulink Data Object with mpt Data Object with Global
Storage Class Default (Custom) Storage Class (Custom) Storage Class
and Definition File Named
mydefinitionfile
In rtwdemo_mpf.c: In global.c: In mydefinitionfile.c:
/* For signal A */
typedef struct {
real_T A;
} ExternalInputs;
7-54
Data Definition and Declaration Management
The results shown in the second and third columns of the preceding table require the
following configuration parameter adjustments on the Code Generation > Code
Placement pane:
See the left column of the table, which shows generated code for Simulink signal and
parameter data objects, whose Storage class field is Auto. The input A is defined as
part of the structure rtU as shown above. In the case of the Simulink parameter data
object F1, since the StorageClass was set to auto, the code generator chose to include
the literal value of F1 in the generated code. F1 is a constant in the Stateflow diagram
whose value is initialized as 2.0:
if(rtU.A * 2.0 > 10.0) { ...
For more details, see “Introduction to Custom Storage Classes” and “Summary of Signal
Storage Class Options” in the Simulink Coder documentation.
See the middle column of the table. The Simulink data objects whose Storage class is
not Auto are defined in a definition statement in the global source file (global.c) and
declared in a declaration statement in the global header file (global.h).
In the right column, Simulink data objects whose Storage class is not Auto are defined
in mydefinitionfile, as you specified. The declarations for those objects are in the
global header file.
You can create data objects (and their properties) one-by-one, based on an external data
source, as follows:
1 Open the external file that contains the data (such as a spreadsheet or database file).
2 Determine the data in this file that correspond to the parameters and signals in the
model. Parameters in the external source belong to the Simulink parameter class
and signals belong to the Simulink signal class.
7-55
7 Data Types
3 On the MATLAB command line, type daexplr and press Enter. The Model Explorer
appears.
4 On the Model Hierarchy (left) pane, expand Simulink Root, and select Base
Workspace.
5 On the Add menu, select Add Custom for an mpt data object or Simulink
Parameter for a Simulink data object. The default name Param appears in the
Contents of (middle) pane.
6 Double-click Param and rename this data object as desired.
7 Repeat steps 5 and 6 for each additional data item in the external file that belongs to
the mpt.Parameter class or Simulink.Parameter class.
Now you will add data items in the external file that belong to the mpt.Signal class
or Simulink.Signal class.
8 On the Add menu, select Add Custom to add an mpt data object or Simulink
Signal to add a Simulink data object. The default name Sig appears in the
Contents of pane.
9 Double-click Sig and rename the data object as desired.
10 Repeat steps 8 and 9 for each additional data item in the external file that belongs to
the mpt.Signal class or Simulink.Signal class.
Note The property values for these data objects are supplied by default.
You can create data objects (and their properties) based on an external data source by
creating and running a .m file. This file contains the same MATLAB commands you could
use for creating data objects one-by-one on the command line, as explained in “ Data
Objects” in the Simulink documentation. But instead of using the command line, you
place the MATLAB commands in the .m file for the desired data in the external file:
7-56
Data Definition and Declaration Management
objects with the indicated properties. The first is for a parameter and the second is
for a signal:
% Parameters
mptParCon = mpt.Parameter;
mptParCon.CoderInfo.CustomStorageClass ='Const';
mptParCon.value = 3;
% Signals
mptSigGlb = mpt.Signal;
mptSigGlb.DataType = 'int8';
3 Run the .m file. The data objects appear in the MATLAB workspace.
Note: If you want to import data from an external data source, you can write functions
that read the information, convert these to data objects, and load them into the MATLAB
workspace. Among available MATLAB functions that you can use for this process
are xmlread, xmlwrite, xlsread, xlswrite, csvread, csvwrite, dlmread, and
dlmwrite.
1 Open the model rtwdemo_mpf by clicking the link or by typing rtwdemo_mpf in the
MATLAB Command Window.
7-57
7 Data Types
In this model,
• A, B, and C are input signals, and L and Final are output signals.
• Subsystem1 receives inputs A and E and contains constants G1 and G2. Signal E is
an output from Data Store Read1.
• Subsystem2 receives inputs C and D. Signal D is an output from Data Store
Read2. There is a constant in Subsystem2 named G3. Also, this subsystem has a
Unit Delay block whose state name is SS.
2 Double-click the Stateflow chart and notice it has constants F1, Gain1, and Gain2,
as shown below:
7-58
Data Definition and Declaration Management
3 Change to a work folder that is not on an installation path and save the model in
that work folder. The code generation software does not allow you to generate code
from an installation folder.
4 Double-click the Invoke Data Object Wizard button on the model. Or, type
dataobjectwizard('rtwdemo_mpf') in the MATLAB Command Window. Data
Object Wizard opens and rtwdemo_mpf appears in the Model name field, as shown
below.
5 Click Find on Data Object Wizard. After a moment, the model's parameters and
signals appear in Data Object Wizard.
6 Click Select All.
7 In the Choose package for selected objects field, select mpt. For an explanation
of “package,” see “Overview of Data Objects” on page 7-43.
8 Click Apply Package. Data Object Wizard associates the selected data objects with
the mpt package, as shown below.
7-59
7 Data Types
9 Click Create. Data Object Wizard creates data objects for the selected parameters
and signals. Data Object Wizard removes the objects from its object view. Also, the
objects are added to the MATLAB workspace, as shown below.
7-60
Data Definition and Declaration Management
You can inspect each data object you selected in the Data Object Wizard using the Model
Explorer:
1 If you have not already done so, complete the steps in “Use Data Object Wizard” on
page 7-57 .
2 Open the Model Explorer.
3 In the left pane, select Base Workspace. Notice that data objects appear in the
middle pane.
4 In the middle pane, select data objects one at a time, and notice their property values
in the right pane. The figure below shows this for signal A. The data objects have
default property values. Note that for an mpt data object, the default in the Storage
class field is Global (Custom). For descriptions of the properties on the Model
Explorer, see “Set Property Values for Data Objects” on page 7-47.
7-61
7 Data Types
1 If you have not already done so, complete the steps in “Use Data Object Wizard” on
page 7-57 and “Inspect Data Objects” on page 7-61.
2 In the left pane of the Model Explorer, expand the rtwdemo_mpf node.
3 In the left pane, click Configuration (Active).
4 In the center pane, click Code Generation. The active configuration parameters
appear in the right pane.
5 In the Report tab, select Create code generation report
6 Select the General tab. Select Generate code only, and then click Generate
Code. After a few moments, the names of the generated files are listed on the Code
Generation Report on the left pane.
7-62
Data Definition and Declaration Management
7 Open and inspect the content of the model source file rtwdemo_mpf.c. The following
data objects are initialized in this file.
real_T F1 = 2.0;
real_T G1 = 6.0;
real_T G2 = -2.6;
real_T G3 = 9.0;
real_T Gain1 = 5.0;
real_T Gain2 = -3.0;
1 Configure the model's generated code to include Simulink data objects (signal and
parameter) in a separate definition file. Set Diagnostics > Data Validity > Signal
resolution to Explicit and implicit.
2 Specify that data be defined in a separate file. Set Code Generation > Code
Placement > Data definition to Data defined in single separate source
file. Accept the default for Data definition filename, global.c
7-63
7 Data Types
3 Specify that data be declared in a separate file. Set Data declaration to Data
declared in a single separate header file and accept the default for
Data declaration filename, global.h. Then, click Apply.
4 Click Generate Code. Notice that the code generation report lists global.c and
global.h files.
5 Inspect the code generation report. Notice that
7-64
Data Definition and Declaration Management
In the following procedure, you move the Final signal to a file called finalsig.c, and
keep the other data objects defined in global.c:
1 In the Model Explorer, display the base workspace and select the Final signal
object. The mpt.Signal properties appear in the right pane.
2 In the Code generation options section, type finalsig.h in the Header file text
box, type finalsig.c in the Definition file text box, and click Apply.
3 On the Code Generation > General pane, click Generate Code. The code
generation report still lists global.c and global.h, but adds finalsig.c and
finalsig.h.
4 Open the files to inspect them. Notice that the Final signal is defined in
finalsig.c. Other data objects are defined in global.c.
Note The capabilities described in this section apply only to mpt data objects.
Overview
Signal and parameter names appear on a Simulink model. The same names appear as
data objects on the Model Explorer. By default, these names are replicated exactly in
the generated code. For example, "Speed" on the model (and workspace) appears as
the identifier "Speed" in the code, by default. But you can change how they appear in
7-65
7 Data Types
the code. For example, if desired, you can change "Speed" to SPEED or speed. Or, you
can choose to use a different name altogether in the generated code, like MPH. The only
restriction is that you follow ANSI® C3/C++ rules for naming identifiers.
There are two ways of changing how a signal name or parameter name is represented in
the generated code. You can do this globally, by following the procedure in this section.
This procedure makes selections on the Configuration Parameters dialog box to change
the names when code generation occurs, according to the same rule. Or, you can change
the names individually by following the steps described in “Set Property Values for Data
Objects” on page 7-47. The relevant field in that procedure is Alias on the Model
Explorer.
If the Alias field is empty, the naming rule that you select on the Configuration
Parameters dialog box applies across data objects. But if you do specify a name in
the Alias field, this overrides the naming rule for that data object. The table below
illustrates these cases. The table assumes that you selected Force lower case as the
naming rule. But with the information provided, you can determine how the naming
rules work for an mpt data object or a Simulink data object (Force upper case, Force
lower case, or Custom M-function).
Naming Rules and Alias Override (Global Change of Force Lower Case Rule)
Name of Data Object Name in Alias Field Package Result in Generated Code
in Model
A Simulink or mpt a
A D Simulink or mpt D
This procedure changes the names of signal identifiers so that they are spelled with
lowercase letters. A in the definition statement located in global.c is changed to a. The
one exception is the Final signal in the finalsig.c file. You change this identifier
name to Final_Signal. The names of the rest of the identifiers in the generated files
remain the same:
1 Open the Code Generation > Symbols pane of the Configuration Parameters
dialog.
2 In the Simulink data object naming rules section, set Signal naming to Force
lower case, and click Apply.
7-66
Data Definition and Declaration Management
5 On the Code Generation > General pane, click Generate Code . Now, the signal
identifiers in global.c and global.h appear with lowercase letters.
real_T F1 = 0.0;
real_T G1 = 1.0;
real_T G2 = 1.0;
real_T G3 = 1.0;
real_T Gain1 = 0.0;
real_T Gain2 = 0.0;
real_T a;
real_T b;
7-67
7 Data Types
real_T c;
real_T d;
real_T ds;
real_T e;
real_T l;
real_T ss;
The statement defining the Final signal in finalsig.c looks like this:
real T Final_Signal;
You specify Simulink data object naming rules on the Code Generation > Symbols
pane of the Configuration Parameters dialog box. To access that pane,
Notice the preconfigured settings on this pane. “Code Generation Pane: Symbols” in
the Simulink Coder documentation describes the fields on this pane and their possible
settings for these procedures.
7-68
Data Definition and Declaration Management
This procedure allows you to change a model's signal names, using the same rule. The
new names will appear as identifiers in the generated code:
1 In the Signal naming menu, click the desired selection. (“Signal naming” explains
the possible selections.) The default is None. If you selected Custom M-function,
go to the next step. Otherwise, click Apply and then generate and inspect code.
2 Write a MATLAB function that changes occurrences of signal names in the model to
appear the way you want as identifiers in the generated code. (An example is shown
in “Define Rules That Change Parameter Names” on page 7-69.)
3 Save the function as a .m file in a folder on the MATLAB path.
4 In the M-function field under Signal naming, type the name of the file you saved
in the previous step.
5 Click Apply and then generate and inspect code.
This procedure allows you to change a model's parameter names, using the same rule.
The new names will appear as identifiers in the generated code:
1 In the Parameter naming field, click the desired selection. (“Parameter naming”
explains the possible selections.) The default is None. If you selected Custom M-
function, go to the next step. Otherwise, click Apply, and proceed to “Define Rules
That Change Signal Names” on page 7-69.
2 Write a MATLAB function that changes occurrences of parameter names in the
model to appear the way you want as identifiers in the generated code. For example,
the code below changes parameter names to make their first letter uppercase, and
their remaining letters lowercase.
function
revisedName = initial_caps_only(name, object)
% INITIAL_CAPS_ONLY: User-defined naming rule causing each
% identifier in the generated code to have initial cap(s).
%
% name: name as spelled in model.
% object: the object of name; includes name's properties.
%
% revisedName: manipulated name returned to MPT for the
code.
%
7-69
7 Data Types
%
:
revisedName = [upper(name(1)),lower(name(2:end))];
:
3 Save the function as a .m file in a folder on the MATLAB path.
4 In the M-function field under Parameter naming, type the name of the file you
saved in the previous step.
5 Click Apply and then define rules applicable to signal names.
This procedure allows you to change a model's parameter names whose storage class
you selected as Define in “Create mpt Data Objects with Data Object Wizard” on page
7-51, using the same rule. The new names will appear as identifiers in the generated
code:
1 In #define naming, click the desired selection. (“#define naming” explains the
possible selections.) The default is None. If you select Custom M-function, go to
the next step. Otherwise, click Apply and proceed to “Define Rules That Change
Parameter Names” on page 7-69.
2 Write a MATLAB function that changes occurrences of the parameter name whose
storage class you specified as Define in “Create mpt Data Objects with Data Object
Wizard” on page 7-51 so that it appears the way you want as an identifier in the
generated code. (An example is shown below.)
3 Save the function as a .m file in a folder on the MATLAB path.
4 In the M-function field under #define naming, type the name of the file you saved
in the previous step.
5 Click Apply and then define rules that change parameter names.
7-70
8
Note: You can create mpt.Signal and mpt.Parameter objects in the base MATLAB
or model workspace. However, if you create the object in a model workspace, the object's
storage class must be set to auto.
The figure below shows an example of the Model Explorer. When you select an
mpt.Parameter or mpt.Signal data object in the middle pane, its properties and
property values display in the rightmost pane.
In the Properties column, the table lists the properties in the order in which they appear
on the Model Explorer.
8-2
MPT Data Object Properties
8-3
8 Module Packaging Tool (MPT) Data Objects
8-4
MPT Data Object Properties
8-5
8 Module Packaging Tool (MPT) Data Objects
8-6
MPT Data Object Properties
8-7
8 Module Packaging Tool (MPT) Data Objects
8-8
MPT Data Object Properties
8-9
8 Module Packaging Tool (MPT) Data Objects
What I noticed when inspecting Change I made to property value What I noticed after
the .c/.cpp file settings regenerating and reinspecting
the file
Example 1: In the Model Explorer, I clicked I notice two differences. One is
Parameter data objects can the data object GAIN. I noticed that now GAIN is declared as
be declared or defined as that the property value for its a variable with the statement
constants. I know that the data Memory section property is set real_T GAIN = 5.0;. The
object GAIN is a parameter. at MemConst. I changed this to second difference is that the
I want this to be declared Default. declaration now is located in
or defined in the .c file as a the MemConst memory section
variable. But I notice that GAIN in the .c or .cpp file.
is declared as a constant by
the statement const real_T
GAIN = 5.0;. Also, this
statement is in the constant
section of the file.
Example 2: I changed the Storage class GAIN is not declared in the .c
I notice again the declaration of selection to Define (Custom). file as a MemConst parameter.
GAIN in the .c file mentioned Rather, it is defined as a
in Example 1. It appears as #define macro by the code
real_T GAIN = 5.0;. But #define GAIN 5.0, and
I have changed my mind. I this is located near the top
want data object GAIN to be of the .c file with the other
#define. preprocessor directives.
Example 3: On the Model Explorer, I notice #define GAIN 5.0 is not
I changed my mind again that the property value for present in this .c file. Instead,
after doing Example 2. I do the Header file property the #include filename.h
want GAIN defined using is blank. I changed this to code appears as a preprocessor
the #define preprocessor filename.h. (I chose the ANSI directive at the top of the file.
directive. But I do not want to C/C++ double quote mechanism
include the #define in this for the #include, but could
file. I know it exists in another have chosen the angle bracket
file and I want to reference that mechanism.) Also, I must make
file. the user-defined filename.h
available to the compiler, placing
it either in the system path or
local directory.
8-10
MPT Data Object Properties
What I noticed when inspecting Change I made to property value What I noticed after
the .c/.cpp file settings regenerating and reinspecting
the file
Example 4: In the Model Explorer, I selected The identifier
I have one more change I the data object data_in. I data_in_alias now appears
want to make. Let us say that noticed that the Alias field in the .c file everywhere
we have declared the data is blank. I changed this to data_in appeared.
object data_in, and that its data_in_alias, which I know
declaration statement in the .c is a valid ANSI C/C++ variable
file reads name.
real_T data_in = 0.0;. I
want to replace this statement
with an alias in the .c file.
8-11
8-12
9
In this section...
“Custom Storage Class Memory Sections” on page 9-3
“Register Custom Storage Classes” on page 9-3
“Custom Storage Class Examples” on page 9-3
During the build process, the storage class specification of a signal, tunable parameter,
block state, or data object specifies how that entity is declared, stored, and represented in
generated code. Note that in the context of the build process, the term “storage class” is
not synonymous with the term “storage class specifier”, as used in the C language.
The Simulink Coder software defines four built-in storage classes for use with targets:
Auto, ExportedGlobal, ImportedExtern, and ImportedExternPointer. These
storage classes provide limited control over the form of the code generated for references
to the data. For example, data of storage class Auto is typically declared and accessed as
an element of a structure, while data of storage class ExportedGlobal is declared and
accessed as unstructured global variables. For information about built-in storage classes,
see “Signals” in the Simulink Coder documentation.
If the built-in storage classes do not provide data representation required by your
application, you can define custom storage classes (CSCs). Embedded Coder (CSCs)
extend the built-in storage classes provided by the Simulink Coder software. CSCs can
provide application-specific control over the constructs required to represent data in an
embedded algorithm. For example, you can use CSCs to:
Custom storage classes affect only code generated for ERT targets. When Configuration
Parameters > Code Generation > Target Selection > System target file specifies
a GRT target, the names of custom storage classes sometimes appear in dialog boxes,
but selecting a CSC is functionally the same as selecting Auto. See “Targets and Code
Formats” for information about ERT and GRT targets.
9-2
Introduction to Custom Storage Classes
See “Create and Edit Memory Section Definitions” on page 9-23 for details about
using the Custom Storage Class designer to define memory sections. While memory
sections are often used with data in custom storage classes, they can also be used with
various other constructs. See “Memory Sections” for more information about using
memory sections with custom storage classes, and complete information about using
memory sections with other constructs.
If you use only predefined CSCs, you do not need to be concerned with CSC registration
files. You cannot add or change CSCs associated with built-in packages and classes, but
you can create your own packages and subclasses, then associate CSCs with those. See
“Custom Storage Class Implementation” on page 9-56 for more information.
9-3
9 Custom Storage Classes
Click the links above, or type the name in the MATLAB Command Window.
9-4
Resources for Defining Custom Storage Classes
• Use MATLAB class syntax to create a data class in a package. You can assign
properties to the data class and add initialization code to enable custom storage
class definition. For complete instructions, see “Define Data Classes” in Simulink
documentation.
• A set of ready-to-use CSCs. These CSCs are designed to be useful in code generation
for embedded systems development. CSC functionality is integrated into the
Simulink.Signal and Simulink.Parameter classes; you do not need to use special
object classes to generate code with CSCs.
• The Custom Storage Class Designer (cscdesigner) tool, which is described in this
chapter. This tool lets you define CSCs that are tailored to your code generation
requirements. The Custom Storage Class Designer provides a graphical user interface
that you can use to implement CSCs. You can use your CSCs in code generation
immediately, without a Target Language Compiler (TLC) or other programming. See
“Design Custom Storage Classes and Memory Sections” on page 9-8 for details.
9-5
9 Custom Storage Classes
You cannot change the CSCs built into the Simulink package, but you can subclass the
package and add CSCs to the subclass, following the steps in “Resources for Defining
Custom Storage Classes” on page 9-5.
Some CSCs in the Simulink package are valid for parameter objects but not signal
objects and vice versa. For example, you can assign the storage class Const to a
parameter but not to a signal, because signal data is not constant. The next table defines
the CSCs built into the Simulink package and shows where each of the CSCs can be
used.
9-6
Simulink Package Custom Storage Classes
9-7
9 Custom Storage Classes
• Load existing custom storage classes and memory sections and view and edit their
properties
• Create new custom storage classes and memory sections
• Create references to custom storage classes and memory sections defined in other
packages
• Copy and modify existing custom storage class and memory section definitions
• Check a custom storage class and memory section definitions
• Preview pseudocode generated from custom storage class and memory section
definitions
• Save custom storage class and memory section definitions
To open the Custom Storage Class Designer for a particular package, type the following
command at the MATLAB prompt:
9-8
Design Custom Storage Classes and Memory Sections
cscdesigner ('mypkg')
When first opened, the Custom Storage Class Designer scans data class packages on
the MATLAB path to detect packages that have a CSC registration file. A message is
displayed while scanning proceeds. When the scan is complete, the Custom Storage Class
Designer window appears:
The Custom Storage Class Designer window is divided into several panels:
• Select package: Lets you select from a menu of data class packages that have CSC
definitions associated with them. See “Select Data Class Package” on page 9-10 for
details.
• Custom Storage Class / Memory Section properties: Lets you select, view, edit,
copy, verify, and perform other operations on CSC definitions or memory section
9-9
9 Custom Storage Classes
definitions. The common controls in the Custom Storage Class / Memory Section
properties panel are described in “Manipulate Custom Storage Classes and Memory
Sections” on page 9-11.
• When the Custom Storage Class tab is selected, you can select a CSC definition
or reference from a list and edit its properties. See “Edit Custom Storage Class
Properties” on page 9-14 for details.
• When the Memory Section tab is selected, you can select a memory section
definition or reference from a list and edit its properties. See “Create and Edit
Memory Section Definitions” on page 9-23 for details.
• Filename: Displays the filename and location of the current CSC registration file,
and lets you save your CSC definition to that file. See “Save Definitions” on page
9-13 for details.
• Pseudocode preview: Displays a preview of code that is generated from objects of
the given class. The preview is pseudocode, since the actual symbolic representation of
data objects is not available until code generation time. See “Preview Generated Code”
on page 9-26 for details.
• Validation result: Displays errors encountered when the currently selected CSC
definition is validated. See “Validate Definitions Category” on page 9-19 for
details.
You need not search for or edit a CSC registration file directly: the Custom Storage Class
Designer locates available CSC registration files. The Select package menu contains
names of data class packages that have a CSC registration file on the MATLAB search
path.
When you select a package, the CSCs and memory section definitions belonging to the
package are loaded into memory and their names are displayed in the scrolling list in the
Custom storage class panel. The name and location of the CSC registration file for the
package is displayed in the Filename panel.
If you select a user-defined package, by default you can use the Custom Storage Class
Designer to edit its custom storage classes and memory sections. If you select a built-
9-10
Design Custom Storage Classes and Memory Sections
in package, you cannot edit its custom storage classes or memory sections. See “Custom
Storage Class Implementation” on page 9-56 for more information.
The Custom Storage Class / Memory Section panel lets you select, view, and (if the
CSC is writable) edit CSC and memory section definitions and references. In the next
figure and the subsequent examples, the selected package is mypkg. Instructions for
creating a user-defined package like mypkg appear in “Design Custom Storage Classes
and Memory Sections”.
The list at the top of the panel displays the definitions/references for the currently
selected package. To select a definition/reference for viewing and editing, click on the
desired list entry. The properties of the selected definition/reference appear in the area
9-11
9 Custom Storage Classes
below the list. The number and type of properties vary for different types of CSC and
memory section definitions. See:
• “Edit Custom Storage Class Properties” on page 9-14 for information about the
properties of the predefined CSCs.
• “Create and Edit Memory Section Definitions” on page 9-23 for information about
the properties of the predefined memory section definitions.
The buttons to the right of the list perform these functions, which are common to both
custom storage classes and memory definitions:
definition_name_n
For example, if you click New, a new custom storage class is created with a default
name:
9-12
Design Custom Storage Classes and Memory Sections
You can now rename the new class by typing the desired name into the Name field, and
specify other fields.
Note: The class name must be a valid MATLAB variable name. See “Variable Names”
Save Definitions
After you have created or edited a CSC or memory section definition or reference,
you must save the changes to the CSC registration file. To do this, click Save in the
Filename panel. When you click Save, the current CSC and memory section definitions
that are in memory are validated, and the definitions are written out.
9-13
9 Custom Storage Classes
If errors occur, they are reported in the Validation result panel. The definitions are
saved whether or not errors exist. However, you should resolve validation errors and
resave your definitions. Trying to use definitions that were saved with validation errors
can cause additional errors. Such problems can occur even it you do not try to use the
specific parts of the definition that contain the validation errors, making the problems
difficult to diagnose.
If you add, change, or delete custom storage class or memory section definitions for a
user-defined class, and objects of that class already exist, you must restart MATLAB to
use the changed definitions and to eliminate obsolete objects. When you save the changed
definitions, a message appears indicating that you must restart MATLAB.
The CSC properties are divided into several categories, selected by tabs. Selecting
a class, and setting property values for that class, can change the available tabs,
properties, and values. As you change property values, the changes in the generated code
is immediately displayed in the Pseudocode preview panel. In most cases, you can
define your CSCs quickly and easily by selecting the Pseudocode preview panel and
using the Validate button frequently.
General Category
Properties in the General category are common to CSCs. In the next figure and the
subsequent examples, the selected custom storage class is ByteField. Instructions for
creating a user-defined custom storage class like ByteField appear in “Manipulate
Custom Storage Classes and Memory Sections” on page 9-11.
9-14
Design Custom Storage Classes and Memory Sections
Properties in the General category, and the possible values for each property, are as
follows:
• Name: The CSC name, selected from the Custom storage class definitions list.
The name cannot be a TLC keyword. Violating this rule causes an error.
• Type: Specifies how objects of this class are stored. Values:
datatype dataname[dimension];
• FlatStructure: Objects of this class are stored as members of a struct. A
Structure Attributes tab is also displayed, allowing you to specify additional
properties such as the struct name. See “Structure Attributes Category” on page
9-18.
• Other: Used for certain data layouts, such as nested structures, that cannot
be generated using the standard Unstructured and FlatStructure custom
storage class types. If you want to generate other types of data, you can create a
new custom storage class from scratch by writing TLC code. See “Define Advanced
Custom Storage Classes Types” on page 9-50 for more information.
• For parameters and For signals: These options let you enable a CSC for use with
only certain classes of data objects. For example, it does not make sense to assign
storage class Const to a Simulink.Signal object. Accordingly, the For signals
option for the Const class is deselected, while the For parameters is selected.
9-15
9 Custom Storage Classes
• Memory section: Selects one of the memory sections defined in the Memory
Section panel. See “Create and Edit Memory Section Definitions” on page 9-23.
• Data scope: Controls the scope of symbols generated for data objects of this class.
Values:
The Macro initialization option is available only for use with unstructured
parameters. It is not available when the class is configured for generation of
structured data, or for signals. If the Data scope value is Imported, a header file
must be specified.
9-16
Design Custom Storage Classes and Memory Sections
Note: The code generator might include dynamic initialization code for signals
and states even if the CSC has Data initialization set to None or Static, if the
initialization is required.
• Data access: Controls whether imported symbols are declared as variables
or pointers. This field is enabled only when Data scope is set to Imported or
Instance-specific. Values:
• Specify: An edit field is displayed to the right of the property. This lets you
specify a header file for exported or imported storage declarations. Specify the full
filename, including the filename extension (such as .h). Use quotes or brackets as
in C code to specify the location of the header file. Leave the edit field empty to not
specify a header file.
• Instance specific: The header file for each data object is defined by the
Header file property of the object. Leave the property undefined to not specify a
header file for that object.
If the Data scope is Exported, specifying a header file is optional. If you specify
a header file name, the custom storage class generates a header file containing the
storage declarations to be exported. Otherwise, the storage declarations are exported
in model.h.
If the Data scope of the class is Imported, and Data initialization is Macro,
you must specify a header file name. A #include directive for the header file is
generated.
9-17
9 Custom Storage Classes
Comments Category
Comments
The Comments panel lets you specify comments to be generated with definitions and
declarations.
Comments must conform to the ANSI C standard (/*...*/). Use \n to specify a new
line.
• Comment rules: If Specify is selected, edit fields are displayed for entering
comments. If Default is selected, comments are generated under control of the code
generation software.
• Type comment: The comment entered in this field precedes the typedef or struct
definition for structured data.
• Declaration comment: Comment that precedes the storage declaration.
• Definition comment: Comment that precedes the storage definition.
The Structure Attributes panel gives you detailed control over code generation for
structs (including bitfields). The Structure Attributes tab is displayed for CSCs whose
Type parameter is set to FlatStructure. The following figure shows the Structure
Attributes panel.
• Struct name: If you select Instance specific, specify the struct name when
configuring each instance of the class.
If you select Specify, an edit field appears for entry of the name of the structure to
be used in the struct definition. Edit fields Type tag, Type token, and Type name
are also displayed.
• Is typedef: When this option is selected a typedef is generated for the struct
definition, for example:
typedef struct {
...
} SignalDataStruct;
9-18
Design Custom Storage Classes and Memory Sections
To validate a CSC definition, select the definition on the Custom Storage Class panel
and click Validate. The Custom Storage Class Designer then checks the definition
for consistency. The Validation result panel displays a errors encountered when the
selected CSC definition is validated. The next figure shows the Validation result panel
with a typical error message:
Validation is also performed whenever CSC definitions are saved. In this case, all CSC
definitions are validated. (See “Save Definitions” on page 9-13.)
9-19
9 Custom Storage Classes
it. Other packages refer to it by pointing to it in its original location. Changes to the
class, including changes to a predefined class in later MathWorks product releases, are
immediately available in every referencing package.
To configure a package to use a custom storage class that is defined in another package:
9-20
Design Custom Storage Classes and Memory Sections
4 In the Custom storage class definitions pane, select the existing definition below
which you want to insert the reference. For example:
A new reference with a default name and properties appears below the previously
selected definition. The new reference is selected, and a Reference tab appears that
shows the reference's initial properties. A typical appearance is:
9-21
9 Custom Storage Classes
6 Use the Name field to enter a name for the new reference. The name must be unique
in the importing package, but can duplicate the name in the source package. The
name cannot be a TLC keyword. Violating this rule causes an error.
7 Set Refer to custom storage class in package to specify the package that
contains the custom storage class you want to reference.
8 Set Custom storage class to reference to specify the custom storage class to be
referenced. Trying to create a circular reference generates an error and leaves the
package unchanged.
9 Click OK or Apply to save the changes to memory. See “Save Definitions” on page
9-13 for information about saving changes permanently.
For example, the next figure shows the custom storage class ConstVolatile imported
from the Simulink package into mypkg, and given the same name that it has in the
source package. Other names could have been used without affecting the properties of
the storage class.
9-22
Design Custom Storage Classes and Memory Sections
You can use Custom Storage Class Designer capabilities to copy, reorder, validate, and
otherwise manage classes that have been added to a class by reference. However, you
cannot change the underlying definitions. You can change a custom storage class only in
the package where it was originally defined.
To change an existing CSC reference, select it in the Custom storage class definitions
pane. The Reference tab appears, showing the current properties of the reference. Make
changes, then click OK or Apply to save the changes to memory. See “Save Definitions”
on page 9-13 for information about saving changes permanently.
9-23
9 Custom Storage Classes
verify memory section definitions. The steps for creating a memory section definition are
essentially the same as for creating a custom storage class definition:
A new memory section definition with a default name appears below the selected
memory section.
5 Set the name and other properties of the memory section.
6 Click OK or Apply.
The next figure shows mypkg with a memory section called MyMemSect:
9-24
Design Custom Storage Classes and Memory Sections
The Memory section definitions list lets you select a memory section definition to
view or edit. The available memory section definitions also appear in the Memory
section name menu in the Custom Storage Class panel. The properties of a memory
section definition are as follows:
• Memory section name: Name of the memory section (displayed in Memory section
definitions list).
• Is const: If selected, a const qualifier is added to the symbol declarations.
9-25
9 Custom Storage Classes
If you click Validate on the Memory Section panel, the Pseudocode preview panel
displays a preview of code that is generated from objects of the given class. The panel
also displays messages (in blue) to highlight changes as they are made. The code preview
changes dynamically as you edit the class properties. The next figure shows a code
preview for the MemConstVolatile memory section.
9-26
Design Custom Storage Classes and Memory Sections
A new reference with a default name and properties appears below the previously
selected definition. The new reference is selected, and a Reference tab appears that
shows the reference's initial properties.
6 Use the Name field to enter a name for the new reference. The name must be unique
in the importing package, but can duplicate the name in the source package.
7 Set Refer to memory section in package to specify the package that contains the
memory section you want to reference.
8 Set Memory section to reference to specify the memory section to be referenced.
Trying to create a circular reference generates an error and leaves the package
unchanged.
9 Click OK or Apply to save the changes to memory. See “Save Definitions” on page
9-13 for information about saving changes permanently.
For example, the next figure shows the memory section MemConstVolatile imported
from the Simulink package into mypkg, and given the same name that it has in the
source package. Other names could have been used without affecting the properties of
the memory section.
9-27
9 Custom Storage Classes
You can use Custom Storage Class Designer capabilities to copy, reorder, validate,
and otherwise manage memory sections that have been added to a class by reference.
However, you cannot change the underlying definitions. You can change a memory
section only in the package where it was originally defined.
9-28
Apply Custom Storage Classes
• To apply a custom storage class to a parameter, you specify the storage class in the
Simulink.Parameter object that defines the parameter in the base workspace.
• To apply a custom storage class to a signal, you specify the storage class in a
Simulink.Signal object that is bound to the signal. You can provide this object in
two ways:
• Create the object in the base workspace, then bind it to the signal as described
in “Symbol Resolution”. When you save the model, you must save the object in a
separate file, as with base workspace objects.
• Use the Signal Properties dialog box to embed the object in the model on the port
where the signal originates. When you save the model, Simulink automatically
saves the embedded signal object as part of the model file.
Most of the GUI techniques, and most of the API techniques, are the same for parameter
and signal objects, and for base workspace and embedded signal objects. Only the initial
steps differ, after which you apply the same GUI or API instructions within the context
that you established in the initial steps.
The following instructions assume that you have already created packages, custom
storage classes, and memory sections, as described in “Design Custom Storage Classes
and Memory Sections” on page 9-8.
9-29
9 Custom Storage Classes
For information about using parameter objects to specify block parameter values, see
“Use Parameter Objects to Specify Parameter Values”. For information about parameter
storage in generated code, see “Parameters”.
ParamName=ParamClass
MyParam =
Simulink.Parameter (handle)
Value: []
9-30
Apply Custom Storage Classes
The object itself is the same in either case; only its location and some of the techniques
for managing it differ. The instructions that begin in this section show you how to create
a signal object in either location using the GUI or API. Later instructions show you how
to specify the custom storage class and custom attributes.
A given signal can be associated with at most one signal object. The signal can refer to
the object more than once, but every reference must resolve to exactly the same object. A
different signal object that has exactly the same properties will not meet the requirement
for uniqueness. A compile-time error occurs if a model associates more than one signal
object with a signal.
Assigning a signal to a non-Auto storage class automatically makes the signal a test
point, overriding the setting of Signal Properties > Logging and accessibility > Test
point. See “Test Points”for more information.
For information about using signal objects to specify signal attributes, see “Using Signal
Objects to Initialize Signals and Discrete States”. For information about signal storage in
generated code, see “Signals”.
9-31
9 Custom Storage Classes
SignalName=SignalClass
MySig =
Simulink.Signal (handle)
CoderInfo: [1x1 Simulink.SignalCoderInfo]
Description: ''
DataType: 'auto'
Min: []
Max: []
DocUnits: ''
Dimensions: -1
9-32
Apply Custom Storage Classes
Complexity: 'auto'
SampleTime: -1
SamplingMode: 'auto'
InitialValue: ''
3 Set parameter attributes other than CoderInfo, which controls custom storage
classes.
4 Give the signal the same name as the signal object, as described in “Signal Names”.
5 Arrange for the signal to resolve to the object, as described in “Symbol Resolution”.
6 Follow the instructions in “Specify Custom Storages Classes Using API” on page
9-42.
• If you use the GUI, you use the Signal Properties dialog box to specify the attributes
you want. The software then creates a Simulink.Signal object and assigns it to the
output port where the signal originates.
• If you use the API, you instantiate Simulink.Signal or a subclass of it, set the
attribute values that you want, and assign the object to the output port where the
signal originates.
In either case, the generated code is the same as if you had created a base workspace
signal object that specified the same name, CSC, and custom attributes as the embedded
signal object. For more information, see “Custom Storage Classes Using Signal Objects”
on page 9-32.
The advantages of using embedded signal objects are that they do not clutter the
base workspace, and they do not need to be saved separately from the model, as base
workspace objects do. When you save a model, Simulink saves embedded signal objects in
the model file, and reloads the objects when you later reload the model.
The disadvantage of embedded signal objects is that you can use such an object only
to specify a custom storage class, custom attributes, and an alias; you must accept the
default values for other signal attributes. You cannot work around this restriction by
providing additional information in a base workspace signal object on the same signal,
because a signal object can have at most one associated signal object, as described in
“Multiple Signal Objects”.
9-33
9 Custom Storage Classes
1 Give the signal a name, which must be a valid ANSI C identifier. Example: MySig.
2 Right-click the signal and choose Properties from the context menu.
3 Do not select Signal name must resolve to Simulink signal object. Selecting
it would require a base workspace signal object, which would conflict with the
embedded signal object.
4 Click the Code Generation tab.
5 The Package is initially ---None---. When a package is not specified, only the
non-custom built-in storage classes defined for both GRT and ERT targets are
available:
9-34
Apply Custom Storage Classes
Applying a storage class when the package is ---None--- sets internal storage
class attributes rather than creating an embedded signal object. For information
about built-in storage classes, see “Signals” in the Simulink Coder documentation.
6 To apply a custom storage class, you must first specify the package where it is
defined. Initially, viewing the Package menu displays only the built-in Simulink
and mpt packages:
9-35
9 Custom Storage Classes
9-36
Apply Custom Storage Classes
Once you have used Refresh in the Signal Properties dialog, Simulink saves the
information for later use, so you do not have to click Refresh again during the
current MATLAB session.
8 Select the package that contains the custom storage class you want to apply, e.g.
Simulink:
9-37
9 Custom Storage Classes
9 Follow the instructions in “Specify Custom Storage Classes Using GUI” on page
9-40.
To delete an embedded signal object with the Model Explorer, delete the name of the
signal to which the object applies, by editing the name in the graphical model or in the
Signal Properties dialog box. Simulink automatically deletes the embedded signal object
as soon as its signal does not have a name.
To provide an embedded signal object using the API, you create the object, set its custom
storage class and custom attributes, then assign the object to the output port on which it
will be embedded.
1 Name the signal if it does not already have a name. The name must be a valid ANSI
C identifier.
9-38
Apply Custom Storage Classes
SignalName=SignalClass
MySig =
Simulink.Signal (handle)
CoderInfo: [1x1 Simulink.SignalCoderInfo]
Description: ''
DataType: 'auto'
Min: []
Max: []
DocUnits: ''
Dimensions: -1
Complexity: 'auto'
SampleTime: -1
SamplingMode: 'auto'
InitialValue: ''
4 Do not set attributes. An embedded signal object can specify only custom storage
class information.
5 Follow the instructions in “Specify Custom Storages Classes Using API” on page
9-42. After specifying the custom storage class, be sure to assign the signal object
to its output port, as described under “Assign Embedded Signal Objects to Output
Ports” on page 9-45.
To change an embedded signal object using the API, you obtain a copy of the object from
the output port on which it is embedded, change the object, then assign the changed
object back to the port.
1 Obtain a copy of the signal object using a handle to the output port. Example:
hps=get_param(gcb,'PortHandles')
hp=hps.Outport(1)
MySig=get_param(hp,'SignalObject')
9-39
9 Custom Storage Classes
2 Change the signal object using the techniques described in “Specify Custom Storages
Classes Using API” on page 9-42. After making the changes, be sure to copy the
signal object to its output port, as described in “Assign Embedded Signal Objects to
Output Ports” on page 9-45.
To delete an embedded signal object with the API, obtain a handle to the output port
where the signal object is embedded, then set the port's SignalObject parameter to []:
hps=get_param(gcb,'PortHandles')
hp=hps.Outport(1)
set_param(hp,'SignalObject',[])
To set the name of a signal to resolve to a Simulink signal object using the API, obtain
the handle to the output port and then set the port's MustResolveToSignalObject
property to on:
hps=get_param(gcb,'PortHandles')
hp=hps.Outport(1)
set_param(hp,'MustResolveToSignalObject', 'on')
After the initial steps, applying a CSC with the GUI is the same for the three cases.
The following instructions show you how to finish applying a CSC with the GUI. The
instructions assume that you have completed one of the previous sets of instructions, and
that the dialog you used to execute those instructions is still open.
The available custom storage classes and custom attributes depend on the package
that you select. The examples in this section assume that you are using the Simulink
package.
9-40
Apply Custom Storage Classes
The dialog that you used to begin the process of applying a CSC with the GUI by
providing an object contains two fields: one for specifying a custom storage class and one
for optionally specifying an alias.
Storage class is Auto because that is the default storage class in the Simulink
package. Other packages may have different defaults. You can specify an Alias whenever
the Storage class is not Auto. If Storage class is Auto, Simulink deletes aliases you
try to specify, leaving the field blank. If you specify an alias, it appears in generated code
instead of the name of the object.
1 View the Storage Class menu, which looks like this for the Simulink package:
Each custom storage class has (custom) suffixed to its name. The storage
classes SimulinkGlobal, ExportedGlobal, ImportedExtern, and
ImportedExternPointer are the built-in non-custom storage classes described in
“Signals” in the Simulink Coder documentation.
2 Choose the desired custom storage class from Storage class, for example, Struct.
3 Provide values for custom attributes. Struct has only one, Struct name. For
example, set Struct name to MyStruct:
9-41
9 Custom Storage Classes
4 Click Apply.
In generated code, data whose storage is controlled by this custom storage class
specification will appear in a structure named MyStruct. See “Generate Code with
Custom Storage Classes” on page 9-46 for an example.
After the initial steps, applying a CSC with the API is the same for the three cases,
except for the case of an assignment for an embedded signal object. The following
instructions show you how to finish applying a CSC with the API. The instructions
assume that you have completed one of the previous sets of instructions, and that the
resulting objects an attributes are unchanged.
The available custom storage classes and custom attributes depend on the package
that you select. The examples in this section assume that you are using the Simulink
package. The examples also assume that the object for which you want to specify a
custom storage class is named MyObj, which is a parameter or signal object that exists in
the base workspace, or a signal object that will be assigned to an output port.
The rest of this section provides information that is specific to custom storage classes
in Embedded Coder. See “Simulink Package Custom Storage Classes” on page 9-6 for a
9-42
Apply Custom Storage Classes
list of the custom storage classes that are built into the Simulink package for use by
Embedded Coder software.
CoderInfo Properties
Each Simulink parameter object or signal object defines properties called CoderInfo
properties. Code generation software uses these properties to control storage class
assignment in the generated code. The CoderInfo properties and their default values
are as follows:
StorageClass: 'Auto'
Alias: ''
CustomStorageClass: 'Default'
CustomAttributes: [1x1 SimulinkCSC.AttribClass_Simulink_Default]
For more information about CoderInfo properties, see “Signals” in the Simulink Coder
documentation.
Whenever you have specified a custom storage class other than Auto, you can specify an
alias by setting the Alias attribute. If you specify an alias, it appears in generated code
instead of the name of the object.
A custom storage class can have properties that define attributes that are specific to
that CSC. Such properties are called instance-specific attributes. For example, if you
specify the Struct custom storage class, you must specify the name of the C language
structure that will store the data. That name is an instance-specific attribute of the
Struct CSC.
9-43
9 Custom Storage Classes
SimulinkCSC.AttribClass_Simulink_Default
1x1 struct array with no fields
MyObj.CoderInfo.CustomAttributes
MATLAB displays:
SimulinkCSC.AttribClass_Simulink_Struct
StructName: ''
MyObj.CoderInfo.CustomAttributes.StructName='MyStruct'
MATLAB displays:
SimulinkCSC.AttribClass_Simulink_Struct
StructName: 'MyStruct'
9-44
Apply Custom Storage Classes
If you are operating on an embedded signal object with the API, you must copy the object
to the port after providing or changing its CoderInfo properties. For example, if MyObj
is a signal object that you want to copy to the output port, enter:
hps=get_param(gcb,'PortHandles')
hp=hps.Outport(1)
set_param(hp,'SignalObject','MyObj')
Subsequent changes to the source object in the base workspace have no effect on the
output port copy, and you can delete the source object:
clear ('MyObj')
9-45
9 Custom Storage Classes
In this section...
“Code Generation Prerequisites” on page 9-46
“Code Generation With Custom Storage Classes” on page 9-46
Otherwise, the code generator ignores CSC specifications and treats data objects as if
their Storage class were Auto.
9-46
Generate Code with Custom Storage Classes
The model contains three named signals: aa, bb, and cc. Using the predefined Struct
custom storage class, the example generates code that packs these signals into a struct
named mySignals. The struct declaration is then exported to externally written code.
To specify the struct, you provide Simulink.Signal objects that specify the Struct
custom storage class, and associate the objects with the signals as described in “Apply
Custom Storage Classes” on page 9-29. The three objects have the same properties. This
figure shows the signal object properties for aa:
The association between identically named model signals and signal objects is formed as
described in “Symbol Resolution”. In this example, the symbols aa, bb, and cc resolve
to the signal objects aa, bb, and cc, which have custom storage class Struct. In the
generated code, storage for the three signals will be allocated within a struct named
mySignals.
9-47
9 Custom Storage Classes
To display the storage class of the signals in the model, select Display > Signals
& Ports > Storage Class in the Simulink editor. The figure below shows the block
diagram with signal data types and signal storage classes displayed.
• model_types.h defines the following struct type for storage of the three signals:
mySignals_type mySignals = {
/* cc */
FALSE,
/* bb */
0,
/* aa */
0
9-48
Generate Code with Custom Storage Classes
};
...
/* Switch: '<Root>/Switch1' */
if(mySignals.cc) {
rtb_Switch1 = mySignals.aa;
} else {
rtb_Switch1 = mySignals.bb;
}
• model.h exports the mySignals Struct variable:
A custom storage class that results in multiple data objects being referenced with a
single variable in the generated code, in the previous example, is called a grouped custom
storage class. In the Simulink package, Bitfield and Struct (shown in the preceding
example) are grouped CSCs. Data grouped by a CSC is referred to as grouped data.
Note: If you use a grouped custom storage class, you cannot specify its properties on an
instance-specific basis. This is because a grouped custom storage class combines multiple
pieces of data into a single data structure. Data in this structure must have the same
properties such as Header file, Data scope, and Data initialization.
9-49
9 Custom Storage Classes
Introduction
Certain data layouts, such as nested structures, cannot be generated using the standard
Unstructured and FlatStructure custom storage class types. You can define an
advanced custom storage class if you want to generate other types of data. Creating
advanced CSCs requires understanding TLC programming and using a special advanced
mode of the Custom Storage Class Designer. This sections explain how to define
advanced CSC types.
For example, the ExportToFile custom storage class requires that you set the
CoderInfo.CustomAttributes.HeaderFile property to specify a .h file used for
exporting each piece of data. See “Simulink Package Custom Storage Classes” on page
9-6 for further information on instance-specific properties.
9-50
Define Advanced Custom Storage Classes Types
Note: If you rename or remove custom attributes, you may need to manually edit the
csc_registration file for the associated package to remove references to the custom
attributes that you renamed or removed.
1 Create a tlc directory inside your package's +directory (if it does not already exist).
The naming convention to follow is
+PackageName/tlc
2 Copy TEMPLATE_v1.tlc (or another CSC template) from matlabroot/toolbox/
rtw/targets/ecoder/csc_templates into your tlc directory to use as a starting
point for defining your custom storage class.
3 Write your TLC code, following the comments in the CSC template file. Comments
describe how to specify code generation for data of your custom storage class (for
example, how data structures are to be declared, defined, and whether they are
accessed by value or by reference).
Alternatively, you can copy a custom storage class TLC file from another existing
package as a starting point for defining your custom storage class.
The advanced mode supports selection of an additional storage class Type, designated
Other. The Other type is designed to support special CSC types that cannot be
accommodated by the standard Unstructured and FlatStructure custom storage
class types. The Other type cannot be assigned to a CSC except when the Custom
Storage Class Designer is in advanced mode.
9-51
9 Custom Storage Classes
1 Launch the Custom Storage Class Designer in advanced mode by typing the
following command at the MATLAB prompt:
cscdesigner -advanced
2 Select your package and create a new custom storage class.
3 Set the Type of the custom storage class to Other. Note that when you do this, the
Other Attributes pane is displayed. This pane is visible only for CSCs whose Type
is set to Other.
• Is grouped: Select this option if you intend to combine multiple data objects of
this CSC into a single variable in the generated code. (for example, a struct).
• TLC file name: Enter the name of the TLC file corresponding to this custom
storage class. The location of the file is assumed to be in the /tlc subdirectory
for the package, so you should not enter the path to the file.
• CSC attributes class name: (optional) If you created a custom attributes class
corresponding to this custom storage class, enter the full name of the custom
attributes class. (see “Create Custom Attributes Classes for Custom Storage
Classes” on page 9-50).
5 Set the remaining properties on the General and Comments panes based on the
layout of the data that you wish to generate (as defined in your TLC file).
9-52
GetSet Custom Storage Class
The GetSet custom storage class is designed primarily for use with the state of the Data
Store Memory block. However, GetSet is capable of handling signals other than data
stores, and is supported for the outputs of most built-in blocks provided by MathWorks.
For more about the definition of the GetSet storage class, look at its associated TLC code
in the file:
matlabroot\toolbox\simulink\simulink\@Simulink\tlc\GetSet.tlc
Property Description
GetFunction String that specifies the name of a function call to read data.
SetFunction String that specifies the name of a function call to write data.
HeaderFile String that specifies the name of a header (.h) file to add as an
(optional) #include in the generated code.
9-53
9 Custom Storage Classes
For example, if the GetFunction of signal X is specified as 'get_X' then the generated
code calls get_X() wherever the value of X is used. Similarly, if the SetFunction of
signal X is specified as 'set_X' then the generated code calls set_X(value) wherever
the value of X is assigned.
If you omit the HeaderFile property for a GetSet data object, you must specify
a header file by an alternative means, such as the Header file field of the Code
Generation > Custom Code pane of the Configuration Parameters dialog box.
Otherwise, the generated code might not compile or might function improperly.
For wide signals, an additional index argument is passed, so the calls to the get and set
functions are get_X(idx) and set_X(idx, value) respectively.
9-54
GetSet Custom Storage Class
The following specifications configure the signal object X to use the GetSet custom
storage class:
X = Simulink.Signal;
X.CoderInfo.StorageClass = 'Custom';
X.CoderInfo.CustomStorageClass = 'GetSet';
X.CoderInfo.CustomAttributes.GetFunction = 'get_X';
X.CoderInfo.CustomAttributes.SetFunction = 'set_X';
X.CoderInfo.CustomAttributes.HeaderFile = 'user_file.h';
The GetSet CSC appears as follows in the code generated for the model:
void getset_csc_step(void)
{
/* local block i/o variables */
real_T rtb_DSRead_o;
/* DataStoreRead: '<Root>/DSRead' */
rtb_DSRead_o = get_X();
/* Outport: '<Root>/Out1' */
getset_csc_Y.Out1 = rtb_DSRead_o;
}
Note that the code uses a local variable rtb_DSRead_o rather than multiple calls to the
get_X function. This technique increases code efficiency and prevents changes to the
value within a simulation step.
9-55
9 Custom Storage Classes
The file that defines a package's custom storage classes is called a CSC registration
file. The file is named csc_registration and resides in the +package directory that
defines the package. A CSC registration file can be a P-file (csc_registration.p) or a
MATLAB file (csc_registration.m). A built-in package defines custom storage classes
in both a P-file and a functionally equivalent MATLAB file. A user-defined package
initially defines custom storage classes only in a MATLAB file.
P-files take precedence over MATLAB files, so when MATLAB looks for a package's CSC
registration file and finds both a P-file and a MATLAB file, MATLAB loads the P-file
and ignores the MATLAB file. The capabilities and tools, including the Custom Storage
Class Designer, then use the CSC definitions stored in the P-file. P-files cannot be edited,
so CSC Designer editing capabilities are disabled for CSCs stored in a P-file. If a P-file
does not exist, MATLAB loads CSC definitions from the MATLAB file. MATLAB files are
editable, so CSC Designer editing capabilities are enabled for CSCs stored in a MATLAB
file.
Because CSC definitions for a built-in package exist in both a P-file and a MATLAB
file, they are uneditable. You can make the definitions editable by deleting the P-file,
but it is not recommended to modify built-in CSC registration files or other files under
matlabroot. The preferred technique is to create packages, data classes, and custom
storage classes, as described in “Define Data Classes” in the Simulink documentation.
The CSC Designer saves CSC definitions for user-defined packages in a MATLAB file,
so the definitions are editable. You can make the definitions uneditable by using the
pcode function to create an equivalent P-file, which will then shadow the MATLAB
file. However, you should preserve the MATLAB file if you may need to make further
changes, because you cannot modify CSC definitions that exist only in a P-file.
You can also use tools or techniques other than the Custom Storage Class Designer to
create and edit MATLAB files that define CSCs. However, that practice is vulnerable
to syntax errors and can give unexpected results. When MATLAB finds an older P-file
that shadows a newer MATLAB file, it displays a warning in the MATLAB Command
Window.
9-56
Custom Storage Class Limitations
• If data is assigned a grouped CSC, such as Struct or Bitfield, the CSC's Data
scope property must be Imported and the data declaration must be provided in a
user-supplied header file. See “Grouped Custom Storage Classes” on page 9-49 for
more information about grouped CSCs.
• If data is assigned an ungrouped CSC, such as Const, and the data's Data scope
property is Exported, its Header file property must be unspecified. This results
in the data being exported with the standard header file, model.h. Note that for
ungrouped data, the Data scope and Header file properties are either specified
by the selected CSC, or as one of the data object's instance-specific properties.
9-57
9-58
10
Note: User-defined packages that you add to the list must contain a Simulink.Signal
subclass named Signal and a Simulink.Parameter subclass named Parameter.
To register Data Object Wizard user package customizations, use the Simulink
customization file sl_customization.m. This file is a mechanism that allows you to
use MATLAB code to perform customizations of the standard Simulink user interface.
The Simulink software reads the sl_customization.m file, if present on the MATLAB
path, when it starts and the customizations specified in the file are applied to the
Simulink session. For more information on the sl_customization.m customization file,
see “Registering Customizations”.
10-2
Register User Packages Using sl_customization.m
function sl_customization(cm)
As a starting point for your customizations, the sl_customization function must first
get the default (factory) customizations, using the following assignment statement:
hObj = cm.slDataObjectCustomizer;
You then invoke methods to register your customizations. The customization manager
object includes the following methods for registering DOW user package customizations:
• addUserPackage(hObj, packageName)
addUserPackage(hObj, cellArrayOfStrings)
Adds the specified user package(s) to the top of the package list, as displayed in the
Choose package for selected data objects pull-down list in Data Object Wizard.
• moveUserPackageToTop(hObj, packageName)
Moves the specified user package to the top of the package list, as displayed in the
Choose package for selected data objects pull-down list in Data Object Wizard.
• moveUserPackageToEnd(hObj, packageName)
Moves the specified user package to the end of the package list, as displayed in the
Choose package for selected data objects pull-down list in Data Object Wizard.
• removeUserPackage(hObj, packageName)
Replaces the entire package list with a specified list of user packages.
Your instance of the sl_customization function should use these methods to register
DOW user package customizations for your Simulink installation.
10-3
10 User Package Registration
The Simulink software reads the sl_customization.m file when it starts. If you
subsequently change the file, in order to use your changes, you must restart your
Simulink session or enter the following command at the MATLAB command line:
sl_refresh_customizations
10-4
User Package Customization Using sl_customization.m
function sl_customization(cm)
% Register user customizations
end
If you include the above file on the MATLAB path of the Simulink installation that you
want to customize, the specified customizations will appear in Data Object Wizard. For
example, you could view the customizations as follows:
10-5
10 User Package Registration
4 In the Data Object Wizard dialog box, click the Find button to generate a list of one
or more data objects.
5 Examine the Choose package for selected data objects drop-down list, noting
the impact of the changes specified in sl_customization.m for User Package
Customizations.
To replace the entire Data Object Wizard package list with a specified list of user
packages, you can use a method invocation similar to the following:
hObj.setUserPackages({'myPackage1', 'ECoderDemos', 'mpt'});
10-6
11
In this section...
“About Function Prototype Control” on page 11-2
“Configure Function Prototypes Using Graphical Interfaces” on page 11-3
“Sample Procedure for Configuring Function Prototypes” on page 11-11
“Configure Function Prototypes Programmatically” on page 11-16
“Sample Script for Configuring Function Prototypes” on page 11-20
“Verify Generated Code for Customized Functions” on page 11-20
“Function Prototype Control Limitations” on page 11-21
(For more detailed information about the default calling interface for the model_step
function, see the model_step reference page.)
The Configure Model Functions button on the Interface pane provides you flexible
control over the model function prototypes that are generated for your model. Clicking
Configure Model Functions launches a Model Interface dialog box (see “Configure
Function Prototypes Using Graphical Interfaces” on page 11-3). Based on the
Function specification value you specify for your model function (supported values
include Default model initialize and step functions and Model specific
C prototypes), you can preview and modify the function prototypes. Once you validate
11-2
Function Prototype Control
and apply your changes, you can generate code based on your function prototype
modifications.
For more information about using the Configure Model Functions button and the
Model Interface dialog box, see “Sample Procedure for Configuring Function Prototypes”
on page 11-11 and the model rtwdemo_fcnprotoctrl, which is preconfigured to
demonstrate function prototype control.
You can also control model function prototypes for nonvirtual subsystems, if you generate
subsystem code using right-click build. To launch the Model Interface for subsystem
dialog box, use the RTW.configSubsystemBuild function.
Right-click building the subsystem generates the step and initialization functions
according to the customizations you make. For more information, see “Configure
Function Prototypes for Nonvirtual Subsystems” on page 11-8.
For limitations that apply, see “Function Prototype Control Limitations” on page
11-21.
Clicking the Configure Model Functions button on the Interface pane of the
Configuration Parameters dialog box launches the Model Interface dialog box. This
dialog box is the starting point for configuring the model function prototypes that
are generated during code generation for ERT-based Simulink models. Based on the
Function specification value you select for your model function (supported values
include Default model initialize and step functions and Model specific
C prototypes), you can preview and modify the function prototype. Once you validate
and apply your changes, you can generate code based on your function prototype
modifications.
11-3
11 Function and Class Interfaces
The figure below shows the Model Interface dialog box in the Default model
initialize and step functions view.
The Default model initialize and step functions view allows you to validate
and preview the predicted default model step and initialization function prototypes.
To validate the default function prototype configuration against your model, click the
Validate button. If the validation succeeds, the predicted step function prototype
appears in the Step function preview subpane.
Note: You cannot use the Default model initialize and step functions view
to modify the function prototype configuration.
11-4
Function Prototype Control
To begin configuring your function control prototype configuration, click the Get Default
Configuration button. This activates and initializes the function names and properties
in the Configure model initialize and step functions subpane, as shown below.
If you click Get Default Configuration again later, only the properties of the step
function arguments are reset to default values.
11-5
11 Function and Class Interfaces
11-6
Function Prototype Control
Parameter Description
Step function name Name of the model_step function.
Initialize function name Name of the model_initialize function.
11-7
11 Function and Class Interfaces
Parameter Description
Qualifier (optional) Specifies a const type qualifier for a function argument.
The available values are dependent on the Category
specified. When you change the Category, if the specified
type is not available, the Qualifier changes to none. The
possible values are:
• none
• const (value)
• const* (value referenced by the pointer)
• const*const (value referenced by the pointer and the
pointer itself)
The Step function preview subpane provides a preview of how your step function
prototype is interpreted in generated code. The preview is updated dynamically as you
make modifications.
You can control step and initialization function prototypes for nonvirtual subsystems
in ERT-based Simulink models, if you generate subsystem code using right-click build.
Function prototype control is supported for the following types of nonvirtual blocks:
• Triggered subsystems
11-8
Function Prototype Control
• Enabled subsystems
• Enabled trigger subsystems
• While subsystems
• For subsystems
• Stateflow blocks
• MATLAB function block
To launch the Model Interface for Subsystem dialog box, open the model containing the
subsystem and invoke the RTW.configSubsystemBuild function.
The Model Interface dialog box for modifying the model-specific C prototypes for the
rtwdemo_counter/Amplifier subsystem appears as follows:
11-9
11 Function and Class Interfaces
Right-click building the subsystem generates the step and initialization functions
according to the customizations you make.
11-10
Function Prototype Control
You can close the report window after you have examined the generated code.
Optionally, you can save rtwdemo_counter.c and other generated files to a
different location for later comparison.
5 From the rtwdemo_counter model, open the Configuration Parameters dialog box.
6 Navigate to the Code Generation > Interface pane and click the Configure
Model Functions button. The Model Interface dialog box appears.
7 In the initial (Default model initialize and step funtions) view of the
Model Interface dialog box, click the Validate button to validate and preview the
default function prototype for the rtwdemo_counter_step function. The function
prototype arguments under Step function preview should correspond to the
default prototype in step 4.
11-11
11 Function and Class Interfaces
8 In the Model Interface dialog box, set Function specification field to Model
specific C prototypes. Making this selection switches the dialog box from
the Default model initialize and step functions view to the Model
specific C prototypes view.
11-12
Function Prototype Control
11-13
11 Function and Class Interfaces
11-14
Function Prototype Control
11 In the Configure model initialize and step functions subpane, in the row for the
Input argument, change the value of Category from Value to Pointer and change
the value of Qualifier from none to const *. The preview reflects your changes.
11-15
11 Function and Class Interfaces
12 Click the Validate button to validate the modified function prototype. The
Validation subpane displays a message that the validation succeeded.
13 Click OK to exit the Model Interface dialog box.
14 Generate code for the model. When the build completes, the code generation report
for rtwdemo_counter appears.
15 In the code generation report, click the link for rtwdemo_counter.c.
16 Locate and examine the generated code for the rtwdemo_counter_custom and
rtwdemo_counter_cust_init functions:
/* Model step function */
void rtwdemo_counter_custom(const int32_T *arg_Input, int32_T *arg_Output)
{
...
}
17 Verify that the generated code is consistent with the function prototype
modifications that you specified in the Model Interface dialog box.
11-16
Function Prototype Control
5 If validation succeeds, save your model and then generate code using the
rtwbuild function.
• Modify and validate an existing function prototype
You can use other function prototype control functions on the returned handle
only if the test isa(obj,'RTW.ModelSpecificCPrototype') returns 1. If the
model does not have a function prototype configuration, the function returns [].
If the function returns a handle to an object of type RTW.FcnDefault, you cannot
modify the existing function prototype.
2 Use the Get and Set functions listed in Function Prototype Control Functions
to test and reset such items as the function names, argument names, argument
positions, argument categories, and argument type qualifiers.
3 Validate the function prototype using
RTW.ModelSpecificCPrototype.runValidation.
4 If validation succeeds, save your model and then generate code using the
rtwbuild function.
• Create and validate a new function prototype, starting with default
configuration information from your Simulink model
11-17
11 Function and Class Interfaces
6 If validation succeeds, save your model and then generate code using the
rtwbuild function.
• Reset the model function prototype to the default ERT function
configuration Create an object of the ERT default function signature. Reset
the model function prototype and undo any custom settings, by calling the
RTW.FcnDefault method, attachToModel, as follows:
obj = RTW.FcnDefault;
obj.attachToModel(model);
model must be a loaded ERT-based model.
Note: You should not use the same model-specific C function prototype object across
multiple models. If you do, changes that you make to the step and initialization function
prototypes in one model are propagated to other models, which is usually not desirable.
Function Description
RTW.ModelSpecificCPrototype.addArgConf Add step function argument configuration
information for Simulink model port to
model-specific C function prototype
RTW.ModelSpecificCPrototype.attachToModel Attach model-specific C function prototype
to loaded ERT-based Simulink model
RTW.ModelSpecificCPrototype.getArgCategoryGet step function argument category for
Simulink model port from model-specific C
function prototype
RTW.ModelSpecificCPrototype.getArgName Get step function argument name for
Simulink model port from model-specific C
function prototype
RTW.ModelSpecificCPrototype.getArgPositionGet step function argument position for
Simulink model port from model-specific C
function prototype
Get step function argument type qualifier
RTW.ModelSpecificCPrototype.getArgQualifier
for Simulink model port from model-specific
C function prototype
11-18
Function Prototype Control
Function Description
RTW.ModelSpecificCPrototype.getDefaultConfGet default configuration information for
model-specific C function prototype from
Simulink model to which it is attached
Get function names from model-specific C
RTW.ModelSpecificCPrototype.getFunctionName
function prototype
RTW.ModelSpecificCPrototype.getNumArgs Get number of step function arguments from
model-specific C function prototype
RTW.ModelSpecificCPrototype.getPreview Get model-specific C function prototype code
previews
RTW.configSubsystemBuild Launch GUI to configure C function
prototype or C++ class interface for right-
click build of specified subsystem
RTW.getFunctionSpecification Get handle to model-specific C function
prototype object
RTW.ModelSpecificCPrototype.runValidation Validate model-specific C function prototype
against Simulink model to which it is
attached
RTW.ModelSpecificCPrototype.setArgCategorySet step function argument category for
Simulink model port in model-specific C
function prototype
RTW.ModelSpecificCPrototype.setArgName Set step function argument name for
Simulink model port in model-specific C
function prototype
RTW.ModelSpecificCPrototype.setArgPositionSet step function argument position for
Simulink model port in model-specific C
function prototype
Set step function argument type qualifier
RTW.ModelSpecificCPrototype.setArgQualifier
for Simulink model port in model-specific C
function prototype
Set function names in model-specific C
RTW.ModelSpecificCPrototype.setFunctionName
function prototype
11-19
11 Function and Class Interfaces
11-20
Function Prototype Control
• Function prototype control supports only step and initialization functions generated
from a Simulink model.
•
Function prototype control supports only single-instance implementations. For
standalone targets, you must set Code interface packaging to Nonreusable
function (on the Code Generation > Interface pane of the Configuration
Parameters dialog box). For model reference targets, you must select One for the
Total number of instances allowed per top model parameter (on the Model
Referencing pane of the Configuration Parameters dialog box).
• For model reference targets, if Code interface packaging is set to Reusable
function, the code generator ignores the setting.
• You must select the Single output/update function parameter (on the Interface
pane of the Configuration Parameters dialog box).
• Function prototype control does not support multitasking models. Multirate models
are supported, but you must configure the models for single-tasking.
• You must configure root-level inports and outports to use Auto storage classes.
• Do not control function prototypes with the static ert_main.c provided by
MathWorks. Specifying a function prototype control configuration other than the
default creates a mismatch between the generated code and the default static
ert_main.c.
• The code generator removes the data structure for the root inports of the model unless
a subsystem implemented by a nonreusable function uses the value of one or more of
the inports.
• The code generator removes the data structure for the root outports of the model
except when you enable MAT-file logging, or if the sample time of one or more of the
outports is not the fundamental base rate (including a constant rate).
• If you copy a subsystem block and paste it to create a new block in either a new model
or the same model, the function prototype control interface information from the
original subsystem block does not copy to the new subsystem block.
• If you have a Stateflow license, for a Stateflow chart that uses a model root inport
value, or that calls a subsystem that uses a model root inport value, you must do one
of the following to generate code:
11-21
11 Function and Class Interfaces
• Clear the Execute (enter) Chart At Initialization check box in the Stateflow
chart.
• Make the Stateflow function a nonreusable function.
• Insert a Simulink Signal Conversion block immediately after the root inport. In
the Signal Conversion block parameters dialog box, select Exclude this block
from 'Block reduction' optimization.
• If a model root inport value connects to a Simscape conversion block, you must
insert a Simulink Signal Conversion block between the root inport and the Simscape
conversion block. In the Signal Conversion block parameters dialog box, select
Exclude this block from 'Block reduction' optimization.
11-22
C++ Class Interface Control
C++ class encapsulation also works for right-click builds of nonvirtual subsystems.
(For information on requirements that apply, see “Configure C++ Class Interfaces for
Nonvirtual Subsystems” on page 11-42.)
If you have an Embedded Coder license and you have selected an ERT target for your
model, you can use additional Code Generation > Interface pane parameters in
the Configuration Parameter dialog box to customize and control the generated C++
class interface to model code. The general procedure for generating custom C++ class
interfaces to model code is as follows:
1 Configure your model to use an ert.tlc system target file provided by MathWorks.
2 Select the C++ language for your model.
11-23
11 Function and Class Interfaces
To get started with an example, see “Simple Use of C++ Class Control” on page 11-24.
For more details about customizing C++ class interfaces for your model code, see
“Customize C++ Class Interfaces Using Graphical Interfaces” on page 11-30 and
“Customize C++ Class Interfaces Programmatically” on page 11-42. For limitations
that apply, see “C++ Class Interface Control Limitations” on page 11-48.
Note: For an example of C++ class code generation, see the example model
rtwdemo_cppclass.
Note: For details about setting C++ class parameters, see the sections that follow this
example, beginning with “Customize C++ Class Interfaces Using Graphical Interfaces”
on page 11-30.
1 Open a model for which you would like to generate C++ class code interfaces. This
example uses the model rtwdemo_counter.
2 Configure the model to use an ert.tlc system target file provided by MathWorks.
For example, open the Configuration Parameters dialog box, go to the Code
Generation pane, select a target value from the System target file menu, and
click Apply.
3 On the Code Generation pane of the Configuration Parameters dialog box, set the
Language parameter to C++.
11-24
C++ Class Interface Control
On the Code Generation > Interface pane, check that the Code interface
packaging parameter is set to C++ class.
Click Apply.
Note: To immediately generate the default style of C++ class code, without exploring
the related model configuration options, skip steps 4–8 and go directly to step 9.
4 Go to the Interface pane of the Configuration Parameters dialog box and examine
the Code interface subpane.
When you select C++ class code interface packaging for your model, additional
C++ class interface controls become available in the Code interface subpane.
See “Configure Code Interface Options” on page 11-31 for descriptions of
these controls. You might want to modify the default settings according to your
application.
5 Click the Configure C++ Class Interface button. This action opens the Configure
C++ class interface dialog box, which allows you to configure the step method for
your generated model class. The dialog box initially displays a view for configuring a
11-25
11 Function and Class Interfaces
void-void style step method (passing no I/O arguments) for the model class. In this
view, you can specify the model class name, step method name, and namespace for
your model.
See “Configure Step Method for Your Model Class” on page 11-35 for descriptions
of these controls.
Note: If the void-void interface style meets your needs, you can skip steps 6–8 and
go directly to step 9.
6 If you want root-level model input and output to be arguments on the step method,
select the value I/O arguments step method from the Function specification
menu. The dialog box displays a view for configuring an I/O arguments style step
method for the model class.
11-26
C++ Class Interface Control
See “Configure Step Method for Your Model Class” on page 11-35 for descriptions
of these controls.
7 Click the Get Default Configuration button. This action causes a Configure C
++ class interface subpane to appear in the dialog box. The subpane displays the
initial interface configuration for your model, which provides a starting point for
further customization.
11-27
11 Function and Class Interfaces
See “Passing I/O Arguments” on page 11-37 for descriptions of these controls.
8 Perform this optional step only if you want to customize the configuration of the I/O
arguments generated for your model step method.
Note: If you choose to skip this step, you should click Cancel to exit the dialog box.
If you choose to perform this step, first you must check that the required option
Remove root level I/O zero initialization is selected on the Optimization pane,
and then navigate back to the I/O arguments step method view of the Configure
C++ class interface dialog box.
Now you can use the dialog box controls to configure I/O argument attributes.
For example, in the Configure C++ class interface subpane, in the row for the
Input argument, you can change the value of Category from Value to Pointer
and change the value of Qualifier from none to const *. The preview updates to
reflect your changes. Click the Validate button to validate the modified interface
configuration.
Continue modifying and validating until you are satisfied with the step method
configuration.
11-28
C++ Class Interface Control
11-29
11 Function and Class Interfaces
Note: If you configured custom I/O arguments for the model step method (optional
step 8), examine the generated code for the step method in rtwdemo_counter.h and
rtwdemo_counter.cpp. The arguments should reflect your changes. For example, if
you performed the Input argument modifications in step 8, the input argument should
appear as const int32_T *arg_Input.
11-30
C++ Class Interface Control
To select C++ class code interface packaging, in the Configuration Parameters dialog
box, on the Code Generation pane, set the Language parameter to C++. Then, in
the Code Generation > Interface pane, check that the Code interface packaging
parameter is set to C++ class:
• Disables model configuration options that C++ class does not support. For details,
see “C++ Class Interface Control Limitations” on page 11-48.
• Adds additional C++ class interface parameters, which are described in the next
section.
When you select C++ class code interface packaging for your model, the Code
interface parameters shown below are displayed on the Interface pane.
11-31
11 Function and Class Interfaces
Specifies the severity level for diagnostics displayed when a model violates
requirements for generating multi-instance code.
11-32
C++ Class Interface Control
Specifies whether to omit the error status field from the generated real-time model
data structure rtModel (off by default). Selecting this option reduces memory usage.
Be aware that selecting this option can cause the code generator to omit the rtModel
data structure from generated code.
• Combine signal/state structures
Specifies whether to combine global block signals and global state data into one data
structure in the generated code (off by default). Selecting this option reduces RAM
and improves readability of the generated code.
• Block parameter visibility
Specifies whether to generate internal data structures, such as Block I/O, DWork
vectors, Runtime model, Zero-crossings, and continuous states, as public, private,
or protected data members of the C++ model class (private by default).
• Block parameter access
Specifies whether to generate access methods for block parameters for the C++ model
class (None by default). You can select noninlined access methods (Method) or inlined
access methods (Inlined method).
• Internal data access
Specifies whether to generate access methods for internal data structures, such as
Block I/O, DWork vectors, Runtime model, Zero-crossings, and continuous states,
for the C++ model class (None by default). You can select noninlined access methods
(Method) or inlined access methods (Inlined method).
• External I/O access
Specifies whether to generate access methods for root-level I/O signals for the C++
model class (None by default). If you want to generate access methods, you have the
following options:
11-33
11 Function and Class Interfaces
• Generate either per-signal or structure-based access methods. That is, you can
generate a series of set and get methods on a per-signal basis, or generate just one
set method that takes the address of an external input structure as an argument
and, for external outputs (if applicable), just one get method that returns a
reference to an external output structure. The generated code for structure-based
access methods has the following general form:
class ModelClass {
...
// Root inports set method
void setExternalInputs(const ExternalInputs* pExternalInputs);
Note: This parameter affects generated code only if you are using the default
(void-void style) step method for your model class; not if you are explicitly passing
arguments for root-level I/O signals using an I/O arguments style step method. For
more information, see “Passing No Arguments (void-void)” on page 11-35 and
“Passing I/O Arguments” on page 11-37.
• Generate destructor
Specifies whether to generate a destructor for the C++ model class (on by default).
• Use dynamic memory allocation for model block instantiation
For a model containing Model blocks, specifies whether generated code should use
dynamic memory allocation, during model object registration, to instantiate objects
for referenced models configured with a C++ class interface (off by default). If you
select this option, during instantiation of an object for the top model in a model
reference hierarchy, the generated code uses the operator new to instantiate objects
for referenced models.
Selecting this option frees a parent model from having to maintain information about
referenced models beyond its direct children. Clearing this option means that a parent
model maintains information about its referenced models, including its direct and
indirect children.
Note:
11-34
C++ Class Interface Control
of new. You must provide code to catch and process the bad_alloc exception in
case an out-of-memory error occurs for a new call during construction of a top
model object.
• If Use dynamic memory allocation for model block instantiation is
selected and the base model contains a Model block, the build process might
generate copy constructor and assignment operator functions in the private
section of the model class. The purpose of the functions is to prevent pointer
members within the model class from being copied by other code. For more
information, see “Model Class Copy Constructor and Assignment Operator” on
page 11-47.
• Configure C++ Class Interface
Opens the Configure C++ class interface dialog box, which allows you to configure the
step method for your model class. For more information, see “Configure Step Method
for Your Model Class” on page 11-35.
To configure the step method for your model class, on the Code Generation > Interface
pane, click the Configure C++ Class Interface button, which is available when
you select C++ class code interface packaging for your model. This action opens the
Configure C++ class interface dialog box, where you can configure the step method for
your model class in either of two styles:
Note: The void-void style of step method specification supports single-rate models
and multirate models, while the I/O arguments style supports single-rate models and
multirate single-tasking models.
The Configure C++ class interface dialog box initially displays a view for configuring a
void-void style step method for the model class.
11-35
11 Function and Class Interfaces
Allows you to specify a step method name other than the default, step.
• Class name
Allows you to specify a model class name other than the default, modelModelClass.
• Namespace
Allows you to specify a namespace for the model class. If specified, the namespace
is emitted in the generated code for the model class. The Namespace parameter
provides a means of scoping C++ model classes. In a model reference hierarchy, you
can specify a different namespace for each referenced model.
• Step function preview
Displays a preview of the model step function prototype as currently configured. The
preview display is dynamically updated as you make configuration changes.
11-36
C++ Class Interface Control
• Validate
Validates your current model step function configuration. The Validation pane
displays the status and an explanation of any failure.
If you select I/O arguments step method from the Function specification menu,
the dialog box displays a view for configuring an I/O arguments style step method for the
model class.
Note: To use the I/O arguments style step method, you must select the option Remove
root level I/O zero initialization on the Optimization pane of the Configuration
Parameters dialog box.
11-37
11 Function and Class Interfaces
Click this button to get the initial interface configuration that provides a starting
point for further customization.
• Step function preview
Displays a preview of the model step function prototype as currently configured. The
preview dynamically updates as you make configuration changes.
• Validate
Validates your current model step function configuration. The Validation pane
displays the status and an explanation of any failure.
11-38
C++ Class Interface Control
When you click Get Default Configuration, the Configure C++ class interface
subpane appears in the dialog box, displaying the initial interface configuration. For
example:
Allows you to specify a step method name other than the default, step.
• Class name
Allows you to specify a model class name other than the default, modelModelClass.
• Namespace
Allows you to specify a namespace for the model class. If specified, the namespace
is emitted in the generated code for the model class. The Namespace parameter
provides a means of scoping C++ model classes. In a model reference hierarchy, you
can specify a different namespace for each referenced model.
• Order
Displays the numerical position of each argument. Use the Up and Down buttons to
change argument order.
• Port Name
Displays the port name of each argument (not configurable using this dialog box).
• Port Type
Displays the port type, Inport or Outport, of each argument (not configurable using
this dialog box).
• Category
11-39
11 Function and Class Interfaces
Displays the passing mechanism for each argument. To change the passing
mechanism for an argument, select Value, Pointer, or Reference from the
argument's Category menu.
• Argument Name
Displays the name of each argument. To change an argument name, click in the
argument's Argument name field, position the cursor for text entry, and enter the
new name.
• Qualifier
Displays the const type qualifier for each argument. To change the qualifier for
an argument, select an available value from the argument's Qualifier menu. The
possible values are:
• none
• const (value)
• const* (value referenced by the pointer)
• const*const (value referenced by the pointer and the pointer itself)
• const & (value referenced by the reference)
Tip When a model includes a referenced model, the const type qualifier for the root
input argument of the referenced model's specified step function interface is set to none
and the qualifier for the source signal in the referenced model's parent is set to a value
other than none, code generation honors the referenced model's interface specification by
generating a type cast that discards the const type qualifier from the source signal. To
override this behavior, add a const type qualifier to the referenced model.
Embedded Coder provides namespace control for scoping model classes generated using
C++ class code interface packaging. In the Configure C++ class interface dialog box, use
the Namespace parameter to specify a namespace for a model class. If specified, the
namespace is emitted in the generated code for the model class. To scope the C++ model
classes in a model reference hierarchy, you can specify a different namespace for each
referenced model.
11-40
C++ Class Interface Control
For an example of namespace control, see the example model rtwdemo_cppclass. This
model assigns namespaces as follows:
If you build the model with its default settings, you can examine the generated header
and source files for each model to see where the namespace is emitted. For example,
the Namespace setting for the model rtwdemo_cppclass_refmid is shown below,
followed by excerpts of the emitted namespace code in the model header and source files.
15 #include "rtwdemo_cppclass_refmid.h"
16 #include "rtwdemo_cppclass_refmid_private.h"
17
18 namespace MiddleNS
19 {
20 // Model step function
21 void MiddleClass::StepMethod(const real_T *arg_In1, const real_T &arg_In2,
22 real_T *arg_Out1, real_T *arg_Out2)
23 {
...
11-41
11 Function and Class Interfaces
43 }
...
83 }
You can configure C++ class interfaces for right-click builds of nonvirtual subsystems in
Simulink models, if the following requirements are met:
• The model is configured for the C++ language and C++ class code interface
packaging.
• The subsystem is convertible to a Model block using the function
Simulink.SubSystem.convertToModelReference. For referenced
model conversion requirements, see the Simulink reference page
Simulink.SubSystem.convertToModelReference.
To configure C++ class interfaces for a subsystem that meets the requirements:
where gcb is the Simulink function gcb, returning the full block path name of the
current block.
This command opens a subsystem equivalent of the Configure C++ class interface
dialog sequence that is described in detail in the preceding section, “Configure Step
Method for Your Model Class” on page 11-35. (For more information about using
the MATLAB command, see RTW.configSubsystemBuild.)
3 Use the Configure C++ class interface dialog boxes to configure C++ class settings for
the subsystem.
4 Right-click the subsystem and select C/C++ Code > Build This Subsystem.
5 When the subsystem build completes, you can examine the C++ class interfaces in
the generated files and the HTML code generation report.
11-42
C++ Class Interface Control
• Create and validate a new step method interface, starting with default
configuration information from your Simulink model
11-43
11 Function and Class Interfaces
4 Save your model and then generate code using the rtwbuild function.
Note: You should not use the same model-specific C++ class interface control
object across multiple models. If you do, changes that you make to the step method
configuration in one model propagate to other models, which is usually not desirable.
Function Description
“attachToModel” Attach model-specific C++ class interface to loaded ERT-based
Simulink model
“getArgCategory” Get argument category for Simulink model port from model-
specific C++ class interface
“getArgName” Get argument name for Simulink model port from model-
specific C++ class interface
“getArgPosition” Get argument position for Simulink model port from model-
specific C++ class interface
“getArgQualifier” Get argument type qualifier for Simulink model port from
model-specific C++ class interface
“getClassName” Get class name from model-specific C++ class interface
“getDefaultConf” Get default configuration information for model-specific C++
class interface from Simulink model to which it is attached
“getNamespace” Get namespace from model-specific C++ class interface
“getNumArgs” Get number of step method arguments from model-specific C+
+ class interface
“getStepMethodName” Get step method name from model-specific C++ class interface
RTW.configSubsystemBuild Open GUI to configure C function prototype or C++ class
interface for right-click build of specified subsystem
RTW.getClass- Get handle to model-specific C++ class interface control object
InterfaceSpecification
“runValidation” Validate model-specific C++ class interface against Simulink
model to which it is attached
11-44
C++ Class Interface Control
Function Description
“setArgCategory” Set argument category for Simulink model port in model-
specific C++ class interface
“setArgName” Set argument name for Simulink model port in model-specific
C++ class interface
“setArgPosition” Set argument position for Simulink model port in model-
specific C++ class interface
“setArgQualifier” Set argument type qualifier for Simulink model port in model-
specific C++ class interface
“setClassName” Set class name in model-specific C++ class interface
“setNamespace” Set namespace in model-specific C++ class interface
“setStepMethodName” Set step method name in model-specific C++ class interface
%% Select C++ class as the code interface packaging for the model
set_param(gcs,'CodeInterfacePackaging','C++ class')
%% Set required option for I/O arguments style step method (cmd off = GUI on)
set_param(gcs,'ZeroExternalMemoryAtStartup','off')
%% Create a C++ class interface using an I/O arguments style step method
a=RTW.ModelCPPArgsClass
%% Get the default C++ class interface configuration from the model
getDefaultConf(a)
11-45
11 Function and Class Interfaces
1 Open an ERT-based model for which Language is set to C++ and Code interface
packaging is set to C++ class.
2 Open the Configuration Parameters dialog box.
3 On the Code Generation > Interface pane, set the Multi-instance code error
diagnostic parameter to a value other than Error.
4 On the Code Generation pane, if the option Ignore custom storage classes is
selected, clear the option.
Note: C++ class code generation does not support the following CSCs:
• The model option “Use dynamic memory allocation for model block
instantiation” is set to on.
• The base model contains a Model block. The Model block is not directly or indirectly
within a subsystem for which Function packaging is set to Reusable function.
Under these conditions, the software generates a private copy constructor and
assignment operator to prevent pointer members within the model class from being
copied by other code.
Note: To prevent generation of these functions, consider clearing the option Use
dynamic memory allocation for model block instantiation.
The code excerpt below shows generated model.h code for a model class that has a
pointer member. (Look for instances of MiddleClass_ptr). The copy constructor and
assignment operator declarations are shown in bold.
class MiddleClass; // class forward declaration for <S1>/Bottom model instance
typedef MiddleClass* MiddleClass_ptr;
...
11-47
11 Function and Class Interfaces
class Top {
...
// private data and function members
private:
// Block signals
BlockIO_cppclass_top cppclass_top_B;
// Block states
D_Work_cppclass_top cppclass_top_DWork;
// Real-Time Model
RT_MODEL_cppclass_top cppclass_top_M;
//Copy Constructor
Top(const Top &rhs);
//Assignment Operator
Top& operator= (const Top &rhs);
Note: The code and data templates on the Templates pane are supported for C+
+ class code generation. However, the following template file features that are
supported for other language selections are not supported for C++ class generated
code:
• Custom tokens
• TLC commands (<! > tokens)
11-48
C++ Class Interface Control
• Global data placement (custom storage classes only) subpane on the Code
Placement pane
• Memory Sections pane
• Among the data exchange interfaces available on the Interface pane of the
Configuration Parameters dialog box, only the C API interface is supported for C++
class code generation. If you select External mode or ASAP2, code generation fails
with a validation error.
• The I/O arguments style of step method specification supports single-rate models and
multirate single-tasking models, but not multirate multitasking models.
• The Code Generation > Export Functions capability does not support C++ class
code interface packaging.
• If you have a Stateflow license, for a Stateflow chart that resides in a root model
configured to use the I/O arguments step method function specification, and
that uses a model root inport value or calls a subsystem that uses a model root inport
value, you must do one of the following to generate code:
• Clear the Execute (enter) Chart At Initialization check box in the Stateflow
chart.
• Insert a Simulink Signal Conversion block immediately after the root inport. In
the Signal Conversion block parameters dialog box, select Exclude this block
from 'Block reduction' optimization.
• If a model root inport value connects to a Simscape conversion block, you must
insert a Simulink Signal Conversion block between the root inport and the Simscape
conversion block. In the Signal Conversion block parameters dialog box, select
Exclude this block from 'Block reduction' optimization.
• When building a referenced model that is configured to generate a C++ class
interface:
• You must use the I/O arguments step method style of the C++ class interface.
The void-void step method style is not supported for referenced models.
• You cannot use a C++ class interface in cases when a referenced model cannot
have a combined output/update function. Cases include a model that
11-49
11 Function and Class Interfaces
By default, the generated code for a nonvirtual subsystem does not separate a
subsystem's internal data from the data of its parent Simulink model. This can make
it difficult to trace and test the code, particularly for nonreusable subsystems. Also, in
large models containing nonvirtual subsystems, data structures can become large and
potentially difficult to compile.
Function with separate data allows you to generate subsystem function code in which
the internal data for a nonvirtual subsystem is separated from its parent model and is
owned by the subsystem. The subsystem data structure is declared independently from
the parent model data structures. A subsystem with separate data has its own block I/O
and DWork data structure. As a result, the generated code for the subsystem is easier to
trace and test. The data separation also tends to reduce the maximum size of global data
structures throughout the model, because they are split into multiple data structures.
• Your model must use an ERT-based system target file (requires a Embedded Coder
license).
• Your subsystem must be configured to be atomic or conditionally executed. For more
information, see “Systems and Subsystems”.
• Your subsystem must use the Nonreusable function setting for Code
Generation > Function packaging.
11-50
Atomic Subsystem Code
To configure your subsystem for generating modular function code, you invoke the
Subsystem Parameters dialog box and make a series of selections to display and enable
the Function with separate data option. See “Configure Subsystem for Generating
Modular Function Code” on page 11-51 and “Modular Function Code for Nonvirtual
Subsystems” on page 11-56 for details. For limitations that apply, see “Nonvirtual
Subsystem Modular Function Code Limitations” on page 11-61.
For more information about generating code for atomic subsystems, see the sections
“Code Generation of Subsystems” and “Generate Code and Executables for Individual
Subsystem” in the Simulink Coder documentation.
1 Verify that the Simulink model containing the subsystem uses an ERT-based system
target file (see the System target file parameter on the Code Generation pane of
the Configuration Parameters dialog box).
2 In your Simulink model, select the subsystem for which you want to generate
modular function code and launch the Subsystem Parameters dialog box (for
example, right-click the subsystem and select Block Parameters (Subsystem)).
The dialog box for an atomic subsystem is shown below. (In the dialog box for a
conditionally executed subsystem, the dialog box option Treat as atomic unit is
greyed out, and you can skip Step 3.)
11-51
11 Function and Class Interfaces
3 If the Subsystem Parameters dialog box option Treat as atomic unit is available
for selection but not selected, the subsystem is neither atomic nor conditionally
executed. Select the option Treat as atomic unit, which enables Function
packaging on the Code Generation tab. Select the Code Generation tab.
11-52
Atomic Subsystem Code
11-53
11 Function and Class Interfaces
Note: Before you generate nonvirtual subsystem function code with the Function
with separate data option selected, you might want to generate function code with
the option deselected and save the generated function .c and .h files in a separate
directory for later comparison.
5 Select the Function with separate data option. After you make this selection,
additional configuration parameters are displayed.
11-54
Atomic Subsystem Code
Note: To control the naming of the subsystem function and the subsystem files in the
generated code, you can modify the subsystem parameters Function name options
and File name options.
6 To save your subsystem parameter settings and exit the dialog box, click OK.
This completes the subsystem configuration for generating modular function code.
You can now generate the code for the subsystem and examine the generated files,
including the function .c and .h files named according to your subsystem parameter
specifications. For more information on generating code for nonvirtual subsystems, see
“Code Generation of Subsystems”. For examples of generated subsystem function code,
see “Modular Function Code for Nonvirtual Subsystems” on page 11-56.
11-55
11 Function and Class Interfaces
1 Open MATLAB and launch the model rtwdemo_atomic using the MATLAB
command rtwdemo_atomic. Examine the Simulink model.
2 Double-click the SS1 subsystem and examine the contents. (You can close the
subsystem window when you are finished.)
3 Use the Configuration Parameters dialog box to change the model's System target
file from GRT to ERT. For example, from the Simulink window, select Simulation >
Model Configuration Parameters. On the Configuration Parameters dialog box,
select the Code Generation pane and specify ert.tlc for the System target file
parameter. Click OK twice to confirm the change.
4 Create a variant of rtwdemo_atomic that illustrates function code without data
separation.
Do not select the option Function with separate data. Click Apply to apply
the changes and click OK to exit the dialog box.
c Save this model variant to a personal work directory, for example,
rtwdemo_atomic1 in d:/atomic.
5 Create a variant of rtwdemo_atomic that illustrates function code with data
separation.
11-57
11 Function and Class Interfaces
1 Selecting Function with separate data causes typedefs for subsystem data to be
generated in the myfun.h file for rtwdemo_atomic2:
11-58
Atomic Subsystem Code
void myfun_initialize(void) {
{
((real_T*)&rtwdemo_atomic2_myfunB.Integrator)[0] = 0.0;
}
rtwdemo_atomic2_myfunDW.Integrator_DSTATE = 0.0;
}
void rtwdemo_atomic2_initialize(void)
{
...
11-59
11 Function and Class Interfaces
void rtwdemo_atomic1_initialize(void)
{
...
/* block I/O */
{
...
((real_T*)&rtwdemo_atomic1_B.Integrator)[0] = 0.0;
}
/* states (dwork) */
rtwdemo_atomic1_DWork.Integrator_DSTATE = 0.0;
...
}
2 Selecting Function with separate data generates the following declarations in the
myfun.c file for rtwdemo_atomic2:
rtDW_myfun rtwdemo_atomic2_myfunDW;
11-60
Atomic Subsystem Code
/* DiscreteIntegrator: '<S1>/Integrator' */
rtwdemo_atomic2_myfunB.Integrator = rtwdemo_atomic2_myfunDW.Integrator_DSTATE;
• The Function with separate data option is available only in ERT-based Simulink
models (requires a Embedded Coder license).
• The nonvirtual subsystem to which the option is applied cannot have multiple sample
times or continuous sample times; that is, the subsystem must be single-rate with a
discrete sample time.
• The nonvirtual subsystem cannot contain continuous states.
• The nonvirtual subsystem cannot output function call signals.
• The nonvirtual subsystem cannot contain noninlined S-functions.
• The generated files for the nonvirtual subsystem will reference model-wide header
files, such as model.h and model_private.h.
• The Function with separate data option is incompatible with the Classic
call interface option, located on the Code Generation > Interface pane of the
Configuration Parameters dialog box. Selecting both generates an error.
• The Function with separate data option is incompatible with setting Code
interface packaging to Reusable function (Code Generation > Interface
pane). Selecting both generates an error.
11-61
11-62
12
Memory Sections
When pragmas surround each function or data definition separately, the text of each
pragma can contain the name of the definition to which it applies.
12-2
Requirements for Defining Memory Sections
1 Set the Simulink model's code generation target to an embedded target such as
ert.tlc.
2 To create packages, specify package properties, or create classes, including custom
storage classes, see “Define Data Classes” in the Simulink documentation.
See also the instructions that appear when you click the Custom Storage Classes
tab.
3 If you need to specify custom storage class properties,
A notification box appears that states Please Wait ... Finding Packages. After
a brief pause, the notification box closes and the Custom Storage Class Designer
appears.
c Select the Custom Storage Class tab. The Custom Storage Class pane
initially looks like this:
12-3
12 Memory Sections
d Use the Custom Storage Class pane to select a writable package and specify
custom storage class properties. Instructions for using this pane appear in
“Design Custom Storage Classes and Memory Sections”.
12-4
Define Memory Sections
In this section...
“Edit Memory Section Properties” on page 12-5
“Specify the Memory Section Name” on page 12-6
“Specify a Qualifier for Custom Storage Class Data Definitions” on page 12-7
“Specify Comment and Pragma Text” on page 12-7
“Surround Individual Definitions with Pragmas” on page 12-7
“Include Identifier Names in Pragmas” on page 12-8
A notification box appears that states Please Wait ... Finding Packages. After
a brief pause, the notification box closes and the Custom Storage Class Designer
appears.
3 Click the Memory Section tab of the Custom Storage Class Designer. The Memory
Section pane initially looks like this:
12-5
12 Memory Sections
4 If you intend to create or change memory section definitions, use the Select
package field to select a writable package.
The rest of this section assumes that you have selected a writable package, and describes
the use of the Memory section subpane on the lower left. For descriptions of the other
subpanes, instructions for validating memory section definitions, and other information,
see “Define Memory Sections” on page 12-5.
12-6
Define Memory Sections
The qualifier will appear in generated code with its components in the same left-to-
right order in which their definitions appear in the dialog box. A preview appears in the
Pseudocode preview subpane on the lower right.
Note: Specifying a qualifier affects only custom storage class data definitions. The code
generator omits the qualifier from other definition categories.
If the Pragma surrounds field for a memory section specifies All variables, the
code generator will insert the comment and prepragma for the section before the
first definition in a contiguous block of custom storage class data definitions, and the
postpragma after the last definition in the block.
Note: Specifying All variables affects only custom storage class data definitions. For
other definition categories, the code generator surrounds each definition separately
regardless of the value of Pragma surrounds.
12-7
12 Memory Sections
You can use %<identifier> with pragmas only when pragmas to surround each
variable. The Validate phase will report an error if you violate this rule.
Note: Although %<identifier> looks like a TLC variable, it is not: it is just a keyword
that directs the code generator to substitute the applicable data definition identifier
when it outputs a pragma. TLC variables cannot appear in pragma specifications in the
Memory Section pane.
12-8
Configure Memory Sections
To... Select...
Specify the package that contains memory The name of a package for Package. Click
sections that you want to apply Refresh package list to refresh the list of
available packages in your configuration.
Apply memory sections to initialize/start and A value for Initialize/Terminate.
terminate functions
Apply memory sections to step, run-time A value for Execution.
initialization, derivative, enable, and disable
functions
Apply memory sections to constant parameters, A value for Constants.
constant, block I/O, or zero representation
Apply memory sections to root inputs or outputs A value for Inputs/Outputs.
Apply memory sections to block I/O, Dwork A value for Internal data.
vectors, run-time models, zero-crossings
Apply memory sections to parameters A value for Parameters.
The interface checks whether the specified package is on the MATLAB path and that the
selected memory sections are in the package. The results of this validation appear in the
field Validation results.
12-9
12 Memory Sections
You can add the volatile qualifier to type definitions generated in code for model
constant block I/O, constant parameters, and ground data (zero representation).
To add the volatile qualifier to type definitions, you must configure your model as
follows:
If you choose to add the volatile qualifier to type definitions in your generated code,
note the following:
• If constant data that is qualified with volatile is passed by pointer, the code
generator casts away the volatility. This occurs because generated functions assume
that data values do not change during execution and, therefore, pass their arguments
as const * (not const volatile *).
• If a variable must be declared const and you specify MemVolatile, the code
generator declares the variable with the const and volatile qualifiers.
• If you set Constants to MemConst or MemConstVolatile, and a variable cannot be
declared as constant data, a TLC warning appears and the code generator does not
qualify the variable with const.
1 On the Configuration Parameters dialog box, in the Optimization > Signals and
Parameters pane, select Inline parameters.
12-10
Declare Constant Data as Volatile
model_data.c
/* Constant parameters (auto storage) */
/* ConstVolatile memory section */
const volatile ConstParam_simple_lookup simple_lookup_ConstP = {
/* Expression: [-5:5]
* Referenced by: '<Root>/Lookup Table'
*/
{ -5.0, -4.0, -3.0, -2.0, -1.0, 0.0, 1.0, 2.0, 3.0, 4.0, 5.0 },
/* Expression: tanh([-5:5])
* Referenced by: '<Root>/Lookup Table'
*/
{ -0.99990920426259511, -0.999329299739067,
-0.99505475368673046, -0.9640275800758169,
-0.76159415595576485, 0.0, 0.76159415595576485,
0.9640275800758169, 0.99505475368673046,
0.999329299739067, 0.99990920426259511 }
};
model.h
/* Real-time Model Data Structure */
struct RT_MODEL_simple_lookup {
const char_T * volatile errorStatus;
};
Also note in the model.c file that a typecast is inserted in the rt_Lookup function
call, removing the volatile qualifier.
/* Lookup: '<Root>/Lookup Table' incorporates:
12-11
12 Memory Sections
* Inport: '<Root>/In1'
*/
OUTPUT = rt_Lookup(((const real_T*)
&simple_lookup_ConstP.LookupTable_XData[0]), 11, INPUT, ((
const real_T*) &simple_lookup_ConstP.LookupTable_YData[0]));
12-12
Apply Memory Sections
In this section...
“Assign Memory Sections to Custom Storage Classes” on page 12-13
“Apply Memory Sections to Model-Level Functions and Internal Data” on page 12-15
“Apply Memory Sections to Atomic Subsystems” on page 12-17
A notification box appears that states Please Wait ... Finding Packages. After
a brief pause, the notification box closes and the Custom Storage Class Designer
appears.
3 Select the Custom Storage Class tab. The Custom Storage Class pane initially
looks like this:
12-13
12 Memory Sections
4 Use the Select package field to select a writable package. The rest of this section
assumes that you have selected a writable package.
5 Select the desired custom storage class in the Custom storage class definitions
pane.
6 Select the desired memory section from the Memory section pull-down.
7 Click Apply to apply changes to the open copy of the model; Save to apply changes
and save them to disk; or OK to apply changes, save changes, and close the Custom
Storage Class Designer.
Generated code for data definitions in the specified custom storage class are enclosed
in the pragmas of the specified memory section. The pragmas can surround contiguous
blocks of definitions or each definition separately, as described in “Surround Individual
Definitions with Pragmas” on page 12-7. For more information, see “Design Custom
Storage Classes and Memory Sections”.
12-14
Apply Memory Sections
Note: The code generator does not generate a pragma around definitions or declarations
for data that has the following built-in storage classes:
• ExportedGlobal
• ImportedExtern
• ImportedExternPointer
The code generator treats data with these built-in storage classes like custom storage
classes without a specified memory section.
When using code generation software, you can apply memory sections to the following
categories of internal data:
12-15
12 Memory Sections
Memory section specifications for model-level functions and internal data apply to the top
level of the model and to its subsystems. However, these specifications are not applicable
to atomic subsystems that contain overriding memory section specifications, as described
in “Apply Memory Sections to Atomic Subsystems” on page 12-17.
1 Open the Configuration Parameters dialog box and select Code Generation >
General.
2 Specify the System target file as an ERT target, such as ert.tlc .
3 Select Memory Sections. The Memory Sections pane looks like this:
12-16
Apply Memory Sections
4 Initially, the Package field specifies ---None--- and the pull-down lists only built-
in packages. If you have defined packages of your own, click Refresh package list.
This action adds user-defined packages on your search path to the package list.
5 In the Package pull-down, select the package that contains the memory sections
that you want to apply.
6 In the pull-down for each category of internal data and model-level function, specify
the memory section that you want to apply to that category. Accepting or specifying
Default omits specifying memory section for that category.
7 Click Apply to save changes to the package and memory section selections.
12-17
12 Memory Sections
For an atomic system, on the Code Generation tab, you can use the Function
packaging field to control the format of the generated code.
4 Specify Function packaging as Nonreusable function or Reusable
function. Otherwise, you cannot specify memory sections for the subsystem.
5 If the code format is Function and you want separate data, check Function with
separate data.
The Code Generation tab now shows applicable memory section options. The
available options depend on the values of Function packaging and the Function
with separate data check box. When the former is Nonreusable function and
the latter is checked, the pane looks like this:
12-18
Apply Memory Sections
6 In the pull-down for each available definition category, specify the memory section
that you want to apply to that category.
• Selecting Inherit from model inherits the corresponding selection from the
model level (not parent subsystem).
• Selecting Default specifies that the category does not have an associated
memory section, overriding model-level specifications for that category.
7 Click Apply to save changes, or OK to save changes and close the dialog box.
Caution If you use Build This Subsystem or Build Selected Subsystem to generate
code for an atomic subsystem that specifies memory sections, the code generator ignores
the subsystem-level specifications and uses the model-level specifications instead.
The generated code is the same as if the atomic subsystem specified Inherit from
model for every category of definition. For information about building subsystems, see
“Generate Code and Executables for Individual Subsystem”.
12-19
12 Memory Sections
It is not possible to specify the memory section for a subsystem in a library. However,
you can specify the memory section for the subsystem after you have copied it into a
Simulink model. This is because in the library it is unknown what code generation target
will be used. You can copy a library block into many different models with different code
generation targets and different memory sections available.
12-20
Generated Code with Memory Sections
Assume that the subsystem is atomic. On the Code Generation tab, the Function
packaging parameter is Reusable function. Memory sections have been created and
assigned as shown in the next two tables; here, data memory sections specify Pragma
surrounds to be Each variable.
12-21
12 Memory Sections
Given the preceding specifications and definitions, the code generator would create the
following code, with minor variations depending on the current version of the Target
Language Compiler.
12-22
Model-Level Data Structures
#pragma IO-begin
ExternalOutputs_mySample mySample_Y;
#pragma IO-end
#pragma InData-begin(mySample_B)
BlockIO_mySample mySample_B;
#pragma InData-end
#pragma InData-begin(mySample_DWork)
D_Work_mySample mySample_DWork;
#pragma InData-end
#pragma InData-begin(mySample_M_)
RT_MODEL_mySample mySample_M_;
#pragma InData-end
#pragma InData-begin(mySample_M)
RT_MODEL_mySample *mySample_M = &mySample_M_;
#pragma InData-end
#pragma Parameters-begin
Parameters_mySample mySample_P = {
0.0 , {2.3}
};
#pragma Parameters-end
Model-Level Functions
#pragma ExecFunc-begin(mySample_step)
void mySample_step(void)
{
real_T rtb_UnitDelay;
rtb_UnitDelay = mySample_DWork.UnitDelay_DSTATE;
mySubsystem(rtb_UnitDelay, &mySample_B.mySubsystem;,
(rtP_mySubsystem *) &mySample_P.mySubsystem);
mySample_Y.Out1_o = mySample_B.mySubsystem.Gain;
mySample_DWork.UnitDelay_DSTATE = mySample_U.In1;
12-23
12 Memory Sections
}
#pragma ExecFunc-end(mySample_step)
#pragma InitTerminate-begin
void mySample_initialize(void)
{
rtmSetErrorStatus(mySample_M, (const char_T *)0);
{
((real_T*)&mySample_B.mySubsystem.Gain)[0] = 0.0;
}
mySample_DWork.UnitDelay_DSTATE = 0.0;
mySample_U.In1 = 0.0;
mySample_Y.Out1_o = 0.0;
mySample_DWork.UnitDelay_DSTATE = mySample_P.UnitDelay_X0;
}
#pragma InitTerminate-end
Subsystem Function
Because the subsystem specifies a memory section for execution functions that overrides
that of the parent model, subsystem code looks like this:
/* File: mySubsystem.c */
If the subsystem had not defined its own memory section for execution functions, but
inherited that of the parent model, the subsystem code would have looked like this:
/* File: mySubsystem.c */
#pragma ExecFunc-begin(mySubsystem)
void mySubsystem(real_T rtu_In1,
rtB_mySubsystem *localB,
rtP_mySubsystem *localP)
{
localB->Gain = rtu_In1 * localP->Gain_Gain;
}
12-24
Model-Level Data Structures
#pragma ExecFunc-end(mySubsystem)
12-25
12-26
Code Generation
13
Configuration
Application Objectives
The first step in applying Embedded Coder configuration options to the application
development process is to consider how your application objectives, particularly with
respect to efficiency, traceability, and safety, map to code generation options in a model
configuration set.
Parameters that you set in the Solver, Data Import/Export, Diagnostics, and Code
Generation panes of the Configuration Parameters dialog box specify the behavior of a
model in simulation and the code generated for the model.
• Define your objectives in the configuration set. For more information, see “High-Level
Code Generation Objectives” on page 13-3.
• Use the Code Generation Advisor to identify parameter values that are not configured
for the objectives that you selected. For more information, see “Determine Model
Configuration for Specified Objectives” on page 13-5.
13-2
High-Level Code Generation Objectives
• Execution efficiency (all targets) — Configure code generation settings to achieve fast
execution time.
• ROM efficiency (ERT-based targets) — Configure code generation settings to reduce
ROM usage.
• RAM efficiency (ERT-based targets) — Configure code generation settings to reduce
RAM usage.
• Traceability (ERT-based targets) — Configure code generation settings to provide
mapping between model elements and code.
• Safety precaution (ERT-based targets) — Configure code generation settings to
increase clarity, determinism, robustness, and verifiability of the code.
• Debugging (all targets) — Configure code generation settings to debug the code
generation build process.
• MISRA-C:2004 guidelines (ERT-based targets) — Configure code generation settings
to increase compliance with MISRA-C:2004 guidelines.
• Polyspace (ERT-based targets) — Configure code generation settings to prepare the
code for Polyspace® analysis.
Based on your objective selections and prioritization, the Code Generation Advisor checks
your model and suggests changes that you can make to achieve your code generation
objectives.
Note: If you select the MISRA-C:2004 guidelines code generation objective, the Code
Generation Advisor checks:
• For blocks that are not supported or recommended for MISRA-C:2004 compliant code
generation.
13-3
13 Configuration
Setting code generation objectives and running the Code Generation Advisor provides
information on how to meet code generation objectives for your model. The Code
Generation Advisor does not alter the generated code. You can use the Code Generation
Advisor to make the suggested changes to your model. The generated code is changed
only after you modify your model and regenerate code. If you use the Code Generation
Advisor to set code generation objectives and check your model, the generated code
includes comments identifying which objectives you specified, the checks the Code
Generation Advisor ran on the model, and the results of running the checks.
13-4
Determine Model Configuration for Specified Objectives
The Code Generation Advisor uses the information presented in “Recommended Settings
Summary” to determine the values. When there is a conflict due to multiple objectives,
the higher-priority objective takes precedence.
You can use the Code Generation Advisor to review a model before generating code, or as
part of the code generation process. When you choose to review a model before generating
code, you specify which model, subsystem, or referenced model the Code Generation
Advisor reviews. When you choose to review a model as part of the code generation
process, the Code Generation Advisor reviews the entire system.
13-5
13 Configuration
1 On the menu bar, select Code > C/C++ Code > Code Generation Advisor.
Alternatively:
•
On the toolbar drop-down list, select Code Generation Advisor.
• Right-click a subsystem, and then select C/C++ Code > Code Generation
Advisor. Go to step 3.
2 In the System Selector window, select the model or subsystem that you want to
review, and then click OK.
3 In the Code Generation Advisor, on the Code Generation Objectives pane, select
the code generation objectives. As you select objectives, on the left pane, the Code
Generation Advisor updates the list of checks it will run on your model. If your
model is configured with an ERT-based target, more objectives are available. For this
example, the model is configured with an ERT-based target. If your objectives are
execution efficiency and traceability, in that priority, do the following:
13-6
Check and Configure Model for Code Generation Objectives
4 Click Run Selected Checks to run the checks listed in the left pane of the Code
Generation Advisor.
5 In the Code Generation Advisor window, review the results for Check model
configuration settings against code generation objectives by selecting it from
the left pane. The results for that check are displayed in the right pane.
• Parameters are set to values other than the value recommended for the specified
code generation objectives.
• Selected code generation objectives differ from the objectives set in the model.
• Parameter to the value recommended for the specified code generation objectives.
• Code generation objectives in the model to the objectives specified in the Code
Generation Advisor.
13-7
13 Configuration
6 In the Code Generation Advisor window, review the results for the remaining checks
by selecting them from the left pane. The right pane populates the results for the
checks.
7 After reviewing the check results, you can choose to fix warnings and failures, as
described in “Fix a Model Check Warning or Failure”.
13-8
Check and Configure Model for Code Generation Objectives
Note: When you specify an efficiency or Safety precaution objective, the Code Generation
Advisor includes additional checks.
When you make changes to one check, the other check results could become invalid. You
must run the checks again.
13-9
13 Configuration
13-10
Check and Configure Model for Code Generation Objectives Using Configuration Parameters Dialog Box
13-11
13 Configuration
8 After reviewing the check results, you can choose to fix warnings and failures, as
described in “Fix a Model Check Warning or Failure”.
Note: When you specify an efficiency or Safety precaution objective, the Code Generation
Advisor includes additional checks. When you make changes to one check, the other
check results could become invalid and you must run the checks again.
13-12
Check and Configure Model for Code Generation Objectives Using Configuration Parameters Dialog Box
For more information, see “Set Objectives — Code Generation Advisor Dialog Box”
13-13
13 Configuration
1 Specify a system target file. If you specify an ERT-based target, more objectives are
available. For this example, specify ert.tlc. model_name is the name or handle to
the model.
set_param(model_name, 'SystemTargetFile', 'ert.tlc');
2 Specify your objectives. For example, if your objectives are execution efficiency and
traceability, in that priority, enter:
set_param(model_name, 'ObjectivePriorities',...
{'Execution efficiency', 'Traceability'});
Note: When you specify a GRT-based system target file, you can specify an objective at
the command line. If you specify ROM efficiency, RAM efficiency, Traceability,
MISRA-C:2004 guidelines, Polyspace, or Safety precaution, the build process
changes the objective to Unspecified because you have specified a value that is invalid
when using a GRT-based target.
13-14
Check Objectives in Referenced Models
To specify different objectives for the top model and each referenced model, review the
models separately without generating code.
13-15
13 Configuration
If you want to check and configure your model for code generation objectives such as
traceability or safety, see “Application Considerations”.
13-16
Check Model During Code Generation
If the Code Generation Advisor issues failures or warnings, and you specified:
Note: When you specify an efficiency or Safety precaution objective, the Code
Generation Advisor includes additional checks. When you make changes to one of
these checks, the other check results could become invalid and you must run the
check again.
For more information, see “Set Objectives — Code Generation Advisor Dialog Box”
13-17
13 Configuration
In this section...
“Specify Parameters in Custom Objectives” on page 13-18
“Specify Checks in Custom Objectives” on page 13-19
“Determine Checks and Parameters in Existing Objectives” on page 13-19
“How to Create Custom Objectives” on page 13-21
The Code Generation Advisor reviews your model based on objectives that you specify. If
the predefined efficiency, traceability, Safety precaution, and debugging objectives do not
meet your requirements, you can create custom objectives.
• Creating a new objective and adding parameters and checks to a new objective.
• Creating a new objective based on an existing objective, then adding, modifying, and
removing the parameters and checks within the new objective.
• addParam — Add parameters and specify the values that the Code Generation
Advisor reviews in Check model configuration settings against code
generation objectives. When you add parameters that have dependencies, the
software includes the dependencies in the list of parameter values that the Code
Generation Advisor reviews.
• modifyInheritedParam — Modify inherited parameter values that the Code
Generation Advisor reviews in Check model configuration settings against code
generation objectives.
• removeInheritedParam — Remove inherited parameters from a new objective
that is based on an existing objective. When a user selects multiple objectives, if
another selected objective includes this parameter, the Code Generation Advisor
reviews the parameter value in Check model configuration settings against
code generation objectives.
13-18
Create Custom Objectives
• addCheck — Add checks to the Code Generation Advisor. When a user selects the
custom objective, the Code Generation Advisor displays the check, unless the user
specifies an additional objective with a higher priority that excludes the check.
For example, you might add a check to the Code Generation Advisor to include a
custom check in the automatic model checking process.
• excludeCheck — Exclude checks from the Code Generation Advisor. When a user
selects multiple objectives, if the user specifies an additional objective that includes
this check as a higher priority objective, the Code Generation Advisor displays this
check.
For example, you might exclude a check from the Code Generation Advisor when a
check takes a long time to process.
• removeInheritedCheck — Remove inherited checks from a new objective that is
based on an existing objective. When a user selects multiple objectives, if another
selected objective includes this check, the Code Generation Advisor displays the
check.
For example, you might remove an inherited check, rather than exclude the check,
when the check takes a long time to process, but the check is important for another
objective.
For example, the Efficiency objective includes checks which you can see in the Code
Generation Advisor. To see the checks in the Code Generation Advisor:
13-19
13 Configuration
3 On the model toolbar, select Code > C/C++ Code > Code Generation Advisor.
4 In the System Selector window, select the model or subsystem that you want to
review, and then click OK.
5 In the Code Generation Advisor, on the Code Generation Objectives pane, select
the code generation objectives. As you select objectives, on the left pane, the Code
Generation Advisor updates the list of checks it will run on your model. For this
example, select Execution efficiency.
In the left pane, the Code Generation Advisor lists the checks for the Execution
efficiency objective. The first check, Check model configuration settings against
code generation objectives, lists parameters and values specified by the objective.
For example, the Code Generation Advisor displays the list of parameters and the
recommended values in the Execution efficiency objective. To see the list of
parameters and values:
In the check results, the Code Generation Advisor displays the list of parameters and
recommended values for the Execution efficiency objective.
13-20
Create Custom Objectives
For example:
function sl_customization(cm)
%SL_CUSTOMIZATION objective customization callback
objCustomizer = cm.ObjectiveCustomizer;
index = objCustomizer.addCallbackObjFcn(@addObjectives);
objCustomizer.callbackFcn{index}();
end
13-21
13 Configuration
• Includes and excludes checks for each objective using the addCheck,
excludeCheck, and removeInheritedCheck methods.
• Registers objectives using the register method.
The following example shows how to create an objective, Reduce RAM Example.
Reduce RAM Example includes five parameters and three checks that the Code
Generation Advisor reviews.
function addObjectives
end
13-22
Create Custom Objectives
addCheck(obj, 'mathworks.codegen.SWEnvironmentSpec');
removeInheritedCheck(obj, 'mathworks.codegen.CodeInstrumentation');
end
4 If you previously opened the Code Generation Advisor, close the model from which
you opened the Code Generation Advisor.
5 Refresh the customization manager. At the MATLAB command line, enter the
sl_refresh_customizations command.
6 Open your model and review the new objectives.
13-23
13 Configuration
Use the Browse button on the Code Generation pane to open the System Target File
Browser (see “Select a Target”. The browser lets you select a preset target configuration
consisting of a system target file, template makefile, and make command.
If you select a target configuration by using the System Target File Browser, your
selection appears in the System target file field (target.tlc).
If you are using a target configuration that does not appear in the System Target File
Browser, enter the name of your system target file in the System target file field. Click
Apply or OK to configure for that target.
“Targets and Code Formats” describes the use of the browser and includes a complete list
of available target configurations.
13-24
Code Generation Targets
You also can select a system target file programmatically from MATLAB code, as
described in “Select a System Target File Programmatically”.
After selecting a system target, you can modify model configuration parameter settings.
If you want to switch between different targets in a single workflow for different code
generation purposes (for example, rapid prototyping versus product code deployment), set
up different configuration sets for the same model and switch the active configuration set
for the current operation. For more information on how to set up configuration sets and
change the active configuration set, see “Manage a Configuration Set”.
The code generator provides variants of the ERT target including the following:
These targets are based on a common system target file, ert.tlc. They are displayed in
the System Target File Browser as shown in the figure below.
13-25
13 Configuration
You can use the ert_shrlib.tlc target to generate a host-based shared library from
your Simulink model. Selecting this target allows you to generate a shared library
version of your model code for your host platform, either a Windows dynamic link library
(.dll) file or a UNIX shared object (.so) file. This feature can be used to package your
source code securely for easy distribution and shared use.
To... Select...
Generate code that creates Support absolute time. For further information on the allocation
and maintains integer and operation of absolute and elapsed timers, see “Timers”. If you
counters for blocks that use do not select this parameter and the model includes block that use
13-26
Code Generation Targets
To... Select...
absolute or elapsed time absolute or elapsed time values, the build process generates an
values (default) error.
Generate code for blocks Support continuous time. If you do not select this parameter
that rely on continuous time and the model includes continuous-time blocks, the build process
generates an error.
When you select Support non-finite numbers, the build process generates an error
if the model includes a C MEX S-function that does not have a corresponding TLC
implementation (for inlining code generation).
Note that inlining S-functions is highly advantageous in production code generation, for
example in implementing device drivers. To enforce the use of inlined S-functions for
code generation, clear Support non-inlined S-functions.
When generating code for a model that contains non-inlined S-functions with an ERT
target and either of the following is true:
There might be a mismatch between the simulation and code generation results. To avoid
such a mismatch select Test hardware is the same as production hardware or
select Generate code only.
13-27
13 Configuration
To... Do...
Generate model function calls that are Select Classic call interface and MAT-file logging.
compatible with the main program In addition, deselect Suppress error status in real-
module of the pre-R2012a GRT target time model data structure. Classic call interface
(grt_main.c or .cpp) provides a quick way to use code generated in R2012a or
higher with a pre-R2012a GRT-based custom target by
generating wrapper function calls that interface to the
generated code.
Reduce overhead and use more local Select Single output/update function
variables by combining the output
and update functions in a single Errors or unexpected behavior can occur if a Model block
model_step function is part of a cycle and “Single output/update function” is
enabled (the default). See “Model Blocks and Direct Feed
through” for details.
Generate a model_terminate Select Terminate function required. For more
function for a model not designed to information, see the description of model_terminate.
run indefinitely
Generate reusable, reentrant code Select Generate reusable code. See “Set Up Support for
from a model or subsystem Code Reuse” on page 13-29 for details.
Statically allocate model data Deselect Generate reusable code. The generated code
structures and access them directly in is not reusable or reentrant. See “Entry-Point Functions
the model code and Scheduling” for information on the calling interface
generated for model functions in this case.
Suppress the generation of an error Select Suppress error status in real-time model data
status field in the real-time model structure. Selecting this parameter can also cause the
data structure, rtModel, for example, rtModel structure to be omitted completely from the
if you do not need to log or monitor generated code.
error messages
When generating code for multiple integrated models, set
this parameter the same for all of the models. Otherwise,
the integrated application might exhibit unexpected
behavior. For example, if you select the option in one
model but not in another, the error status might not be
registered by the integrated application.
13-28
Code Generation Targets
To... Do...
Open the Model Step Functions dialog Click Configure Step Function. Based on the Function
box preview and modify the model's specification value you select for your model_step
model_step function prototype function (supported values include Default model-step
(see “Entry-Point Functions and function and Model specific C prototype), you
Scheduling”) can preview and modify the function prototype. Once you
validate and apply your changes, you can generate code
based on your function prototype modifications. For more
information about using the Configure Step Function
button and the Model Step Functions dialog box, see
“Function Prototype Control”.
Pass root-level I/O as provides options that control how model inputs and outputs at
the root level of the model are passed to the model_step function.
To... Select...
Pass each root-level model input and output Generate reusable code and Pass root-level
argument to the model_step function I/O as > Individual arguments.
individually (the default)
Pack root-level input arguments and root-level Generate reusable code and Pass root-level
output arguments into separate structures that I/O as > Structure reference
are then passed to the model_step function
In some cases, selecting Generate reusable code can generate code that compiles
but is not reentrant. For example, if a signal, DWork structure, or parameter data has
a storage class other than Auto, global data structures are generated. To handle such
cases, use the Reusable code error diagnostic parameter to choose the severity levels
for diagnostics.
In some cases, the Embedded Coder software is unable to generate valid and compilable
code. For example, if the model contains one of the following, the code generated would be
invalid.
13-29
13 Configuration
For more information about replacing code, using code replacement libraries that
MathWorks provides, see “What Is Code Replacement?” and “Code Replacement
Libraries”. For information about developing code replacement libraries, see “What Is
Code Replacement Customization?” in the Embedded Coder documentation.
13-30
Configuration Variations
Configuration Variations
Every model contains one or more named configuration sets that specify model
parameters such as solver options, code generation options, and other choices. A model
can contain multiple configuration sets, but only one configuration set is active at a
time. For more information on configuration sets and how to view and edit them in the
Configuration Parameters dialog box, see “About Model Configurations”.
A configuration set includes options that specify code generation in general. For more
information, see “Configure a Model for Code Generation”. With Embedded Coder and
an ERT target more parameters are available for fine-tuning the generated code with
respect to customizing the appearance and optimizing the generated code.
13-31
13 Configuration
Wizard
In this section...
“Configure and Optimize Model with Configuration Wizard Blocks” on page 13-32
“Add a Configuration Wizard Block” on page 13-33
“Use Configuration Wizard Blocks” on page 13-35
“Create a Custom Configuration Wizard Block” on page 13-35
The library provides a Configuration Wizard block you can customize, and four preset
Configuration Wizard blocks.
Block Description
Custom MATLAB file Automatically update active configuration
parameters of parent model using a custom
file
ERT (optimized for fixed-point) Automatically update active configuration
parameters of parent model for ERT fixed-
point code generation
ERT (optimized for floating-point) Automatically update active configuration
parameters of parent model for ERT
floating-point code generation
GRT (debug for fixed/floating-point) Automatically update active configuration
parameters of parent model for GRT fixed-
or floating-point code generation with
debugging enabled
GRT (optimized for fixed/floating-point) Automatically update active configuration
parameters of parent model for GRT fixed-
or floating-point code generation
13-32
Wizard
When you add one of the preset Configuration Wizard blocks to your model and double-
click it, a predefined MATLAB file script executes and configures parameters of the
model's active configuration set without manual intervention. The preset blocks configure
the options optimally for one of the following cases:
The Custom block is associated with an example MATLAB file script that you can adapt
to your requirements.
You can also set up the Configuration Wizard blocks to invoke the build process after
configuring the model.
13-33
13 Configuration
The Configuration Wizard blocks are available in the Embedded Coder block library. To
use a Configuration Wizard block:
6 You can set up the Configuration Wizard block to invoke the build process after
executing its configuration script. If you do not want to use this feature, skip to the
next step.
13-34
Wizard
If you want the Configuration Wizard block to invoke the build process, right-
click on the Configuration Wizard block in your model, and select Mask > Mask
Parameters... from the context menu. Then, select the Invoke build process after
configuration parameter.
7 Click Apply, and close the Mask Parameters dialog box.
Note You should not change the Configure the model for option, unless you want
to create a custom block and script. In that case, see “Create a Custom Configuration
Wizard Block” on page 13-35.
8 Save the model.
9 You can now use the Configuration Wizard block to configure the model, as described
in the next section.
If the Invoke build process after configuration option for the block was selected, the
script also initiates the code generation and build process.
Note: You can add more than one Configuration Wizard block to your model. This
provides a quick way to switch between configurations.
Both the block and the script are intended to provide a starting point for customization.
This section describes:
13-35
13 Configuration
This section describes how to set up a custom Configuration Wizard block and link it to
a script. If you want to use the block in more than one mode, it is advisable to create a
Simulink library to contain the block.
1 Create a folder to store your custom script. This folder should not be anywhere inside
the MATLAB folder structure (that is, it should not be under matlabroot).
This statement is used later as a test to verify that your custom block has executed
the script.
5 Save your script and close the MATLAB editor.
The next step is to create a Simulink library and add a custom block to it. Do this as
follows:
1 Open the Embedded Coder library and the Configuration Wizards sublibrary, as
described in “Add a Configuration Wizard Block” on page 13-33.
2 Select New > Library from the File menu of the Configuration Wizards sublibrary
window. An empty library window opens.
3 Select the Custom MATLAB file block from the Configuration Wizards sublibrary
and drag and drop it into the empty library window.
13-36
Wizard
4 To distinguish your custom block from the original, edit the Custom MATLAB file
label under the block as desired.
5 Select Save as from the File menu of the new library window; save the library to
the /my_wizards folder, under your library name of choice. In the figure below,
the library has been saved as ex_custom_button, and the block has been labeled
my_wizard MATLAB-file.
The next step is to link the custom block to the custom script:
1 Right-click on the block in your model, and select Mask > Mask Parameters from
the context menu. Notice that the Configure the model for menu is set to Custom.
When Custom is selected, the Configuration function edit field is enabled, so that
you can enter the name of a custom script.
2 Enter the name of your custom script into the Configuration function field. (Do
not enter the .m filename extension, which is implicit.) In the figure below, the script
name my_configscript has been entered into the Configuration function field.
This establishes the linkage between the block and script.
3 Note that by default, the Invoke build process after configuration option is
deselected. You can change the default for your custom block by selecting this option.
For now, leave this option deselected.
4 Click Apply and close the Mask Parameters dialog box.
5 Save the library.
13-37
13 Configuration
6 Close the Embedded Coder library and the Configuration Wizards sublibrary. Leave
your custom library open for use in the next step.
vdp
2 Open the Configuration Parameters dialog box and view the options by clicking on
Code Generation in the list in the left pane of the dialog box.
3 Observe that vdp is configured, by default, for the GRT target. Close the
Configuration Parameters dialog box.
4 Select your custom block from your custom library. Drag and drop the block into the
vdp model.
5 In the vdp model, double-click your custom block.
6 In the MATLAB window, you should see the test message you previously added to
your script:
Before applying further edits to your custom script, proceed to the next section to learn
about the operation and conventions of Configuration Wizard scripts.
You should create your custom Configuration Wizard script by copying and modifying the
example script, rtwsampleconfig.m. This section provides guidelines for modification.
The Configuration Function
The example script implements a single function without a return value. The function
takes a single argument cs:
function rtwsampleconfig(cs)
The argument cs is a handle to a proprietary object that contains information about the
model's active configuration set. The Simulink software obtains this handle and passes
13-38
Wizard
Your custom script should conform to this prototype. Your code should use cs as a “black
box” object that transmits information to and from the active configuration set, using the
accessor functions described below.
Access Configuration Set Parameters
To set parameters or obtain parameter values, use the Simulink set_param and
get_param functions.
To obtain the current setting of an option in the active configuration set, call get_param.
Pass in the cs object as the first argument, followed by the internal option name. For
example, the following code excerpt tests the setting of the Create code generation
report option:
To set an option in the active configuration set, call set_param. Pass in the cs object
as the first argument, followed by one or more parameter/value pairs that specify the
internal option name and its value. For example, the following code excerpt turns off the
Support absolute time option:
set_param(cs,'SupportAbsoluteTime','off');
Select a Target
A Configuration Wizard script must select a target configuration. The example script
uses the ERT target as a default. The script first stores string variables that correspond
to the required System target file, Template makefile, and Make command
settings:
stf = 'ert.tlc';
13-39
13 Configuration
tmf = 'ert_default_tmf';
mc = 'make_rtw';
The system target file is selected by passing the cs object and the stf string to the
switchTarget function:
switchTarget(cs,stf,[]);
The template makefile and make command options are set by set_param calls:
set_param(cs,'TemplateMakefile',tmf);
set_param(cs,'MakeCommand',mc);
To select a target, your custom script needs only to set up the string variables stf, tmf,
and mc and pass them to the calls, as above.
Obtain Target and Configuration Set Information
The following utility functions and properties are provided so that your code can obtain
information about the current target and configuration set, with the cs object:
isERT = strcmp(get_param(cs,'IsERTTarget'),'on');
This information can be used to determine whether or not the script should configure
ERT-specific options, for example:
if isERT
set_param(cs,'ZeroExternalMemoryAtStartup','off');
set_param(cs,'ZeroInternalMemoryAtStartup','off');
set_param(cs,'InitFltsAndDblsToZero','off');
set_param(cs,'InlinedParameterPlacement',...
'NonHierarchical');
set_param(cs,'NoFixptDivByZeroProtection','on')
end
13-40
Wizard
Configuration Wizard scripts can be run from the MATLAB command prompt. (The
Configuration Wizard blocks are provided as a graphical convenience, but are not
essential.)
Before invoking the script, you must open a model and instantiate a cs object to pass in
as an argument to the script. After running the script, you can invoke the build process
with the rtwbuild command. The following example opens, configures, and builds a
model.
open my_model;
cs = getActiveConfigSet ('my_model');
rtwsampleconfig(cs);
rtwbuild('my_model');
13-41
13-42
14
Code Appearance
14-2
Add Custom Comments to Generated Code
Goal Specify
Include the text specified in the Description Simulink block descriptions
field of a block's Block Properties dialog box as
comments in the code generated for each block.
Add a comment that includes the block name at Simulink block descriptions
the start of the code for each block.
Include the text specified in the Description Simulink data object descriptions
field of a Simulink data object (such as a signal,
parameter, data type, or bus) in the Simulink
Model Explorer as comments in the code
generated for each object.
Include comments just above signals and Custom comments (MPT objects only)
parameter identifiers in the generated code as
specified in the MATLAB or TLC function.
Include the text specified in the Description Stateflow object descriptions
field in the Properties dialog box for a Stateflow
object as comments just above the code
generated for each object.
Include requirements assigned to Simulink Requirements in block comments
blocks in the generated code comments (for more
information, see “Generate Code for Models with
Requirements Links”).
• The description text for blocks and Stateflow objects and block names generated
as comments can include international (non-US-ASCII) characters. For details on
international character support, see “International Character Support”.
14-3
14 Code Appearance
• The code generation software automatically inserts comments into the generated
code for custom blocks. Therefore, you do not need to include block comments in the
associated TLC file for a custom block.
Note: If you have existing TLC files with manually inserted comments for block
descriptions, the code generation process emits these comments instead of the
automatically generated comments. Consider removing existing block comments
from your TLC files. Manually inserted comments might be poorly formatted in the
generated code and code-to-model traceability might not work.
• For virtual blocks or blocks that have been removed due to block reduction, comments
are not generated.
14-4
Add Custom Comments for Signal or Parameter Identifiers
You can include some or all of the property values for the data object. Each Simulink
signal or parameter data object has properties, as described in “Parameter and Signal
Property Values”. This example comment contains some of the property values for the
data object MAP as specified on the Model Explorer:
/* DocUnits: PSI */
/* Owner: */
/* DefinitionFile: specialDef */
real_T MAP = 0.0;
You can type text in the Description field in the Model Explorer for a signal or
parameter data object. If you select the Simulink data object descriptions check
box on the Comments pane in the Configuration Parameters dialog box, this text
appears beside the signal or parameter identifier in the generated code as a comment.
For example, typing Manifold Absolute Pressure in the Description field for the
data object MAP results in the following in the generated code:
real_T MAP = 0.0; /* Manifold Absolute Pressure */
To add a comment just above a signal or parameter identifier in the generated code:
1 The signal or parameter MPT object must use a custom storage class. Open the MPT
object properties dialog box and confirm that the Storage class is a custom storage
class ((Custom) suffixed to its name). The default storage class for an MPT object is
Global (Custom).
2 Write a MATLAB or TLC function that places comments in the generated files. An
example .m file named rtwdemo_comments_mptfun.m is provided in the matlab/
toolbox/rtw/rtwdemos folder.
The MATLAB function must have three arguments that correspond to objectName,
modelName, and request, respectively. The TLC function must have three
14-5
14 Code Appearance
14-6
Add Global Comments
The following examples show how to add a global comment to a Simulink model so
that the comment text appears in the generated file or files where you want. Specify a
template symbol name with a Simulink DocBlock, a Simulink annotation, or a Stateflow
note. You can also use a sorted-notes capability that works with Simulink annotations or
Stateflow notes (but not DocBlocks). For more information about template symbols, see
“Template Symbols and Rules” on page 14-69.
Note Template symbol names Description and ModifiedHistory also are fields
in the Model Properties dialog box. If you use one of these symbol names for global
comment text, and its Model Properties field also has text in it, both names appear in the
generated files.
• Abstract
• Description
• History
• ModifiedHistory
14-7
14 Code Appearance
• Notes
If you are using a DocBlock to add comments to your code, set the Document type
to Text. If you set Document type to RTF or HTML, your comments will not appear
in the code.
6 In the Block Properties dialog box, on the Block Annotation tab, select
%<ECoderFlag> and click OK. The symbol name that you typed in the previous step
now appears under the DocBlock in the model.
14-8
Add Global Comments
7 Save the model. After you generate code, the code generator places the comment in
each generated file whose template has the symbol name that you typed. The code
generator places the comment in the generated file at the location that corresponds
to where the symbol name is located in the template file.
8 To add more comments to the generated files, repeat steps 1–7.
14-9
14 Code Appearance
• Abstract
• Description
• History
• ModifiedHistory
• Notes
• Abstract
• Description
14-10
Add Global Comments
• History
• ModifiedHistory
• Notes
You can use sorted notes with a Simulink annotation or a Stateflow note, but not with a
DocBlock.
• In the Simulink annotation or the Stateflow note, type <S:NoteY> followed by the
first comment. Y is a number or a letter.
• Repeat for as many additional comments you want. Replace Y with a subsequent
number or letter.
The figure illustrates sorted notes on a model, and where the code generator places each
note in a generated file.
14-11
14 Code Appearance
The relevant fragment from the generated file for this model is:
** NOTES
**
14-12
Specify Comment Style
• C code uses /*...*/ notation for both single-line and multiple-line comments.
• C++ code uses //... notation and contains only single-line comments.
If you have an Embedded Coder license, you can modify the comment style for generated
code using the command-line parameter CommentStyle. The parameter takes the
following values:
Value Description
Auto (default) For C, generate single or multiple-line comments delimited by /*
and */.
For C++, generate single-line comments preceded by //.
Multi-line Generate single or multiple-line comments delimited by /* and */.
Single-line Generate single-line comments preceded by //.
For example, the following command sets the comment style to single-line comments:
>> set_param('rtwdemo_counter','CommentStyle','Single-line')
Note: For C code generation, select Single-line only if your compiler supports it
14-13
14 Code Appearance
Goal Specify
Set the maximum number of characters the An integer value for the “Maximum identifier
code generator uses for function, typedef, and length” parameter. For more information, see
variable names (default 31) “Specify Identifier Length to Avoid Naming
Collisions”. If you expect your model to generate
lengthy identifiers (due to use of long signal or
parameter names, for example), or you find that
identifiers are mangled more than expected,
increase the value of this parameter. For more
information, see “Specify Identifier Length to
Avoid Naming Collisions”.
Define a macro string that specifies certain A macro string for the Identifier format
substrings that are included within generated control parameters. For more information, see
identifiers for: “Identifier Format Control” on page 14-16.
For exceptions and limitations, see “Exceptions
• Global variables to Identifier Formatting Conventions” on
• Global types page 14-23 and “Identifier Format Control
Parameters Limitations” on page 14-24.
• Field names of global types
• Subsystem methods
• Subsystem method arguments
• Local temporary variables
• Local block output variables
• Constant macros
• Shared utilities
Set the minimum number of characters that the An integer value for the “Minimum mangle
code generator uses for the mangling string length” parameter. For more information,
see “Control Name Mangling in Generated
Identifiers” on page 14-19.
14-14
Customize Generated Identifier Naming Rules
Goal Specify
Control whether shortened names are used for Shortened for the “System-generated
system-generated identifiers identifiers” parameter. This setting:
For more information on these parameters, see “Code Generation Pane: Symbols”.
14-15
14 Code Appearance
• Valid tokens, which are listed in Identifier Format Tokens. You can use or omit
tokens depending on what you want to include in the identifier name. The Shared
utilities parameter requires you to specify the checksum string token, $C . The
other parameters require the mangling string token, $M. For more information, see
“Control Name Mangling in Generated Identifiers” on page 14-19. The mangling
string token is subject to the use and ordering restrictions noted in Identifier Format
Control Parameter Values.
• Valid C or C++ language identifier characters (a-z, A-Z, _ , 0-9).
The build process generates each identifier by expanding tokens and inserting the
resultant strings into the identifier. The tokens are expanded in the order listed in
Identifier Format Tokens. Character strings are inserted in the positions that you specify
around tokens directly into the identifier. Contiguous token expansions are separated by
the underscore (_) character.
Token Description
$M This token is required. If necessary, the code generator inserts a name
mangling string to avoid naming collisions. The position of the $M token
in the Identifier format control parameter specification determines
the position of the name mangling string in the generated identifier. For
example, if you use the specification $R$N$M, the name mangling string is
appended (if required) to the end of the identifier. For more information,
see “Control Name Mangling in Generated Identifiers” on page 14-19
.
$F Insert method name (for example, _Update for update method). This
token is available only for subsystem methods.
14-16
Identifier Format Control
Token Description
$N Insert name of object (block, signal or signal object, state, parameter,
shared utility function or parameter object) for which identifier is being
generated.
$R Insert root model name into identifier, replacing unsupported characters
with the underscore (_) character. When you use referenced models, this
token is required in addition to $M (see “Avoid Identifier Name Collisions
with Referenced Models” on page 14-21).
Note: This token replaces the Prefix model name to global identifiers
option in previous releases.
$H Insert tag indicating system hierarchy level. For root-level blocks, the tag
is the string root_. For blocks at the subsystem level, the tag is of the
form sN_. N is a unique system number assigned by the Simulink software.
This token is available only for subsystem methods and field names of
global types.
Note: This token replaces the Include data type acronym in identifier
option in previous releases.
$I Insert u if the argument is an input or y if the argument is an output. (For
example, rtu_ for an input argument and rty_ for an output argument).
This token is available only for subsystem method arguments.
$C This token is required for Shared utilities. If the identifier exceeds the
Maximum identifier length, the code generator inserts an 8-character
checksum to avoid naming collisions. The position of the $C token in
the Identifier format control parameter specification determines the
position of the checksum in the generated identifier. For example, if you
use the specification $N$C, the checksum is appended to the end of the
identifier. This token is available only for shared utilities.
Identifier Format Control Parameter Values lists the default macro string, the supported
tokens, and the applicable restrictions for each Identifier format control parameter.
14-17
14 Code Appearance
Non-ERT-based targets (such as the GRT target) implicitly use a default $R$N$M
specification. This default specification consists of the root model name, followed by the
name of the generating object (signal, parameter, state, and so on), followed by a name
mangling string.
For limitations that apply to Identifier format control parameters, see “Exceptions
to Identifier Formatting Conventions” on page 14-23 and “Identifier Format Control
Parameters Limitations” on page 14-24.
14-18
Control Name Mangling in Generated Identifiers
The length of the name mangling string is specified by the Minimum mangle length
parameter. The default value is 1, but this automatically increases during code
generation as a function of the number of collisions. To minimize disturbance to the
generated code during development, specify a larger Minimum mangle length. A
Minimum mangle length of 4 is a conservative value. A value of 4 allows for over 1.5
million collisions for a particular identifier before the mangle length is increased.
• Avoid name collisions. One way to avoid name collisions is to not use default block
names (for example, Gain1, Gain2...) when there are many blocks of the same type
in the model.
14-19
14 Code Appearance
If changes to the model create more or fewer collisions, an existing name mangling
string increases or decreases in length. If the length of the name mangling string
increases, additional characters are appended to the existing string. For example,
the mangling string 'xyz' can change to 'xyzQ'. For fewer collisions, the name
mangling string 'xyz' changes to 'xy'.
14-20
Avoid Identifier Name Collisions with Referenced Models
• You must include the $R token in the Identifier format control parameter
specifications (in addition to the $M token).
• The Maximum identifier length must be large enough to accommodate full
expansions of the $R and $M tokens. If Maximum identifier length is too small, a
code generation error occurs.
When a name conflict occurs between an identifier within the scope of a higher-level
model and an identifier within the scope of a referenced model, the identifier from the
referenced model is preserved. Name mangling is performed on the identifier from the
higher-level model.
If your model contains two referenced models with the same input or output port
names, and one of the referenced models contains an atomic subsystem with “Function
packaging” set to Nonreuseable function, a name conflict can occur and the build
process produces an error.
14-21
14 Code Appearance
• Choose unique names for Simulink objects (blocks, signals, states, and so on) as much
as possible.
• Use name mangling when conflicts cannot be avoided.
The position of the name mangling string is specified by the placement of the $M token in
the Identifier format control parameters. Mangle characters consist of alphanumeric
characters that are unique to each object. For more information, see “Control Name
Mangling in Generated Identifiers” on page 14-19.
14-22
Exceptions to Identifier Formatting Conventions
• Type name generation: name mangling conventions do not apply to type names (that
is, typedef statements) generated for global data types. If the $R token is included in
the Identifier format control parameter specification, the model name is included
in the typedef. When generating type definitions, the Maximum identifier length
parameter is not respected.
• Non-Auto storage classes: the Identifier format control parameters specification
does not affect objects (such as signals and parameters) that have a storage class
other than Auto (such as ImportedExtern or ExportedGlobal).
• For shared utilities, code generation inserts the checksum specified by $C to prevent
name collisions in the following situations:
14-23
14 Code Appearance
• The following autogenerated identifiers currently do not fully comply with the setting
of the Maximum identifier length parameter on the Code Generation > Symbols
pane of the Configuration Parameters dialog box.
• Model methods
• Model methods
• Reentrant model function arguments
14-24
Identifier Format Control Parameters Limitations
14-25
14 Code Appearance
For more information on these parameters, see “Specify Data Object Naming Rules”.
14-26
Control Code Style
You can change the code style, cast expressions, and indentation of your generated code
to conform to certain coding standards. Modify style options by setting parameters on the
Code Generation > Code Style pane.
In the generated code, you can control the following style aspects:
14-27
14 Code Appearance
The following example model shows the three levels of parentheses control that you
can set before generating code: rtwdemo_parentheses. For more information on this
parameter, see “Parentheses level”.
K&R
K&R stands for Kernighan and Ritchie. Each function has the opening and closing brace
on its own line at the same level of indentation as the function header. Code within the
function is indented according to the Indent size.
For blocks within a function, opening braces are on the same line as the control
statement. Closing braces are on a new line at the same level of indentation as the
control statement. Code within the block is indented according to the Indent size.
For example, here is generated code with the Indent style set to K&R with an Indent
size of 2:
void rt_OneStep(void)
{
14-28
Control Code Style
OverrunFlag = TRUE;
rtwdemo_counter_step();
OverrunFlag = FALSE;
}
Allman
Each function has the opening and closing brace on its own line at the same level of
indentation as the function header. Code within the function is indented according to the
Indent size.
For blocks within a function, opening and closing braces for control statements are on
a new line at the same level of indentation as the control statement. This is the key
difference between K&R and Allman styles. Code within the block is indented according
to the Indent size.
For example, here is generated code with the Indent style set to Allman with an
Indent size of 4:
void rt_OneStep(void)
{
static boolean_T OverrunFlag = 0;
if (OverrunFlag)
{
rtmSetErrorStatus(rtwdemo_counter_M, "Overrun");
return;
}
OverrunFlag = TRUE;
rtwdemo_counter_step();
OverrunFlag = FALSE;
}
14-29
14 Code Appearance
From the Casting Modes drop-down list, three parameter options control how the code
generator casts data types.
• Nominal instructs the code generator to generate code that has minimal data type
casting and is compatible with previous code generator versions. When you do not
have special data type information requirements, choose Nominal .
• Standards Compliant instructs the code generator to cast data types to conform to
MISRA standards when it generates code. The MISRA data type casting eliminates
common MISRA standard violations, including address arithmetic and assignment. It
reduces 10.1, 10.2, 10.3, and 10.4 violations.
When you choose Nominal casting mode, the code generator does not create data type
casts for variables in the generated code.
1 On the Code Generation > Code Style pane, from the Casting Modes drop-down
list, select Nominal.
2 On the Code Generation > Report pane, select Create code generation report.
14-30
Control Code Style
/* Switch: 'XRootX/Switch' */
if (!rtb_equal_to_count) {
/* Update for UnitDelay: 'XRootX/X' incorporates:
* Constant: 'XRootX/RESET'
14-31
14 Code Appearance
*/
rtDWork.X = 0U;
}
When you choose Standards Compliant casting mode, the code generator creates
MISRA standards compliant data type casts for variables in the generated code.
1 On the Code Style pane, from the Casting Modes drop-down list, select
Standards Compliant.
2 On the Code Generation pane, click Apply.
3 Click Generate Code.
4 In the Code Generation report left pane, click rtwdemo_rtwecintro.c to see the
code.
void rtwdemo_rtwecintro_step(void)
{
boolean_T rtb_equal_to_count;
14-32
Control Code Style
rtPrevZCSigState.Amplifier_Trig_ZCE = (uint8_T)(int32_T)(rtb_equal_to_count ?
(int32_T)(uint8_T)POS_ZCSIG : (int32_T)(uint8_T)ZERO_ZCSIG);
/* Switch: '<Root>/Switch' */
if (!rtb_equal_to_count) {
/* Update for UnitDelay: '<Root>/X' incorporates:
* Constant: '<Root>/RESET'
*/
rtDWork.X = 0U;
}
When you choose Explicit casting mode, the code generator creates explicit data type
casts for variables in the generated code.
1 On the Code Style pane, from the Casting Modes drop-down list, select Explicit.
2 On the Code Generation pane, click Apply.
3 Click Generate Code.
4 In the Code Generation report left pane, click rtwdemo_rtwecintro.c to see the
code.
14-33
14 Code Appearance
*/
rtb_equal_to_count = (boolean_T)((int32_T)rtDWork.X != 16);
/* Switch: '<Root>/Switch' */
if (!(int32_T)rtb_equal_to_count) {
/* Update for UnitDelay: '<Root>/X' incorporates:
* Constant: '<Root>/RESET'
*/
rtDWork.X = 0U;
}
More About
• “Code Generation Pane: Code Style”
14-34
Customize Code Organization and Format
Custom file processing (CFP) tools allow you to customize the organization and
formatting of your generated code. With these tools, you can:
• Generate a source (.c or .cpp) or header (.h) file. Using a custom file processing
template (CFP template), you can control how code emits to the standard generated
model files (for example, model.c or .cpp, model.h) or generate files that are
independent of model code.
• Organize generated code into sections (such as includes, typedefs, functions, and
more). Your CFP template can emit code (for example, functions), directives (such as
#define or #include statements), or comments into each section.
• Generate custom file banners (comment sections) at the start and end of generated
code files and custom function banners that precede functions in the generated code.
• Generate code to call model functions, such as model_initialize, model_step,
and so on.
• Generate code to read and write model inputs and outputs.
• Generate a main program module.
• Obtain information about the model and the generated files from the model.
• Code generation template (CGT) files: a CGT file defines the top-level organization
and formatting of generated code. See “Code Generation Template (CGT) Files” on
page 14-38.
• The code template API: a high-level Target Language Compiler (TLC) API that
provides functions with which you can organize code into named sections and
subsections of generated source and header files. The code template API also provides
utilities that return information about generated files, generate standard model calls,
and perform other functions. See “Code Template API Summary” on page 14-58.
14-35
14 Code Appearance
• Custom file processing (CFP) templates: a CFP template is a TLC file that manages
the process of custom code generation. A CFP template assembles code to be
generated into buffers. A CFP template also calls the code template API to emit the
buffered code into specified sections of generated source and header files. A CFP
template interacts with a CGT file, which defines the ordering of major sections of the
generated code. See “Custom File Processing (CFP) Templates” on page 14-42.
To use CFP templates, you must understand TLC programming, for more information,
see “Target Language Compiler”.
Goal Action
Specify a template that defines Enter a code generation template (CGT) file for the Source
the top-level organization and file (*.c) template parameter.
formatting of generated source
code (.c or .cpp) files
Specify a template that defines Enter a CGT file for the Header file (*.h) template
the top-level organization and parameter. This template file can be the same template file
formatting of generated header that you specify for Source file (.c) template. If you use the
(.h) files same template file, source and header files contain identical
banners. The default template is matlabroot
/toolbox/rtw/targets/ecoder/
ert_code_template.cgt.
Specify a template that organizes Enter a custom file processing (CFP) template file for the
generated code into sections (such “File customization template” parameter. A CFP template can
as includes, typedefs, functions, emit code, directives, or comments into each section. For more
and more) information, see “Custom File Processing (CFP) Templates” on
page 14-42.
Generate a model-specific example Select Generate an example main program. For more
main program module information, see “Generate a Standalone Program”.
Note: Place the template files that you specify on the MATLAB path.
14-36
Specify Templates For Code Generation
Select and edit CGT files and CFP templates, and specify their use in the code generation
process in the Code Generation > Templates pane of a model configuration set. The
following figure shows options configured for their defaults.
• The Source file (.c) template field in the Code templates and Data templates
sections. This field specifies the name of a CGT file to use when generating source (.c
or .cpp) files. You must place this file on the MATLAB path.
• The Header file (.h) template field in the Code templates and Data templates
sections. This field specifies the name of a CGT file to use when generating header
(.h) files. You must place this file on the MATLAB path.
By default, the template for both source and header files is matlabroot/toolbox/rtw/
targets/ecoder/ert_code_template.cgt.
• The File customization template edit field in the Custom templates section. This
field specifies the name of a CFP template file to use when generating code files. You
must place this file on the MATLAB path. The default CFP template is matlabroot/
toolbox/rtw/targets/ecoder/example_file_process.tlc.
In each of these fields, click Browse to navigate to and select an existing CFP template
or CGT file. Click Edit to open the specified file into the MATLAB editor where you can
customize it.
14-37
14 Code Appearance
(Required) This section contains tokens that define an ordered partitioning of the
generated code into a number of sections (such as Includes and Defines sections).
Tokens have the form of:
%<SectionName>
For example,
%<Includes>
The code generation software defines a minimal set of required tokens. These tokens
generate C or C++ source or header code. They are built-in tokens (see “Built-In Tokens
and Sections” on page 14-39). You can also define custom tokens and custom sections.
Each token functions as a placeholder for a corresponding section of generated code. The
ordering of the tokens defines the order in which the corresponding sections appear in
the generated code. If you do not include a token, then the corresponding section is not
generated. To generate code into a given section, explicitly call the code template API
from a CFP template, as described in “Custom File Processing (CFP) Templates” on page
14-42.
14-38
Code Generation Template (CGT) Files
The CGT tokens define the high-level organization of generated code. Using the code
template API, you can partition each code section into named subsections, as described in
“Subsections” on page 14-40.
In the code insertion section, you can also insert C or C++ comments between tokens.
Such comments emit directly into the generated code.
(Optional) This section contains comments and tokens you use in generating a custom file
banner.
(Optional) This section contains comments and tokens for use in generating a custom
function banner.
(Optional) This section contains comments and tokens for use in generating a custom
shared utility function banner.
(Optional) This section contains comments for use in generating a custom trailer banner.
For more information on these sections, see “Generate Custom File and Function
Banners” on page 14-61.
14-39
14 Code Appearance
Note: If you modify a CGT file and then rebuild your model, the code generation process
does not force a top model build. To regenerate the code, see “Force Regeneration of Top
Model Code”.
The following table summarizes the built-in tokens and corresponding section names,
and describes the code sections.
Subsections
You can define one or more named subsections for any section. Some of the built-in
sections have predefined subsections summarized in table “Subsections Defined for Built-
In Sections”.
14-40
Code Generation Template (CGT) Files
Note: Sections and subsections emit to the source or header file in the order listed in the
CGT file.
Using the custom section feature, you can define additional sections. See “Generate a
Custom Section”.
14-41
14 Code Appearance
Once you have created a CFP template, you must integrate it into the code generation
process, using the File customization template edit field. See “Specify Templates For
Code Generation” on page 14-37.
Code for each section is assembled in buffers and then emitted, in the order listed, to the
file being generated.
To generate a file section, your CFP template must first assemble the code to be
generated into a buffer. Then, to emit the section, your template calls the TLC function
LibSetSourceFileSection(fileH, section, tmpBuf)
where
14-42
Custom File Processing (CFP) Templates
• If Subsections Defined for Built-In Sections does not define subsections for a given
section, use the section name as the section argument.
• If Subsections Defined for Built-In Sections defines one or more subsections for
a given section, you can use either the section name or a subsection name as the
section argument.
• If you have defined a custom token denoting a custom section, do not call
LibSetSourceFileSection. Special API calls are provided for custom sections
(see “Generate a Custom Section” on page 14-51).
• tmpBuf is the buffer containing the code to be emitted.
There is no requirement to generate all of the available sections. Your template need only
generate the sections you require in a particular file.
Note that legality or syntax checking is not performed on the custom code within each
section.
See “Generate Source and Header Files with a Custom File Processing (CFP) Template”
on page 14-46, for typical usage examples.
14-43
14 Code Appearance
The following fragment shows the rtwdemo_mpf.c file header that is generated using
this default template:
/*
* File: rtwdemo_mpf.c
*
* Code generated for Simulink model 'rtwdemo_mpf'.
*
* Model version : 1.88
* Simulink Coder version : 8.0 (R2011a) 26-Aug-2010
* TLC version : 7.6 (Sep 3 2010)
* C/C++ source code generated on : Thu Sep 09 10:10:14 2010
*
* Target selection: ert.tlc
* Embedded hardware selection: Generic->32-bit Embedded Processor
* Code generation objectives: Unspecified
* Validation result: Not run
*/
You can change the organization of generated files using code templates and data
templates. Code templates organize the files that contain functions, primarily. Data
templates organize the files that contain identifiers. In this procedure, you organize the
generated files, using the supplied code and data templates:
14-44
Change the Organization of a Generated File
** FILE INFORMATION:
** Filename: rtwdemo_mpf.c
** File Creation Date: 09-Sep-2010
**
** ABSTRACT:
**
**
** NOTES:
**
**
** MODEL INFORMATION:
** Model Name: rtwdemo_mpf
** Model Description: Data packaging examples
** Model Version: 1.89
** Model Author: The MathWorks Inc. - Mon Mar 01 11:23:00 2004
**
** MODIFICATION HISTORY:
** Model at Code Generation: ssulliva - Thu Sep 09 10:19:35 2010
**
** Last Saved Modification: ssulliva - Thu Sep 09 10:19:13 2010
**
**
*******************************************************************************
**/
14-45
14 Code Appearance
This example shows you the process of generating a simple source (.c or .cpp) and
header (.h) file using the example CFP template. Then, it examines the template and the
code generated by the template.
Follow the steps below to become acquainted with the use of CFP templates:
14-46
Generate Source and Header Files with a Custom File Processing (CFP) Template
It now reads:
%assign ERTCustomFileTest = TLC_TRUE
14-47
14 Code Appearance
Source (.c or .cpp) and header (.h) files are created by calling LibCreateSourceFile,
as in the following excerpts:
%assign cFile = LibCreateSourceFile("Source", "Custom", "timestwo")
...
%assign hFile = LibCreateSourceFile("Header", "Custom", "timestwo")
Subsequent code refers to the files by the file reference returned from
LibCreateSourceFile.
The code template API lets you partition the code generated to each file into sections,
tagged as Definitions, Includes, Functions, Banner, and so on. You can append
code to each section as many times as required. This technique gives you a great deal of
flexibility in the formatting of your custom code files.
Subsections Defined for Built-In Sections describes the available file sections and their
order in the generated file.
For each section of a generated file, use %openfile and %closefile to store the text
for that section in temporary buffers. Then, to write (append) the buffer contents to a
file section, call LibSetSourceFileSection, passing in the desired section tag and file
reference. For example, the following code uses two buffers (tmwtypesBuf and tmpBuf)
to generate two sections (tagged "Includes" and "Functions") of the source file
timestwo.c or .cpp (referenced as cFile):
%openfile tmwtypesBuf
#include "tmwtypes.h"
%closefile tmwtypesBuf
%<LibSetSourceFileSection(cFile,"Includes",tmwtypesBuf)>
14-48
Generate Source and Header Files with a Custom File Processing (CFP) Template
%openfile tmpBuf
%closefile tmpBuf
%<LibSetSourceFileSection(cFile,"Functions",tmpBuf)>
#include "tmwtypes.h"
The timestwo.c or .cpp file generated in the previous example was independent
of the standard code files generated from a model (for example, model.c or .cpp,
model.h, and so on). You can use similar techniques to generate custom code within
the model files. The code template API includes functions to obtain the names of the
standard models files and other model-related information. The following excerpt calls
LibGetMdlPubHdrBaseName to obtain the name for the model.h file. It then obtains a
file reference and generates a definition in the Defines section of model.h:
%% Add a #define to the model's public header file model.h
%openfile tmpBuf
%closefile tmpBuf
%<LibSetSourceFileSection(modelH,"Defines",tmpBuf)>
Examine the generated rtwdemo_udt.h file to see the generated #define directive.
14-49
14 Code Appearance
Normally, the ERT target determines whether and how to generate an ert_main.c
or .cpp module based on the settings of the Generate an example main program
and Target operating system options on the Templates pane of the Configuration
Parameters dialog box. You can use a CFP template to override the normal behavior and
generate a main program module customized for your target environment.
To support generation of main program modules, two TLC files are provided:
When generating your own main program module, you disable the default generation of
ert_main.c or .cpp. The TLC variable GenerateSampleERTMain controls generation
of ert_main.c or .cpp. You can directly force this variable to TLC_FALSE. The
examples bareboard_mrmain.tlc and bareboard_srmain.tlc use this technique, as
shown in the following excerpt from bareboard_srmain.tlc.
%if GenerateSampleERTMain
%assign CompiledModel.GenerateSampleERTMain = TLC_FALSE
%warning Overriding example ert_main.c!
%endif
14-50
Generate Source and Header Files with a Custom File Processing (CFP) Template
The following code illustrates how to deselect and disable the Generate an example
main program option in the context of a SelectCallback function.
slConfigUISetVal(hDlg, hSrc, 'GenerateSampleERTMain', 'off');
slConfigUISetEnabled(hDlg, hSrc, 'GenerateSampleERTMain',0);
Note Creation of a main program for your target environment requires some
customization; for example, in a bareboard environment you need to attach rt_OneStep
to a timer interrupt. It is expected that you will customize either the generated code,
the generating TLC code, or both. See “Guidelines for Modifying the Main Program” and
“Guidelines for Modifying rt_OneStep” for further information.
• Add a custom token to the code insertion section of your CGT file.
• In your CFP file:
14-51
14 Code Appearance
The following code examples illustrate the addition of a custom token, Myincludes, to
a CGT file, and the subsequent association of the custom section Myincludes with the
built-in section Includes in a CFP file.
Note: If you have not already created custom CGT and CFP files for your model, copy the
default template files matlabroot/toolbox/rtw/targets/ecoder/ert_code_template.cgt and
matlabroot/toolbox/rtw/targets/ecoder/example_file_process.tlc to a work folder that is
outside the MATLAB folder structure but on the MATLAB or TLC path, rename them
(for example, add the prefix test_ to each file), and update the Templates pane of the
Configuration Parameters dialog box to reference them.
First, add the token Myincludes to the code insertion section of your CGT file. For
example:
%<Includes>
%<Myincludes>
%<Defines>
%<Types>
%<Enums>
%<Definitions>
%<Declarations>
%<Functions>
Next, in the CFP file, add code to generate include directives into a buffer. For example,
in your copy of the example CFP file, you could insert the following section between the
Includes section and the Create a simple main section:
%openfile tmpBuf
#include "moretables1.h"
#include "moretables2.h"
%closefile tmpBuf
%<LibAddSourceFileCustomSection(modelC,"Includes","Myincludes")>
%<LibSetSourceFileCustomSection(modelC,"Myincludes",tmpBuf)>
14-52
Generate Source and Header Files with a Custom File Processing (CFP) Template
In the generated code, the include directives generated to the custom section appear after
other code directed to Includes.
#include "rtwdemo_udt.h"
#include "rtwdemo_udt_private.h"
/* #include "mytables.h" */
#include "moretables1.h"
#include "moretables2.h"
Note: The placement of the custom token in this example CGT file is arbitrary. By
locating %<Myincludes> after %<Includes>, the CGT file specifies only that the
Myincludes code appears after Includes code.
Custom Tokens
Custom tokens are automatically translated to TLC syntax as a part of the build process.
To escape a token, that is to prepare it for normal TLC expansion, use the '!' character.
For example, the token %<!TokenName> is expanded to %<TokenName> by the template
conversion program. You can specify valid TLC code, including TLC function calls: %<!
MyTLCFcn()>.
14-53
14 Code Appearance
• Define what code the code generation software should add to the generated file
• Control the location of code in the file
• Optionally insert comments in the generated file
Notice %<Includes>, for example, on the template. The term Includes is a symbol
name. A percent sign and brackets (%< >) must enclose every symbol name. You can
add the desired symbol name (within the %< > delimiter) at a particular location in
the template. This is how you control where the code generator places an item in the
generated file.
14-54
Comparison of a Template and Its Generated File
Portion of
Example Template Corresponding Portion of Generated File
. .
. .
. .
/*#INCLUDES*/ (1) 26 /*#INCLUDES*/
%<Includes> 27 #include "rtwdemo_codetemplate.h"
/*#DEFINES*/ (2) None 28 #include "rtwdemo_codetemplate_private.h"
%<Defines> 29
#pragma string1 (3) 30 /*#DEFINES*/
31 #pragma string1
/*DEFINITIONS*/ (4) 32 /*DEFINITIONS*/
%<Definitions> 33 /* Block states (auto storage) */
#pragma string2 (5) 34 rtDWork;
%<Declarations> (6) 35
%<Functions> (7) 36 /* External output ( fed by signals with auto storage) */
37 rtY;
38
39 /* Real-time model */
40 rtM_;
41 *rtM = &rtM_;
42 #pragma string2
43
None 44 /* Model step function */
45 void rtwdemo_codetemplate_step(void)
46 {
47
48 /* local block i/o variables */
49
50 rtb_Switch;
51 rtb_RelOpt;
52
53 /* Sum: '' incorporates:
54 * UnitDelay: ''
55 */
56 rtb_Switch = ()(()rtDWork.X + 1U);
57
58 /* RelationalOperator: '' */
59 rtb_RelOpt = (rtb_Switch != 16U);
60
61 /* Outport: '' */
62 rtY.Out = rtb_RelOpt;
63
64 /* Switch: '' */
65 if(rtb_RelOpt) {
66 } else {
67 rtb_Switch = 0U;
68 }
69
70 /* Update for UnitDelay: '' */
71 rtDWork.X = rtb_Switch;
72
73 /* (no update code required) */
74 }
.
.
.
14-55
14 Code Appearance
14-56
Comparison of a Template and Its Generated File
For a list of template symbols and the rules for using them, see “Template Symbol
Groups” on page 14-69, “Template Symbols” on page 14-72, and “Rules for
Modifying or Creating a Template” on page 14-75. To set comment options, from the
Simulation menu, select Model Configuration Parameters. On the Configuration
Parameters dialog box, select the Code Generation > Comments pane. For details, see
“Configure Code Comments”.
14-57
14 Code Appearance
Function Description
LibGetNumSourceFiles Returns the number of created source files
(.c or .cpp and .h).
LibGetSourceFileTag Returns <filename>_h and
<filename>_c for header and source files,
respectively, where filename is the name of
the model file.
LibCreateSourceFile Creates a new C or C++ file and returns its
reference. If the file already exists, simply
returns its reference.
LibGetSourceFileFromIdx Returns a model file reference based on its
index. This is useful for a common operation
on all files, such as to set the leading file
banner of all files.
LibSetSourceFileSection Adds to the contents of a specified section
within a specified file (see also “Custom File
Processing (CFP) Template Structure” on
page 14-42).
LibIndentSourceFile Indents a file (from within the TLC
environment).
LibCallModelInitialize Returns code for calling the model's
model_initialize function (valid for ERT
only).
LibCallModelStep Returns code for calling the model's
model_step function (valid for ERT only).
LibCallModelTerminate Returns code for calling the model's
model_terminate function (valid for ERT
only).
14-58
Code Template API Summary
Function Description
LibCallSetEventForThisBaseStep Returns code for calling the model's set
events function (valid for ERT only).
LibWriteModelData Returns data for the model (valid for ERT
only).
LibSetRTModelErrorStatus Returns the code to set the model error
status.
LibGetRTModelErrorStatus Returns the code to get the model error
status.
LibIsSingleRateModel Returns true if model is single rate and false
otherwise.
LibGetModelName Returns name of the model (without an
extension).
LibGetMdlSrcBaseName Returns the name of model's main source file
(for example, model.c or .cpp).
LibGetMdlPubHdrBaseName Returns the name of model's public header
file (for example, model.h).
LibGetMdlPrvHdrBaseName Returns the name of the model's
private header file (for example,
model_private.h).
LibIsSingleTasking Returns true if the model is configured for
single-tasking execution.
LibWriteModelInput Returns the code to write to a particular root
input (that is, a model inport block). (valid
for ERT only).
LibWriteModelOutput Returns the code to write to a particular root
output (that is, a model outport block). (valid
for ERT only).
LibWriteModelInputs Returns the code to write to root inputs (that
is, all model inport blocks). (valid for ERT
only)
LibWriteModelOutputs Returns the code to write to root outputs
(that is, all model outport blocks). (valid for
ERT only).
14-59
14 Code Appearance
Function Description
LibNumDiscreteSampleTimes Returns the number of discrete sample
times in the model.
LibSetSourceFileCodeTemplate Set the code template to be used for
generating a specified source file.
LibSetSourceFileOutputDirectory Set the folder into which a specified source
file is to be generated.
LibAddSourceFileCustomSection Add a custom section to a source file. The
custom section must be associated with
one of the built-in (required) sections:
Includes, Defines, Types, Enums,
Definitions, Declarations, or
Functions.
LibSetSourceFileCustomSection Adds to the contents of a specified custom
section within a specified file. The custom
section must have been previously created
with LibAddSourceFileCustomSection.
LibGetSourceFileCustomSection Returns the contents of a specified custom
section within a specified file.
LibSetCodeTemplateComplianceLevel This function must be called from your CFP
template before other code template API
functions are called. Pass in 2 as the level
argument.
14-60
Generate Custom File and Function Banners
To specify banners, create a custom CGT file with customized banner sections. The build
process creates an executable TLC file from the CGT file. The code generation process
then invokes the TLC file.
You do not need to be familiar with TLC programming to generate custom banners. You
can modify example files that are supplied with the ERT target.
Note Prior releases supported direct use of customized TLC files as banner templates.
You specified these with the Source file (.c) banner template and Header file (.h)
banner template options of the ERT target. You can still use a custom TLC file banner
templates, however, you can now use CGT files instead.
ERT template options on the Code Generation > Templates pane of a configuration
set, in the Code templates section, support banner generation.
• “Code templates: Source file (*.c) template”: CGT file to use when generating source
(.c or .cpp) files. Place this file on the MATLAB path.
• “Code templates: Header file (*.h) template”: CGT file to use when generating header
(.h) files. You must place this file on the MATLAB path. This file can be the same
template specified in the Code templates: Source file (*.c) template field, in which
case identical banners are generated in source and header files.
By default, the template for both source and header files is matlabroot/toolbox/rtw/
targets/ecoder/ert_code_template.cgt.
• In each of these fields, click Browse to navigate to and select an existing CGT file
for use as a template. Click Edit to open the specified file into the MATLAB editor,
where you can customize it.
14-61
14 Code Appearance
14-62
Generate Custom File and Function Banners
Customize a Code Generation Template (CGT) File for File and Function
Banner Generation
This section describes how to edit a CGT file for custom file and function banner
generation. For a description of CGT files, see “Code Generation Template (CGT) Files”
on page 14-38.
Components of the File and Function Banner Sections in the CGT file
In a CGT file, you can modify the following sections: file banner, function banner, shared
utility function banner, and file trailer. Each section is defined by open and close tags.
The tags specific to each section are shown in the following table.
You can customize your banners by including tokens and comments between the
open and close tag for each section. Tokens are typically TLC variables, for example
<ModelVersion>, which are replaced with values in the generated code.
Note: Including C comment indicators, '/*' or a '*/', in the contents of your banner might
introduce an error in the generated code.
An open tag includes tag attributes. Enclose the value of the attribute in double quotes.
The attributes available for an open tag are:
• width: specifies the width of the file or function banner comments in the generated
code. The default value is 80.
• style: specifies the boundary for the file or function banner comments in the
generated code.
14-63
14 Code Appearance
• classic
/* single line comments */
/*
* multiple line comments
* second line
*/
• classic_cpp
// single line comments
//
// multiple line comments
// second line
//
• box
/**********************************************************/
/* banner contents */
/**********************************************************/
• box_cpp
////////////////////////////////////////////////////////////
// banner contents //
////////////////////////////////////////////////////////////
• open_box
/**********************************************************
* banner contents
**********************************************************/
• open_box_cpp
////////////////////////////////////////////////////////////
// banner contents
////////////////////////////////////////////////////////////
• doxygen
/** single line comments */
/**
* multiple line comments
* second line
14-64
Generate Custom File and Function Banners
*/
• doxygen_cpp
/// single line comments
///
/// multiple line comments
/// second line
///
• doxygen_qt
/*! single line comments */
/*!
* multiple line comments
* second line
*/
• doxygen_qt_cpp
//! single line comments
//!
//! multiple line comments
//! second line
//!
File Banner
This section contains comments and tokens for use in generating a custom file banner.
The file banner precedes C or C++ code generated by the model. If you omit the file
banner section from the CGT file, then no file banner emits to the generated code. The
following section is the file banner section provided with the default CGT file, matlabroot/
toolbox/rtw/targets/ecoder/ert_code_template.cgt.
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%% Custom file banner section (optional)
%%
<FileBanner style="classic">
File: %<FileName>
14-65
14 Code Appearance
%<CodeGenSettings>
</FileBanner>
Function Banner
This section contains comments and tokens for use in generating a custom function
banner. The function banner precedes C or C++ function generated during the build
process. If you omit the function banner section from the CGT file, the default function
banner emits to the generated code. The following section is the default function banner
section provided with the default CGT file, matlabroot/toolbox/rtw/targets/ecoder/
ert_code_template.cgt.
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%% Custom function banner section (optional)
%% Customize function banners by using the following predefined tokens:
%% %<ModelName>, %<FunctionName>, %<FunctionDescription>, %<Arguments>,
%% %<ReturnType>, %<GeneratedFor>, %<BlockDescription>.
%%
<FunctionBanner style="classic">
%<FunctionDescription>
%<BlockDescription>
</FunctionBanner>
14-66
Generate Custom File and Function Banners
The shared utility function banner section contains comments and tokens for use in
generating a custom shared utility function banner. The shared utility function banner
precedes C or C++ shared utility function generated during the build process. If you omit
the shared utility function banner section from the CGT file, the default shared utility
function banner emits to the generated code. The following section is the default shared
utility function banner section provided with the default CGT file, matlabroot/toolbox/
rtw/targets/ecoder/ert_code_template.cgt.
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%% Custom shared utility function banner section (optional)
%% Customize banners for functions generated in shared location by using the
%% following predefined tokens: %<FunctionName>, %<FunctionDescription>,
%% %<Arguments>, %<ReturnType>.
%%
<SharedUtilityBanner style="classic">
%<FunctionDescription>
</SharedUtilityBanner>
14-67
14 Code Appearance
File Trailer
The file trailer section contains comments for generating a custom file trailer. The file
trailer follows C or C++ code generated from the model. If you omit the file trailer section
from the CGT file, no file trailer emits to the generated code. The following section is the
default file trailer provided in the default CGT file.
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%% Custom file trailer section (optional)
%%
<FileTrailer style="classic">
File trailer for generated code.
[EOF]
</FileTrailer>
Tokens available for the file banner are available for the file trailer. See Summary of
Tokens for File Banner Generation.
14-68
Template Symbols and Rules
Introduction
“Template Symbol Groups” on page 14-69 and “Template Symbols” on page 14-72
describe custom file processing (CFP) template symbols and rules for using them. The
location of a symbol in one of the supplied template files (code_c_template.cgt,
code_h_template.cgt, data_c_template.cgt, or data_h_template.cgt)
determines where the items associated with that symbol are located in the corresponding
generated file. “Template Symbol Groups” on page 14-69 identifies the symbol
groups, starting with the parent (“Base”) group, followed by the children of each parent.
“Template Symbols” on page 14-72 lists the symbols alphabetically.
Defines
Definitions
Documentation
Enums
Functions
Includes
Types
Declarations ExternalCalibrationLookup1D
14-69
14 Code Appearance
ExternalCalibrationScalar
ExternalVariableScalar
Defines LocalDefines
LocalMacros
Definitions FilescopeCalibrationLookup1D
FilescopeCalibrationLookup2D
FilescopeCalibrationScalar
FilescopeVariableScalar
GlobalCalibrationLookup1D
GlobalCalibrationLookup2D
GlobalCalibrationScalar
GlobalVariableScalar
14-70
Template Symbols and Rules
Banner
Created
Creator
Date
Description
FileName
History
LastModifiedDate
LastModifiedBy
ModelName
ModelVersion
ModifiedBy
ModifiedComment
ModifiedHistory
Notes
ToolVersion
Functions CFunctionCode
Types This parent has no children.
14-71
14 Code Appearance
Template Symbols
14-72
Template Symbols and Rules
14-73
14 Code Appearance
14-74
Template Symbols and Rules
* Symbol names must be enclosed between %< >. For example, %<Functions>.
** This symbol can be used to add a comment to the generated files. See “Add Global
Comments”. The code generator places the comment in each generated file whose
template has this symbol name. The code generator places the comment at the location
that corresponds to where the symbol name is located in the template file.
*** The description can be deduced from the symbol name. For example,
GlobalCalibrationScalar is a symbol that identifies a scalar. It contains data of
global scope that you can calibrate .
1 Place a symbol on a template within the %< > delimiter. For example, the symbol
named Includes should look like this on a template: %<Includes>. Note that
symbol names are case sensitive.
2 Place a symbol on a template where desired. Its location on the template determines
where the item associated with this symbol is located in the generated file. If no item
is associated with it, the symbol is ignored.
3 Place a C/C++ statement outside of the %< > delimiter, and on a different line than
a %< > delimiter, for that statement to appear in the generated file. For example,
#pragma message ("my text") in the template results in #pragma message
("my text") at the corresponding location in the generated file. Note that the
statement must be compatible with your C/C++ compiler.
4 Use the .cgt extension for every template filename. ("cgt" stands for code
generation template.)
14-75
14 Code Appearance
14-76
Code Annotation for Justifying Polyspace Checks
Polyspace might highlight overflows for certain operations that are legitimate because
of the way Embedded Coder implements these operations. Consider the following model
and the corresponding generated code.
Embedded Coder software recognizes that the largest built-in data type is 32-bit. It is not
possible to saturate the results of the additions and subtractions using MIN_INT32 and
MAX_INT32 and a bigger single-word integer data type. Instead the software detects the
results overflow and the direction of the overflow, and saturates the result.
If you do not provide justification for the addition operator on line 36, a Polyspace
verification generates an orange check that indicates a potential overflow. The
verification does not take into account the saturation function of lines 37 to 43. In
addition, the trace-back functionality of Polyspace Code Prover does not identify the
reason for the orange check.
14-77
14 Code Appearance
When you generate code, the Embedded Coder software annotates the code with
comments for Polyspace. For example:
32 /* Sum: '<Root>/Sum' incorporates:
33 * Inport: '<Root>/In1'
34 * Inport: '<Root>/In2'
35 */
36 qY_0 = sat_add_U.In1 +/*MW:OvOk*/ sat_add_U.In2;
When you run a verification using Polyspace Code Prover, the Polyspace software uses
the annotations to justify the operator-related orange checks and assigns the Not a
defect classification to the checks.
14-78
Manage Placement of Data Definitions and Declarations
The following six MPF settings are distributed among the main procedures and form an
important interdependency:
• The Data definition field on the Code Placement pane of the Configuration
Parameters dialog box.
• The Data declaration field on the Code Placement pane of the Configuration
Parameters dialog box.
• The Owner field of the data object in the Model Explorer and the checkbox for Use
owner from data object for data definition placement on the Code Placement
pane of the Configuration Parameters dialog box. The term "ownership settings"
refers to these fields together.
• The Definition file field of the data object on the Model Explorer.
• The Header file field of the data object on the Model Explorer.
• The Memory section field of the data object on the Model Explorer.
14-79
14 Code Appearance
Overview
There is a priority order among interdependent MPF settings. From highest to lowest,
the priorities are
Priority order varies inversely with frequency of use, as illustrated below. For example,
Definition File is highest priority but least used.
Header File
Ownership
Read-Write Global
Lowest priority Most used
14-80
Manage Placement of Data Definitions and Declarations
Unless they are overridden, the Read-Write and Global priorities place in the generated
files all of the model's MPF-derived data objects that you selected using Data Object
Wizard. (See “Create Data Objects with Data Object Wizard” for details.) Before
generating the files, you can use the higher priority Definition file, Header file, and
Ownership, as desired, to override Read-Write or Global priorities for single data objects.
Most users will employ Read-Write or Global, without an override. A few users, however,
will want to do an override for certain data objects. We expect that those users whose
applications include multiple modules will want to use the Ownership priority.
The priorities are used only for those data objects that are derived from
Simulink.Signal and Simulink.Parameter, and whose custom storage classes are
specified using the Custom Storage Class Designer. (For details, see “Design Custom
Storage Classes and Memory Sections”.) Otherwise, the build process determines the
data placement.
Read-Write Priority
This is the lowest priority. Consider that a model consists of one or more Simulink
blocks or Stateflow diagrams. There can be subsystems within these. For the purpose of
illustration, think of a model with one top-level block called fuelsys. You double-clicked
the block and now see three subsystems labeled subsys1, subsys2 and subsys3, as
shown in the next figure. Signals a and b are outputs from the top-level block (fuelsys).
Signal a is an input to subsys1 and b is input to subsys2. Signal c is an output from
subsys1. Notice the other inputs and outputs (d and e). Signals a through e have
corresponding data objects.
14-81
14 Code Appearance
Model
a subsys1
c
subsys3 e
d
b subsys2
a b
fuelsys
We generate code for this model. As shown in the figure below, this results in a .c
source file corresponding to each of the subsystems. (In actual applications, there could
be more than one .c source file for a subsystem. This is based on the file partitioning
previously selected for the model. But for our illustration, we only need to show one
for each subsystem.) Data objects a through e have corresponding identifiers in the
generated files.
A .c source file has one or more functions in it, depending on the internal operations
(functions) of its corresponding subsystem. An identifier in a generated .c file has local
scope when it is used only in one function of that .c file. An identifier has file scope when
more than one function in the same .c file uses it. An identifier has global scope when
more than one of the generated files uses it.
A subsystem's source file contains the definitions for that subsystem's data objects that
have local scope or file scope. (These definitions are not shown in the figure.) But where
are the definitions and declarations for data objects of global scope? These are shown in
the next figure.
14-82
Manage Placement of Data Definitions and Declarations
subsys2.c fuelsys.c
b subsys2
int d; int a;
extern int b; int b;
a b
fuelsys
For the Read-Write priority, this source file contains the definitions for the subsystem's
global data objects, if this is the file that first writes to the data object's address. Other
files that read (use) that data object only include a reference to it. This is why this
priority is called Read-Write. Since a read and a write of a file are analogous to input
and output of a model's block, respectively, there is another way of saying this. The
definitions of a block's global data objects are located in the corresponding generated file,
if that data object is an output from that block. The declarations (extern) of a block's
global data objects are located in the corresponding generated file, if that data object is
an input to that block.
The generated files and what they include, as just described, occur when the Read-Write
priority is used. For this to be the case, the other priorities are turned off. That is,
• The Data definition field on the Code Placement pane is set to Data defined in
source file.
• The Data declaration field on the Code Placement pane is set to Data declared
in source file.
14-83
14 Code Appearance
• The Owner field on the Model Explorer is blank, and the checkbox for the Use
owner from data object for data definition placement field on the Code
Placement pane is not checked.
• Definition file and Header file on the Model Explorer are blank.
Global Priority
This has the same priority as Read-Write (the lowest) priority. The settings for this are
the same as for Read-Write Priority, except
• The Data definition field on the Code Placement pane is set to Data defined in
single separate source file.
• The Data declaration field on the Code Placement pane is set to Data declared
in single separate header file.
The generated files that result are shown in the next figure. A subsystem's data objects
of local or file scope are defined in the .c source file where the subsystem's functions are
located (not shown). The data objects of global scope are defined in another .c file (called
global.c in the figure). The declarations for the subsystem's data objects of global scope
are placed in a .h file (called global.h).
For example, data objects of local and file scope for subsys1 are defined in subsys1.c.
Signal c in the model is an output of subsys1 and an input to subsys2. So c is used by
more than one subsystem and thus is a global data object. Because of the global priority,
the definition for c (int c;) is in global.c. The declaration for c (extern int c;) is
in global.h. Since subsys2 uses (reads) c, #include "global.h" is in subsys2.c.
14-84
Manage Placement of Data Definitions and Declarations
global.c global.h
a b
int a; extern int a;
int b; extern int b;
fuelsys int c;. extern int c;
int d; extern int d;
int e; extern int e;
While the Read-Write and Global priorities operate on all MPF-derived data objects that
you want defined in the generated code, the remaining priorities allow you to override
the Read-Write or Global priorities for one or more particular data objects. There is a
high-to-low priority among these remaining priorities — Definition File, Header File, and
Ownership — for a particular data object, as shown in MPF Settings Priority and Usage
Ownership Settings
Ownership settings refers to the on or off setting specified using the Use owner from
data object for data definition placement checkbox on the Code Placement pane
of the Configuration Parameters dialog box, and the Owner field of a data object in the
Model Explorer. These settings do not control what files are generated. These settings
14-85
14 Code Appearance
only specify definitions and extern statements. There are four possible configurations,
as shown in “Ownership Settings” on page 14-95.
If you specify a filename for Definition file, and select Default, MemConst,
MemVolatile or MemConstVolatile for the Memory section property, the code
generation software generates a .c file and an .h file. The .c file contains the definition
for the data object with the pragma statement or qualifier associated with the Memory
section selection. The .h file contains the declaration for the data object. The .h file can
be included, using the preprocessor directive #include, in files that need to reference
the data object.
You can add more memory sections. For more information, see “Design Custom Storage
Classes and Memory Sections” and “Memory Sections”.
Introduction
“Settings and Resulting Generated Files” on page 14-95 provides example settings for
one data object of a model. Eight examples are listed so that you can see the generated
14-86
Manage Placement of Data Definitions and Declarations
files that result from a wide variety of settings. Four examples from this table are
discussed below in more detail. These discussions provide information for understanding
settings you might choose. For illustration purposes, the four examples assume that we
are dealing with an overall system that controls engine idle speed.
The next figure shows that the software component of this example system consists of
two modules, IAC (Idle Air Control), and IO (Input-Output).
/* External Data*/
Depends on MPF Settings extern real_T meas_spd;
extern real_T iac_cmd;
The code in the IO module controls the system's IO hardware. Code is generated only for
the IAC module. (Some other means produced the code for the IO module, such as hand-
coding.) So the code in IO is external to MPF, and can illustrate legacy code. To simplify
matters, the IO code contains one source file, called IO.c, and one header file, called
IO.h.
The IAC module consists of two Stateflow charts, spd_filt and iac_ctrl. The
spd_filt chart has two signals (meas_spd) and filt_spd), and one parameter (a).
The iac_ctrl chart also has two signals (filt_spd and iac_cmd) and a parameter
(ref_spd). (The parameters are not visible in the top-level charts.) One file for each
14-87
14 Code Appearance
chart is generated. This example system allows us to illustrate referencing from file to
file within the MPF module, and model to external module. It also illustrates the case
where there is no such referencing.
Read-Write
These settings and the generated files that result are shown as Example Settings 1 in
“Settings and Resulting Generated Files” on page 14-95. As you can see from the
table, this example illustrates the case in which only one .c source file (for each chart) is
generated.
So, for the IAC model, select the following settings. Accept the Data defined in
source file in the Data definition field and the Data declared in source
file in the Data declaration field on the Code Placement pane of the Configuration
Parameters dialog box. Accept the default unchecked Use owner from data object
for data definition placement field. Accept the default blank settings for the Owner,
Definition file and Header file fields on the Model Explorer. For Memory section,
accept Default. Now the Read-Write priority is active. Generate code. The next figure
shows the results in terms of definition and declaration statements.
14-88
Manage Placement of Data Definitions and Declarations
spd_filt.c IO.c
/* Definitions*/ /* Definitions*/
const real_T a = 0.9; real_T meas_spd = 0.0;
real_T filt_spd = 0.0; real_T iac_cmd = 0.0;
real_T meas_spd = 0.0;
The code generator generated a spd_filt.c for the spd_filt chart and iac_ctrl.c
for the iac_ctrl chart. As you can see, MPF placed definitions of data objects for the
spd_filt chart in spd_filt.c. It placed definitions of data objects for the iac_ctrl
chart in iac_ctrl.c.
However, notice real_T filt_spd. This data object is defined in spd_filt.c and
declared in iac_ctrl.c. That is, since the Read-Write priority is active, filt_spd is
defined in the file that first writes to its address. And, it is declared in the file that reads
(uses) it. Further, real_T meas_spd is defined in both spd_filt.c and the external
IO.c. And, real_T iac_cmd is defined in both iac_ctrl.c and IO.c.
Ownership
See tables “Ownership Settings” on page 14-95 and “Settings and Resulting
Generated Files” on page 14-95. In the “Read-Write” on page 14-88, there are
several instances where the same data object is defined in more than one .c source file,
14-89
14 Code Appearance
and there is no declaration (extern) statement. This would result in compiler errors
during link time. But in this example, we configure MPF Ownership rules so that linking
can take place. Notice the Example Settings 2 row in “Settings and Resulting Generated
Files” on page 14-95. Except for the ownership settings, assume these are the settings
you made for the model in the IAC module. Since this example has no Definition file or
Header file specified, now Ownership takes priority. (If you specified a Definition file
or Header file, MPF ignores the ownership settings.)
On the Code Placement pane of the Configuration Parameters dialog box, check the box
for the Use owner from data object for data definition placement field. Open the
Model Explorer (by issuing the MATLAB command daexplr) and, for all data objects
except meas_spd and iac_cmd, type IAC in the Owner field (case sensitive). Then, only
for the meas_spd and iac_cmd data objects, type IO as their Owner (case sensitive).
Generate code.
The results are shown in the next figure. Notice the extern real_T meas_spd
statement in spd_filt.c, and extern real_T iac_cmd in iac_ctrl.c. MPF placed
these declaration statements in the files where these data objects are used. This allows
the generated source files (spd_filt.c and iac_ctrl.c) to be compiled and linked
with IO.c.
14-90
Manage Placement of Data Definitions and Declarations
Header File
These settings and the generated files that result are shown as Example Settings 3
in “Settings and Resulting Generated Files” on page 14-95. This example has no
Definition file specified. If you specified a Definition file, MPF ignores the Header
file setting. The focus of this example is to show how the Header file settings result in
the linking of the two chart source files to the external IO files, shown in the next figure.
(Also, ownership settings will be used to link the two chart files with each other.)
As you can see in the figure, the meas_spd and iac_cmd identifiers are defined in IO.c
and declared in IO.h. Both of these identifiers are external to the generated .c files.
You open the Model Explorer and select both the meas_spd and iac_cmd data objects.
For each of these data objects, in the Header file field, specify IO.h, since this is where
these two objects are declared. This setting allows the spd_filt.c source file to compile
and link with the external IO.c file.
14-91
14 Code Appearance
Now we configure the ownership settings. In the Model Explorer, select the filt_spd
data object and set its Owner field to IAC. Then, on the Code Placement pane of the
Configuration Parameters dialog box, check the box for the Use owner from data
object for data definition placement field. Now the spd_filt source file links to the
iac_ctrl source file. Generate code. See the figure below.
Since you specified the IO.h filename for the Header file field for the meas_spd and
iac_ctrl objects, the code generator assumed that their declarations are in IO.h.
So the code generator placed #include IO.h in each source file: spd_filt.c and
iac_ctrl.c. So these two files will link with the external IO files. Also, due to the
ownership settings that were specified, the code generator places the real_T filt_spd
= 0.0; definition in spd_filt.c and declares the filt_spd identifier in iac_ctrl.c
with extern real_T iac_cmd;. Consequently, the two source files will link together.
14-92
Manage Placement of Data Definitions and Declarations
Definition File
These settings and the generated files that result are shown as Example Settings 4 in
“Settings and Resulting Generated Files” on page 14-95. Notice that a definition
filename is specified. The settings in the table only apply to the data object called a. You
have decided that you do not want this object defined in spd_filt.c, the generated
source file for the spd_filt chart. (There are many possible organizational reasons
one might want an object declared in another file. It is not important for this example to
specify the reason.)
For this example, assume the settings for all data objects are the same as those indicated
in “Header File” on page 14-91, except for the data object a. The description below
identifies only the differences that result from this.
Open the Model Explorer, and select data object a. In the Definition file field specify a
filename. Choose filter_constants.c. Generate code. The results are shown in the
next figure.
14-93
14 Code Appearance
filter constants.c
/* Definitions */ IO.h
const real_T a = 0.9;
/* External Data*/
global.h extern real_T meas_spd;
/* Declarations */ extern real_T iac_cmd;
extern real_T a;
The code generator generates the same files as in the “Header File” on page 14-91,
and adds a new file, filter_constants.c. Data object a now is defined in
filter_constants.c, rather than in the source file spd_filt.c, as it is in the
example. This data object is declared with an extern statement in global.h
14-94
Manage Placement of Data Definitions and Declarations
Ownership Settings
14-95
14 Code Appearance
* "Blank" in ownership setting means that the check box for the Use owner from data
object for data definition placement field on the Code Placement pane is Off and
the Owner field on the Model Explorer is blank. "Name of module specified" can be a
variety of ownership settings as defined in “Ownership Settings” on page 14-95.
** The code generator generates a definition .c/.cpp file for every data object for
which you specified a definition filename (unless you selected #DEFINE for the Memory
section field). For example, if you specify the same definition filename for all data
objects, only one definition .c/.cpp file is generated. The code generator places
declarations in model.h by default, unless you specify Data declared in single
separate header file for the Data declaration option on the Code Generation
> Code Placement pane of the Configuration Parameter dialog box. If you select
that data placement option, the code generator places declarations in global.h. If
you specify a definition filename for each data object, the code generator generates one
definition .c/.cpp file for each data object and places declarations in model.h by
default, unless you specify Data declared in single separate header file for
Data declaration. If you select that data placement option, the code generator places
declarations in global.h.
14-96
Manage Placement of Data Definitions and Declarations
Note: If you generate C++ rather than C code, the .c files listed in the following table
will be .cpp files.
14-97
14 Code Appearance
14-98
Manage Placement of Data Definitions and Declarations
14-99
14 Code Appearance
14-100
Manage Placement of Data Definitions and Declarations
14-101
14 Code Appearance
14-102
Manage Placement of Data Definitions and Declarations
Notes
• A Declaration Inclusion Approach is a file in which the header file that contains the
data declarations is included.
• D/C stands for don't care.
• Dec stands for declaration.
• Def stands for definition.
• gbl stands for global.
14-103
14 Code Appearance
Note 5: model.h is included directly in all source files that use #define.
Note 6: header.h is included in model.h, which is in source files that use #define.
Note 10: When you specify a definition filename for a data object, a header file is not
generated for that data object. The code generator declares the data object according to
the data placement priorities.
Note 12: Signal: Either not defined because it is expression folded, or local data, or
defined in a structure in model.c, all depending on model's code generation settings.
Parameter: Either inlined in the code, or defined in model_data.c.
14-104
Specify Delimiter for #Includes
Further, when specifying the filename as the Header file property value, you may
or may not place it within the double-quote or angle-bracket delimiter. That is, you can
specify it as filename.h, "filename.h", or <filename.h>. The code generator finds
every data object for which you specified a filename as its Header file property value
without a delimiter. By default, it assigns to each of these the double-quote delimiter.
This procedure allows you to specify the angle-bracket delimiter for these instead of the
default double-quote delimiter. See the figure below.
1 In the #include file delimiter field on the Code Placement pane of the
Configuration Parameters dialog box, select #include <header.h> instead of the
default #include "header.h".
2 Click Apply.
14-105
14-106
15
model='rtwdemo_rtwecintro';
open_system(model)
2. Open the Configuration Parameters dialog box from the model editor by clicking
Simulation > Model Configuration Parameters.
cs = getActiveConfigSet(model);
openDialog(cs);
15-2
Generating Code Using Embedded Coder®
You can generate code for a particular target environment or purpose. Some built-
in targeting options are provided using system target files, which control the code
generation process for a target.
15-3
15 Source Code Generation
The ERT target includes a utility to specify and prioritize code generation settings based
on your application objectives.
15-4
Generating Code Using Embedded Coder®
You can set and prioritize objectives for the generated code. For example, while code
traceability might be a very important criterion for your application, you might not want
to prioritize it at the cost of code execution efficiency.
7. In the Set Objectives pane, select Execution efficiency and Traceability. Click
OK.
You can select and prioritize a combination of objectives before generating code.
15-5
15 Source Code Generation
The report includes rtwdemo_rtwecintro.c, associated utility and header files, and
traceability and validation reports.
15-6
Generating Code Using Embedded Coder®
15-7
15 Source Code Generation
bdclose(model)
rtwdemoclean;
15-8
Generate Code Modules
Introduction
This section summarizes the code modules and header files that make up a Embedded
Coder program and describes where to find the code modules and header files.
The easiest way to locate and examine the generated code files is to use the HTML code
generation report. The code generation report provides a table of hyperlinks that you
click to view the generated code in the MATLAB Help browser. For more information, see
“Traceability in Code Generation Report”.
Embedded Coder File Packaging summarizes the structure of source code generated by
the Embedded Coder software.
15-9
15 Source Code Generation
File Description
model.h Declares model data structures and a public interface to the model
entry points and data structures. Also provides an interface to the
real-time model data structure (model_M) with accessor macros.
model.h is included in the subsystem .c or .cpp files of the model.
• MAT-file logging
• External mode from the Interface list
model_reference_types.hContains type definitions for timing bridges. File is generated for a
model reference target or a model containing model reference blocks.
builtin_typeid_types.h Defines an enumerated type corresponding to built-in data types.
File is generated when you select one or more of the following in the
Configuration Parameters dialog box on the Code Generation >
Interface pane:
15-10
Generate Code Modules
File Description
• MAT-file logging
• C API from the Interface list
ert_main.c or .cpp If the Generate an example main program option is on, this
(optional) file is generated. (This option is on by default.) See “Generate an
example main program”.
rtmodel.h If the Generate an example main program option is off, this file
(optional) is generated. (See “Generate an example main program”.)
• File packaging formats: Specify the number of source files generated for your
model. In the Configuration Parameter dialog box, on the Code Generation >
Code Placement pane, specify the File packaging format parameter. For more
information, see “Customize Generated Code Modules” on page 15-12.
15-11
15 Source Code Generation
• Module Packaging Features (MPF): Direct the generated code into a required set of .c
or .cpp and .h files, and control the internal organization of the generated files. For
details, see “Data, Function, and File Definition”.
Establish a working folder for your own code modules. Put your working folder on the
MATLAB path. Minimally, you must also modify the ERT template makefile and system
target file so that the build process can find your source and object files. If you want to
generate code for a particular microprocessor or development board and deploy the code
on target hardware with a cross-development system, make more extensive modifications
to the ERT target files.
For information on how to customize the ERT target for your production requirements,
see “Target Development”.
model.h
model_types.h
15-12
Generate Code Modules
model_data.c
(conditional)
Compact (with model.c model_private.h
separate data file)
model.h model_types.h (conditional,
see below)
model_data.c
(conditional)
Compact model.c model_data.c
model.h model_private.h
model_types.h (conditional,
see below)
The code generation process places the content of the removed files as follows:
You can specify a different file packaging format for each referenced model.
If you specify Shared code placement as Shared location on the Code Generation
> Interface pane of the Configuration Parameter dialog box, the code generation
process generates separate files for utility code in a shared location, regardless of the file
packaging format. If you specify the Shared code placement as Auto, the generated
code for utilities is dependent on the file packaging format as follows:
File packaging formats Compact and Compact (with separate data file)
generate model_types.h for models containing:
15-13
15 Source Code Generation
File packaging formats Compact and Compact (with separate data file) are not
compatible with the following:
15-14
Generate Reentrant Code from MATLAB Code
With an Embedded Coder license, you can use codegen to generate reusable code. For
more information, see “Generate Reentrant Code” on page 15-16.
15-15
15 Source Code Generation
If you do not choose to generate reentrant code, codegen generates code that uses
statically allocated memory for function variables that are too large to fit on the stack,
and for global and persistent variables. The use of static memory allocation for these
variables means that you cannot deploy the generated code in environments that require
code to be reentrant. In addition, the generated code can result in static memory size
overflow if you cannot adjust the static memory allocation size to accommodate the static
memory requirements of the program.
When you generate reentrant code, codegen creates input data structures for
function variables that are too large to fit on the stack, and for persistent and global
variables. You can then dynamically allocate memory for these input structures. The
use of dynamic memory allocation means that you can deploy the code in reentrant
environments.
Procedure
Alternatively, you can set this parameter using the MATLAB Coder Project Settings
dialog box. On the Interface pane , select Reusable function code interface packaging.
15-16
Generate Reentrant Code from MATLAB Code
• primary_function_nameStackData
This structure contains the user allocated memory. You must pass a pointer to this
structure as the first parameter to all functions that use it either directly, because the
function uses a field in the structure, or indirectly, because the function passes the
structure to a called function.
For more information on using these global structures, see “Multithreaded Examples” on
page 15-18.
• primary_function_name_initialize.
• primary_function_name.
15-17
15 Source Code Generation
• primary_function_name_terminate.
• primary_function_name_initialize.
• primary_function_name.
• primary_function_name_terminate.
Multithreaded Examples
15-18
Generate Reentrant Code from MATLAB Code
To call the reentrant code, you must provide a main function that:
15-19
15 Source Code Generation
#include <stdio.h>
#include <stdlib.h>
#include <pthread.h>
#include "matrix_exp.h"
#include "matrix_exp_initialize.h"
#include "matrix_exp_terminate.h"
#include "rtwtypes.h"
#define NUMELEMENTS (160*160)
typedef struct {
real_T in[NUMELEMENTS];
real_T out[NUMELEMENTS];
matrix_expStackData* spillData;
} IODATA;
int main() {
pthread_t thread1, thread2;
int iret1, iret2;
IODATA data1;
IODATA data2;
int32_T i;
data1.spillData = sd1;
data2.spillData = sd2;
for (i=0;i<NUMELEMENTS;i++) {
data1.in[i] = 1;
data1.out[i] = 0;
data2.in[i] = 1.1;
data2.out[i] = 0;
}
/*Initializing the 2 threads and passing required data to the thread functions*/
printf("Starting thread 1...\n");
iret1 = pthread_create(&thread1, NULL, thread_function, (void*) &data1);
if (iret1 != 0){
perror( "Thread 1 creation failed.");
exit(EXIT_FAILURE);
15-20
Generate Reentrant Code from MATLAB Code
free(sd1);
free(sd2);
printf("Finished Execution!\n");
exit(EXIT_SUCCESS);
Run the following script at the MATLAB command line to generate code.
% This example can only be run on Unix platforms
if ~isunix
error('This example requires pthread libraries and can only be run on Unix.');
end
% Compiling
codegen -config e main.c matrix_exp.m -report -args ones(160,160)
These commands:
15-21
15 Source Code Generation
• Check that the example is running on UNIX platforms and generates an error
message if not.
• Create a Simulink Coder configuration object for an ERT target.
• Enable the MultiInstanceCode option to generate reusable, reentrant code.
• Use the PostCodeGenCommand option to set the post-code-generation command to be
the setbuildargs function. This function sets the -lpthread flag to specify that
the build include the pthread library.
function setbuildargs(buildInfo)
% The example being compiled requires pthread support.
% The -lpthread flag requests that the pthread library
% be included in the build
linkFlags = {'-lpthread'};
addLinkFlags(buildInfo, linkFlags);
For more information about the PostCodeGenCommand option, see “Customize the
Post-Code-Generation Build Process”.
• Invoke codegen with the following options:
#ifndef __MATRIX_EXP_TYPES_H__
#define __MATRIX_EXP_TYPES_H__
/* Type Definitions */
typedef struct {
struct {
real_T F[25600];
real_T Y[25600];
15-22
Generate Reentrant Code from MATLAB Code
} f0;
} matrix_expStackData;
#endif
/* End of MATLAB Coder code generation (matrix_exp_types.h) */
E = zeros(size(X));
F = eye(size(X));
k = 1;
while norm(E+F-E,1) > 0
E = E + F;
F = X*F/k;
k = k+1;
end
Y = E ;
numTimes = count;
To call reentrant code that uses persistent data, you must provide a main function that:
15-23
15 Source Code Generation
typedef struct {
real_T in[NUMELEMENTS];
real_T out[NUMELEMENTS];
real_T numTimes;
matrix_expStackData* spillData;
} IODATA;
void main() {
HANDLE thread1, thread2;
IODATA data1;
IODATA data2;
int32_T i;
15-24
Generate Reentrant Code from MATLAB Code
sd1->pd = pd1;
sd2->pd = pd2;
data1.spillData = sd1;
data2.spillData = sd2;
for (i=0;i<NUMELEMENTS;i++) {
data1.in[i] = 1;
data1.out[i] = 0;
data2.in[i] = 1.1;
data2.out[i] = 0;
}
data1.numTimes = 0;
data2.numTimes = 0;
/*Initializing the 2 threads and passing required data to the thread functions*/
printf("Starting thread 1...\n");
thread1 = CreateThread(NULL, 0, thread_function, (PVOID) &data1, 0, NULL);
if (thread1 == NULL){
perror( "Thread 1 creation failed.");
exit(EXIT_FAILURE);
}
free(sd1);
free(sd2);
free(pd1);
free(pd2);
printf("Finished Execution!\n");
exit(EXIT_SUCCESS);
Run the following script at the MATLAB command line to generate code.
15-25
15 Source Code Generation
% Compiling
codegen -config e main.c -report matrix_exp.m -args ones(160,160)
These commands:
• Check that the example is running on Windows platforms and generates an error
message if not.
• Create a code generation configuration object for an ERT target.
• Enable the MultiInstanceCode option to generate reusable, reentrant code.
• Invoke codegen with the following options:
• The matrix_expStackData global structure that contains local variables that are
too large to fit on the stack and a pointer to the matrix_expPersistentData global
structure.
• The matrix_expPersistentData global structure that contains persistent data.
/*
* matrix_exp_types.h
*
* MATLAB Coder code generation for function 'matrix_exp'
*
15-26
Generate Reentrant Code from MATLAB Code
*/
#ifndef __MATRIX_EXP_TYPES_H__
#define __MATRIX_EXP_TYPES_H__
/* Type Definitions */
typedef struct {
real_T count;
} matrix_expPersistentData;
typedef struct {
struct {
real_T F[25600];
real_T Y[25600];
} f0;
matrix_expPersistentData *pd;
} matrix_expStackData;
#endif
/* End of code generation (matrix_exp_types.h) */
persistent count;
if isempty(count)
count = 0;
end
count = count+1;
E = zeros(size(X));
F = eye(size(X));
k = 1;
while norm(E+F-E,1) > 0
15-27
15 Source Code Generation
E = E + F;
F = X*F/k;
k = k+1;
end
Y = E ;
numTimes = count;
To call reentrant code that uses persistent data, you must provide a main function that:
typedef struct {
real_T in[NUMELEMENTS];
real_T out[NUMELEMENTS];
real_T numTimes;
matrix_expStackData* spillData;
} IODATA;
15-28
Generate Reentrant Code from MATLAB Code
int main() {
pthread_t thread1, thread2;
int iret1, iret2;
IODATA data1;
IODATA data2;
int32_T i;
sd1->pd = pd1;
sd2->pd = pd2;
data1.spillData = sd1;
data2.spillData = sd2;
for (i=0;i<NUMELEMENTS;i++) {
data1.in[i] = 1;
data1.out[i] = 0;
data2.in[i] = 1.1;
data2.out[i] = 0;
}
data1.numTimes = 0;
data2.numTimes = 0;
/*Initializing the 2 threads and passing required data to the thread functions*/
printf("Starting thread 1...\n");
iret1 = pthread_create(&thread1, NULL, thread_function, (void*) &data1);
if (iret1 != 0){
perror("Thread 1 creation failed.");
exit(EXIT_FAILURE);
}
15-29
15 Source Code Generation
free(sd1);
free(sd2);
free(pd1);
free(pd2);
printf("Finished Execution!\n");
return(0);
Run the following script at the MATLAB command line to generate code.
% Compiling
codegen -config e main.c -report matrix_exp.m -args ones(160,160)
These commands:
• Check that the example is running on UNIX platforms and generates an error
message if not.
• Create a code generation configuration object.
• Enable the MultiInstanceCode option to generate reusable, reentrant code.
• Use the PostCodeGenCommand option to set the post-code-generation command to be
the setbuildargs function. This function sets the -lpthread flag to specify that
the build include the pthread library.
function setbuildargs(buildInfo)
% The example being compiled requires pthread support.
15-30
Generate Reentrant Code from MATLAB Code
• The matrix_expStackData global structure that contains local variables that are
too large to fit on the stack and a pointer to the matrix_expPersistentData global
structure.
• The matrix_expPersistentData global structure that contains persistent data.
/*
* matrix_exp_types.h
*
* MATLAB Coder code generation for function 'matrix_exp'
*
*/
#ifndef __MATRIX_EXP_TYPES_H__
#define __MATRIX_EXP_TYPES_H__
/* Type Definitions */
typedef struct {
real_T count;
} matrix_expPersistentData;
typedef struct {
struct {
real_T F[25600];
real_T Y[25600];
} f0;
matrix_expPersistentData *pd;
} matrix_expStackData;
#endif
/* End of code generation (matrix_exp_types.h) */
15-31
15 Source Code Generation
15-32
Generate Reentrant Code from Top-Level Models
• By default, the generated model.c source file does not contain an allocation function
that dynamically allocates model data for each instance of the model. Use the Use
dynamic memory allocation for model initialization option to control whether
an allocation function is generated.
• The generated code passes the real-time model data structure in, by reference, as an
argument to model_step and the other model entry point functions.
• The real-time model data structure is exported with the model.h header file.
• By default, root-level input and output arguments are passed to the reusable model
entry-point functions as individual arguments. Use the Pass root-level I/O as
parameter to control whether root-level input and output arguments are included
in the real-time model data structure that is passed to the functions, passed as
individual arguments, or passed as references to an input structure and an output
structure.
1 In the Code Generation > Interface pane of the Configuration Parameters dialog
box, set “Code interface packaging” to the value Reusable function. This
action enables the parameters Multi-instance code error diagnostic, Pass root-
level I/O as, and Use dynamic memory allocation for model initialization.
2 Examine the setting of “Multi-instance code error diagnostic”. Leave the
parameter at its default value Error unless you have a specific need to alter the
severity level for diagnostics displayed when a model violates requirements for
generating multi-instance code.
3 Configure “Pass root-level I/O as” to control how root-level model input and output
are passed to model_step and the other generated model entry-point functions.
When you set Code interface packaging to Reusable function, model data
(such as block I/O, DWork, and parameters) is packaged into the real-time model
data structure, and the model structure is passed to the model entry-point functions.
If you set Pass root-level I/O as to Part of model data structure, the
root-level model input and output also are packaged into the real-time model data
structure.
15-33
15 Source Code Generation
4 If you want the generated model code to contain a function that dynamically
allocates memory for model instance data, select the option “Use dynamic memory
allocation for model initialization”. If you do not select this option, the generated
code statically allocates memory for model data structures.
5 Generate model code.
6 Examine the model entry-point function interfaces in the generated files and the
HTML code generation report. For more information about generating and calling
model entry-point functions, see “Entry-Point Functions and Scheduling”.
For an example of a model configured to generate reusable, reentrant code, open the
example model rtwdemo_reusable. Click the button View Interface Configuration and
examine the Code interface parameters on the Code Generation > Interface pane.
15-34
16
Report Generation
• The Summary section lists version, date, and code generation objectives information.
The Configuration settings at the time of code generation link opens a
noneditable view of the Configuration Parameters dialog box. The dialog box shows
the Simulink model settings at the time of code generation, including TLC options.
• The Subsystem Report section contains information on nonvirtual subsystems in
the model.
• In the Generated Files section on the Contents pane, you can click the names of
source code files generated from your model to view their contents in a MATLAB Web
browser window. In the displayed source code, global variables are hypertext that
links to their definitions.
• A Find box at the top of the window. For more information, see “Search Code
Generation Report” on page 16-7.
For an example, see “Generate a Code Generation Report” on page 16-8 and “View
Code Generation Report in Model Explorer” on page 16-14.
The contents of HTML reports varies depending on different target types. You can
generate individual HTML reports for a subsystem or referenced model. For more
information, see “HTML Code Generation Report for Referenced Models” on page
16-6 and “Generate Code for Referenced Models”.
If you have a Simulink Report Generator license, you can document your code generation
project in multiple formats, including HTML, PDF, RTF, Microsoft Word, and XML. For
an example of how to create a Microsoft Word report, see “Document Generated Code
with Simulink Report Generator” on page 16-53.
16-2
HTML Code Generation Report Extensions
• The Code Interface Report section provides information about the generated code
interface, including model entry point functions and input/output data. For more
information, see “Analyze the Generated Code Interface” on page 16-24.
• The Traceability Report section allows you to account for Eliminated / Virtual
Blocks that are untraceable versus the listed Traceable Simulink Blocks /
Stateflow Objects / MATLAB Scripts. This provides a complete mapping between
model elements and code. For more information, see “Customize Traceability
Reports”.
• The Static Code Metrics Report section provides statistics of the generated
code. Metrics are estimated from static analysis of the generated code. For more
information, see “Static Code Metrics” on page 16-36.
• The Code Replacements Report section allows you to account for code replacement
library (CRL) functions that were used during code generation, providing a mapping
between each replacement instance and the Simulink block that triggered the
replacement. For more information, see “Analyze Code Replacements in the
Generated Code” on page 16-51.
• The model Web view displays an interactive model diagram within the code
generation report and supports traceability between the source code and the model.
Therefore, you can share your model and generated code outside of the MATLAB
environment. For more information, see “Generate HTML Code Generation Report
with Model Web View” on page 16-20.
On the Contents pane, in the Generated Files section, you can click the names of
source code files generated from your model to view their contents in a MATLAB Web
browser window. In the displayed source code:
• If you enable code-to-model traceability, hyperlinks within the displayed source code
navigate to the blocks or subsystems from which the code is generated. For more
information, see “Traceability in Code Generation Report” on page 16-18 and
“Trace Code to Model Objects Using Hyperlinks”.
16-3
16 Report Generation
• If you enable model-to-code traceability, you can navigate to the generated code for
a block in the model. For more information, see “Trace Model Objects to Generated
Code”.
• If you set the Code coverage tool parameter on the Code Generation >
Verification pane, you can view the code coverage data and annotations. For more
information, see “Configure SIL and PIL Code Coverage”.
• If you select the Static code metrics check box on the Code Generation > Report
pane, you can view code metrics information and navigate to code definitions and
declarations in the generated code. For more information, see “View Code Metrics and
Definitions in the Generated Code”.
16-4
HTML Code Generation Report Location
16-5
16 Report Generation
• From the top-model code generation report, you can access the referenced model code
generation report by clicking a link under Referenced Models in the left navigation
pane. Clicking a link opens the code generation report for the referenced model in
the browser. To navigate back to the top model code generation report, use the Back
button at the top of the left navigation pane.
• From the referenced model diagram window, select Code > C/C++ Code > Code
Generation Report > Open Model Report.
To generate a code generation report for a referenced model individually, follow the
instructions in “Generate a Code Generation Report” on page 16-8 and “Open Code
Generation Report” on page 16-11 for the referenced model.
16-6
Search Code Generation Report
Pressing Ctrl-F sets focus to the Find box. Type text into the Find box and hit Enter to
start the search. The search highlights the found terms in the displayed page and scrolls
to the first instance found. Press Enter to scroll through the subsequent search hits. If
no terms are found, the background of the search box is highlighted red.
16-7
16 Report Generation
1 In the Simulink Editor, select Code > C/C++ Code > Code Generation Report
> Options. The Configuration Parameters dialog box opens with the Code
Generation > Report pane visible.
2 Select the Create code generation report parameter.
3 If you want the code generation report to automatically open after generating code,
select the Open report automatically parameter (which is enabled by selecting
Create code generation report).
4 Generate code.
The build process writes the code generation report files to the html subfolder of the
build folder (see “HTML Code Generation Report Location” on page 16-5). Next, the build
process automatically opens a MATLAB Web browser window and displays the code
generation report.
To open an HTML code generation report at any time after a build, see “Open Code
Generation Report” on page 16-11 and “Generate Code Generation Report After Build
Process” on page 16-9.
16-8
Generate Code Generation Report After Build Process
1 In the model diagram window, select Code > C/C++ Code > Code Generation
Report > Open Model Report.
2 If your current working folder contains the code generation files the following dialog
opens.
Enter the full path of the build folder for your model, ../model_target_rtw and
click Open Report.
16-9
16 Report Generation
Note: An alternative method for generating the report after the build process is complete
is to configure your model to generate a report and build your model. In this case, the
software generates the report without regenerating the code.
16-10
Open Code Generation Report
If your current working folder does not contain the code generation files and the code
generation report, the following dialog box opens:
Enter the full path of the build folder for your model, ../model_target_rtw and click
Open Report.
Limitation
After building your model or generating the code generation report, if you modify
legacy or custom code, you must rebuild your model or regenerate the report for the
code generation report to include the updated legacy source files. For example, if you
modify your legacy code, and then use the Code > C/C++ Code > Code Generation
16-11
16 Report Generation
Report > Open Model Report menu to open an existing report, the software does not
check if the legacy source file is out of date compared to the generated code. Therefore,
the code generation report is not regenerated and the report includes the out-of-date
legacy code. This issue also occurs if you open a code generation report using the
coder.report.open function.
16-12
Generate Code Generation Report Programmatically
16-13
16 Report Generation
When you generate code, or open a model that has generated code for its current target
configuration in your working folder, the Hierarchy (left) pane of Model Explorer
contains a node named Code for model. Under that node are other nodes, typically
called This Model and Shared Code. Clicking This Model displays in the Contents
(middle) pane a list of generated source code files in the build folder of that model. The
next figure shows code for the rtwdemo_counter model.
The views in the Document (right) pane are read only. The code listings there contain
hyperlinks to functions and macros in the generated code. Clicking the file hyperlink
opens that source file in a text editing window where you can modify its contents.
If an open model contains Model blocks, and if generated code for these models exists in
the current slprj folder, nodes for the referenced models appear in the Hierarchy pane
16-14
View Code Generation Report in Model Explorer
one level below the node for the top model. Such referenced models do not need to be open
for you to browse and read their generated source files.
If the Simulink Coder software generates shared utility code for a model, a node named
Shared Code appears directly under the This Model node. It collects source files that
exist in the ./slprj/target/_sharedutils subfolder.
Note You cannot use the Search tool built into Model Explorer toolbar to search
generated code displayed in the Code Viewer. On PCs, typing Ctrl+F when focused on
the Document pane opens a Find dialog box that you can use to search for strings in the
currently displayed file. You can also search for text in the HTML report window, and
you can open the files in the editor.
16-15
16 Report Generation
• /slprj
• html subfolder of the build folder, model_target_rtw, for example
rtwdemo_counter_grt_rtw/html
• /slprj
• Build folder: model_target_rtw
2 Right-click to open the context menu.
3 In the context menu, select Create Zip File. A file appears in the Current Folder
browser.
4 Name the zip file.
Alternatively, you can use the MATLAB zip command to zip the code generation report
files:
zip('myzip',{'slprj','rtwdemo_counter_grt_rtw'})
Note: If you need to relocate the static and generated code files for a model to another
development environment, such as a system or an integrated development environment
(IDE) that does not include MATLAB and Simulink products, use the Simulink Coder
pack-and-go utility. For more information, see “Relocate Code to Another Development
Environment”.
16-16
Package and Share the Code Generation Report
16-17
16 Report Generation
1 With your ERT-based model open, open the Configuration Parameters dialog box or
Model Explorer and navigate to the Code Generation > Report pane.
2 Select Create code generation report if it is not already selected. By default,
Open report automatically and Code-to-model are selected. Model-to-code is
not selected.
3 Select the Model-to-code parameter.
4 If your model contains referenced models and you want to enable traceability for
the referenced model’s code generation report, repeat steps 2–3 for each referenced
model.
5 Generate code for your model by clicking Build on the Code Generation pane
of the Configuration Parameters dialog box. The build process opens the code
generation report in a MATLAB Web browser.
6 In the left navigation pane, select a source code file. In the source code in the right
pane, there are hyperlinks to blocks in the model.
7 Click a hyperlink in the code. The model diagram window displays and highlights
the corresponding block in the model.
8 To highlight the generated code for a block in your Simulink model, right-click the
block and select C/C++ Code > Navigate to C/C++ Code. This selection highlights
the generated code for the block in the HTML code generation report.
9 If you have a referenced model in your model, in the left navigation pane, below
Reference Models, click the link to a referenced model. The code generation report
for the referenced model is now displayed in the window.
10 In the left navigation pane, click the Back button to go back to the previous code
generation report.
Related Examples
• “Trace Model Objects to Generated Code”
• “Trace Code to Model Objects Using Hyperlinks”
More About
• “Traceability Limitations”
16-18
View Code Metrics and Definitions in the Generated Code
• On the Code Generation > Report pane, if you select the Static code metrics
check box you can hover your cursor over global variables and functions in the code
window to see code metrics information.
• In the code window, if you click linked variables or functions, the code inspect window
is displayed. The window provides links to definitions for the variables or functions.
On the Code Generation > Report pane, if you selected the Static code metrics
check box, you can also see code metrics information for the variable or function.
16-19
16 Report Generation
A Simulink Report Generator license is required to include a “Web view” of the model in
the code generation report.
Web view requires a Web browser that supports Scalable Vector Graphics (SVG). Web
view uses SVG to render and navigate models.
• Mozilla Firefox Version 1.5 or later, which has native support for SVG. To download
the Firefox browser, go to www.mozilla.com/.
• The Microsoft Internet Explorer® Web browser with the Adobe® SVG Viewer plug-in.
To download the Adobe SVG Viewer plug-in, go to www.adobe.com/svg/.
• Apple Safari Web browser
16-20
Web View of Model in Code Generation Report
2 Open the Configuration Parameters dialog box or Model Explorer and navigate to
the Code Generation pane.
3 Specify ert.tlc for the System target file parameter.
4 Open the Code Generation > Report pane.
5 Select the following parameters:
Note: These settings specify only the top model, not referenced models.
6 Open the Configuration Parameters for the referenced model, rtwdemo_mdlrefbot
and perform steps 3–5.
7 Save the models, rtwdemo_mdlreftop and rtwdemo_mdlrefbot.
8 From the top model diagram, press Ctrl+B. After building the model and generating
code, the code generation report for the top model opens in a MATLAB Web browser.
9 In the left navigation pane, select a source code file. The corresponding source code is
displayed in the right pane and includes hyperlinks.
16-21
16 Report Generation
10 Click a link in the code. The model Web view displays and highlights the
corresponding block in the model.
11 To highlight the generated code for a referenced model block in your model, click
CounterB. The corresponding code is highlighted in the source code pane.
Note: You cannot open the referenced model diagram in the Web view by double-
clicking the referenced model block in the top model.
12 To open the code generation report for a referenced model, in the left navigation
pane, below Referenced Models, click the link, rtwdemo_mdlrefbot. The
16-22
Web View of Model in Code Generation Report
source files for the referenced model are displayed along with the Web view of the
referenced model.
13 To go back to the code generation report for the top model, at the top of the left
navigation pane, click the Back button until the top model’s report is displayed.
For more information about exploring a model in a Web view, see “Navigate the Web
View” in the Simulink Report Generator documentation.
For more information about navigating between the generated code and the model
diagram, see :
• Code is not generated for virtual blocks. In the model Web view of the code generation
report, when tracing between the model and the code, when you click a virtual block,
it is highlighted yellow.
• In the model Web view, you cannot open a referenced model diagram by double-
clicking the referenced model block in the top model. Instead, open the code
generation report for the referenced model by clicking a link under Referenced
Models in the left navigation pane.
• Stateflow truth tables, events, and links to library charts are not supported in the
model Web view.
• Searching in the code generation report does not find or highlight text in the model
Web view.
• If you navigate from the actual model diagram (not the model Web view in the
report), to the source code in the HTML code generation report, the model Web view
is disabled and not visible. To enable the model Web view, open the report again, see
“Open Code Generation Report”.
• For a subsystem build, the traceability hyperlinks of the root level inport and outport
blocks are disabled.
• “Traceability Limitations” that apply to tracing between the code and the actual
model diagram.
16-23
16 Report Generation
In this section...
“Code Interface Report Overview” on page 16-24
“Generating a Code Interface Report” on page 16-25
“Navigating Code Interface Report Subsections” on page 16-27
“Interpreting the Entry Point Functions Subsection” on page 16-28
“Interpreting the Inports and Outports Subsections” on page 16-31
“Interpreting the Interface Parameters Subsection” on page 16-32
“Interpreting the Data Stores Subsection” on page 16-34
“Code Interface Report Limitations” on page 16-35
For limitations that apply to code interface reports, see “Code Interface Report
Limitations” on page 16-35.
16-24
Analyze the Generated Code Interface
1 Open your model, go to the Code Generation pane of the Configuration Parameters
dialog box, and select ert.tlc or an ERT-based System target file, if one is not
already selected.
2 Go to the Code Generation > Report pane of the Configuration Parameters dialog
box and select the option Create code generation report, if it is not already
selected. The rtwdemo_basicsc, rtwdemo_mrmtbb, and rtwdemo_fcnprotoctrl
models used in this section select multiple Report pane options by default. But
selecting only Create code generation report, generates a Code Interface
Report section in the HTML report.
Alternatively, you can programmatically select the option by issuing the following
MATLAB command:
If the Report pane option Code-to-model is selected, the generated report contains
hyperlinks to the model. Leave this value selected unless you plan to use the report
outside the MATLAB environment.
3 Build the model. If you selected the Report pane option Open report
automatically, the code generation report opens automatically after the build
process is complete. (Otherwise, you can open it manually from within the model
build folder.)
4 To display the code interface report for your model, go to the Contents pane of
the HTML report and click the Code Interface Report link. For example, here
is the generated code interface report for the model rtwdemo_basicsc (with the
ExportedGlobal Storage Class button selected in the model window).
16-25
16 Report Generation
16-26
Analyze the Generated Code Interface
For help navigating the content of the code interface report subsections, see “Navigating
Code Interface Report Subsections” on page 16-27. For help interpreting the content
of the code interface report subsections, see the sections beginning with “Interpreting the
Entry Point Functions Subsection” on page 16-28.
• For a large subsection, the report provides [-] and [+] symbols that allow you to
collapse or expand that section. In the example in the previous section, the symbols
are provided for the Inports and Interface Parameters sections.
• Several forms of hyperlink navigation are provided in the code interface report. For
example:
• The Table of Contents located at the top of the code interface report provides
links to each subsection.
• You can click each function name to go to its definition in model.c.
• You can click each function's header file name to go to the header file source
listing.
• If you selected the Report pane option Code-to-model for your model, to go to
the corresponding location in the model display, you can click hyperlinks for any of
the following:
• Function argument
• Function return value
• Inport
• Outport
• Interface parameter (if the parameter source is a block)
• Data store (if the data store source is a Data Store Memory block)
For backward and forward navigation within the HTML code generation report, use the
Back and Forward buttons above the Contents section in the upper-left corner of the
report.
16-27
16 Report Generation
Field Description
Function: Lists the function name. You can click the function name to go to
its definition in model.c.
Prototype Displays the function prototype, including the function return
value, name, and arguments.
Description Provides a text description of the function's purpose in the
application.
Timing Describes the timing characteristics of the function, such as how
many times the function is called, or if it is called periodically,
and at what time interval. For a multirate timing example, see
the following rtwdemo_mrmtbb report excerpt.
Arguments If the function has arguments, displays the number, name,
data type, and Simulink description for each argument. If you
selected the Report pane option Code-to-model for your
model, you can click the hyperlink in the description to go to the
block corresponding to the argument in the model display. For
argument examples, see the rtwdemo_fcnprotoctrl report
excerpt below.
Return value If the function has a return value, this field displays the return
value data type and Simulink description. If you selected the
Report pane option Code-to-model for your model, you can click
the hyperlink in the description to go to the block corresponding
to the return value in the model display. For a return value
example, see the following rtwdemo_fcnprotoctrl report
excerpt.
Header file Lists the name of the header file for the function. You can click
the header file name to go to the header file source listing.
For example, here is the Entry Point Functions subsection for the model
rtwdemo_basicsc.
16-28
Analyze the Generated Code Interface
To illustrate how timing information might be listed for a multirate model, here are the
Entry Point Functions and Inports subsections for the model rtwdemo_mrmtbb.
This multirate, discrete-time, multitasking model contains Inport blocks 1 and 2,
which specify 1-second and 2-second sample times, respectively. The sample times are
constrained to the specified times by the Periodic sample time constraint option on
the Solver pane of the Configuration Parameters dialog box.
16-29
16 Report Generation
16-30
Analyze the Generated Code Interface
To illustrate how function arguments and return values are displayed in the report,
here is the Entry Point Functions description of the model step function for the model
rtwdemo_fcnprotoctrl.
Field Description
Block Name Displays the Simulink block name of the inport or outport. If you
selected the Report pane option Code-to-model for your model,
you can click on each inport or outport Block Name value to go
to its location in the model display.
Code Identifier Lists the identifier associated with the inport or outport data in
the generated code, as follows:
16-31
16 Report Generation
Field Description
• If the data is declared but not defined in the generated code —
for example, if the data is resolved with an imported storage
class — the field displays the identifier string prefixed with
the label 'Imported data:'.
• If the data is neither defined nor declared in the generated
code — for example, if Reusable function code interface
packaging is selected for the model — the field displays the
string 'Defined externally'.
Data Type Lists the data type of the inport or outport.
Dimension Lists the dimensions of the inport or outport (for example, 1 or
[4, 5]).
For example, here are the Inports and Outports subsections for the model
rtwdemo_basicsc.
Field Description
Parameter Source Lists the source of the parameter value, as follows:
16-32
Analyze the Generated Code Interface
Field Description
Lookup1. If you selected the Report pane option Code-to-
model for your model, you can click the Parameter Source
value to go to the parameter's location in the model display.
• If the source of the parameter value is a workspace variable,
the field displays the name of the workspace variable.
Code Identifier Lists the identifier associated with the tunable parameter data in
the generated code, as follows:
For example, here is the Interface Parameters subsection for the model
rtwdemo_basicsc (with the ExportedGlobal Storage Class button selected in the
model window).
16-33
16 Report Generation
Field Description
Data Store Source Lists the source of the data store memory, as follows:
For example, here is the Data Stores subsection for the model rtwdemo_basicsc (with
the ExportedGlobal Storage Class button selected in the model window).
16-34
Analyze the Generated Code Interface
• The code interface report does not support the GRT interface with an ERT target or C
++ class code interface packaging. For these configurations, the code interface report
is not generated and does not appear in the HTML code generation report Contents
pane.
• The code interface report supports data resolved with most custom storage classes
(CSCs), except when the CSC properties are set in any of the following ways:
• The CSC property Type is set to FlatStructure. For example, the BitField
and Struct CSCs in the Simulink package have Type set to FlatStructure.
• The CSC property Type is set to Other. For example, the GetSet CSC in the
Simulink package has Type set to Other.
• The CSC property Data access is set to Pointer, indicating that imported
symbols are declared as pointer variables rather than simple variables. This
property is accessible only when the CSC property Data scope is set to Imported
or Instance-specific.
In these cases, the report displays empty Data Type and Dimension fields.
• For outports, the code interface report cannot describe the associated memory (data
type and dimensions) if the memory is optimized. In these cases, the report displays
empty Data Type and Dimension fields.
• The code interface report does not support data type replacement using the Code
Generation > Data Type Replacement pane of the Configuration Parameters
dialog box. The data types listed in the report will link to built-in data types rather
than their specified replacement data types.
16-35
16 Report Generation
• “Generate Static Code Metrics Report for Simulink Model” on page 16-39
• “Generate a Static Code Metrics Report for MATLAB Code” on page 16-45
16-36
Static Code Metrics
the Static Code Metrics section of the HTML Code Generation Report. The static code
metrics report does not support the C++ target language. The report is not available if
you generate a MEX function from MATLAB code.
• Uses the specified C data types. For Simulink models, you specify these data
types in the Hardware Implementation > Production hardware pane of the
Configuration Parameters dialog box. For code generation from MATLAB code, you
specify them in the Hardware tab of the MATLAB Coder Project Settings dialog box
or using a code generation configuration object. Actual object code metrics might differ
due to target-specific compiler and platform settings.
• Includes custom code only if you specify it. For Simulink models, you specify custom
code on the Code Generation > Custom Code pane in the model configuration. For
code generation from MATLAB code, you specify it on the Custom Code tab of the
MATLAB Coder Project Settings dialog box or using a code generation configuration
object. An error report is generated if the generated code includes platform-specific
files not contained in the standard C run-time library.
• For Simulink models, includes the generated code from referenced models.
• Uses 1-byte alignment for all members of a structure for estimating global and local
data structure sizes. The size of a structure is calculated by summing the sizes of all
of its fields. This estimation represents the smallest possible size for a structure.
• Calculates the self stack size of a function as the size of local data within a function,
excluding input arguments. The accumulated stack size of a function is the self stack
size plus the maximum of the accumulated stack sizes of its called functions. For
example, if the accumulated stacks sizes for the called functions are represented as
accum_size1...accum_sizeN, then the accumulated stack size for a function is
accumulated_stack_size = self_stack_size + max(accum_size1,...,accum_sizeN)
• When estimating the stack size of a function, static analysis stops at the first instance
of a recursive call. The Function Information table indicates when recursion occurs
in a function call path. Code generation generates only recursive code for Stateflow
event broadcasting and for graphical functions if it is written as a recursive function.
• Calculates the cyclomatic complexity of a function as the number of decisions plus
one:
CC = Number of decisions + 1
The following constructs add a decision:
• If statement
16-37
16 Report Generation
• Else-If statement
• Switch statement (1 decision for each case branch)
• Loop statements: While, For, Do-while
Note: Boolean operators in the above constructs do not add extra decisions.
• Does not include ert_main.c, because you have the option to provide your own
main.c.
16-38
Generate Static Code Metrics Report for Simulink Model
1 Before generating the HTML Code Generation Report, open the Configuration
Parameters dialog box for your model. On the Code Generation > Report pane,
select the “Static code metrics” check box.
If your model includes referenced models, select the Static code metrics check box
in each referenced model’s configuration set. Otherwise, you cannot view a separate
static code metrics report for a referenced model.
2 Press Ctrl+B to build your model and generate the HTML code generation report.
For more information, see “Traceability in Code Generation Report”.
3 If the HTML Code Generation Report is not already open, open the report. On the
left navigation pane, in the Contents section, select Static Code Metrics Report.
4 Hover your cursor over column titles and some column values to see a description of
the corresponding data.
16-39
16 Report Generation
5 To see the generated files and how many lines of code are generated per file, look at
the File Information section.
6 If your model includes referenced models, the File information section includes a
Referenced Model column. In this column, click the referenced model name to open
its static code metrics report. If the static code metrics report is not available for
a referenced model, specify the Static code metrics parameter in the referenced
model’s configuration set and rebuild your model.
7 To view the global variables in the generated code, their size, and the number of
accesses, see the Global Variables section.
16-40
Generate Static Code Metrics Report for Simulink Model
The Reads/Writes column displays the total number of read and write accesses
to the global variable. The Reads/Writes in a Function column displays the
maximum number of read and write accesses to the global variable within a function.
You use this information is to estimate the benefit of turning on optimizations, which
reduce the number of global references. For more information, see “Optimize Global
Variable Usage”.
16-41
16 Report Generation
8 To navigate from the report to the source code, click a global variable or function
name. These names are hyperlinks to their definitions.
9 To view the function call tree of the generated code, in the Function Information
section, click Call Tree at the top of the table.
16-42
Generate Static Code Metrics Report for Simulink Model
ert_main.c is not included in the code metrics analysis, therefore it is not shown in
the call tree format. The Complexity column includes the cyclomatic complexity of
each function.
10 To view the functions in a table format, click Table.
16-43
16 Report Generation
The second column, Called By, lists functions that call the function listed in the first
column, using the following criteria:
16-44
Generate a Static Code Metrics Report for MATLAB Code
By default, when you generate standalone C code with MATLAB Coder, the code
generation report now includes a static code metrics report. The static code metrics
report is not available for generated MEX functions.
By default, the project opens in the MATLAB workspace on the right side.
b On the project Overview tab, click the Add files link. Browse to the file
moving_average.m. Click OK to add the file to the project.
The file is displayed on the Overview tab. Both inputs are undefined.
c Define the type of input u.
i On the Overview tab, click the field to the right of the input parameter x
and, from the list of input options, select double.
ii From the list of size options, select 1 x 1 to specify that the input is a
scalar.
3 Repeat the previous step for input z.
16-45
16 Report Generation
MATLAB Coder builds the project and generates a C static library and supporting
files in the default folder, codegen/lib/moving_average and provides a link to
the code generation report.
9 Open the code generation report and click Static Code Metrics Report to open the
report.
10 To see the generated files and how many lines of code are generated per file, look at
the File Information section.
16-46
Generate a Static Code Metrics Report for MATLAB Code
11 To view the global variables in the generated code and their size, see the Global
Variables section.
16-47
16 Report Generation
To navigate from the report to the source code, click a global variable name. The
names are hyperlinks to their definitions.
12 To view the function call tree of the generated code, in the Function Information
section, click Call Tree at the top of the table.
To navigate from the report to the function code, click a function name.
13 To view the functions in a table format, click Table.
16-48
Generate a Static Code Metrics Report for MATLAB Code
The second column, Called By, lists functions that call the function listed in the first
column, using the following criteria:
1 Create a code generation configuration object for standalone code generation. For
example, to generate a static library:
cfg = coder.config('lib');
2 Generate code, passing the configuration object as a parameter and specifying the -
report option. For example:
Alternatively,
16-49
16 Report Generation
1 Create a code generation configuration object for standalone code generation. For
example, to generate a static library:
cfg = coder.config('lib');
2 Set the configuration object GenerateReport and GenerateCodeMetricsReport
parameters to true.
cfg.GenerateReport = true;
cfg.GenerateCodeMetricsReport = true;
3 Generate code, passing the configuration object as a parameter. For example:
codegen -config cfg foo
16-50
Analyze Code Replacements in the Generated Code
The figure below shows a Code Replacements Report generated for the CRL model
rtwdemo_crladdsub. Each replacement function used is listed with a link to the block
that triggered the replacement.
16-51
16 Report Generation
If you click a block path in the report, the block that triggered the replacement is
highlighted in the model diagram. If the replacement was triggered by a Stateflow chart
or a MATLAB function, a window opens to display the chart or function.
For more information, see “Trace Code Replacements Generated Using Your Code
Replacement Library”.
16-52
Document Generated Code with Simulink Report Generator
The Simulink Report Generator software creates documentation from your model in
multiple formats, including HTML, PDF, RTF, Microsoft Word, and XML. This example
shows one way to document a code generation project in Microsoft Word. The generated
report includes:
To adjust Simulink Report Generator settings to include custom code and then generate
a report for a model, complete the following tasks:
16-53
16 Report Generation
A Simulink Report Generator license is required for the following report formats: PDF,
RTF, Microsoft Word, and XML. For more information on generating reports in these
formats, see the Simulink Report Generator documentation.
1 In the MATLAB Current Folder browser, navigate to a folder where you have write
access.
2 Create a working folder from the MATLAB command line by typing:
mkdir report_ex
3 Make report_ex your working folder:
cd report_ex
4 Open the slexAircraftExample model by entering the model name on the
MATLAB command line.
5 In the model window, choose File > Save As, navigate to the working folder,
report_ex, and save a copy of the slexAircraftExample model as myModel.
6 Open the Configuration Parameters dialog box by selecting Model Configuration
Parameters from the Simulation menu.
7 Select the Solver pane. In the Solver options section, specify the Type parameter
as Fixed-step.
8 Select the Code Generation pane. Select Generate code only.
9 Click Apply.
10 Click Generate code. The build process generates code for the model.
16-54
Document Generated Code with Simulink Report Generator
3
Double-click codegen.rpt or select it and click the Open report button . The
Report Explorer displays the structure of the setup file in the outline pane (left).
16-55
16 Report Generation
1 In the properties pane, under Report Options, review the options listed.
16-56
Document Generated Code with Simulink Report Generator
1 In the outline pane (left), select Model Loop. Report Generator displays Model Loop
component options in the properties pane.
2 If not already selected, select Current block diagram for the Model name
option.
3 In the outline pane, click Report - codegen.rpt*.
16-57
16 Report Generation
1 In the outline pane (left), expand the node Chapter - Generated Code. By default,
the report includes two sections, each containing one of two report components.
2 Expand the node Section 1 — Code Generation Summary.
3 Select Code Generation Summary. Options for the component are displayed in the
properties pane.
4 Click Help to review the report customizations that you can make with the Code
Generation Summary component. For this example, do not customize the component.
5 In the Report Explorer window, expand the node Section 1 — Generated Code
Listing.
6 Select Import Generated Code. Options for the component are displayed in the
properties pane.
7 Click Help to review the report customizations that you can make with the Import
Generated Code component.
16-58
Document Generated Code with Simulink Report Generator
When the report is complete, open the report, MyModelCGReport.rtf in the folder
report_ex (in this example).
For alternative ways of generating reports with the Simulink Report Generator, see
“Generate Reports”.
16-59
16-60
17
• Optimization for a specific run-time environment, including, but not limited to,
specific target hardware.
• Integration with existing application code.
• Compliance with a standard, such as AUTOSAR.
• Modification of code behavior, such as enabling or disabling nonfinite or inline
support.
• Application- or project-specific code requirements, such as:
• Elimination of math.h.
• Elimination of system header files.
• Elimination of calls to memcpy or memset.
• Use of BLAS.
• Use of a specific BLAS.
To apply this technique, configure the code generator to apply a code replacement
library (CRL) during code generation. By default, the code generator does not apply a
code replacement library. You can choose from the following libraries that MathWorks
provides:
• GNU C99 extensions—GNU®5 gcc math library, which provides C99 extensions as
defined by compiler option -std=gnu99.
• Intel IPP for x86-64 (Windows)—Generates calls to the Intel® Performance Primitives
(IPP) library for the x86-64 Windows platform.
• Intel IPP/SSE with GNU99 extensions for x86-64 (Windows)—GNU libraries for Intel
Performance Primitives (IPP) and Streaming SIMD Extensions (SSE), with GNU C99
extensions.
• Intel IPP for x86/Pentium (Windows)—Generates calls to the Intel Performance
Primitives (IPP) library for the x86/Pentium Windows platform.
5. GNU is a registered trademark of the Free Software Foundation.
17-2
What Is Code Replacement?
Libraries that include GNU99 extensions are intended for use with the GCC compiler. If
use one of those libraries with another compiler, generated code might not compile.
Depending on the product licenses that you have, other libraries might be available . If
you have an Embedded Coder license, you can view and choose from other libraries and
you can create custom code replacement libraries.
Related Examples
• “Replace Code Generated from Simulink Models”
• “Choose a Code Replacement Library”
More About
• “Code You Can Replace From Simulink Models”
• “Code Replacement Libraries”
• “Code Replacement Terminology”
• “Code Replacement Limitations”
17-3
17 Code Replacement for Simulink Models
For information on how to explore functions and operators that a code replacement
library supports, see “Choose a Code Replacement Library” license and want to develop a
custom code replacement library, see Code Replacement Customization.
Function Data Type Support Scalar, Vector, Matrix Real, Complex Support
Support
abs1 Integer Scalar Real
Floating point Vector
Fixed point Matrix
acos Floating point Scalar Real
17-4
Code You Can Replace From Simulink Models
Function Data Type Support Scalar, Vector, Matrix Real, Complex Support
Support
Complex input/complex output
Real input/complex output
acosd2 Floating point Scalar Real
Vector Complex
Matrix
acosh Floating point Scalar Real
Vector Complex input/complex output
Matrix Real input/complex output
acot2 Floating point Scalar Real
Vector Complex
Matrix
acotd2 Floating point Scalar Real
Vector Complex
Matrix
acoth2 Floating point Scalar Real
Vector Complex
Matrix
acsc2 Floating point Scalar Real
Vector Complex
Matrix
acscd2 Floating point Scalar Real
Vector Complex
Matrix
acsch2 Floating point Scalar Real
Vector Complex
Matrix
asec2 Floating point Scalar Real
Vector Complex
Matrix
asecd2 Floating point Scalar Real
Vector Complex
Matrix
17-5
17 Code Replacement for Simulink Models
Function Data Type Support Scalar, Vector, Matrix Real, Complex Support
Support
asech2 Floating point Scalar Real
Vector Complex
Matrix
asin Floating point Scalar Real
Complex input/complex output
Real input/complex output
asind2 Floating point Scalar Real
Vector Complex
Matrix
asinh Floating point Scalar Real
Vector Complex input/complex output
Matrix Real input/complex output
atan Floating point Scalar Real
Vector Complex input/complex output
Matrix Real input/complex output
atan2 Floating point Scalar Real
Vector
Matrix
atan2d2 Floating point Scalar Real
Vector
Matrix
atand2 Floating point Scalar Real
Vector Complex
Matrix
atanh Floating point Scalar Real
Vector Complex input/complex output
Matrix Real input/complex output
ceil • Floating-point • Floating-point • Floating-point
• Scalar • Scalar • Scalar
cos 3 Floating point Scalar Real
Vector Complex input/complex output
Matrix Real input/complex output
17-6
Code You Can Replace From Simulink Models
Function Data Type Support Scalar, Vector, Matrix Real, Complex Support
Support
cosd2 Floating point Scalar Real
Vector Complex
Matrix
cosh Floating point Scalar Real
Vector Complex input/complex output
Matrix Real input/complex output
cot2 Floating point Scalar Real
Vector Complex
Matrix
cotd2 Floating point Scalar Real
Vector Complex
Matrix
coth2 Floating point Scalar Real
Vector Complex
Matrix
csc2 Floating point Scalar Real
Vector Complex
Matrix
cscd2 Floating point Scalar Real
Vector Complex
Matrix
csch2 Floating point Scalar Real
Vector Complex
Matrix
exactrSqrt Integer Scalar Real
Floating point
exp Floating point Scalar Real
Vector
Matrix
fix Floating point Scalar Real
floor • Floating-point • Floating-point • Floating-point
• Scalar • Scalar • Scalar
17-7
17 Code Replacement for Simulink Models
Function Data Type Support Scalar, Vector, Matrix Real, Complex Support
Support
fmod4 Floating point Scalar Real
frexp Floating point Scalar Real
hypot Floating point Scalar Real
Vector
Matrix
ldexp Floating point Scalar Real
ln Floating point Scalar Real
log Floating point Scalar Real
Vector
Matrix
log10 Floating point Scalar Real
Vector
Matrix
log22 Floating point Scalar Real
Vector Complex
Matrix
max Integer Scalar Real
Floating point
Fixed point
min Integer Scalar Real
Floating point
Fixed point
mod Integer Scalar Real
Floating point Vector
Matrix
pow Floating point Scalar Real
Vector
Matrix
rem Floating point Scalar Real
Vector
Matrix
round Floating point Scalar Real
17-8
Code You Can Replace From Simulink Models
Function Data Type Support Scalar, Vector, Matrix Real, Complex Support
Support
rSqrt Integer Scalar Real
Floating point Vector
Matrix
saturate Integer Scalar Real
Floating point Vector
Fixed point Matrix
sec2 Floating point Scalar Real
Vector Complex
Matrix
secd2 Floating point Scalar Real
Vector Complex
Matrix
sech2 Floating point Scalar Real
Vector Complex
Matrix
sign Integer Scalar Real
Floating point Vector
Fixed point Matrix
signPow Floating point Scalar Real
Vector
Matrix
sin3 Floating point Scalar Real
Vector Complex input/complex output
Matrix Real input/complex output
sincos3 Floating point Scalar Real
Vector Complex input/complex output
Matrix Real input/complex output
sind2 Floating point Scalar Real
Vector Complex
Matrix
sinh Floating point Scalar Real
Vector Complex input/complex output
Matrix Real input/complex output
17-9
17 Code Replacement for Simulink Models
Function Data Type Support Scalar, Vector, Matrix Real, Complex Support
Support
sqrt Integer Scalar Real
Floating point Vector
Fixed point Matrix
tan Floating point Scalar Real
Vector Complex input/complex output
Matrix Real input/complex output
tand2 Floating point Scalar Real
Vector Complex
Matrix
tanh Floating point Scalar Real
Vector Complex input/complex output
Matrix Real input/complex output
1
Wrap on integer overflow only. Clear block parameter Saturate on integer overflow.
2
Only when used with the MATLAB Function block.
3
Supports the CORDIC approximation method.
4
Stateflow support only.
Function Data Type Support Scalar, Vector, Matrix Real, Complex Support
Support
abs1 Integer Scalar Real
Floating point
acos2 Floating point Scalar Real
Vector Complex
Matrix Complex input/complex
output
17-10
Code You Can Replace From Simulink Models
Function Data Type Support Scalar, Vector, Matrix Real, Complex Support
Support
Real input/complex output
acosd3 Floating point Scalar Real
Vector Complex
Matrix
acot3 Floating point Scalar Real
Vector Complex
Matrix
acotd3 Floating point Scalar Real
Vector Complex
Matrix
acoth3,5 Floating point Scalar Real
Vector Complex
Matrix
acsc3 Floating point Scalar Real
Vector Complex
Matrix
acscd3 Floating point Scalar Real
Vector Complex
Matrix
acsch3 Floating point Scalar Real
Vector Complex
Matrix
asec3 Floating point Scalar Real
Vector Complex
Matrix
asecd3 Floating point Scalar Real
Vector Complex
Matrix
asech3 Floating point Scalar Real
Vector Complex
Matrix
17-11
17 Code Replacement for Simulink Models
Function Data Type Support Scalar, Vector, Matrix Real, Complex Support
Support
asin2 Floating point Scalar Real
Vector Complex
Matrix Complex input/complex
output
Real input/complex output
asind3 Floating point Scalar Real
Vector Complex
Matrix
atan2 Floating point Scalar Real
Vector Complex
Matrix Complex input/complex
output
Real input/complex output
atan22 Floating point Scalar Real
Vector
Matrix
atan2d3 Floating point Scalar Real
Vector
Matrix
atand3 Floating point Scalar Real
Vector Complex
Matrix
ceil • Floating-point • Floating-point • Floating-point
• Scalar • Scalar • Scalar
cos 3 Floating point Scalar Real
Vector Complex
Matrix Complex input/complex
output
Real input/complex output
cosd3 Floating point Scalar Real
Vector Complex
Matrix
17-12
Code You Can Replace From Simulink Models
Function Data Type Support Scalar, Vector, Matrix Real, Complex Support
Support
cosh2 Floating point Scalar Real
Vector Complex
Matrix Complex input/complex
output
Real input/complex output
cot3 Floating point Scalar Real
Vector Complex
Matrix
cotd3 Floating point Scalar Real
Vector Complex
Matrix
coth3 Floating point Scalar Real
Vector Complex
Matrix
csc3 Floating point Scalar Real
Vector Complex
Matrix
cscd3 Floating point Scalar Real
Vector Complex
Matrix
csch3 Floating point Scalar Real
Vector Complex
Matrix
exp Floating point Scalar Real
floor • Floating-point • Floating-point • Floating-point
• Scalar • Scalar • Scalar
fmod Floating point Scalar Real
hypot 3 Floating point Scalar Real
Vector
Matrix
ldexp Floating point Scalar Real
17-13
17 Code Replacement for Simulink Models
Function Data Type Support Scalar, Vector, Matrix Real, Complex Support
Support
log2 Floating point Scalar Real
Vector Complex
Matrix
log102 Floating point Scalar Real
Vector Complex
Matrix
log23 Floating point Scalar Real
Vector Complex
Matrix
max Integer Scalar Real
Floating point
min Integer Scalar Real
Floating point
pow Floating point Scalar Real
sec3 Floating point Scalar Real
Vector Complex
Matrix
secd3 Floating point Scalar Real
Vector Complex
Matrix
sech3 Floating point Scalar Real
Vector Complex
Matrix
sin2 Floating point Scalar Real
Vector Complex
Matrix Complex input/complex
output
Real input/complex output
sind3 Floating point Scalar Real
Vector Complex
Matrix
17-14
Code You Can Replace From Simulink Models
Function Data Type Support Scalar, Vector, Matrix Real, Complex Support
Support
sinh2 Floating point Scalar Real
Vector Complex
Matrix Complex input/complex
output
Real input/complex output
sqrt Floating point Scalar Real
tan 2 Floating point Scalar Real
Vector Complex
Matrix Complex input/complex
output
Real input/complex output
tand3 Floating point Scalar Real
Vector Complex
Matrix
tanh2 Floating point Scalar Real
Vector Complex
Matrix Complex input/complex
output
Real input/complex output
1
Wrap on integer overflow only.
2
For models involving vectors or matrices, the code generator replaces only functions coded in the
MATLAB action language.
3
The code generator replaces only functions coded in the MATLAB action language.
Memory Functions
Depending on code replacement libraries available in your development environment,
you can configure the code generator to replace instances of the following memory
functions with application-specific implementations.
Function Data Type Support Scalar, Vector, Matrix Real, Complex Support
Support
memcmp Void pointer (void*) Scalar Real
17-15
17 Code Replacement for Simulink Models
Function Data Type Support Scalar, Vector, Matrix Real, Complex Support
Support
Vector Complex
Matrix
memcpy Void pointer (void*) Scalar Real
Vector Complex
Matrix
memset Void pointer (void*) Scalar Real
Vector Complex
Matrix
memset2zero Void pointer (void*) Scalar Real
Vector Complex
Matrix
Some target processors provide optimized functions to set memory to zero. Use the code
replacement library programming interface to replace the memset2zero function with
more efficient target-specific functions.
Nonfinite Functions
Depending on code replacement libraries available in your development environment,
you can configure the code generator to replace instances of the following nonfinite
functions with application-specific implementations.
17-16
Code You Can Replace From Simulink Models
• Before code for a data transfer between tasks enters the critical section, mutex
lock or semaphore wait function calls to reserve a critical section of code.
• After code for a data transfer between tasks finishes executing the critical section,
mutex unlock or semaphore post function calls to release the critical section of
code.
• In model termination code, an optional destroy function call to explicitly delete the
mutex or semaphore.
Function Key
Mutex Destroy RTW_MUTEX_DESTROY
Mutex Init RTW_MUTEX_INIT
Mutex Lock RTW_MUTEX_LOCK
Mutex Unlock RTW_MUTEX_UNLOCK
Semaphore Destroy RTW_SEM_DESTROY
Semaphore Init RTW_SEM_INIT
Semaphore Post RTW_SEM_POST
Semaphore Wait RTW_SEM_WAIT
17-17
17 Code Replacement for Simulink Models
Operators
When generating C/C++ code from a Simulink model, depending on code replacement
libraries available in your development environment, you can configure the code
generator to replace instances of the following operators with application-specific
implementations.
17-18
Code You Can Replace From Simulink Models
17-19
17 Code Replacement for Simulink Models
17-20
Code You Can Replace From Simulink Models
Related Examples
• “Choose a Code Replacement Library”
17-21
17 Code Replacement for Simulink Models
More About
• “What Is Code Replacement?”
• “Code Replacement Limitations”
• “Code Replacement Terminology”
• “Code Replacement Libraries”
17-22
Code Replacement Libraries
A code replacement table contains one or more code replacement entries, with each entry
representing a potential replacement for a function or operator. Each entry maps a
conceptual representation of a function or operator to an implementation representation
and priority.
17-23
17 Code Replacement for Simulink Models
When the code generator looks for a match in a code replacement library, it creates and
populates a call site object with the function or operator conceptual representation. If
a match exists, the code generator uses the matched code replacement entry populated
with the implementation representation and uses it to generate code.
The code generator searches the tables in a code replacement library for a match in the
order that the tables appear in the library. If the code generator finds multiple matches
within a table, the priority determines the match. The code generator uses a higher-
priority entry over a similar entry with a lower priority.
Related Examples
• “Replace Code Generated from Simulink Models”
• “Choose a Code Replacement Library”
More About
• “What Is Code Replacement?”
• “Code You Can Replace From Simulink Models”
• “Code Replacement Terminology”
17-24
Code Replacement Terminology
17-25
17 Code Replacement for Simulink Models
Term Definition
'u1', 'u2', ...) and data types familiar to the code
generator.
Conceptual representation Represents match criteria that the code generator
uses to qualify functions and operators for
replacement. Consists of:
17-26
Code Replacement Terminology
Term Definition
Priority Defines the match priority for a code replacement
entry relative to other entries, which have the
same name and conceptual argument list, within
a code replacement library. The priority can
range from 0 to 100, with 0 being the highest
priority. The default is 100. If a library provides
two implementations for a function or operator, the
implementation with the higher priority shadows
the one with the lower priority.
More About
• “What Is Code Replacement?”
• “Code Replacement Libraries”
17-27
17 Code Replacement for Simulink Models
Related Examples
• “Replace Code Generated from Simulink Models”
More About
• “Code You Can Replace From Simulink Models”
• “Code Replacement Libraries”
17-28
Replace Code Generated from Simulink Models
1 Make sure that MATLAB, Simulink, Simulink Coder, and a C compiler are installed
on your system. Some code replacement libraries available in your development
environment can also require Embedded Coder.
If you are not sure which library to use, explore the available libraries.
1 Configure the code generator to apply a code replacement library during code
generation for the model.
17-29
17 Code Replacement for Simulink Models
If you have an Embedded Coder license, you can configure the code generator to include
a code replacement section in the code generation report. The additional information can
help you verify code replacements.
Generate C/C++ code from the model and, if you configured the code generator
accordingly, a code generation report. For example, on the Code Generation > General
pane, click Generate Code.
The code generator produces the code and displays the report.
Verify code replacements by examining the generated code. It is possible that code
replacement behaves differently than you expect. For example, data types that you
observe in the code generator input might not match what the code generator uses as
intermediate data types during an operation.
Related Examples
• “Choose a Code Replacement Library”
• “Code Generation Configuration”
• “Review and Test Code Replacements”
More About
• “Code replacement library”
• “Generate code only”
• “Create code generation report”
• “Open report automatically”
17-30
Replace Code Generated from Simulink Models
17-31
17 Code Replacement for Simulink Models
1 Explore available libraries. Identify one that best meets your application needs.
• Consider the lists of application code replacement requirements and libraries that
MathWorks provides in “What Is Code Replacement?”.
• See “Explore Available Code Replacement Libraries”.
2 Explore the contents of the library. See “Explore Code Replacement Library
Contents”.
If you do not find a suitable library and you have an Embedded Coder license, you can
create a custom code replacement library.
17-32
Choose a Code Replacement Library
>> RTW.viewTfl
The viewer opens. To view the content of a specific library, specify the name of the
library as an argument in single quotes. For example:
>> RTW.viewTfl('GNU C99 extensions')
2 In the left pane, select the name of a library. The viewer displays information about
the library in the right pane.
3 In the left pane, expand the library, explore the list of tables it contains, and select a
table from the list. In the middle pane, the viewer displays the function and operator
entries that are in that table, along with abbreviated information for each entry.
4 In the middle pane, select a function or operator. The viewer displays information
from the table entry in the right pane.
If you select an operator entry that specifies net slope fixed-point parameters
(instantiated from entry class RTW.TflCOperationEntryGenerator or
RTW.TflCOperationEntryGenerator_NetSlope), the viewer displays an
additional tab that shows fixed-point settings.
See Code Replacement Viewer for details on what the viewer displays.
Related Examples
• “Replace Code Generated from Simulink Models”
More About
• “What Is Code Replacement?”
• “Code You Can Replace From Simulink Models”
• “Code Replacement Libraries”
• “Code Replacement Terminology”
• “Code Replacement Limitations”
17-33
17-34
Deployment
18
Desktops
18 Desktops
In this section...
“About Host-Based Shared Libraries” on page 18-2
“Generate Shared Library Version of Model Code” on page 18-3
“Create Application Code to Use Shared Library” on page 18-3
“Host-Based Shared Library Limitations” on page 18-7
To view a list of symbols contained in a generated shared library file, you can
18-2
Shared Object Libraries
1 To configure your model code for shared use by applications, open your model
and select the ert_shrlib.tlc target on the Code Generation pane of the
Configuration Parameters dialog box. Click OK.
Selecting the ert_shrlib.tlc target causes the build process to generate a shared
library version of your model code into your current working folder. The selection
does not change the code that is generated for your model.
2 Build the model.
3 After the build completes, you can examine the generated code in the model
subfolder, and the .dll file or .so file that has been generated into your current
folder.
18-3
18 Desktops
Note: It is recommended that you change directory to a new or empty folder before
running the rtwdemo_shrlib script.
The model uses the following example application files, which are located in
matlabroot/toolbox/rtw/rtwdemos/shrlib_demo.
File Description
rtwdemo_shrlib_app.h Example application header file
rtwdemo_shrlib_app.c Example application that loads and uses the
shared library file generated for the model
run_rtwdemo_shrlib_app.m Script to compile, link, and execute the example
application
You can view each of these files by clicking white buttons in the model window.
Additionally, running the script places the relevant source and generated code files in
your current folder. The files can be used as templates for writing application code for
your own ERT shared library files.
The following sections present key excerpts of the example application files.
typedef struct {
int32_T Input;
} ExternalInputs_rtwdemo_shrlib;
typedef struct {
int32_T Output;
} ExternalOutputs_rtwdemo_shrlib;
#endif /*_APP_MAIN_HEADER_*/
18-4
Shared Object Libraries
#else /* UNIX */
#include <dlfcn.h>
#define GETSYMBOLADDR dlsym
#define LOADLIB dlopen
#define CLOSELIB dlclose
#endif
int main()
{
void* handleLib;
...
#if defined(_WIN64)
handleLib = LOADLIB("./rtwdemo_shrlib_win64.dll");
#else
#if defined(_WIN32)
handleLib = LOADLIB("./rtwdemo_shrlib_win32.dll");
#else /* UNIX */
handleLib = LOADLIB("./rtwdemo_shrlib.so", RTLD_LAZY);
#endif
#endif
...
return(CLOSELIB(handleLib));
}
The following code excerpt shows how the C application accesses the model's exported
data and functions. Notice the hooks for adding user-defined initialization, step, and
termination code.
int32_T i;
...
void (*mdl_initialize)(boolean_T);
void (*mdl_step)(void);
void (*mdl_terminate)(void);
ExternalInputs_rtwdemo_shrlib (*mdl_Uptr);
ExternalOutputs_rtwdemo_shrlib (*mdl_Yptr);
uint8_T (*sum_outptr);
...
#if (defined(LCCDLL)||defined(BORLANDCDLL))
18-5
18 Desktops
if ((mdl_initialize && mdl_step && mdl_terminate && mdl_Uptr && mdl_Yptr &&
sum_outptr)) {
/* === user application initialization function === */
mdl_initialize(1);
/* insert other user defined application initialization code here */
18-6
Shared Object Libraries
The application script run_rtwdemo_shrlib_app.m loads and rebuilds the model, and
then compiles, links, and executes the model's shared library target file. You can view the
script source file by opening rtwdemo_shrlib and clicking a white button to view source
code. The script constructs platform-dependent command strings for compilation, linking,
and execution that may apply to your development environment. To run the script, click
the blue button.
• Code generation for the ert_shrlib.tlc target exports only the following as data:
You can change the default behavior and retain the .lib file by modifying the
corresponding template makefile (TMF). If you do this, the generated model.h file
needs a small modification to be used together with the generated ert_main.c
for implicit linking. For example, if you are using Visual C++, you need to declare
__declspec(dllimport) in front of data to be imported implicitly from the shared
library file.
• To reconstruct a model simulation using a generated host-based shared library, the
application author must maintain the timing between system and shared library
function calls in the original application. The timing needs to be consistent so that you
can check the simulation and integration results.
18-7
18-8
19
1 In the Custom templates section of the Code Generation > Templates pane
of the Configuration Parameters dialog box, select the Generate an example
main program option (which is on by default). This enables the Target operating
system menu.
2 From the Target operating system menu, select BareBoardExample (the default
selection).
3 Generate the code.
Different code is generated for multirate models depending on the following factors:
19-2
Standalone Programs (No Operating System)
These factors affect the scheduling algorithms used in generated code, and in some cases
affect the API for the model entry point functions. The following sections discuss these
variants.
The main loop is periodically interrupted by a timer. The function rt_OneStep is either
installed as a timer interrupt service routine (ISR), or called from a timer ISR at each
clock step.
The execution driver, rt_OneStep, sequences calls to the model_step functions. The
operation of rt_OneStep differs depending on whether the generating model is single-
rate or multirate. In a single-rate model, rt_OneStep simply calls the model_step
function. In a multirate model, rt_OneStep prioritizes and schedules execution of blocks
according to the rates at which they run.
Main Program
• “Overview of Operation” on page 19-3
• “Guidelines for Modifying the Main Program” on page 19-4
Overview of Operation
main()
{
Initialization (including installation of rt_OneStep as an
interrupt service routine for a real-time clock)
Initialize and start timer hardware
Enable interupts
While(not Error) and (time < final time)
Background task
EndWhile
Disable interrupts (Disable rt_OneStep from executing)
Complete any background tasks
Shutdown
}
19-3
19 Real-Time and Embedded Systems
The pseudocode is a design for a harness program to drive your model. The main
program only partially implements this design. You must modify it according to your
specifications.
This section describes the minimal modifications you should make in your production
version of the main program module to implement your harness program.
1 Call model_initialize.
2 Initialize target-specific data structures and hardware, such as ADCs or DACs.
3 Install rt_OneStep as a timer ISR.
4 Initialize timer hardware.
5 Enable timer interrupts and start the timer.
Note rtModel is not in a valid state until model_initialize has been called.
Servicing of timer interrupts should not begin until model_initialize has been
called.
6 Optionally, insert background task calls in the main loop.
7 On termination of the main loop (if applicable):
19-4
Standalone Programs (No Operating System)
Overview of Operation
The operation of rt_OneStep depends upon
Permitted Solver Modes for Embedded Coder Targeted Models summarizes the permitted
solver modes for single-rate and multirate models. Note that for a single-rate model, only
SingleTasking solver mode is allowed.
The generated code for rt_OneStep (and associated timing data structures and support
functions) is tailored to the number of rates in the model and to the solver mode. The
following sections discuss each possible case.
19-5
19 Real-Time and Embedded Systems
void model_step(void)
The overrun flag is cleared only upon successful return from model_step. Therefore,
if rt_OneStep is reinterrupted before completing model_step, the reinterruption is
detected through the overrun flag.
Note that the design of rt_OneStep assumes that interrupts are disabled before
rt_OneStep is called. rt_OneStep should be noninterruptible until the interrupt
overflow flag has been checked.
rt_OneStep()
{
Check for base-rate interrupt overrun
Enable "rt_OneStep" interrupt
Determine which rates need to run this time step
19-6
Standalone Programs (No Operating System)
Task Identifiers
The execution of blocks having different sample rates is broken into tasks. Each block
that executes at a given sample rate is assigned a task identifier (tid), which associates
it with a task that executes at that rate. Where there are NumTasks tasks in the system,
the range of task identifiers is 0..NumTasks-1.
Prioritization of Base-Rate and Subrate Tasks
Tasks are prioritized, in descending order, by rate. The base-rate task is the task that
runs at the fastest rate in the system (the hardware clock rate). The base-rate task has
highest priority (tid 0). The next fastest task (tid 1) has the next highest priority, and
so on down to the slowest, lowest priority task (tid NumTasks-1).
The slower tasks, running at multiples of the base rate, are called subrate tasks.
Rate Grouping and Rate-Specific model_step Functions
In a single-rate model, the block output computations are performed within a single
function, model_step. For multirate, multitasking models, the code generator tries to
use a different strategy. This strategy is called rate grouping. Rate grouping generates
separate model_step functions for the base rate task and each subrate task in the
model. The function naming convention for these functions is
model_stepN
where N is a task identifier. For example, for a model named my_model that has three
rates, the following functions are generated:
void my_model_step0 (void);
void my_model_step1 (void);
void my_model_step2 (void);
Each model_stepN function executes the blocks sharing tid N; in other words, the
block code that executes within task N is grouped into the associated model_stepN
function.
Scheduling model_stepN Execution
On each clock tick, rt_OneStep maintains scheduling counters and event flags for each
subrate task. The counters are implemented as taskCounter arrays indexed on tid.
The event flags are implemented as arrays indexed on tid.
The scheduling counters and task flags for sub-rates are maintained by rt_OneStep.
The scheduling counters are basically clock rate dividers that count up the sample period
19-7
19 Real-Time and Embedded Systems
associated with each sub-rate task. A pair of tasks that exchanges data maintains an
interaction flag at the faster rate. Task interaction flags indicate that both fast and slow
tasks are scheduled to run.
The event flags indicate whether or not a given task is scheduled for execution.
rt_OneStep maintains the event flags based on a task counter that is maintained by
code in the main program module for the model. When a counter indicates that a task's
sample period has elapsed, the main code sets the event flag for that task.
On each invocation, rt_OneStep updates its scheduling data structures and steps
the base-rate task (rt_OneStep calls model_step0 because the base-rate task must
execute on every clock step). Then, rt_OneStep iterates over the scheduling flags in tid
order, unconditionally calling model_stepN for any task whose flag is set. The tasks are
executed in order of priority.
Preemption
Note that the design of rt_OneStep assumes that interrupts are disabled before
rt_OneStep is called. rt_OneStep should be noninterruptible until the base-rate
interrupt overflow flag has been checked (see pseudocode above).
The event flag array and loop variables used by rt_OneStep are stored as local (stack)
variables. Therefore, rt_OneStep is reentrant. If rt_OneStep is reinterrupted, higher
priority tasks preempt lower priority tasks. Upon return from interrupt, lower priority
tasks resume in the previously scheduled order.
Overrun Detection
Note If you have developed multirate S-functions, or if you use a customized static main
program module, see “Rate Grouping Compliance and Compatibility Issues” on page
19-17 for information about how to adapt your code for rate grouping compatibility.
This adaptation lets your multirate, multitasking models generate more efficient code.
19-8
Standalone Programs (No Operating System)
In a multirate single-tasking program, blocks execute at different rates, but under the
same task identifier. The operation of rt_OneStep, in this case, is a simplified version
of multirate multitasking operation. Rate grouping is not used. The only task is the base-
rate task. Therefore, only one model_step function is generated:
void model_step(void)
On each clock tick, rt_OneStep checks the overrun flag and calls model_step. The
scheduling function for a multirate single-tasking program is rate_scheduler (rather
than rate_monotonic_scheduler). The scheduler maintains scheduling counters on
each clock tick. There is one counter for each sample rate in the model. The counters are
implemented in an array (indexed on tid) within the Timing structure within rtModel.
The counters are clock rate dividers that count up the sample period associated with each
subrate task. When a counter indicates that a sample period for a given rate has elapsed,
rate_scheduler clears the counter. This condition indicates that blocks running at that
rate should execute on the next call to model_step, which is responsible for checking the
counters.
rt_OneStep does not require extensive modification. The only required modification is
to reenable interrupts after the overrun flags and error conditions have been checked. If
applicable, you should also
• Save and restore your FPU context on entry and exit to rt_OneStep.
• Set model inputs associated with the base rate before calling model_step0.
• Get model outputs associated with the base rate after calling model_step0.
Note: If you modify rt_OneStep to read a value from a continuous output port after
each base-rate model step, see the relevant cautionary guideline below.
• In a multirate, multitasking model, set model inputs associated with subrates before
calling model_stepN in the subrate loop.
• In a multirate, multitasking model, get model outputs associated with subrates after
calling model_stepN in the subrate loop.
In multirate rt_OneStep, you can improve performance by unrolling for and while
loops.
19-9
19 Real-Time and Embedded Systems
In addition, you may choose to modify the overrun behavior to continue execution after
error recovery is complete.
• You should not modify the way in which the counters, event flags, or other timing
data structures are set in rt_OneStep, or in functions called from rt_OneStep. The
rt_OneStep timing data structures (including rtModel) and logic are critical to the
operation of the generated program.
• If you have customized the main program module to read model outputs after each
base-rate model step, be aware that selecting model options Support: continuous
time and Single output/update function together may cause output values read
from main for a continuous output port to differ slightly from the corresponding
output values in the model's logged data. This is because, while logged data is a
snapshot of output at major time steps, output read from main after the base-
rate model step potentially reflects intervening minor time steps. To eliminate the
discrepancy, either separate the generated output and update functions (clear the
Single output/update function option) or place a Zero-Order Hold block before the
continuous output port.
Overview
In most cases, the easiest strategy for deploying generated code is to use the Generate
an example main program option to generate the ert_main.c or .cpp module (see
“Generate a Standalone Program” on page 19-2).
However, if you turn the Generate an example main program option off, you can
use a static main module as an example or template for developing your embedded
applications. Static main modules provided by MathWorks include:
19-10
Standalone Programs (No Operating System)
The static main module is not part of the generated code; it is provided as a basis for
your custom modifications, and for use in simulation. If your existing applications
depend upon a static ert_main.c (developed in releases before R2012b), rt_main.c,
rt_malloc_main.c, or rt_cppclass_main.cpp, you may need to continue using a
static main program module.
When developing applications using a static main module, you should copy the module to
your working folder and rename it before making modifications. For example, you could
rename rt_main.c to model_rt_main.c. Also, you must modify the template makefile
or toolchain settings such that the build process creates a corresponding object file, such
as model_rt_main.obj (on UNIX, model_rt_main.o), in the build folder.
For single-rate models, the operation of rt_OneStep and the main function are
essentially the same in the static main module as they are in the autogenerated version
described in “About Standalone Program Execution” on page 19-2. For multirate,
multitasking models, however, the static and generated code are slightly different. The
next section describes this case.
Targets based on the ERT target sometimes use a static main module and disallow use of
the Generate an example main program option. This is done because target-specific
modifications have been added to the static main module, and these modifications would
not be preserved if the main program were regenerated.
Your static main module may or may not use rate grouping compatible model_stepN
functions. If your main module is based on the static rt_main.c, rt_malloc_main.c,
19-11
19 Real-Time and Embedded Systems
By default, when the Generate an example main program option is off, the ERT
target generates a model_step “wrapper” for multirate, multitasking models. The
purpose of the wrapper is to interface the rate-specific model_stepN functions to the
old-style call. The wrapper code dispatches to the model_stepN call with a switch
statement, as in the following example:
switch(tid) {
case 0 :
mymodel_step0();
break;
case 1 :
mymodel_step1();
break;
case 2 :
mymodel_step2();
break;
default :
break;
}
}
The following pseudocode shows how rt_OneStep calls model_step from the static
main program in a multirate, multitasking model.
rt_OneStep()
{
Check for base-rate interrupt overflow
Enable "rt_OneStep" interrupt
Determine which rates need to run this time step
19-12
Standalone Programs (No Operating System)
EndIf
EndFor
}
You can use the TLC variable RateBasedStepFcn to specify that only the rate-based
step functions are generated, without the wrapper function. If your target calls the rate
grouping compatible model_stepN function directly, set RateBasedStepFcn to 1. In
this case, the wrapper function is not generated.
As with the generated ert_main.c or .cpp, you should make a few modifications to the
main loop and rt_OneStep. See “Guidelines for Modifying the Main Program” on page
19-4 and “Guidelines for Modifying rt_OneStep” on page 19-9.
Also, you should replace the rt_OneStep call in the main loop with a background task
call or null statement.
• If applicable, follow comments in the code regarding where to add code for reading/
writing model I/O and saving/restoring FPU context.
19-13
19 Real-Time and Embedded Systems
• If you have cleared the Terminate function required option, remove or comment
out the following in your production version of rt_main.c, rt_malloc_main.c, or
rt_cppclass_main.cpp:
If you are using a static main program module, and your model is configured for
Reusable function code interface packaging, but the model option Use dynamic
memory allocation for model initialization is not selected, model instance data must
be allocated either statically or dynamically by the calling main code. Pointers to the
individual model data structures (such as Block IO, DWork, and Parameters) must be set
up in the top-level real-time model data structure.
To support main modifications, the build process generates a subset of the following real-
time model (RTM) macros, based on the data requirements of your model, into model.h.
19-14
Standalone Programs (No Operating System)
Use these macros in your static main program to access individual model data structures
within the RTM data structure. For example, suppose that the example model
rtwdemo_reusable is configured with Reusable function code interface packaging,
Use dynamic memory allocation for model initialization cleared, Pass root-level
I/O as set to Individual arguments, and Optimization pane option Remove root
level I/O zero initialization cleared. Building the model generates the following model
data structures and model entry-points into rtwdemo_reusable.h:
/* Block states (auto storage) for system '<Root>' */
typedef struct {
real_T Delay_DSTATE; /* '<Root>/Delay' */
} D_Work;
19-15
19 Real-Time and Embedded Systems
};
Additionally, if Generate an example main program is not selected for the model,
rtwdemo_reusable.h contains definitions for the RTM macros rtmGetDefaultParam,
rtmsetDefaultParam, rtmGetRootDWork, and rtmSetRootDWork.
Also, for reference, the generated rtmodel.h file contains an example parameter
definition with initial values (non-executing code):
#if 0
#endif
In the definitions section of your static main file, you could use the following code
to statically allocate the real-time model data structures and arguments for the
rtwdemo_reusable model:
static RT_MODEL rtM_;
static RT_MODEL *const rtM = &rtM_; /* Real-time model */
static Parameters rtP = {
2.0 /* Variable: k1
* Referenced by: '<Root>/Gain'
*/
}; /* Modifiable parameters */
/* '<Root>/In1' */
static real_T rtU_In1;
/* '<Root>/In2' */
static real_T rtU_In2;
/* '<Root>/Out1' */
static real_T rtY_Out1;
In the body of your main function, you could use the following RTM macro calls to set up
the model parameters and DWork data in the real-time model data structure:
19-16
Standalone Programs (No Operating System)
rtmSetDefaultParam(rtM, &rtP);
rtmSetRootDWork(rtM, &rtDWork);
/* Initialize model */
rtwdemo_reusable_initialize(rtM, &rtU_In1, &rtU_In2, &rtY_Out1);
...
}
Follow a similar approach to set up multiple instances of model data, where the real-time
model data structure for each instance has its own data. In particular, the parameter
structure (rtP) should be initialized, for each instance, to the desired values, either
statically as part of the rtP data definition or at run time.
When the Generate an example main program option is off, code generation produces
slightly different rate grouping code, for compatibility with the older static ert_main.c
module. See “Rate Grouping and the Static Main Program” on page 19-11 for details.
Built-in Simulink blocks, as well as DSP System Toolbox blocks, are compliant with
the requirements for generating rate grouping code. However, user-written multirate
inlined S-functions may not be rate grouping compliant. Noncompliant blocks generate
less efficient code, but are otherwise compatible with rate grouping. To take full
advantage of the efficiency of rate grouping, your multirate inlined S-functions must be
upgraded to be fully rate grouping compliant. You should upgrade your TLC S-function
implementations, as described in this section.
19-17
19 Real-Time and Embedded Systems
• Warning messages issued at compile time. Such warnings are caused when dead code
references temporary variables before initialization. Since the dead code does not run,
this problem does not affect the run-time behavior of the generated code.
To make your S-functions rate grouping compliant, you can use the following TLC
functions to generate ModelOutputs and ModelUpdate code, respectively:
OutputsForTID(block, system, tid)
UpdateForTID(block, system, tid)
The code listings below illustrate generation of output computations without rate
grouping (Listing 1) and with rate grouping (Listing 2). Note the following:
as in Listing 2.
19-18
Standalone Programs (No Operating System)
%%
%function Outputs(block, system) Output
/* %<Type> Block: %<Name> */
%assign enable = LibBlockInputSignal(0, "", "", 0)
{
int_T *enabled = &%<LibBlockIWork(0, "", "", 0)>;
if (*enabled) {
%assign signal = LibBlockInputSignal(1, "", "", 0)
if (%<LibIsSFcnSampleHit("OutputPortIdx0")>) {
%assign y = LibBlockOutputSignal(0, "", "", 0)
%<y> = %<signal>;
}
if (%<LibIsSFcnSampleHit("OutputPortIdx1")>) {
%assign y = LibBlockOutputSignal(1, "", "", 0)
%<y> = %<signal>;
}
}
}
%endfunction
%% [EOF] sfun_multirate.tlc
19-19
19 Real-Time and Embedded Systems
%endfunction
%switch(tid)
%case LibGetGlobalTIDFromLocalSFcnTID("InputPortIdx0")
%if LibGetSFcnTIDType("InputPortIdx0") == "continuous"
%% Only check the enable signal on a major time step.
if (%<LibIsMajorTimeStep()>) {
%<enabled> = (%<enable> > 0.0);
}
%else
%<enabled> = (%<enable> > 0.0);
%endif
%break
%case LibGetGlobalTIDFromLocalSFcnTID("OutputPortIdx0")
if (%<enabled>) {
%assign y = LibBlockOutputSignal(0, "", "", 0)
%<y> = %<signal>;
}
%break
%case LibGetGlobalTIDFromLocalSFcnTID("OutputPortIdx1")
if (%<enabled>) {
%assign y = LibBlockOutputSignal(1, "", "", 0)
%<y> = %<signal>;
}
%break
%default
%% error it out
%endswitch
%endfunction
%% [EOF] sfun_multirate.tlc
19-20
Operating System Integration
19-21
19 Real-Time and Embedded Systems
19-22
20
• A function-call subsystem that contains only blocks that support code generation
• A virtual subsystem that contains only such subsystems and a few other types of
blocks
• Create a SIL block that represents the generated code
You can use these capabilities only if the subsystem and its interface to the Simulink
model conform to certain requirements and constraints, as described in “Requirements
for Exporting Function-Call Subsystems” on page 20-3. For limitations that apply,
see “Function-Call Subsystems Export Limitations” on page 20-11. To see an example
of exported function-call subsystems, type rtwdemo_exporting_functions in the
MATLAB Command Window.
Note: For models designed in earlier releases, Embedded Coder software also supports
the ability to export functions from triggered subsystems. In general, the requirements
and limitations stated for exporting functions from function-call subsystems also apply to
exporting functions from triggered subsystems, with the following exceptions:
20-2
Export Function-Call Subsystems
• The section “Export Functions That Depend on Elapsed Time” on page 20-7 is
not applicable to exporting functions from triggered subsystems.
Additional Information
See the following in the Simulink documentation for additional information relating to
exporting function-call subsystems:
If you want to use Stateflow blocks to trigger exportable function-call subsystems, you
may also need information from “Interface with Simulink”.
For brevity, exported subsystem in this section means only an exported function-call
subsystem or an exported virtual subsystem that contains such subsystems. The
requirements listed do not necessarily apply to other types of exported subsystems.
These requirements apply to both exported function-call subsystems and exported virtual
subsystems that contain such subsystems.
20-3
20 Export Code Generated from Model to External Application
All blocks within an exported subsystem must support code generation. However, blocks
outside the subsystem need not support code generation unless they will be converted to
code in some other context.
Blocks Must Not Use Absolute Time
Certain blocks use absolute time. Blocks that use absolute time are not supported in
exported function-call subsystems. For a complete list of such blocks, see “Limitations on
the Use of Absolute Time” in the Simulink Coder documentation.
Blocks Must Not Depend on Elapsed Time
Certain blocks, like the Sine Wave block and Discrete Integrator block, depend on
elapsed time. If an exported function-call subsystem contains a block that depends on
elapsed time, the subsystem must specify periodic execution. See “Export Functions That
Depend on Elapsed Time” on page 20-7 in the Simulink Coder documentation.
Trigger Signals Require a Common Source
If more than one trigger signal crosses the boundary of an exported system, all of the
trigger signals must be periodic and originate from the same function-call initiator.
Trigger Signals Must Be Scalar
A trigger signal that crosses the boundary of an exported subsystem must be scalar.
Input and output data signals that do not act as triggers need not be scalar.
Data Signals Must Be Nonvirtual
A data signal that crosses the boundary of an exported system cannot be a virtual bus,
and cannot be implemented as a Goto-From connection. Every data signal crossing the
export boundary must be scalar, muxed, or a nonvirtual bus.
These requirements apply only to exported virtual subsystems that contain function-call
subsystems.
Virtual Subsystem Must Use Only Permissible Blocks
The top level of an exported virtual subsystem that contains function-call subsystem
blocks can contain only the following other types of blocks:
20-4
Export Function-Call Subsystems
These restrictions do not apply within function-call subsystems, whether or not they
appear in a virtual subsystem. They apply only at the top level of an exported virtual
subsystem that contains one or more function-call subsystems.
Constant Blocks Must Be Inlined
When a constant block appears at the top level of an exported virtual subsystem, the
containing model must check Inline parameters on the Optimization > Signals and
Parameters pane of the Configuration Parameters dialog box.
Constant Outputs Must Specify a Storage Class
When a constant signal drives an output port of an exported virtual subsystem, the
signal must specify a storage class.
General Workflow
1 Check that the subsystem to be exported satisfies the “Requirements for Exporting
Function-Call Subsystems” on page 20-3.
2 In the Configuration Parameters dialog box:
a On the Code Generation pane, specify an ERT code generation target such as
ert.tlc.
b If you want a SIL block with the generated code, go to the Verification pane
and, from the Create block drop-down list, select SIL.
c Click OK or Apply.
20-5
20 Export Code Generated from Model to External Application
3 Right-click the subsystem block and choose C/C++ Code > Export Functions from
the context menu.
The Build code for subsystem: Subsystem dialog box appears. This dialog
box is not specific to exporting function-call subsystems, and generating code does
not require entering information in the box.
4 Click Build.
The MATLAB Command Window displays messages similar to the code generation
sequence. Simulink generates code and places it in the working folder.
If you set Create block to SIL in step 2b, Simulink opens a new window that
contains an S-function block that represents the generated code. This block has the
same size, shape, and connectors as the original subsystem.
Code generation and optional block creation are now complete. You can test and use the
code and optional block as you could for generated ERT code and S-function block.
You can specify a custom name for the initialize function of your exported function as an
argument to the rtwbuild command. When used for this purpose, the command takes
the following form:
blockHandle = rtwbuild('subsystem', 'Mode', 'ExportFunctionCalls',..
’ExportFunctionInitializeFunctionName’, ’fcnname’)
where fcnname specifies the desired function name. For example, if you specify the name
'myinitfcn', the build process emits code similar to the following:
/* Model initialize function */
void myinitfcn(void){
...
}
You can enter a custom description for an exported function using the Block Properties
dialog box of an Inport block. To do this, go to the subsystem that is to be exported as
a function, right-click on the Inport block that drives the control port of the subsystem,
and select Properties. In the General tab, use the Description field to enter your
descriptive text. During function export, the text you enter is emitted to the generated
code in the header for the Inport block. For example, if you open the example program
20-6
Export Function-Call Subsystems
• Specify a storage class for every input signal and output signal that crosses the
boundary of the subsystem.
• For each function-call subsystem to be exported (whether directly or within a virtual
subsystem):
1 Right-click the subsystem and choose Block Parameters (Subsystem) from the
context menu.
2 Select the Code Generation tab and set the Function packaging parameter to
Auto.
3 Click OK or Apply.
When a block that depends on elapsed time exists in a function-call subsystem, the
subsystem cannot be exported unless it specifies periodic execution. To specify for this:
1 Right-click the Trigger block in the function-call subsystem and choose Block
Parameters from the context menu.
2 Specify periodic in the Sample time type field.
20-7
20 Export Code Generated from Model to External Application
3 Set the Sample time to the same granularity specified (directly or by inheritance) in
the function-call initiator.
4 Click OK or Apply.
The next figure shows the contents of Subsystem in the previous figure. The subsystem
contains two function-call subsystems, each driven by one of the signals input from the
top level.
20-8
Export Function-Call Subsystems
In the preceding model, the Stateflow chart can assert either of two scalar signals,
Toggle and Select.
• Asserting Toggle toggles the Boolean state of the function-call subsystem Toggle
Output Subsystem.
• Asserting Select causes the function-call subsystem Select Input Subsystem
to assign the value of DataIn1 or DataIn2 to its output signal. The value assigned
depends on the current state of Toggle Output Subsystem.
The following generated code implements the subsystem named Subsystem. The code
is typical for virtual subsystems that contain function-call subsystems. It specifies an
initialization function and a function for each contained subsystem, and would also
include functions to enable and disable subsystems if applicable.
#include "Subsystem.h"
#include "Subsystem_private.h"
/* Real-time model */
RT_MODEL_Subsystem Subsystem_M_;
RT_MODEL_Subsystem *Subsystem_M = &Subsystem_M_;
void Toggle_Init(void)
{
/* Initial conditions for function-call system: '<S1>/Toggle Output Subsystem' */
void Toggle(void)
{
/* Output and update for function-call system: '<S1>/Toggle Output Subsystem' */
20-9
20 Export Code Generated from Model to External Application
void Select(void)
{
/* Output and update for function-call system: '<S1>/Select Input Subsystem' */
void Subsystem_initialize(void)
{
/* initialize error status */
rtmSetErrorStatus(Subsystem_M, (const char_T *)0);
/* block I/O */
/* states (dwork) */
/* external inputs */
DataIn1 = 0.0;
DataIn2 = 0.0;
Toggle_Init();
}
void Subsystem_terminate(void)
{
/* (no terminate code required) */
}
20-10
Export Function-Call Subsystems
• Subsystem block parameters do not control the names of the files containing the
generated code. Such filenames begin with the name of the exported subsystem.
• Subsystem block parameters do not control the names of top-level functions in the
generated code. Each function name reflects the name of the signal that triggers the
function, or for an unnamed signal, the block from which the signal originates.
• The software cannot export reusable code for a function-call subsystem. The Code
interface packaging value Reusable function does not apply for a function-call
subsystem.
• The function-call subsystem export capability does not support C++ class code
interface packaging.
• The software supports a SIL or PIL block in Accelerator mode only if its function-call
initiator is noninlined in Accelerator mode. Examples of noninlined initiators include
Stateflow charts.
• The SIL block must be driven by a Level-2 S-function initiator block, such as a
Stateflow chart or the built-in Function-call Generator block.
• An asynchronous (sample-time) function-call system can be exported, but the software
does not support the SIL or PIL block wrapper for an asynchronous system.
• The software does not support MAT-file logging for exported function calls.
Specifications that enable MAT-file logging is ignored.
• The use of the TLC function LibIsFirstInit is deprecated for exported function
calls.
20-11
20 Export Code Generated from Model to External Application
(For more detailed information about the default calling interface for the model_step
function, see the model_step reference page.)
The Configure Model Functions button on the Interface pane provides you flexible
control over the model function prototypes that are generated for your model. Clicking
Configure Model Functions launches a Model Interface dialog box. Based on the
Function specification value you specify for your model function (supported values
include Default model initialize and step functions and Model specific
C prototypes), you can preview and modify the function prototypes. Once you validate
and apply your changes, you can generate code based on your function prototype
modifications.
For more information about using the Configure Model Functions button and the
Model Interface dialog box, see “Sample Procedure for Configuring Function Prototypes”
and the example model rtwdemo_fcnprotoctrl, which is preconfigured to demonstrate
function prototype control.
You can also control model function prototypes for nonvirtual subsystems, if you generate
subsystem code using right-click build. To launch the Model Interface for subsystem
dialog box, use the RTW.configSubsystemBuild function.
20-12
Control Generation of Function Prototypes
Right-click building the subsystem generates the step and initialization functions
according to the customizations you make. For more information, see “Configure
Function Prototypes for Nonvirtual Subsystems”.
20-13
20 Export Code Generated from Model to External Application
C++ class encapsulation also works for right-click builds of nonvirtual subsystems.
(For information on requirements that apply, see “Configure C++ Class Interfaces for
Nonvirtual Subsystems”.)
The general procedure for generating C++ class interfaces to model code is as follows:
1 Configure your model to use an ert.tlc system target file provided by MathWorks.
2 Select the C++ language for your model.
3 Select C++ class code interface packaging for your model.
4 Optionally, configure related C++ class interface settings for your model code, using
either a graphical user interface (GUI) or application programming interface (API).
5 Generate model code and examine the results.
To get started with an example, see “Simple Use of C++ Class Control”. For more
details about configuring C++ class interfaces for your model code, see “Customize C+
+ Class Interfaces Using Graphical Interfaces” and “Customize C++ Class Interfaces
Programmatically”. For limitations that apply, see “C++ Class Interface Control
Limitations”.
Note: For an example of C++ class code generation, see the example model
rtwdemo_cppclass.
20-14
21
21-2
What Is Code Replacement Customization?
Related Examples
• “Quick Start Library Development”
• “Develop a Code Replacement Library”
More About
• “What Is Code Replacement?”
• “Code You Can Replace From Simulink Models”
• “Code Replacement Libraries”
• “Code Replacement Terminology”
• “Code Replacement Customization Limitations”
21-3
21 Code Replacement Customization for Simulink Models
For information on how to explore functions and operators that a code replacement
library supports, see “Choose a Code Replacement Library” license and want to develop a
custom code replacement library, see Code Replacement Customization.
21-4
Code You Can Replace From Simulink Models
Function Data Type Support Scalar, Vector, Matrix Real, Complex Support
Support
acosd2 Floating point Scalar Real
Vector Complex
Matrix
acosh Floating point Scalar Real
Vector Complex input/complex output
Matrix Real input/complex output
acot2 Floating point Scalar Real
Vector Complex
Matrix
acotd2 Floating point Scalar Real
Vector Complex
Matrix
acoth2 Floating point Scalar Real
Vector Complex
Matrix
acsc2 Floating point Scalar Real
Vector Complex
Matrix
acscd2 Floating point Scalar Real
Vector Complex
Matrix
acsch2 Floating point Scalar Real
Vector Complex
Matrix
asec2 Floating point Scalar Real
Vector Complex
Matrix
asecd2 Floating point Scalar Real
Vector Complex
Matrix
asech2 Floating point Scalar Real
Vector Complex
Matrix
21-5
21 Code Replacement Customization for Simulink Models
Function Data Type Support Scalar, Vector, Matrix Real, Complex Support
Support
asin Floating point Scalar Real
Complex input/complex output
Real input/complex output
asind2 Floating point Scalar Real
Vector Complex
Matrix
asinh Floating point Scalar Real
Vector Complex input/complex output
Matrix Real input/complex output
atan Floating point Scalar Real
Vector Complex input/complex output
Matrix Real input/complex output
atan2 Floating point Scalar Real
Vector
Matrix
atan2d2 Floating point Scalar Real
Vector
Matrix
atand2 Floating point Scalar Real
Vector Complex
Matrix
atanh Floating point Scalar Real
Vector Complex input/complex output
Matrix Real input/complex output
ceil • Floating-point • Floating-point • Floating-point
• Scalar • Scalar • Scalar
cos 3 Floating point Scalar Real
Vector Complex input/complex output
Matrix Real input/complex output
cosd2 Floating point Scalar Real
Vector Complex
Matrix
21-6
Code You Can Replace From Simulink Models
Function Data Type Support Scalar, Vector, Matrix Real, Complex Support
Support
cosh Floating point Scalar Real
Vector Complex input/complex output
Matrix Real input/complex output
cot2 Floating point Scalar Real
Vector Complex
Matrix
cotd2 Floating point Scalar Real
Vector Complex
Matrix
coth2 Floating point Scalar Real
Vector Complex
Matrix
csc2 Floating point Scalar Real
Vector Complex
Matrix
cscd2 Floating point Scalar Real
Vector Complex
Matrix
csch2 Floating point Scalar Real
Vector Complex
Matrix
exactrSqrt Integer Scalar Real
Floating point
exp Floating point Scalar Real
Vector
Matrix
fix Floating point Scalar Real
floor • Floating-point • Floating-point • Floating-point
• Scalar • Scalar • Scalar
fmod4 Floating point Scalar Real
frexp Floating point Scalar Real
21-7
21 Code Replacement Customization for Simulink Models
Function Data Type Support Scalar, Vector, Matrix Real, Complex Support
Support
hypot Floating point Scalar Real
Vector
Matrix
ldexp Floating point Scalar Real
ln Floating point Scalar Real
log Floating point Scalar Real
Vector
Matrix
log10 Floating point Scalar Real
Vector
Matrix
log22 Floating point Scalar Real
Vector Complex
Matrix
max Integer Scalar Real
Floating point
Fixed point
min Integer Scalar Real
Floating point
Fixed point
mod Integer Scalar Real
Floating point Vector
Matrix
pow Floating point Scalar Real
Vector
Matrix
rem Floating point Scalar Real
Vector
Matrix
round Floating point Scalar Real
21-8
Code You Can Replace From Simulink Models
Function Data Type Support Scalar, Vector, Matrix Real, Complex Support
Support
rSqrt Integer Scalar Real
Floating point Vector
Matrix
saturate Integer Scalar Real
Floating point Vector
Fixed point Matrix
sec2 Floating point Scalar Real
Vector Complex
Matrix
secd2 Floating point Scalar Real
Vector Complex
Matrix
sech2 Floating point Scalar Real
Vector Complex
Matrix
sign Integer Scalar Real
Floating point Vector
Fixed point Matrix
signPow Floating point Scalar Real
Vector
Matrix
sin3 Floating point Scalar Real
Vector Complex input/complex output
Matrix Real input/complex output
sincos3 Floating point Scalar Real
Vector Complex input/complex output
Matrix Real input/complex output
sind2 Floating point Scalar Real
Vector Complex
Matrix
sinh Floating point Scalar Real
Vector Complex input/complex output
Matrix Real input/complex output
21-9
21 Code Replacement Customization for Simulink Models
Function Data Type Support Scalar, Vector, Matrix Real, Complex Support
Support
sqrt Integer Scalar Real
Floating point Vector
Fixed point Matrix
tan Floating point Scalar Real
Vector Complex input/complex output
Matrix Real input/complex output
tand2 Floating point Scalar Real
Vector Complex
Matrix
tanh Floating point Scalar Real
Vector Complex input/complex output
Matrix Real input/complex output
1
Wrap on integer overflow only. Clear block parameter Saturate on integer overflow.
2
Only when used with the MATLAB Function block.
3
Supports the CORDIC approximation method.
4
Stateflow support only.
Function Data Type Support Scalar, Vector, Matrix Real, Complex Support
Support
abs1 Integer Scalar Real
Floating point
acos2 Floating point Scalar Real
Vector Complex
Matrix Complex input/complex
output
21-10
Code You Can Replace From Simulink Models
Function Data Type Support Scalar, Vector, Matrix Real, Complex Support
Support
Real input/complex output
acosd3 Floating point Scalar Real
Vector Complex
Matrix
acot3 Floating point Scalar Real
Vector Complex
Matrix
acotd3 Floating point Scalar Real
Vector Complex
Matrix
acoth3,5 Floating point Scalar Real
Vector Complex
Matrix
acsc3 Floating point Scalar Real
Vector Complex
Matrix
acscd3 Floating point Scalar Real
Vector Complex
Matrix
acsch3 Floating point Scalar Real
Vector Complex
Matrix
asec3 Floating point Scalar Real
Vector Complex
Matrix
asecd3 Floating point Scalar Real
Vector Complex
Matrix
asech3 Floating point Scalar Real
Vector Complex
Matrix
21-11
21 Code Replacement Customization for Simulink Models
Function Data Type Support Scalar, Vector, Matrix Real, Complex Support
Support
asin2 Floating point Scalar Real
Vector Complex
Matrix Complex input/complex
output
Real input/complex output
asind3 Floating point Scalar Real
Vector Complex
Matrix
atan2 Floating point Scalar Real
Vector Complex
Matrix Complex input/complex
output
Real input/complex output
atan22 Floating point Scalar Real
Vector
Matrix
atan2d3 Floating point Scalar Real
Vector
Matrix
atand3 Floating point Scalar Real
Vector Complex
Matrix
ceil • Floating-point • Floating-point • Floating-point
• Scalar • Scalar • Scalar
cos 3 Floating point Scalar Real
Vector Complex
Matrix Complex input/complex
output
Real input/complex output
cosd3 Floating point Scalar Real
Vector Complex
Matrix
21-12
Code You Can Replace From Simulink Models
Function Data Type Support Scalar, Vector, Matrix Real, Complex Support
Support
cosh2 Floating point Scalar Real
Vector Complex
Matrix Complex input/complex
output
Real input/complex output
cot3 Floating point Scalar Real
Vector Complex
Matrix
cotd3 Floating point Scalar Real
Vector Complex
Matrix
coth3 Floating point Scalar Real
Vector Complex
Matrix
csc3 Floating point Scalar Real
Vector Complex
Matrix
cscd3 Floating point Scalar Real
Vector Complex
Matrix
csch3 Floating point Scalar Real
Vector Complex
Matrix
exp Floating point Scalar Real
floor • Floating-point • Floating-point • Floating-point
• Scalar • Scalar • Scalar
fmod Floating point Scalar Real
hypot 3 Floating point Scalar Real
Vector
Matrix
ldexp Floating point Scalar Real
21-13
21 Code Replacement Customization for Simulink Models
Function Data Type Support Scalar, Vector, Matrix Real, Complex Support
Support
log2 Floating point Scalar Real
Vector Complex
Matrix
log102 Floating point Scalar Real
Vector Complex
Matrix
log23 Floating point Scalar Real
Vector Complex
Matrix
max Integer Scalar Real
Floating point
min Integer Scalar Real
Floating point
pow Floating point Scalar Real
sec3 Floating point Scalar Real
Vector Complex
Matrix
secd3 Floating point Scalar Real
Vector Complex
Matrix
sech3 Floating point Scalar Real
Vector Complex
Matrix
sin2 Floating point Scalar Real
Vector Complex
Matrix Complex input/complex
output
Real input/complex output
sind3 Floating point Scalar Real
Vector Complex
Matrix
21-14
Code You Can Replace From Simulink Models
Function Data Type Support Scalar, Vector, Matrix Real, Complex Support
Support
sinh2 Floating point Scalar Real
Vector Complex
Matrix Complex input/complex
output
Real input/complex output
sqrt Floating point Scalar Real
tan 2 Floating point Scalar Real
Vector Complex
Matrix Complex input/complex
output
Real input/complex output
tand3 Floating point Scalar Real
Vector Complex
Matrix
tanh2 Floating point Scalar Real
Vector Complex
Matrix Complex input/complex
output
Real input/complex output
1
Wrap on integer overflow only.
2
For models involving vectors or matrices, the code generator replaces only functions coded in the
MATLAB action language.
3
The code generator replaces only functions coded in the MATLAB action language.
Memory Functions
Depending on code replacement libraries available in your development environment,
you can configure the code generator to replace instances of the following memory
functions with application-specific implementations.
Function Data Type Support Scalar, Vector, Matrix Real, Complex Support
Support
memcmp Void pointer (void*) Scalar Real
21-15
21 Code Replacement Customization for Simulink Models
Function Data Type Support Scalar, Vector, Matrix Real, Complex Support
Support
Vector Complex
Matrix
memcpy Void pointer (void*) Scalar Real
Vector Complex
Matrix
memset Void pointer (void*) Scalar Real
Vector Complex
Matrix
memset2zero Void pointer (void*) Scalar Real
Vector Complex
Matrix
Some target processors provide optimized functions to set memory to zero. Use the code
replacement library programming interface to replace the memset2zero function with
more efficient target-specific functions.
Nonfinite Functions
Depending on code replacement libraries available in your development environment,
you can configure the code generator to replace instances of the following nonfinite
functions with application-specific implementations.
21-16
Code You Can Replace From Simulink Models
• Before code for a data transfer between tasks enters the critical section, mutex
lock or semaphore wait function calls to reserve a critical section of code.
• After code for a data transfer between tasks finishes executing the critical section,
mutex unlock or semaphore post function calls to release the critical section of
code.
• In model termination code, an optional destroy function call to explicitly delete the
mutex or semaphore.
Function Key
Mutex Destroy RTW_MUTEX_DESTROY
Mutex Init RTW_MUTEX_INIT
Mutex Lock RTW_MUTEX_LOCK
Mutex Unlock RTW_MUTEX_UNLOCK
Semaphore Destroy RTW_SEM_DESTROY
Semaphore Init RTW_SEM_INIT
Semaphore Post RTW_SEM_POST
Semaphore Wait RTW_SEM_WAIT
21-17
21 Code Replacement Customization for Simulink Models
Operators
When generating C/C++ code from a Simulink model, depending on code replacement
libraries available in your development environment, you can configure the code
generator to replace instances of the following operators with application-specific
implementations.
21-18
Code You Can Replace From Simulink Models
21-19
21 Code Replacement Customization for Simulink Models
21-20
Code You Can Replace From Simulink Models
Related Examples
• “Develop a Code Replacement Library”
• “Quick Start Library Development”
• “Choose a Code Replacement Library”
More About
• “What Is Code Replacement?”
• “What Is Code Replacement Customization?”
• “Code Replacement Libraries”
• “Code Replacement Terminology”
• “Code Replacement Customization Limitations”
21-21
21 Code Replacement Customization for Simulink Models
1 Creates and partially populates a code replacement entry object with the function or
operator name or key and conceptual arguments.
2 Uses the entry object to query the configured code replacement library for a
conceptual representation match. The code generator searches the tables in a code
replacement library for a match in the order that the tables appear in the library.
When searching for a match, the code generator takes into account:
When the code generator encounters a call site for a function or operator, it:
1 Creates and partially populates a code replacement entry object with the function or
operator name or key and conceptual arguments.
2 Uses the entry object to query the configured code replacement library for a
conceptual representation match. The code generator searches the tables in a code
replacement library for a match in the order that the tables appear in the library.
When searching for a match, the code generator takes into account:
21-22
Code Replacement Match and Replacement Process
Related Examples
• “Customize Matching and Replacement Process for Functions”
• “Customize Matching and Replacement Process for Operators”
More About
• “Code Replacement Libraries”
• “Code Replacement Terminology”
21-23
21 Code Replacement Customization for Simulink Models
• Software-in-the-loop (SIL)
• Processor-in-the-loop (PIL)
• Model reference parameters
• Exported functions in Stateflow charts
• Data alignment is not honored in code generation for shared utilities if the
replacement would impose alignment requirements on the shared utility interface
arguments. Under these conditions, replacement does not occur. Replacement is
allowed if the registered data alignment type specification supports alignment of
local variables, and the replacement involves only local variables.
• For Simulink.Bus:
21-24
Code Replacement Customization Limitations
Related Examples
• “Review and Test Code Replacements”
• “Specify Build Information for Replacement Code”
• “Data Alignment for Code Replacement”
• “Replace MATLAB Functions with Custom Code Using coder.replace”
• “Develop a Code Replacement Library”
• “Quick Start Library Development”
More About
• “Code Replacement Libraries”
• “Code Replacement Terminology”
21-25
21 Code Replacement Customization for Simulink Models
Related Examples
• “Replace MATLAB Functions with Custom Code Using coder.replace”
• “Replace MATLAB Functions Specified in MATLAB Function Blocks”
More About
• “What Is Code Replacement?”
• “What Is Code Replacement Customization?”
• “Code You Can Replace From Simulink Models”
• “Code Replacement Libraries”
• “Code Replacement Terminology”
• “Code Replacement Customization Limitations”
21-26
Quick Start Library Development
Prerequisites
• MATLAB
• Simulink
• Simulink Coder
• Embedded Coder
For instructions on installing MathWorks products, see the “Installation Guide”. If you
have installed MATLAB and want to see what other MathWorks products are installed,
in the Command Window, enter ver.
1 In the Code Replacement Tool window, select File > New table.
2 In the right pane, name the table crl_table_sinfcn and click Apply. Later, when
you save the table, the tool saves it with the file name crl_table_sinfcn.m.
21-27
21 Code Replacement Customization for Simulink Models
Create a table entry that maps a sin function with double input and double output to
a custom implementation function.
1 In the left pane, select table crl_table_sinfcn. Then, select File > New entry >
Function. The new entry appears in the middle pane, initially without a name.
2 In the middle pane, select the new entry.
3 In the right pane, on the Mapping Information tab, from the Function menu,
select sin.
4 Leave Algorithm set to Unspecified, and leave parameters in the Conceptual
function group set to default values.
5 In the Replacement function group, name the replacement function sin_dbl.
6 Leave the remaining parameters in the Replacement function group set to default
values.
21-28
Quick Start Library Development
7 Click Apply. The tool updates the Function signature preview to reflect the
specified replacement function name.
8 Scroll to the bottom of the Mapping Information tab and click Validate entry.
The tool validates your entry.
21-29
21 Code Replacement Customization for Simulink Models
21-30
Quick Start Library Development
1 On the Build Information tab, for the Implementation header file parameter,
enter sin_dbl.h.
2 Leave the remaining parameters set to default values.
3 Click Apply.
4 Optionally, you can revalidate the entry. Return to the Mapping Information tab
and click Validate entry.
Create an entry that maps a sin function with single input and double output to
a custom implementation function named sin_sgl. Create the entry by copying and
pasting the sin_dbl entry.
21-31
21 Code Replacement Customization for Simulink Models
2 If the tool reports errors, fix them, and rerun the validation. Repeat fixing and
validating errors until the tool does not report errors. The following figure shows a
validation report.
Save the code replacement table to a MATLAB file in your working folder. Select File >
Save table. By default, the tool uses the table name to name the file. For this example,
the tool saves the table in the file crl_table_sinfcn.m.
Consider reviewing the MATLAB code for your code replacement table definition. After
using the tool to create an initial version of a table definition file, you can update,
enhance, or copy the file in a text editor.
To review it, in MATLAB or another text editor, open the file crl_table_sinfcn.m.
Before you can use your code replacement table, you must register it as part of a code
replacement library. Use the Code Replacement Tool to generate a registration file.
1 In the Code Replacement Tool, select File > Generate registration file.
2 In the Generate registration file dialog box, edit the dialog box fields to match the
following figure, and then click OK.
21-32
Quick Start Library Development
3 In the Select location dialog box, specify a location for the registration file. The
location must be on the MATLAB path or in the current working folder. Save the file.
The tool saves the file as rtwTargetInfo.m.
sl_refresh_customizations
Apply your code replacement library. Verify that the code generator makes code
replacements that you expect.
1 Check for errors. At the command line, invoke the table definition file. For example:
tbl = crl_table_sinfcn
tbl =
Version: '1.0'
ReservedSymbols: []
StringResolutionMap: []
AllEntries: [2x1 RTW.TflCFunctionEntry]
EnableTrace: 1
If an error exists in the definition file, the invocation triggers a message. Fix the
error and try again.
2 Use the Code Replacement Viewer to check your code replacement entries. For
example:
In the viewer, select entries in your table and verify that the content is what you
expect. The viewer can help you detect issues such as:
21-33
21 Code Replacement Customization for Simulink Models
4 Open the model and configure it for code generation with an Embedded Coder (ERT-
based) target.
5 See whether your library is listed as an available option for the Code Generation
> Interface > Code replacement library model configuration parameter. If it is,
select it.
If it is not listed, open the registration file, rtwTargetInfo.m. See whether you
entered the correct code replacement table name when you created the file. If you
hover the cursor over the selected library, a tool tip appears. This tip contains
information derived from your code replacement library registration file, such as the
library description and the list of tables it contains.
6 Configure the code generation report for code replacement analysis by setting the
following parameters:
• On the Code Generation > Report pane, select Create code generation
report, Open report automatically, Code-to-model, Model-to-code, and
Summarize which blocks triggered code replacements.
• On the Code Generation > Comments pane, select Include comments,
Simulink block / Stateflow object comments, and Simulink block
descriptions.
7 Configure the model to generate code only. Before you build an executable, confirm
that the code generator is replacing code as expected.
8 Generate code for the model.
9 Review code replacement results in the Code Replacement Report section of the code
generation report.
21-34
Quick Start Library Development
The report indicates that the code generator found a match and applied the
replacement code for the function sin_dbl.
10 Review the code replacements. In the model window, right-click the Trigonometric
Function block. Select C/C++ Code > Navigate to C/C++ Code. The code
generation report opens and highlights the code replacement in my_sin_func.c. In
this case, the code generator replaced sin with sin_dbl.
21-35
21 Code Replacement Customization for Simulink Models
Related Examples
• “Develop a Code Replacement Library”
More About
• “What Is Code Replacement?”
• “What Is Code Replacement Customization?”
• “Code You Can Replace From Simulink Models”
• “Code Replacement Libraries”
• “Code Replacement Terminology”
• “Code Replacement Customization Limitations”
21-36
Identify Code Replacement Requirements
In this section...
“Mapping Information Requirements” on page 21-37
“Build Information Requirements” on page 21-38
“Registration Information Requirements” on page 21-38
• Math operation
• Function
• BLAS operation
• CBLAS operation
• Net slope fixed-point operation
• Semaphore or mutex functions
• Do you want to change the inline or nonfinite behavior for functions?
• What specific functions and operations do you want to replace?
• What input and output arguments does the function or operator that you are
replacing take? For each argument, what is the data type, complexity, and
dimensionality?
• What does the prototype for your replacement code look like?
21-37
21 Code Replacement Customization for Simulink Models
• What is the data type, complexity, and dimensionality of each argument and
return value?
21-38
Identify Code Replacement Requirements
general TI device library as the base library for a more specific TI C28x device
library.
• Do you need to specify data alignment for the library? What data alignments are
required? For each specification, what type of alignment is required and for what
programming language?
Related Examples
• “Develop a Code Replacement Library”
• “Define Code Replacement Mappings”
• “Specify Build Information for Replacement Code”
• “Register Code Replacement Mappings”
• “Review and Test Code Replacements”
• “Quick Start Library Development”
More About
• “What Is Code Replacement?”
• “What Is Code Replacement Customization?”
• “Code You Can Replace From Simulink Models”
• “Code Replacement Libraries”
• “Code Replacement Terminology”
• “Code Replacement Customization Limitations”
21-39
21 Code Replacement Customization for Simulink Models
• Common entries
• Entries for TI devices
• Entries for TI C6xx devices
• Entries specific to the TI C67x device
• If support files, such as header files, additional source files, and dynamically linked
libraries are not in your current working folder, note their location. You need to
specify the paths for such files.
Related Examples
• “Develop a Code Replacement Library”
• “Define Code Replacement Mappings”
• “Specify Build Information for Replacement Code”
• “Register Code Replacement Mappings”
• “Review and Test Code Replacements”
• “Quick Start Library Development”
More About
• “What Is Code Replacement?”
21-40
Prepare for Code Replacement Library Development
21-41
21 Code Replacement Customization for Simulink Models
The following table lists situations to help you decide when to use each approach.
Situation Approach
Defining mappings for the first Code Replacement Tool.
time.
Rapid prototyping mappings. Code Replacement Tool to quickly generate, register,
and test mappings.
Developing a mapping as a Code Replacement Tool to generate definition code
template or starting point for that you can copy and modify.
defining similar mappings.
Modifying a registration file, MATLAB Editor to update the programming interface
including copying and pasting directly.
content.
Defining mappings that specify Programming interface.
attributes not available from
the Code Replacement Tool
(for example, sets of algorithm
parameters).
21-42
Define Code Replacement Mappings
The Custom button is available only for ERT-based targets. Although an Embedded
Coder license is not required to create a custom code replacement library, you must
have an Embedded Coder license to use a such a library.
By default, the tool displays, left to right, a root pane, a list pane, and a dialog pane. You
can manipulate the display:
• Drag boundaries to widen, narrow, shorten, or lengthen panes, and to resize table
columns.
• Select View > Show dialog pane to hide or display the rightmost pane.
• Click a table column heading to sort the table based on contents of the selected
column.
• Right-click a table column heading and select Hide to remove the column from the
display. (You cannot hide the Name column.)
1 In the Code Replacement Tool window, select File > New table.
21-43
21 Code Replacement Customization for Simulink Models
2 In the right pane, name the table and click Apply. Later, when you save the table,
the tool uses the table name that you specify to name the file. For example, if you
enter the name my_sinfcn, the tool names the file my_sinfcn.m.
Create one or more table entries. Each entry maps the conceptual representation of a
function or operator to your implementation representation. The information that you
enter depends on the type of entry you create. You must enter the following information:
1 In the left pane, select the table to which you want to add the entry.
2 Select File > New entry > entry-type, where entry-type is one of:
• Math Operation
• Function
• BLAS Operation
• CBLAS Operation
• Net Slope Fixed Point Operation
• Semaphore entry
• Customization entry
The new entry appears in the middle pane, initially without a name.
3 In the middle pane, select the new entry.
4 In the right pane, on the Mapping Information tab, from the Function or
Operation menu, select the function or operation that you want the code generator
to replace. Regardless of the entry type, you must make a selection from this menu.
Your selection determines what other information you specify.
With the exception of customization entries, you also specify information for your
replacement function prototype. You can also specify implementation attributes,
such as the rounding modes to apply.
5 If prompted, specify additional entry information that you want the code generator
to use when searching for a match. For example, when you select an addition or
subtraction operation, the tool prompts you to specify an algorithm (Cast before
operation or Cast after operation).
6 Review the conceptual argument information that the tool populates for the function
or operation. Conceptual input and output arguments represent arguments for
21-44
Define Code Replacement Mappings
If you do not want the data types for your implementation to be the same as the
conceptual argument types, clear the Make the conceptual and implementation
argument types the same check box. For example, most ANSI-C functions
operate on and return double data. Clear the check box if want to map a conceptual
representation of the function, such as sin, which specifies an argument and
return value of type single (single sin(single)), to an implementation
representation that specifies an argument and return value of type double (double
sin(double). In this case, the code generator produces the following code:
y = (single) sin(u1);
If you select Custom for a function entry, specify only conceptual argument
information.
7 Specify the name and argument information for your replacement function. As you
enter the information and click Apply, the tool updates the Function signature
preview.
8 Specify additional implementation attributes that apply. For example, depending on
the type and name of the entry that you specify, the tool prompts you to specify:
The Code Replacement Tool provides a way to validate the syntax of code replacement
tables and table entries as you define them. If the tool finds validation errors, you can
address them and retry the validation. Repeat the process until the tool does not report
errors.
To... Do...
Validate table entries Select an entry, scroll to the bottom of the Mapping
Information tab, and click Validate entry.
21-45
21 Code Replacement Customization for Simulink Models
To... Do...
Alternatively, select one or more entries, right-click,
and select Validate entries.
Validate a table Select the table. Then, select Actions > Validate
table.
Save a Table
If you open multiple tables, you can manage the tables together. For example, use the
tool to:
21-46
Define Code Replacement Mappings
1 Create a table definition file that contains a function definition. For example:
function hTable = crl_table_sinfcn()
2 Within the function body, create the table by calling the function RTW.TflTable.
hTable = RTW.TflTable;
For each function or operator that you want the code generator to replace, map
a conceptual representation of the function or operator to an implementation
representation as a table entry.
1 Within the body of a table definition file, create a code replacement entry object. Call
one of the following functions:
21-47
21 Code Replacement Customization for Simulink Models
For example:
hEnt = RTW.TflCFunctionEntry;
You can combine steps of creating the entry, setting entry parameters, creating
conceptual and implementation arguments, and adding the entry to a table with a
single function call to registerCFunctionEntry, registerCPPFunctionEntry, or
registerCPromotableMacroEntry if you are creating an entry for a function and the
function implementation meets the following criteria:
• Implementation argument names and order match the names and order of
corresponding conceptual arguments.
• Input arguments are of the same type.
• The return and input argument names follow the code generator’s default naming
conventions:
For example:
Set entry parameters, such as the priority, algorithm information, and implementation
(replacement) function name. Call the function listed in the following table for the entry
type that you created.
21-48
Define Code Replacement Mappings
To see a list of the parameters that you can set, at the command line, create a new entry
and omit the semicolon at the end of the command. For example:
hEnt = RTW.TflCFunctionEntry
hEnt =
21-49
21 Code Replacement Customization for Simulink Models
RoundingModes: {'RTW_ROUND_UNSPECIFIED'}
TypeConversionMode: 'RTW_EXPLICIT_CONVERSION'
AcceptExprInput: 1
SideEffects: 0
UsageCount: 0
RecordedUsageCount: 0
Description: ''
StoreFcnReturnInLocalVar: 0
TraceManager: [1x1 RTW.TflTraceManager]
ans =
HeaderFile: ''
SourceFile: ''
HeaderPath: ''
SourcePath: ''
Return: []
StructFieldMap: []
Name: ''
Arguments: [0x1 handle]
ArgumentDescriptor: []
For example, to set entry parameters for the sin function and name your replacement
function sin_dbl, use the following function call:
setTflCFunctionEntryParameters(hEnt, ...
'Key', 'sin', ...
'ImplementationName', 'sin_dbl');
Create conceptual arguments and add them to the entry’s array of conceptual arguments.
21-50
Define Code Replacement Mappings
1 Identify whether the argument is for input or output, the name, and data type. If you
do not know what arguments to specify for a supported function or operation, use the
Code Replacement Tool to find them. For example, to find the conceptual arguments
for the sin function, open the tool, create a table, create a function entry, and in the
Function menu select sin.
2 Create and add the conceptual argument to an entry. You can choose a method from
the methods listed in this table.
If Then
You want simpler code or Call the function createAndAddConceptualArg. For
want to explicitly specify example:
whether the argument
is scalar or nonscalar createAndAddConceptualArg(hEnt, ...
(vector or matrix).
'RTW.TflArgNumeric', ...
'Name', 'y1',...
'IOType', 'RTW_IO_OUTPUT',...
'DataTypeMode', 'double');
The following code shows the conceptual output and input argument definitions for the
sin function:
% Conceptual Args
21-51
21 Code Replacement Customization for Simulink Models
Create implementation arguments for the C or C++ replacement function and add them
to the entry.
• When replacing code, the code generator uses the argument names to determine how
it passes data to the implementation function.
• For function replacements, the order of implementation argument names must match
the order of the conceptual argument names.
• For operator replacements, the order of implementation argument names do not
have to match the order of the conceptual argument names. For example, for an
operator replacement for addition, y1=u1+u2, the conceptual arguments are y1, u1,
and u2, in that order. If the signature of your implementation function is t myAdd(t
u2, t u1), where t is a valid C type, based on the argument name matches, the
code generator passes the value of the first conceptual argument, u1, to the second
implementation argument of myAdd. The code generator passes the value of the
second conceptual argument, u2, to the first implementation argument of myAdd.
• For operator replacements, you can remap operator output arguments to
implementation function input arguments.
1 Identify whether the argument is for input or output, the name, and the data type.
2 Create and add the implementation argument to an entry. You can choose a method
from the methods listed in this table.
If Then
You want to populate Call the function
implementation copyConceptualArgsToImplementation. For example:
arguments as copies
of previously created copyConceptualArgsToImplementation(hEnt);
matching conceptual
arguments
21-52
Define Code Replacement Mappings
If Then
You want to create and Call functions createAndSetCImplementationReturn
add implementation andcreateAndAddImplementationArg . For example:
arguments individually,
or vary argument createAndSetCImplementationReturn(hEnt,
attributes, while 'RTW.TflArgNumeric', ...
'Name', 'y1', ...
maintaining conceptual 'IOType', 'RTW_IO_OUTPUT', ...
argument order 'IsSigned', true, ...
'WordLength', 32, ...
'FractionLength', 0);
createAndAddImplementationArg(op_entry,
'RTW.TflArgNumeric',...
'Name', 'u1', ...
'IOType', 'RTW_IO_INPUT',...
'IsSigned', true,...
'WordLength', 32, ...
'FractionLength', 0 );
21-53
21 Code Replacement Customization for Simulink Models
If Then
You want to minimize Create the argument with a call to the function
the amount of code, getTflArgFromString. Then, use the convenience
or specify constant method setReturn or addArgument to specify whether
arguments to pass to an argument is a return value or argument and to add
the implementation the argument to the entry’s array of implementation
function arguments. For example:
arg = getTflArgFromString(hEnt, 'y1','double');
arg.IOType = 'RTW_IO_OUTPUT';
hEnt.Implementation.setReturn(arg);
21-54
Define Code Replacement Mappings
The following code shows the implementation output and input argument definitions
for the sin function:
% Implementation Args
arg = hEnt.getTflArgFromString('y1','double');
arg.IOType = 'RTW_IO_OUTPUT';
hEnt.Implementation.setReturn(arg);
arg = hEnt.getTflArgFromString('u1','double');
hEnt.Implementation.addArgument(arg);
addEntry(hTable, hEnt);
Validate an Entry
After you create or modify a code replacement table entry, validate it by invoking it at
the MATLAB command line. For example:
hTbl = crl_table_sinfcn
hTbl =
RTW.TflTable
Version: '1.0'
AllEntries: [2x1 RTW.TflCFunctionEntry]
ReservedSymbols: []
StringResolutionMap: []
If the table includes errors, MATLAB reports them. The following examples shows how
MATLAB reports a typo in a data type name:
hTbl = crl_table_sinfcn
21-55
21 Code Replacement Customization for Simulink Models
Save a Table
Save the table definition file. Use the name of the table definition function to name the
file, for example, crl_table_sinfcn.m.
Related Examples
• “Identify Code Replacement Requirements”
• “Prepare for Code Replacement Library Development”
• “Specify Build Information for Replacement Code”
• “Register Code Replacement Mappings”
• “Develop a Code Replacement Library”
• “Quick Start Library Development”
• “Math Function Code Replacement”
• “Memory Function Code Replacement”
• “Nonfinite Function Code Replacement”
• “Semaphore and Mutex Function Replacement”
• “Algorithm-Based Code Replacement”
• “Lookup Table Function Code Replacement”
• “Data Alignment for Code Replacement”
• “Replace MATLAB Functions with Custom Code Using coder.replace”
• “Replace MATLAB Functions Specified in MATLAB Function Blocks”
• “Customize Matching and Replacement Process for Functions”
• “Scalar Operator Code Replacement”
• “Addition and Subtraction Operator Code Replacement”
• “Small Matrix Operation to Processor Code Replacement”
• “Matrix Multiplication Operation to MathWorks BLAS Code Replacement”
• “Matrix Multiplication Operation to ANSI/ISO C BLAS Code Replacement”
• “Remap Operator Output to Function Input”
• “Customize Matching and Replacement Process for Operators”
• “Fixed-Point Operator Code Replacement”
• “Binary-Point-Only Scaling Code Replacement”
21-56
Define Code Replacement Mappings
More About
• “Code You Can Replace From Simulink Models”
• “Code Replacement Libraries”
• “Code Replacement Terminology”
• “Code Replacement Customization Limitations”
21-57
21 Code Replacement Customization for Simulink Models
The following table lists situations to help you decide when to use each approach.
Situation Approach
Creating code replacement Code Replacement Tool.
entries for the first time.
You used the Code Replacement Code Replacement Tool to quickly specify the build
Tool to create the entries for information.
which the build information
applies.
Rapid prototyping entries. Code Replacement Tool to quickly generate, register,
and test entries.
21-58
Specify Build Information for Replacement Code
Situation Approach
Developing an entry to use as Code Replacement Tool to generate entry code that
a template or starting point for you can copy and modify.
defining similar entries.
Modifying existing mappings. MATLAB Editor to update the programming interface
directly.
• If you use the programming interface, paths that you specify can include tokens.
A token is a variable defined as a string or cell array of strings in the MATLAB
workspace that you enclose with dollar signs ($variable$). The code generator
evaluates and replaces a token with the defined value. For example, consider the
path $myfolder$\folder1, where myfolder is a string variable defined in the
MATLAB workspace as 'd:\work\source\module1'. The code generator generates
the custom path as d:\work\source\module1\folder1.
• If an entry uses header, source, or object files that reside in a folder other than the
build folder, you must copy the files to the build folder before the code generator can
build the code. The Code Replacement Tool and programming information provide a
way to specify this copy operation.
21-59
21 Code Replacement Customization for Simulink Models
Field Specify
Implementation header file File name and extension for the header file
the code generator needs to generate the
replacement code. For example, sin_dbl.h.
Implementation source file File name and extension for the C or C++ source
file the code generator needs to generate the
replacement code. For example, sin_dbl.c.
Additional header files/include Paths and file names for additional header
paths files the code generator needs to generate
the replacement code. For example, C:\libs
\headerFiles and C:\libs\headerFiles
\common.h.
Additional source files/ paths Paths and file names for additional source
files the code generator needs to generate
the replacement code. For example, C:
\libs\srcFiles and C:\libs\srcFiles
\common.c.
Additional object files/ paths Paths and file names for additional object files
the linker needs to build the replacement code.
For example, C:\libs\objFiles and C:
\libs\objFiles\common.obj.
Additional link flags Flags the linker needs to generate an executable
file for the replacement code.
Additional compile flags Flags the compiler needs to generate object code
for the replacement code.
Copy files to build directory Whether the code generator needs to copy
header, source, or object files from an external
location to the build folder before building the
replacement code.
6 Click Apply.
7 Select the Mapping Information tab. Scroll to the bottom of that table and click
Validate entry. The tool validates the changes that you made to the entry.
8 Save the table that includes the entry that you just modified.
21-60
Specify Build Information for Replacement Code
1 Identify or create the code replacement entry that you want to specify the build
information.
2 Determine what information to specify.
3 Specify your build information.
Specify Action
Implementation Use one of the following:
header file
• Set properties ImplementationHeaderFile
and ImplementationHeaderPath in a call
to setTflCFunctionEntryParameters,
setTflCOperationEntryParameters, or
setTflCSemaphoreEntryParameters. For example:
setTflCFunctionEntryParameters(hEnt, ...
'ImplementationHeaderFile', 'sin_dbl.h', ...
'ImplementationHeaderPath', 'D:/lib/headerFiles'
'Key', 'sin', ...
'ImplementationName', 'sin_dbl');
• Set argument headerFile in a call to
registerCFunctionEntry, registerCPPFunctionEntry, or
registerCPromotableMacroEntry
Implementation Set properties ImplementationSourceFile
source file and ImplementationSourcePath in a call
to setTflCFunctionEntryParameters,
setTflCOperationEntryParameters, or
setTflCSemaphoreEntryParameters. For example:
setTflCFunctionEntryParameters(hEnt, ...
'ImplementationHeaderFile', 'sin_dbl.c', ...
21-61
21 Code Replacement Customization for Simulink Models
Specify Action
'ImplementationHeaderPath', 'D:/lib/sourceFiles'
'Key', 'sin', ...
'ImplementationName', 'sin_dbl');
Additional header For each file, specify the file name and path in calls to the functions
files/include paths addAdditionalHeaderFile and addAdditionalIncludePath. For
example:
libdir = fullfile('$(MATLAB_ROOT)','..', '..', 'lib');
hEnt = RTW.TflCFunctionEntry;
addAdditionalHeaderFile(hEnt, 'common.h');
addAdditionalIncludePath(hEnt, fullfile(libdir, 'include'));
Additional source For each file, specify the file name and path in calls to the functions
files/paths addAdditionalSourceFile and addAdditionalSourcePath. For
example:
libdir = fullfile('$(MATLAB_ROOT)','..', '..', 'lib');
hEnt = RTW.TflCFunctionEntry;
addAdditionalSourceFile(hEnt, 'common.c');
addAdditionalSourcePath(hEnt, fullfile(libdir, 'src'));
Additional object For each file, specify the file name and path in calls to the functions
files/paths addAdditionalLinkObj and addAdditionalLinkObjPath. For
example:
libdir = fullfile('$(MATLAB_ROOT)','..', '..', 'lib');
hEnt = RTW.TflCFunctionEntry;
addAdditionalLinkObj(hEnt, 'sin.o');
addAdditionalLinkObjPath(hEnt, fullfile(libdir, 'bin'));
Compile flags Set the entry property AdditionalCompileFlags to a cell array of strings
representing the required compile flags. For example:
hEnt = RTW.TflCFunctionEntry;
21-62
Specify Build Information for Replacement Code
Specify Action
Link flags Set the entry property AdditionalLinkFlags to a cell array of strings
representing the required link flags. For example:
hEnt = RTW.TflCFunctionEntry;
setTflCFunctionEntryParameters(hEnt, ...
'ImplementationHeaderFile', 'sin_dbl.h', ...
'ImplementationHeaderPath', 'D:/lib/headerFiles'
'Key', 'sin', ...
'ImplementationName', 'sin_dbl'
'GenCallback', 'RTW.copyFileToBuildDir');
• Set argument genCallback in a call to
registerCFunctionEntry, registerCPPFunctionEntry,
or registerCPromotableMacroEntry to
'RTW.copyFileToBuildDir'.
After generating the C or C++ code, the code generator calls the function
RTW.copyFileToBuildDir. The specified files are then available for the
remaining steps of the build process.
4 Save the table that includes the entry that you added or modified.
The following example defines a table entry for an optimized multiplication function
that takes signed 32-bit integers and returns a signed 32-bit integer, taking saturation
into account. Multiplications in the generated code are replaced with calls to the
optimized function. The optimized function does not reside in the build folder. For the
code generator to access the files, they must be copied into the build folder to be compiled
and linked into the application.
The table entry specifies the source and header file names and paths. To request the
copy operation, the table entry sets the genCallback to 'RTW.copyFileToBuildDir'
in the call to the setTflCOperationEntryParameters function. In this example,
21-63
21 Code Replacement Customization for Simulink Models
the header file s32_mul.h contains an inlined function that invokes assembly
functions contained in s32_mul.s. If a match occurs for the table entry, the function
RTW.copyFileToBuildDir copies the specified source and header files to the build
folder.
function hTable = make_my_crl_table
hTable = RTW.TflTable;
op_entry = RTW.TflCOperationEntry;
setTflCOperationEntryParameters(op_entry, ...
'Key', 'RTW_OP_MUL', ...
'Priority', 100, ...
'SaturationMode', 'RTW_SATURATE_ON_OVERFLOW', ...
'RoundingModes', {'RTW_ROUND_UNSPECIFIED'}, ...
'ImplementationName', 's32_mul_s32_s32_sat', ...
'ImplementationHeaderFile', 's32_mul.h', ...
'ImplementationSourceFile', 's32_mul.s', ...
'ImplementationHeaderPath', {fullfile('$(MATLAB_ROOT)','crl')}, ...
'ImplementationSourcePath', {fullfile('$(MATLAB_ROOT)','crl')}, ...
'GenCallback', 'RTW.copyFileToBuildDir');
.
.
.
addEntry(hTable, op_entry);
op_entry = RTW.TflCOperationEntry;
setTflCOperationEntryParameters(op_entry, ...
'Key', 'RTW_OP_ADD', ...
'Priority', 90, ...
'SaturationMode', 'RTW_SATURATE_UNSPECIFIED', ...
'RoundingModes', {'RTW_ROUND_UNSPECIFIED'}, ...
'ImplementationName', 's32_add_s32_s32', ...
'ImplementationHeaderFile', 's32_add_s32_s32.h', ...
'ImplementationSourceFile', 's32_add_s32_s32.c'...
'GenCallback', 'RTW.copyFileToBuildDir');
addAdditionalHeaderFile(op_entry, 'all_additions.h');
addAdditionalIncludePath(op_entry, fullfile(libdir, 'include'));
addAdditionalSourceFile(op_entry, 'all_additions.c');
addAdditionalSourcePath(op_entry, fullfile(libdir, 'src'));
21-64
Specify Build Information for Replacement Code
addAdditionalLinkObj(op_entry, 'addition.o');
addAdditionalLinkObjPath(op_entry, fullfile(libdir, 'bin'));
.
.
.
addEntry(hTable, op_entry);
Related Examples
• “Identify Code Replacement Requirements”
• “Prepare for Code Replacement Library Development”
• “Define Code Replacement Mappings”
• “Register Code Replacement Mappings”
• “Develop a Code Replacement Library”
• “Quick Start Library Development”
More About
• “What Is Code Replacement Customization?”
• “Code Replacement Libraries”
• “Code Replacement Terminology”
• “Code Replacement Customization Limitations”
21-65
21 Code Replacement Customization for Simulink Models
The following table lists situations when you might consider one approach over the other.
If... Then...
Registering a code replacement Use the Code Replacement Tool.
table for the first time
You used the Code Replacement Use the Code Replacement Tool to quickly register the
Tool to create the table table.
Rapid prototyping code Use the Code Replacement Tool to quickly generate,
replacement register, and test entries.
Creating registration file to use Use the Code Replacement Tool to generate code that
as a template or starting point you can copy and modify.
for defining similar registration
files
21-66
Register Code Replacement Mappings
If... Then...
Modifying existing registration Use the MATLAB Editor to update the registration
files file.
Defining multiple code Use the MATLAB Editor to create a new or extend an
replacement libraries in one existing registration file.
registration file
Defining code replacement Use the MATLAB Editor to create a new or extend an
library hierarchy in a existing registration file.
registration file
1 After you validate and save a code replacement table, select File > Generate
registration file to open the Generate registration file dialog box.
21-67
21 Code Replacement Customization for Simulink Models
For... Specify...
Registry name String naming the code replacement library. For example,
Sin Function Example.
Table list Strings naming one or more code replacement tables to
include in the library. Specify each table as one of the
following:
You can specify multiple tables. If you do, separate the table
specifications with a comma. For example:
crl_table_sinfcn, c:/work_crl/crl_table_muldiv
For... Specify...
Description Text string that describes the purpose and content of the
library.
Target HW device Strings naming one or more hardware devices the code
replacement library supports. Separate names with a
comma. To support all device types, enter an asterisk (*). For
example, TI C28x, TI C62x.
Base CRL String naming a code replacement library that you want to
serve as a base library for the library you are registering.
Use this field to specify library hierarchies. For example,
you can specify a general TI device library as the base
library for a more specific TI C28x device library.
21-68
Register Code Replacement Mappings
For... Specify...
Generate data Flag that enables data alignment specification.
alignment
specification
The basic workflow for creating a registration file programmatically consists of the
following steps:
function rtwTargetInfo(cm)
cm.registerTargetInfo(@loc_register_tfl);
this(1) = RTW.TflRegistry;
this(1).Name = 'crl-name';
this(1).TableList = {'table',...};
For... Replace...
this(1).Name = 'crl-name'; crl-name with a string naming the code
replacement library. For example, Sin
Function Example.
this(1).TableList = table with a string that identifies the code
{'table',...}; replacement table that contains your code
replacement entries. Specify a table as one of
the following:
21-69
21 Code Replacement Customization for Simulink Models
For... Replace...
• Name of a table file on the MATLAB search
path
• Absolute path to a table file
• Path to a table file relative to
$(MATLAB_ROOT)
For... Replace...
this(1).Description = text with a string that describes the purpose
'text' and content of the library.
this(1).TargetHWDeviceType device-type with a string that names a
= {'device-type',...} hardware device the code replacement library
supports. You can specify multiple device
types. Separate device types with a comma. For
example, TI C28x, TI C62x. To support all
device types, enter an asterisk (*).
this(1).BaseTfl = 'base- base-lib with a string that names a code
lib' replacement library that you want to serve as a
base library for the library you are registering.
Use this field to specify library hierarchies.
For example, you can specify a general TI
device library as the base library for a TI
C28x device library.
21-70
Register Code Replacement Mappings
For example:
function rtwTargetInfo(cm)
cm.registerTargetInfo(@loc_register_tfl);
this(1) = RTW.TflRegistry;
this(1).Name = 'Sin Function Example';
this(1).TableList = {'crl_table_sinfcn'};
this(1).TargetHWDeviceType = {'*'};
this(1).Description = 'Example - sin function replacement';
2 Save the file with the name rtwTargetInfo.m.
3 Place the file on the MATLAB path. When the file is on the MATLAB path, the code
generator reads the file after starting and applies the customizations during the
current MATLAB session.
sl_refresh_customizations
cm.registerTargetInfo(@locCrlRegFcn);
21-71
21 Code Replacement Customization for Simulink Models
cm.registerTargetInfo(@locCrlRegFcn);
21-72
Register Code Replacement Mappings
Related Examples
• “Define Code Replacement Mappings”
• “Data Alignment for Code Replacement”
• “Specify Build Information for Replacement Code”
• “Develop a Code Replacement Library”
• “Quick Start Library Development”
• “Deploy Code Replacement Library”
More About
• “What Is Code Replacement?”
• “What Is Code Replacement Customization?”
• “Code Replacement Libraries”
• “Code Replacement Terminology”
21-73
21 Code Replacement Customization for Simulink Models
In this section...
“Code Replacement Table Validation” on page 21-74
“Validate a Table Definition File” on page 21-74
“Review Table Content” on page 21-75
“Verify Library Registration and Content” on page 21-76
“Review and Trace Code Replacements Generated Using a Code Replacement Library”
on page 21-77
“Determine Why Code Replacement Functions Are Not Used” on page 21-81
ans =
MATLAB displays errors that it finds. In the following example, MATLAB detects a typo
in a data type name.
21-74
Review and Test Code Replacements
isvalid(crl_table_sinfcn)
1 Open the viewer. At the MATLAB command line, enter the following command,
where table is the name of the code replacement table you want to review:
RTW.viewTfl(table)
For example,
RTW.viewTfl(crl_table_sinfcn)
2 Select entries in the table and verify that the display of the contents meets your
expectations. For example:
21-75
21 Code Replacement Customization for Simulink Models
1 Open the viewer. At the MATLAB command line, enter the following command,
where library is the name of the code replacement library you want to review:
RTW.viewTfl('library')
For example:
RTW.viewTfl('Sin Function Example')
21-76
Review and Test Code Replacements
2 Select your library and examine and compare its tables. Common problems that you
can detect include:
• Relative order of tables in the library is not correct (by default, the tool displays
tables in search order)
• Table entry problems as listed in the previous section
• Check the Code Replacement Report section of the code generation report for expected
replacements
• Trace code replacements
For models that consist of model hierarchies, repeat the following procedure for each
model in the hierarchy. Generate code for and review the trace information of each
referenced model separately (stand alone). Logged cache hit and miss information
captured in the Code Replacement Viewer is valid for the last model for which code was
generated only. The code generator overwrites logged information as you generate code
for each model in the hierarchy.
21-77
21 Code Replacement Customization for Simulink Models
3 Configure the code generation report. On the Code Generation > Report pane,
select:
• Include comments
• Either or both of Simulink block / Stateflow object comments and
Simulink block descriptions
21-78
Review and Test Code Replacements
21-79
21 Code Replacement Customization for Simulink Models
Inspect the generated code to see if the function or operator replacement occurred as
expected.
If a function or operator is not replaced as expected, a call site request did not match one
of your table entries. The code generator used a higher-priority (lower priority value)
match or did not find a match.
To analyze the code replacement match and replacement behavior, use the following
resources:
21-80
Review and Test Code Replacements
Code replacement can behave differently than you expect. To verify code replacements,
first inspect the generated code, as described in “Review and Trace Code Replacements
Generated Using a Code Replacement Library” on page 21-77.
• “View Cache Hits and Misses Using Viewer Trace Information” on page 21-81
• “View Cache Hits and Misses Using Command-Line” on page 21-84
For models that consist of model hierarchies, you must generate code for and review
the trace information of each referenced model separately (stand alone). Logged cache
hit and miss information captured in the Code Replacement Viewer is valid for the
last model for which code was generated only. The code generator overwrites logged
information as you generate code for each model in the hierarchy.
When debugging a code replacement table entry, you can use hit and miss information
in the Code Replacement Viewer to help determine why the code generator did not use a
replacement function in the generated code.
The following example shows how to display the cache hits and misses logged for
a code replacement table entry applied during code generation of example model
rtwdemo_crladdsub.
21-81
21 Code Replacement Customization for Simulink Models
2 Configure the code generator to use your code replacement library. In the
Configuration Parameters dialog box, on the Code Generation > Interface pane,
set the Code replacement library parameter to the name of your library. For the
example model, the library is set to Addition & Subtraction Examples.
3 Configure the code generation report. On the Code Generation > Report pane,
select:
7 In the middle pane, select the table entry to examine. In the right pane, the viewer
displays General Information and Trace Information about the table entry.
21-82
Review and Test Code Replacements
8 In the right pane, select the Trace Information tab. The following example shows
trace information for the int16 addition table entry.
The Trace Information tab lists Hit Source Locations and Miss Source
Locations. The usage count for the entry is 2. The Trace Information tab lists 2
hits and 2 misses. The display provides links to each source location (the source for
which code replacement was considered) and, for misses, lists a Miss Reason. In
the display above, in one case a saturation mode setting did not match between the
table entry and the source block, and in another case the signedness attribute did
21-83
21 Code Replacement Customization for Simulink Models
not match. If an expected replacement did not occur, you can use the hit and miss
information to modify the match criteria in the code replacement table entry.
To display the code replacement cache hits and misses logged during the most recent
code generation session in the command window, use the following command:
>> crl=get_param('model', 'TargetFcnLibHandle')
Field Description
HitCache Table containing code replacement entries that were matched
during a code generation session. These entries represent function
implementations that should appear in the generated code.
MissCache Table containing code replacement entries that failed to match during a
code generation session. These entries are created by the code generation
process for the purpose of querying the library to locate a registered
implementation.
In the following example, the most recent code generation session logged one cache hit
and zero cache misses. You can examine the logged HitCache entry using its table index.
a=get_param('my_sin_func','TargetFcnLibHandle')
a =
RTW.TflControl
Version: '1.0'
HitCache: [2x1 RTW.TflCFunctionEntry]
MissCache: []
TLCCallList: [0x1 handle]
TflTables: [10x1 RTW.TflTable]
TargetHWWordLengths: '8,16,32,32'
SupportNonFinite: 1
TLCSupported: 1
Recording: 0
LoadedLibrary: 'Sin Function Example'
TargetCharacteristics: [1x1 RTW.TargetCharacteristics]
CurrentHWDevice: 'Specified'
a.HitCache(1)
ans =
21-84
Review and Test Code Replacements
Related Examples
• “Choose a Code Replacement Library”
• “Replace Code Generated from Simulink Models”
• “Generate a Code Generation Report”
• “Traceability in Code Generation Report”
• “Choose a SIL or PIL Approach”
21-85
21 Code Replacement Customization for Simulink Models
• “Program Builds”
• “Build and Run a Program”
• “Develop a Code Replacement Library”
• “Quick Start Library Development”
More About
• “Reports for Code Generation”
• “About Code Tracing”
• “About SIL and PIL Simulations”
• “Code Replacement Libraries”
• “Code Replacement Terminology”
• “Code Replacement Customization Limitations”
21-86
Deploy Code Replacement Library
1 Move your code replacement table files to an area that is on the MATLAB search
path and that is accessible to and shared by other users.
2 Move the rtwTargetInfo.m registration file, to an area that is on the MATLAB
search path and that is accessible to and shared by other users. If you are deploying
a library to a folder in a development environment that already contains a
rtwTargetInfo.m file, copy the registration code from your code replacement
library version of rtwTargetInfo.m and paste it into the shared version of that file.
3 Register the library customizations or restart MATLAB.
4 Verify that the libraries are available for configuring the code generator and that
code replacements occur as expected.
5 Inform users that the libraries are available and provide direction on when and how
to apply them.
Related Examples
• “Relocate Code to Another Development Environment”
• “Review and Test Code Replacements”
• “Develop a Code Replacement Library”
More About
• “What Is Code Replacement?”
• “What Is Code Replacement Customization?”
• “Code Replacement Libraries”
• “Code Replacement Terminology”
21-87
21 Code Replacement Customization for Simulink Models
hTable = RTW.TflTable;
3 Create an entry for the function mapping with a call to the
RTW.TflCFunctionEntry function.
5 Create conceptual arguments y1 and u1. This example uses calls to the
createAndAddConceptualArg function to create and add an argument with one
function call.
createAndAddConceptualArg(fcn_entry, 'RTW.TflArgNumeric', ...
'Name', 'y1',...
'IOType', 'RTW_IO_OUTPUT',...
'DataTypeMode', 'double');
21-88
Math Function Code Replacement
copyConceptualArgsToImplementation(fcn_entry);
7 Add the entry to a code replacement table with a call to the addEntryfunction.
addEntry(hTable, fcn_entry);
Related Examples
• “Define Code Replacement Mappings”
• “Data Alignment for Code Replacement”
• “Algorithm-Based Code Replacement”
• “Reserved Identifiers and Code Replacement ”
• “Customize Matching and Replacement Process for Functions”
• “Develop a Code Replacement Library”
• “Quick Start Library Development”
More About
• “Code You Can Replace From Simulink Models”
• “Code Replacement Terminology”
21-89
21 Code Replacement Customization for Simulink Models
5 Create conceptual arguments y1, u1, u2, and u3. This example uses calls to the
getTflArgFromString and addConceptualArg functions to create and add the
arguments.
arg = getTflArgFromString(hTable, 'y1', 'void*');
arg.IOType = 'RTW_IO_OUTPUT';
addConceptualArg(fcn_entry, arg);
21-90
Memory Function Code Replacement
7 Add the entry to a code replacement table with a call to the addEntryfunction.
addEntry(hTable, fcn_entry);
To test this example, create model that uses the memcpy function for vector assignments.
For example:
1 Use In, Out, and Mux blocks to create the following model. (Alternatively, open the
example model rtwdemo_crlmath and copy the contents of Subsystem1 to a new
model.)
2 Select the diagram and use Edit > Subsystem to make it a subsystem.
21-91
21 Code Replacement Customization for Simulink Models
Related Examples
• “Define Code Replacement Mappings”
• “Review and Test Code Replacements”
• “Data Alignment for Code Replacement”
• “Reserved Identifiers and Code Replacement ”
• “Customize Matching and Replacement Process for Functions”
• “Develop a Code Replacement Library”
• “Quick Start Library Development”
More About
• “Code You Can Replace From Simulink Models”
• “Code Replacement Terminology”
21-92
Nonfinite Function Code Replacement
hTable = RTW.TflTable;
3 Create entries for the function mappings. To minimize the size of this function, the
example uses a local function, locAddFcnEnt, to group lines of code repeated for
each entry. A call to the RTW.TflCFunctionEntry function creates an entry for the
collection of local function entry definitions.
%% Create entries for nonfinite utility functions
% locAddFcnEnt(hTable, key, implName, out, in1, hdr)
%% Local Function
function locAddFcnEnt(hTable, key, implName, out, in1, hdr)
if isempty(hTable)
return;
end
fcn_entry = RTW.TflCFunctionEntry;
5 Create conceptual arguments y1 and u1. This example uses calls to the
getTflArgFromString and addConceptualArg functions to create and add the
arguments.
arg = getTflArgFromString(hTable, 'y1', out);
arg.IOType = 'RTW_IO_OUTPUT';
addConceptualArg(fcn_entry, arg);
21-93
21 Code Replacement Customization for Simulink Models
7 Add the entry to a code replacement table with a call to the addEntryfunction.
addEntry(hTable, fcn_entry);
To test this example, create a model that uses a nonfinite function. For example:
1 Create a model that includes a Math Function block that is set to the rem function.
For example:
Related Examples
• “Define Code Replacement Mappings”
• “Review and Test Code Replacements”
• “Data Alignment for Code Replacement”
21-94
Nonfinite Function Code Replacement
More About
• “Code You Can Replace From Simulink Models”
• “Code Replacement Terminology”
21-95
21 Code Replacement Customization for Simulink Models
Note: A custom target that supports concurrent multitasking must set the target
configuration parameter ConcurrentExecutionCompliant. For more information, see
“Support Concurrent Execution of Multiple Tasks” in the Simulink Coder documentation.
During code generation for a multicore target environment, if the build process generates
semaphore or mutex function calls for data transfer between tasks, use a custom library
to replace the generated function calls with custom semaphore or mutex implementations
that are optimal for your target environment. Using the Code Replacement Tool
(crtool) or equivalent code replacement functions, you can:
• Configure code replacement table entries for custom semaphore or mutex functions.
During system startup, execution of the code for data transfer between tasks, and
system shutdown the generated code calls these functions.
• Configure DWork arguments that represent global data, which the semaphore or
mutex functions access. A DWork pointer is passed to the model entry functions.
21-96
Semaphore and Mutex Function Replacement
This example shows how to create code replacement table entries for a mutex
replacement scenario. You configure a multicore target model for concurrent execution
and for data transfer between tasks of differing rates, which are handled by Rate
Transition blocks. In the generated code for the model, each Rate Transition block has
a separate, unique mutex. Mutex lock and unlock operations within the Rate Transition
block generated code share access to the same global data by using the unique mutex
created for that Rate Transition block.
a Select File > New entry > Semaphore entry to open a new table entry for
configuring a semaphore or mutex replacement.
b In the Mapping Information tab, use the Function parameter to select
Mutex Init. Initial default values for the table entry appear. In the
Conceptual function section, typically you can leave the argument settings at
their defaults.
c In the DWork attributes section, the Allocate DWork option is selected. The
dialog box provides a unique entry tag for the DWork argument d1.
21-97
21 Code Replacement Customization for Simulink Models
The only data type supported for the DWork Data type parameter is void*.
d In the Replacement function section, enter a function name in the Name
field. This example uses myMutexCreate. In the list of Function arguments,
leave the DWork argument d1 data type as void**.
21-98
Semaphore and Mutex Function Replacement
21-99
21 Code Replacement Customization for Simulink Models
d In the Replacement function section, Name field, enter a function name. This
example uses myMutexLock, myMutexUnlock, and myMutexDelete. In the list
of Function arguments, leave the DWork argument d1 data type as void*.
21-100
Semaphore and Mutex Function Replacement
7 Save the table to a MATLAB file in your working folder, for example, using File >
Save table. The name of the saved file is the table name, crl_table_rt_mutex,
with an .m extension. Optionally, you can open the saved file and examine the
MATLAB code for the code replacement table definition.
To test this example, create a model that contains a rate transition for which the build
process generates mutex function calls. Configure the model for a multicore target
environment. For example:
21-101
21 Code Replacement Customization for Simulink Models
Related Examples
• “Define Code Replacement Mappings”
• “Review and Test Code Replacements”
• “Data Alignment for Code Replacement”
• “Reserved Identifiers and Code Replacement ”
• “Customize Matching and Replacement Process for Functions”
• “Develop a Code Replacement Library”
• “Quick Start Library Development”
More About
• “Code You Can Replace From Simulink Models”
• “Code Replacement Terminology”
21-102
Algorithm-Based Code Replacement
You can define code replacement entries to replace these functions for one or all of the
available computation methods. For example, you can define an entry to replace only
Newton-Raphson instances of the rSqrt function.
To set the algorithm for a function in an entry definition, use the EntryInfoAlgorithm
property in a call to the function setTflCFunctionEntryParameters. The following
table lists arguments for specifying the computation method to match during code
generation.
Function Argument
rSqrt • 'RTW_DEFAULT' (match the default computation method,
Exact)
• 'RTW_NEWTON_RAPHSON'
• 'RTW_UNSPECIFIED' (match any computation method)
sin • 'RTW_CORDIC'
cos • 'RTW_DEFAULT' (match the default approximation
sincos method, None)
• 'RTW_UNSPECIFIED' (match any approximation method)
For example, to replace only Newton-Raphson instances of the rSqrt function, create
an entry as follows:
21-103
21 Code Replacement Customization for Simulink Models
hTable = RTW.TflTable;
3 Create an entry for the function mapping with a call to the
RTW.TflCFunctionEntry function.
5 Create conceptual arguments y1 and u1. This example uses calls to the
createAndAddConceptualArg function to create and add an argument with one
function call.
7 Add the entry to a code replacement table with a call to the addEntryfunction.
addEntry(hTable, fcn_entry);
The generated code for a Newton-Raphson instance of the rSqrt function looks like the
following code:
21-104
Algorithm-Based Code Replacement
Related Examples
• “Math Function Code Replacement”
• “Define Code Replacement Mappings”
• “Develop a Code Replacement Library”
• “Quick Start Library Development”
More About
• “Code You Can Replace From Simulink Models”
• “Code Replacement Terminology”
21-105
21 Code Replacement Customization for Simulink Models
If the code generated for available algorithm options does not meet requirements for your
application, you can create custom code replacement table entries to replace generated
algorithm code. You can create the table entries programmatically or interactively by
using the Code Replacement Tool.
For more information about using lookup table blocks, see “Nonlinearity” in the Simulink
documentation.
21-106
Lookup Table Function Code Replacement
21-107
21 Code Replacement Customization for Simulink Models
relevant algorithm parameters. The following table provides the conceptual function
signature information.
21-108
Lookup Table Function Code Replacement
21-109
21 Code Replacement Customization for Simulink Models
The following table lists required and optional parameters that pertain to lookup table
algorithms. When defining a table entry programmatically:
21-110
Lookup Table Function Code Replacement
Identify or create the C or C++ replacement function for the algorithm that you want to
use in place of an algorithm provided by the Simulink software.
This example uses the following C replacement function source and header files that are
in the folder matlab/help/toolbox/ecoder/examples/code_replacement:
• myLookup1D.c
• myLookup1D.h
Open and examine the code in myLookup1D.c. Note the function signature. When you
enter the implementation argument specification in the Code Replacement Tool, you
must specify argument properties.
#include "myLookup1D.h"
21-111
21 Code Replacement Customization for Simulink Models
real_T y;
uint16_T frac;
uint32_T bpIdx;
uint32_T maxIndex=9U;
while ((bpIdx < maxIndex - 1U) && (u0 >= bp0[bpIdx + 1U])) {
bpIdx++;
}
if (bpIdx == maxIndex) {
y = table[bpIdx];
} else {
y = (table[bpIdx + 1U] - table[bpIdx]) * ((real_T)frac * 3.0517578125E-5) +
table[bpIdx];
}
return y;
}
Open and examine the model. Note input and output specifications and block parameter
settings. To achieve a match, you must specify conceptual arguments based on how the
1D Lookup Table block is configured in the example model.
21-112
Lookup Table Function Code Replacement
1 At the command prompt, enter crtool to open the Code Replacement Tool.
2 Add a new table, select that table, and add a new function entry.
3 On the Mapping Information tab, select Custom for the Function parameter.
4 Look up the call signature and algorithm parameter information for the lookup
function that you want to update with an algorithm replacement. See “Lookup Table
Function Signatures” on page 21-107.
For this example, you replace the algorithm for the conceptual function associated
with the 1–D Lookup Table block. The signature for that function is:
y1 = lookup1D(u1, u2, u3, u4)
Arguments u1, u2, u3, u4 represent input, breakpoint data, table data, and table
dimension length, respectively. The function returns output to y1.
If the code generator finds a match of the conceptual function signature and
algorithm parameter values, an algorithm replacement occurs.
5 To the right of the Function drop-down list, in the function-name text box, enter
the name of the Simulink lookup table function. For this example, type the name
lookup1D. Type the name exactly as it appears in the documented signature,
including character casing. Press Enter.
6 Set the algorithm parameters to match the settings of the 1-D Lookup Table block in
the example model to trigger a match.
Set To
Interpolation method Linear
Extrapolation method Clip
Index search method Linear search
21-113
21 Code Replacement Customization for Simulink Models
Set To
Remove protection against out-of-range input off
Support tunable table size off
Use last table value for inputs at or above last on
breakpoint
7 Specify the conceptual arguments. Under the Conceptual arguments list box,
click + to add the arguments that are in the documented function signature. The
lookup1D function takes one output argument and three input arguments. Click +
four times.
The tool creates an output argument y1 and four input arguments u1, u2, u3, and
u4. By default, the four arguments are scalars of type double.
You can adjust the conceptual argument properties. For this example, you do not
make changes for y1 and u1. However, as the block parameter dialog box for the
example model shows, you must adjust the argument properties for the breakpoint
and table data arguments.
21-114
Lookup Table Function Code Replacement
Adjust the conceptual argument properties by using the following table. Then, click
Apply.
Signature Conceptual Data type I/O type Argument Lower range Upper range
Argument Argument Name type
Name
y y1 double OUTPUT Scalar Not Not
applicable applicable
u1 u1 double INPUT Scalar Not Not
applicable applicable
bp1 u2 double INPUT Matrix [0 0] [Inf Inf]
table u3 double INPUT Matrix [0 0] [Inf Inf]
tdl u4 uint32 INPUT Scalar Not Not
applicable applicable
8 Enter information for the replacement function prototype. The prototype for the
example function is:
real_T my_Lookup1D_Repl(real_T u0, const real_T *bp0, const real_T *table, uint32_T tdl)
In the Replacement function > Function prototype section, type the function
name my_Lookup1D_Repl in the Name text box.
9 Specify the arguments for the replacement function. Under the Function
arguments list box, click + four times to add four implementation arguments.
You might need to adjust the function argument properties. Make changes for y1
and u1. However, as the replacement function signature shows, you must adjust
the argument properties for the breakpoint, table data, and table dimension length
arguments. For u2 (breakpoints) and u3 (table), select the Const check box. For u4,
set Data type to uint32.
10 Set relevant implementation attributes. Use the default settings.
11 Validate the entry. If the tool reports errors, fix them, and retry the validation.
Repeat until the tool does not report errors.
12 Save the code replacement table in your working folder as
my_lookup_replacement_table.m.
21-115
21 Code Replacement Customization for Simulink Models
If you copied the example files to a folder other than the working folder containing the
test model, lookup1d.slx, specify the source and header file paths. Otherwise, leave
the other Build Information parameters set to default values. Click Apply.
Programmatic Specification
This example shows how to programmatically specify code replacement table entries for
lookup table functions.
Identify or create the C or C++ replacement function for the algorithm that you want to
use in place of an algorithm provided by the Simulink software.
This example uses the following C replacement function source and header files that are
in the folder matlab/help/toolbox/ecoder/examples/code_replacement:
• myLookup1D.c
21-116
Lookup Table Function Code Replacement
• myLookup1D.h
Open and examine the code in myLookup1D.c. Note the function signature. When you
enter the implementation argument specification in the Code Replacement Tool, you
must specify argument properties.
#include "myLookup1D.h"
while ((bpIdx < maxIndex - 1U) && (u0 >= bp0[bpIdx + 1U])) {
bpIdx++;
}
if (bpIdx == maxIndex) {
y = table[bpIdx];
} else {
y = (table[bpIdx + 1U] - table[bpIdx]) * ((real_T)frac * 3.0517578125E-5) +
table[bpIdx];
}
return y;
}
Open and examine the model. Note input and output specifications and block parameter
settings. To achieve a match, you must specify conceptual arguments based on how the
1D Lookup Table block is configured in the example model.
21-117
21 Code Replacement Customization for Simulink Models
Look up the call signature and algorithm parameter information for the lookup function
that you want to update with an algorithm replacement. See “Lookup Table Function
Signatures” on page 21-107.
Replace the algorithm for the function associated with the 1–D Lookup Table block. The
signature for that function is:
Arguments u1, u2, u3, and u4 represent input, breakpoint data, table data, and table
dimension length, respectively. The function returns output to y1.
Set the algorithm parameters ExtrapMethod and InterpMethod. Optionally, you can
specify values for:
• IndexSearchMethod
• RemoveProtectionInput
• RndMeth
• SaturateOnIntegerOverflow
• UseLastTableValue
If the code generator finds a match of the function signature and algorithm parameter
settings, an algorithm replacement occurs.
Create a code replacement table file, as a MATLAB function, that describes the lookup
table function code replacement table entries. Place a copy of the file matlab/help/
toolbox/ecoder/examples/code_replacement/Lookup1D_CRLtable.m in
21-118
Lookup Table Function Code Replacement
your working folder. This file defines a code replacement table for the C function
my_Lookup1D_Repl.
5 Create conceptual arguments and add them to the entry. This example uses calls to
the getTflArgFromString and addConceptualArg functions to create and add
the arguments.
The example defines five conceptual arguments for the lookup1D function, one
output argument y1 and four input arguments u1, u2, u3, and u4. Arguments y1
and u1 are defined as scalar double data. Arguments u2 and u3 represent bp1 and
table in the signature and are defined as 1x10 matrices of double data. Argument
u4 represents tdl and is defined as scalar of uint32 data. This definition triggers a
match with the example model.
21-119
21 Code Replacement Customization for Simulink Models
arg = hEnt.getTflArgFromString('y1','double');
arg.IOType = 'RTW_IO_OUTPUT';
addConceptualArg(hEnt, arg);
arg = hEnt.getTflArgFromString('u1','double');
addConceptualArg(hEnt, arg);
arg = hEnt.getTflArgFromString('u4','uint32');
addConceptualArg(hEnt, arg);
6 Set the algorithm properties for Lookup1D with calls to the function
addAlgorithmProperty. The calls to addAlgorithmProperty set the algorithm
parameters as listed in the following table. These settings trigger a match with the
example model.
Set To
InterpMethod Linear
ExtrapMethod Clip
IndexSearchMethod Linear search
RemoveProtectionInput Off
UseLastTableValue On
addAlgorithmProperty(hEnt, 'ExtrapMethod','Clip');
addAlgorithmProperty(hEnt, 'InterpMethod','Linear');
addAlgorithmProperty(hEnt, 'IndexSearchMethod','Linear search');
addAlgorithmProperty(hEnt, 'UseLastTableValue','on');
7 Create the implementation arguments and add them to the entry. This example
uses calls to the getTflArgFromString function to create five implementation
arguments that map to arguments in the replacement function prototype: one output
argument y1 and four input arguments u1, u2, u3, and u4. The convenience methods
setReturn and addArgument specify whether an argument is a return value or
argument and adds the argument to the entry’s array of implementation arguments.
arg = hEnt.getTflArgFromString('y1','double');
arg.IOType = 'RTW_IO_OUTPUT';
21-120
Lookup Table Function Code Replacement
hEnt.Implementation.setReturn(arg);
arg = hEnt.getTflArgFromString('u1','double');
hEnt.Implementation.addArgument(arg);
arg = hEnt.getTflArgFromString('u2','double*');
hEnt.Implementation.addArgument(arg);
arg = hEnt.getTflArgFromString('u3','double*');
hEnt.Implementation.addArgument(arg);
arg = hEnt.getTflArgFromString('u4','uint32');
hEnt.Implementation.addArgument(arg);
8 Add the entry to a code replacement table with a call to the addEntryfunction.
addEntry(hLib, hEnt);
hLib = RTW.TflTable;
hEnt = RTW.TflCFunctionEntry;
setTflCFunctionEntryParameters(hEnt, ...
'Key', 'lookup2D', ...
'Priority', 100, ...
21-121
21 Code Replacement Customization for Simulink Models
% Conceptual Args
arg = hEnt.getTflArgFromString('y1','double');
arg.IOType = 'RTW_IO_OUTPUT';
addConceptualArg(hEnt, arg);
arg = hEnt.getTflArgFromString('u1','double');
addConceptualArg(hEnt, arg);
arg = hEnt.getTflArgFromString('u2','double');
addConceptualArg(hEnt, arg);
arg = hEnt.getTflArgFromString('u6','uint32');
addConceptualArg(hEnt, arg);
arg = hEnt.getTflArgFromString('u7','uint32');
addConceptualArg(hEnt, arg);
% Algorithm Parameters
addAlgorithmProperty(hEnt, 'ExtrapMethod','Clip');
addAlgorithmProperty(hEnt, 'IndexSearchMethod','Linear search');
addAlgorithmProperty(hEnt, 'InterpMethod','Linear');
addAlgorithmProperty(hEnt, 'RemoveProtectionInput','off');
addAlgorithmProperty(hEnt, 'UseLastTableValue','on');
% Implementation Args
21-122
Lookup Table Function Code Replacement
arg = hEnt.getTflArgFromString('y1','double');
arg.IOType = 'RTW_IO_OUTPUT';
hEnt.Implementation.setReturn(arg);
arg = hEnt.getTflArgFromString('u1','double');
hEnt.Implementation.addArgument(arg);
arg = hEnt.getTflArgFromString('u2','double');
hEnt.Implementation.addArgument(arg);
arg = hEnt.getTflArgFromString('u3','double*');
arg.Type.BaseType.ReadOnly = true;
hEnt.Implementation.addArgument(arg);
arg = hEnt.getTflArgFromString('u4','double*');
arg.Type.BaseType.ReadOnly = true;
hEnt.Implementation.addArgument(arg);
arg = hEnt.getTflArgFromString('u5','double*');
arg.Type.BaseType.ReadOnly = true;
hEnt.Implementation.addArgument(arg);
arg = hEnt.getTflArgFromString('u6','uint32');
hEnt.Implementation.addArgument(arg);
arg = hEnt.getTflArgFromString('u7','uint32');
hEnt.Implementation.addArgument(arg);
arg = hEnt.getTflArgFromString('u6','uint32');
hEnt.Implementation.addArguments(arg);
arg = hEnt.getTflArgFromString('u7','uint32');
hEnt.Implementation.addArguments(arg);
hLib.addEntry(hEnt);
Related Examples
• “Define Code Replacement Mappings”
• “Review and Test Code Replacements”
• “Data Alignment for Code Replacement”
• “Reserved Identifiers and Code Replacement ”
• “Customize Matching and Replacement Process for Functions”
21-123
21 Code Replacement Customization for Simulink Models
More About
• “Code You Can Replace From Simulink Models”
• “Code Replacement Terminology”
21-124
Data Alignment for Code Replacement
For examples, see “Basic Example of Code Replacement Data Alignment” on page
21-132 and the “Data Alignment for Function Implementations” section of the
“Replacing Math Functions and Operators” example page.
21-125
21 Code Replacement Customization for Simulink Models
21-126
Data Alignment for Code Replacement
The equivalent alignment boundary specification in the Code Replacement Tool dialog
box is in this figure.
21-127
21 Code Replacement Customization for Simulink Models
Additionally, you can specify the alignment boundary for complex types by using the
addComplexTypeAlignment function.
• If you are generating a customization file function using the Code Replacement Tool,
fill out the following fields for each compiler.
21-128
Data Alignment for Code Replacement
21-129
21 Code Replacement Customization for Simulink Models
21-130
Data Alignment for Code Replacement
as = RTW.AlignmentSpecification;
as.AlignmentType = {'DATA_ALIGNMENT_LOCAL_VAR', ...
'DATA_ALIGNMENT_STRUCT_FIELD', ...
'DATA_ALIGNMENT_GLOBAL_VAR'};
as.AlignmentSyntaxTemplate = '__attribute__((aligned(%n)))';
as.AlignmentPosition = 'DATA_ALIGNMENT_PREDIRECTIVE';
as.SupportedLanguages = {'c', 'c++'};
da.addAlignmentSpecification(as);
tc = RTW.TargetCharacteristics;
tc.DataAlignment = da;
21-131
21 Code Replacement Customization for Simulink Models
1 Create and save the following code replacement table definition file,
crl_table_mmul_4x4_single_align.m. This table defines a replacement entry
for the * (multiplication) operator, the single data type, and input dimensions
[4,4]. The entry also specifies a data alignment boundary of 16 bytes for each
replacement function argument. The entry expresses the requirement that the
starting memory address for the data allocated for the function arguments during
code generation is a multiple of 16.
function hLib = crl_table_mmul_4x4_single_align
%CRL_TABLE_MMUL_4x4_SINGLE_ALIGN - Describe matrix operator entry with data alignment
hLib = RTW.TflTable;
entry = RTW.TflCOperationEntry;
setTflCOperationEntryParameters(entry, ...
'Key', 'RTW_OP_MUL', ...
'Priority', 90, ...
'ImplementationName', 'matrix_mul_4x4_s');
% conceptual arguments
createAndAddConceptualArg(entry, 'RTW.TflArgMatrix',...
'Name', 'y1', ...
'IOType', 'RTW_IO_OUTPUT', ...
'BaseType', 'single', ...
'DimRange', [4 4]);
21-132
Data Alignment for Code Replacement
createAndAddConceptualArg(entry, 'RTW.TflArgMatrix',...
'Name', 'u1', ...
'BaseType', 'single', ...
'DimRange', [4 4]);
createAndAddConceptualArg(entry, 'RTW.TflArgMatrix',...
'Name', 'u2', ...
'BaseType', 'single', ...
'DimRange', [4 4]);
% implementation arguments
arg = getTflArgFromString(hLib, 'y2', 'void');
arg.IOType = 'RTW_IO_OUTPUT';
entry.Implementation.setReturn(arg);
hLib.addEntry(entry);
21-133
21 Code Replacement Customization for Simulink Models
as = RTW.AlignmentSpecification;
as.AlignmentType = {'DATA_ALIGNMENT_LOCAL_VAR', ...
'DATA_ALIGNMENT_GLOBAL_VAR', ...
'DATA_ALIGNMENT_STRUCT_FIELD'};
as.AlignmentSyntaxTemplate = '__attribute__((aligned(%n)))';
as.SupportedLanguages={'c', 'c++'};
3 To register your library with code generator without having to restart MATLAB,
enter this command:
RTW.TargetRegistry.getInstance('reset');
4 Configure the code generator to use your code replacement library.
5 Generate code and a code generation report.
6 Review the code replacements. For example, check whether a multiplication
operation is replaced with a matrix_mul_4x4_s function call. In mmalign.h,
check whether the gcc alignment directive __attribute__((aligned(16))) is
generated to align the function variables.
Related Examples
• “Define Code Replacement Mappings”
• “Develop a Code Replacement Library”
• “Quick Start Library Development”
More About
• “Code You Can Replace From Simulink Models”
• “Code Replacement Terminology”
21-134
Data Alignment for Code Replacement
21-135
21 Code Replacement Customization for Simulink Models
• MATLAB Coder
• MATLAB code in a Simulink MATLAB Function block
Related Examples
• “Define Code Replacement Mappings”
• “Register Code Replacement Mappings”
• “Develop a Code Replacement Library”
• “Quick Start Library Development”
More About
• “Code You Can Replace From Simulink Models”
• “Code Replacement Terminology”
21-136
Replace MATLAB Functions with Custom Code Using coder.replace
21-137
21 Code Replacement Customization for Simulink Models
addpath(fullfile(docroot,'toolbox','ecoder','examples'))
ex_replace
2 View the MATLAB Function Block code. In the model, double-click the MATLAB
Function block to view the code in the MATLAB editor.
assert(isa(u1,'int32'));
assert(isa(u2,'int32'));
y = power(u1,u2);
hTable = RTW.TflTable;
5 Create an entry for the function mapping with a call to the
RTW.TflCFunctionEntry function.
hEnt = RTW.TflCFunctionEntry;
6 Set function entry parameters with a call to the
setTflCFunctionEntryParameters function.
setTflCFunctionEntryParameters(hEnt, ...
'Key', 'customFcn', ...
21-138
Replace MATLAB Functions Specified in MATLAB Function Blocks
7 Create conceptual arguments y1, u1 and u1. This example uses calls to the
getTflArgFromString and addConceptualArg functions to create and add the
arguments.
arg = getTflArgFromString(hEnt, 'y1','int32');
arg.IOType = 'RTW_IO_OUTPUT';
addConceptualArg(hEnt, arg);
8 Create the implementation arguments and add them to the entry. This example uses
calls to the getTflArgFromString function to create implementation arguments
that map to arguments in the replacement function prototype: output argument
void, input arguments u1 and u2, and output argument y1. The convenience
methods setReturn and addArgument specify whether an argument is a return
value or argument and adds the argument to the entry’s array of implementation
arguments.
addEntry(hLib, hEnt);
1 Register the table that contains the entry in a code replacement library.
21-139
21 Code Replacement Customization for Simulink Models
2 Create files MyMath.c and MyMath.h that define the replacement function,
scalarFcnReplacement, which has two int32 inputs and one int32 output.
MyMath.c
#include "MyMath.h"
MyMath.h
#ifndef _ScalarMath_h
#define _ScalarMath_h
#include "rtwtypes.h"
#ifdef __cplusplus
extern "C" {
#endif
#ifdef __cplusplus
}
#endif
#endif
3 Open the ex_replace model.
4 Configure the code generator to use the code replacement library and to include the
Code Replacements Report in the code generation report.
5 Generate the replacement code and a code generation report.
6 Review the code replacements. In the code generation report, view the generated
code for ex_replace.c.
void ex_replace_step(void)
{
int32_T y;
scalarFcnReplacement(ex_replace_U.In1, ex_replace_U.In2, &y);
ex_replace_Y.Out1 = y;
}
21-140
Replace MATLAB Functions Specified in MATLAB Function Blocks
Related Examples
• “Define Code Replacement Mappings”
• “Register Code Replacement Mappings”
• “Develop a Code Replacement Library”
• “Quick Start Library Development”
More About
• “Code You Can Replace From Simulink Models”
• “Code Replacement Terminology”
21-141
21 Code Replacement Customization for Simulink Models
To view a list of reserved identifiers for the code replacement library that you
use to generate code, specify the name of the library in a call to the function
RTW.TargetRegistry.getInstance.getTflReservedIdentifiers. For example:
crl_ids = RTW.TargetRegistry.getInstance.getTflReservedIdentifiers('GNU99 (GNU)')
In a code replacement table, the code generator registers each function implementation
name defined by a table entry as a reserved identifier. You can register additional
reserved identifiers for the table on a per-header-file basis. Providing additional reserved
identifiers can help prevent duplicate symbols and other identifier-related compile and
link issues.
You can register up to four reserved identifier structures in a code replacement table.
You can associate one set of reserved identifiers with a code replacement library, while
the other three (if present) must be associated with ANSI C. The following example
shows a reserved identifier structure that specifies two identifiers and the associated
header file.
d{1}.LibraryName = 'ANSI_C';
d{1}.HeaderInfos{1}.HeaderName = 'math.h';
d{1}.HeaderInfos{1}.ReservedIds = {'y0', 'y1'};
The code generator adds the identifiers to the list of reserved identifiers and honors them
during the build procedure.
Related Examples
• “Define Code Replacement Mappings”
• “Register Code Replacement Mappings”
• “Review and Test Code Replacements”
• “Develop a Code Replacement Library”
21-142
Reserved Identifiers and Code Replacement
More About
• “What Is Code Replacement Customization?”
• “Code Replacement Terminology”
21-143
21 Code Replacement Customization for Simulink Models
• Preset match criteria to identify functions and operators for which application-specific
implementations replace default implementations.
• Preset replacement function signatures.
However, preset match criteria and preset replacement function signatures might not
completely meet your function and operator replacement needs. For example,
When you need to add extra logic into the code replacement matching and replacement
process, create custom code replacement table entries. With custom entries you can
specify additional match criteria and modify the replacement function signature to meet
application needs.
a Add additional match criteria that the base class does not provide. The base
class provides a match based on argument number, argument name, signedness,
word size, slope (if not specified with wildcards), bias (if not specified with
wildcards), math modes such as saturation and rounding, and operator or
function key. Aaccept a match only when additional size or range conditions are
met.
b Modify the implementation signature by adding additional arguments or setting
constant input argument values. You can inject a constant value, such as an
input scaling value, as an additional argument to the replacement function.
21-144
Customize Matching and Replacement Process for Functions
3 Create code replacement entries that instantiate your custom entry class.
4 Register a library containing the code replacement table that includes your entries.
During code generation, the code replacement matching process first tries to match
function or operator call sites with the base class of your derived entry class. If the
process finds a match, the software calls your do_match method to execute your
additional match logic (if any) and your replacement function customizations (if any).
1 To exercise the custom code replacement table entries that you create in this
example, create an ERT-based model with a sine function block, such as this model.
In the import block parameters, set the signal Data type to double. If the target
platform selected for your model on the Hardware Implementation pane in the
Configuration Parameters dialog box supports an integer size other than 32, either
temporarily select a target platform with a 32-bit integer size, or modify the code to
match the integer size of your target platform.
2 Create a class folder using the name of your derived class, such as
@TflCustomFunctionEntry. Verify that the class folder is on the MATLAB search
path or in your current working folder.
3 In the class folder, create and save the following class definition
file, TflCustomFunctionEntry.m. This file defines the class
TflCustomFunctionEntry, which is derived from the base class
RTW.TflCFunctionEntryML.
The derived class defines a do_match method. In the do_match method signature:
• ent is the return handle, which is returned either as empty (indicating that the
match failed) or as a TflCFunctionEntry handle.
21-145
21 Code Replacement Customization for Simulink Models
The do_match method adds required additional match criteria not provided by the
base class and makes required modifications to the implementation signature. In
this case, the do_match method must match only targetBitPerInt, representing
the number of bits in the C int data type for the current target, to the value 32. If
a match is made, the method sets the return handle and creates and adds an input
argument, representing whether units are expressed as degrees or radians, to the
replacement function signature.
Note: Alternatively, you can create and add the additional implementation function
argument for passing a units flag in each code replacement table definition file that
instantiates this class. In that case, this class definition code does not create the
argument. That code only sets the argument value. For an example of creating and
adding additional implementation function arguments in a table definition file, see
“Customize Matching and Replacement Process for Operators” on page 21-180.
ent = []; % default the return to empty, indicating the match failed.
21-146
Customize Matching and Replacement Process for Functions
Exit the class folder and return to the previous working folder.
4 Create and save the following code replacement table definition file,
crl_table_custom_sinfcn_double.m. This file defines a code replacement table
containing a function table entry for sine with double input and output. This entry
instantiates the derived class from the previous step, TflCustomFunctionEntry.
function hTable = crl_table_custom_sinfcn_double
hTable = RTW.TflTable;
%% Add TflCustomFunctionEntry
fcn_entry = TflCustomFunctionEntry;
setTflCFunctionEntryParameters(fcn_entry, ...
'Key', 'sin', ...
'Priority', 30, ...
'ImplementationName', 'mySin', ...
'ImplementationHeaderFile', 'mySin.h', ...
'ImplementationSourceFile', 'mySin.c');
addEntry(hTable, fcn_entry);
21-147
21 Code Replacement Customization for Simulink Models
Related Examples
• “Define Code Replacement Mappings”
• “Register Code Replacement Mappings”
• “Develop a Code Replacement Library”
• “Quick Start Library Development”
More About
• “What Is Code Replacement?”
• “What Is Code Replacement Customization?”
• “Code Replacement Match and Replacement Process”
• “Code Replacement Terminology”
21-148
Scalar Operator Code Replacement
hTable = RTW.TflTable;
3 Create an entry for the operator mapping with a call to the
RTW.TflCOperationEntry function.
5 Create conceptual arguments y1, u1, and u2. This example uses calls to the
getTflArgFromString and addConceptualArg functions to create and add the
arguments.
arg = getTflArgFromString(hTable, 'y1', 'uint8');
arg.IOType = 'RTW_IO_OUTPUT';
addConceptualArg(op_entry, arg);
21-149
21 Code Replacement Customization for Simulink Models
7 Add the entry to a code replacement table with a call to the addEntryfunction.
addEntry(hTable, op_entry);
Related Examples
• “Define Code Replacement Mappings”
• “Review and Test Code Replacements”
• “Addition and Subtraction Operator Code Replacement”
• “Data Alignment for Code Replacement”
• “Remap Operator Output to Function Input”
• “Customize Matching and Replacement Process for Operators”
• “Develop a Code Replacement Library”
• “Quick Start Library Development”
More About
• “What Is Code Replacement?”
21-150
Scalar Operator Code Replacement
21-151
21 Code Replacement Customization for Simulink Models
In this section...
“Algorithm Options” on page 21-152
“Interactive Specification with Code Replacement Tool” on page 21-153
“Programmatic Specification” on page 21-153
“Algorithm Classification” on page 21-153
“Limitations” on page 21-155
Algorithm Options
When creating a code replacement table entry for an addition or subtraction operator,
first determine the type of algorithm that your library function implements.
• Cast-after-operation (CAO) — The algorithm computes the ideal result of the addition
or subtraction operation of the two inputs. The algorithm then type casts the result
to the output data type. Loss occurs during the type cast. This algorithm behaves
similarly to the C language except when the signedness of the operands does not
match. For example, when you add a signed long operand to an unsigned long
operand, standard C language rules convert the signed long operand to an unsigned
long operand. The result is a value that is not ideal.
21-152
Addition and Subtraction Operator Code Replacement
Programmatic Specification
Create a code replacement table file, as a MATLAB function, that describes
the addition or subtraction code replacement table entry. In the call to
setTflCOperationEntryParameters, set at least these parameters:
This example sets parameters for a code replacement operator entry for a cast-after-
operation implementation of a uint8 addition.
op_entry = RTW.TflCOperationEntry;
setTflCOperationEntryParameters(op_entry, ...
'Key', 'RTW_OP_ADD', ...
'EntryInfoAlgorithm', 'RTW_CAST_AFTER_OP', ...
'ImplementationName', 'u8_add_u8_u8');
Algorithm Classification
During code generation, the code generator examines addition and subtraction
operations, including adjacent type cast operations, to determine the type of algorithm
to compute the expression result. Based on the data types in the expression and the type
of the accumulator (type used to hold the result of the addition or subtraction operation),
the code generator uses these rules.
Input 1 Data Input 2 Data Accumulator Data Output Data Type Classification
Type Type Type
double double double double CBO, CAO
21-153
21 Code Replacement Customization for Simulink Models
Input 1 Data Input 2 Data Accumulator Data Output Data Type Classification
Type Type Type
double double double single —
double double single double —
double double single single CBO
double single double double CBO, CAO
double single double single —
double single single double —
double single single single CBO
single single single single CBO, CAO
single single single double —
single single double single —
single single double double CBO, CAO
• Floating-point and fixed-point types on the immediate addition or subtraction
operation
Algorithm Conditions
CBO One of the following is true:
Algorithm Conditions
CBO At least one of the following is true:
21-154
Addition and Subtraction Operator Code Replacement
Algorithm Conditions
CAO Net bias is zero and the data types in the expression have equal slope
adjustment factors. For more information on net bias, see “Addition” or
“Subtraction” in “Fixed-Point Operator Code Replacement” (for MATLAB
code) or “Fixed-Point Operator Code Replacement” (for Simulink
models).
In many cases, the numerical result of a CBO operation is equal to that of a CAO
operation. For example, if the input and output types are such that the operation
produces the ideal result, as in the case of int8 + int8 —> int16. To maximize the
probability of code replacement occurring in such cases, set the algorithm to cast-after-
operation.
Limitations
• The code generator does not replace operations with nonzero net bias.
• When classifying an operation as a CAO operation, the code generator includes the
adjacent casts in the expression when the expression involves only fixed-point types.
Otherwise, the code generator classifies and replaces only the immediate addition or
subtraction operation. Casts that the code generator excludes from the classification
appear in the generated code.
• To enable the code generator to include multiple cast operations, which follow an
addition or subtraction of fixed-point data, in the classification of an expression, the
rounding mode must be simplest or floor. Consider the expression y=(cast A)
(cast B)(u1+u2). If the rounding mode of (cast A), (cast B), and the addition
operator (+) are set to simplest or floor, the code generator takes into account
(cast A) and (cast B) when classifying the expression and performing the
replacement only.
Related Examples
• “Define Code Replacement Mappings”
• “Fixed-Point Operator Code Replacement”
• “Data Alignment for Code Replacement”
• “Remap Operator Output to Function Input”
• “Customize Matching and Replacement Process for Operators”
21-155
21 Code Replacement Customization for Simulink Models
More About
• “What Is Code Replacement?”
• “What Is Code Replacement Customization?”
• “Code You Can Replace From Simulink Models”
• “Code Replacement Match and Replacement Process”
• “Code Replacement Libraries”
• “Code Replacement Terminology”
21-156
Small Matrix Operation to Processor Code Replacement
hTable = RTW.TflTable;
3 Create the entry for the first operator mapping with a call to the
RTW.TflCOperationEntry function.
5 Create conceptual arguments y1, u1, and u2. This example uses calls to the
createAndAddConceptualArg function to create and add an argument with one
function call. To specify a matrix argument in the function call, use the argument
21-157
21 Code Replacement Customization for Simulink Models
class RTW.TflArgMatrix. Sspecify the base type and the dimensions for which the
argument is valid. The first table entry specifies [2 2] and the second table entry
specifies [3 3].
% Specify operands and result
createAndAddConceptualArg(op_entry, 'RTW.TflArgMatrix', ...
'Name', 'y1', ...
'IOType', 'RTW_IO_OUTPUT', ...
'BaseType', 'double', ...
'DimRange', [2 2]);
createAndAddConceptualArg(op_entry, 'RTW.TflArgMatrix',...
'Name', 'u1', ...
'BaseType', 'double', ...
'DimRange', [2 2]);
createAndAddConceptualArg(op_entry, 'RTW.TflArgMatrix',...
'Name', 'u2', ...
'BaseType', 'double', ...
'DimRange', [2 2]);
7 Add the entry to a code replacement table with a call to the addEntryfunction.
addEntry(hTable, op_entry);
8 Create the entry for the second operator mapping.
% Create table entry for matrix_sum_3x3_double
op_entry = RTW.TflCOperationEntry;
setTflCOperationEntryParameters(op_entry, ...
'Key', 'RTW_OP_ADD', ...
'Priority', 30, ...
'SaturationMode', 'RTW_WRAP_ON_OVERFLOW', ...
'ImplementationName', 'matrix_sum_3x3_double', ...
'ImplementationHeaderFile', 'MatrixMath.h', ...
21-158
Small Matrix Operation to Processor Code Replacement
addEntry(hTable, op_entry);
21-159
21 Code Replacement Customization for Simulink Models
• On the Solver pane, select a fixed-step, discrete solver with a fixed-step size such
as 0.1.
• On the Code Generation pane, select an ERT-based system target file.
• On the Code Generation > Interface pane, select the code replacement library
that contains your addition operation entry.
3 In the Model Explorer, configure the Signal Attributes for the In1 and In2 source
blocks. For each source block, set Port dimensions to [3,3], and set Data type to
double. Apply the changes. Save the model.
4 Generate code and a code generation report.
5 Review the code replacements. The code generator replaces the + operator with
matrix_sum_3x3_double in the generated code.
6 Reconfigure Port dimensions for In1 and In2 to [2 2], regenerate code. Observe
that code containing the + operator is replaced with matrix_sum_2x2_double.
Related Examples
• “Define Code Replacement Mappings”
• “Review and Test Code Replacements”
• “Matrix Multiplication Operation to MathWorks BLAS Code Replacement”
• “Matrix Multiplication Operation to ANSI/ISO C BLAS Code Replacement”
• “Data Alignment for Code Replacement”
• “Remap Operator Output to Function Input”
• “Customize Matching and Replacement Process for Operators”
• “Develop a Code Replacement Library”
• “Quick Start Library Development”
More About
• “What Is Code Replacement?”
• “What Is Code Replacement Customization?”
• “Code You Can Replace From Simulink Models”
• “Code Replacement Match and Replacement Process”
21-160
Small Matrix Operation to Processor Code Replacement
21-161
21 Code Replacement Customization for Simulink Models
21-162
Matrix Multiplication Operation to MathWorks BLAS Code Replacement
6 Create conceptual arguments y1, u1, and u2. This example uses calls to the
createAndAddConceptualArg function to create and add an argument with
one function call. To specify a matrix argument in the function call, use the
argument class RTW.TflArgMatrix and specify the base type and the dimensions
for which the argument is valid. This type of table entry supports a range of
dimensions specified in the format [Dim1Min Dim2Min ... DimNMin; Dim1Max
Dim2Max ... DimNMax]. For example, [2 2; inf inf] means a two-dimensional
matrix of size 2x2 or larger. The conceptual output argument for the dgemm32 entry
for matrix/matrix multiplication replacement specifies dimensions [2 2; inf
inf], while the conceptual output argument for the dgemv32 entry for matrix/vector
multiplication replacement specifies dimensions [2 1; inf 1].
% Specify operands and result
createAndAddConceptualArg(op_entry, 'RTW.TflArgMatrix', ...
'Name', 'y1', ...
'IOType', 'RTW_IO_OUTPUT', ...
21-163
21 Code Replacement Customization for Simulink Models
arg = RTW.TflArgCharConstant('TRANSA');
% Possible values for PassByType property are
% RTW_PASSBY_AUTO, RTW_PASSBY_POINTER,
% RTW_PASSBY_VOID_POINTER, RTW_PASSBY_BASE_POINTER
arg.PassByType = 'RTW_PASSBY_POINTER';
op_entry.Implementation.addArgument(arg);
arg = RTW.TflArgCharConstant('TRANSB');
arg.PassByType = 'RTW_PASSBY_POINTER';
op_entry.Implementation.addArgument(arg);
21-164
Matrix Multiplication Operation to MathWorks BLAS Code Replacement
op_entry.Implementation.addArgument(arg);
8 Add the entry to a code replacement table with a call to the addEntryfunction.
addEntry(hTable, op_entry);
9 Create the entry for the second mapping.
% Create table entry for dgemv32
op_entry = RTW.TflBlasEntryGenerator;
if ispc
21-165
21 Code Replacement Customization for Simulink Models
libExt = 'lib';
elseif ismac
libExt = 'dylib';
else
libExt = 'so';
end
setTflCOperationEntryParameters(op_entry, ...
'Key', 'RTW_OP_MUL', ...
'Priority', 100, ...
'ImplementationName', 'dgemv32', ...
'ImplementationHeaderFile', 'blascompat32.h', ...
'ImplementationHeaderPath', fullfile('$(MATLAB_ROOT)','extern','include'), ...
'AdditionalLinkObjs', {['libmwblascompat32.' libExt]}, ...
'AdditionalLinkObjsPaths', {LibPath},...
'SideEffects', true);
arg = RTW.TflArgCharConstant('TRANS');
arg.PassByType = 'RTW_PASSBY_POINTER';
op_entry.Implementation.addArgument(arg);
21-166
Matrix Multiplication Operation to MathWorks BLAS Code Replacement
op_entry.Implementation.addArgument(arg);
addEntry(hTable, op_entry);
21-167
21 Code Replacement Customization for Simulink Models
2 For each Product block, set the block parameter Multiplication to the value
Matrix(*).
3 Configure the model with the following settings:
• On the Solver pane, select a fixed-step, discrete solver with a fixed-step size such
as 0.1.
• On the Code Generation pane, select an ERT-based system target file.
• On the Code Generation > Interface pane, select the code replacement library
that contains your addition operation entry.
4 In the Model Explorer, configure the Signal Attributes for the In1, In2, and In3
source blocks. For In1 and In2, set Port dimensions to [3 3] and set the Data
type to double. For In3, set Port dimensions to [3 1] and set the Data type to
double.
5 Generate code and a code generation report.
6 Review the code replacements.
Related Examples
• “Define Code Replacement Mappings”
• “Review and Test Code Replacements”
• “Small Matrix Operation to Processor Code Replacement”
• “Matrix Multiplication Operation to ANSI/ISO C BLAS Code Replacement”
• “Data Alignment for Code Replacement”
• “Remap Operator Output to Function Input”
• “Customize Matching and Replacement Process for Operators”
• “Develop a Code Replacement Library”
• “Quick Start Library Development”
21-168
Matrix Multiplication Operation to MathWorks BLAS Code Replacement
More About
• “What Is Code Replacement?”
• “What Is Code Replacement Customization?”
• “Code You Can Replace From Simulink Models”
• “Code Replacement Match and Replacement Process”
• “Code Replacement Libraries”
• “Code Replacement Terminology”
21-169
21 Code Replacement Customization for Simulink Models
21-170
Matrix Multiplication Operation to ANSI/ISO C BLAS Code Replacement
6 Create conceptual arguments y1, u1, and u2. This example uses calls to the
createAndAddConceptualArg function to create and add an argument with
one function call. To specify a matrix argument in the function call, use the
argument class RTW.TflArgMatrix and specify the base type and the dimensions
for which the argument is valid. This type of table entry supports a range of
dimensions specified in the format [Dim1Min Dim2Min ... DimNMin; Dim1Max
Dim2Max ... DimNMax]. For example, [2 2; inf inf] means a two-dimensional
matrix of size 2x2 or larger. The conceptual output argument for the dgemm32 entry
for matrix/matrix multiplication replacement specifies dimensions [2 2; inf
inf]. The conceptual output argument for the dgemv32 entry for matrix/vector
multiplication replacement specifies dimensions [2 1; inf 1].
% Specify operands and result
createAndAddConceptualArg(op_entry, 'RTW.TflArgMatrix', ...
'Name', 'y1', ...
'IOType', 'RTW_IO_OUTPUT', ...
'BaseType', 'double', ...
'DimRange', [2 2; inf inf]);
createAndAddConceptualArg(op_entry, 'RTW.TflArgMatrix', ...
'Name', 'u1', ...
'BaseType', 'double', ...
'DimRange', [2 2; inf inf]);
createAndAddConceptualArg(op_entry, 'RTW.TflArgMatrix', ...
'Name', 'u2', ...
'BaseType', 'double', ...
'DimRange', [1 1; inf inf]);
21-171
21 Code Replacement Customization for Simulink Models
% use integer. (This will cause problems with C++ code generation,
% so for C++, use a wrapper function to cast each int to the
% corresponding enumeration type.)
%
% When a match occurs, the code generator computes the
% values for M, N, K, LDA, LDB, and LDC and insert them into the
% generated code.
21-172
Matrix Multiplication Operation to ANSI/ISO C BLAS Code Replacement
op_entry.Implementation.addArgument(arg);
8 Add the entry to a code replacement table with a call to the addEntryfunction.
addEntry(hTable, op_entry);
9 Create the entry for the second mapping.
% Create table entry for cblas_dgemv
op_entry = RTW.TflCBlasEntryGenerator;
setTflCOperationEntryParameters(op_entry, ...
'Key', 'RTW_OP_MUL', ...
'Priority', 100, ...
'ImplementationName', 'cblas_dgemv', ...
'ImplementationHeaderFile', 'cblas.h', ...
'ImplementationHeaderPath', LibPath, ...
'AdditionalIncludePaths', {LibPath}, ...
'GenCallback', 'RTW.copyFileToBuildDir', ...
'SideEffects', true);
21-173
21 Code Replacement Customization for Simulink Models
addEntry(hTable, op_entry);
21-174
Matrix Multiplication Operation to ANSI/ISO C BLAS Code Replacement
• On the Solver pane, select a fixed-step, discrete solver with a fixed-step size such
as 0.1.
• On the Code Generation pane, select an ERT-based system target file.
• On the Code Generation > Interface pane, select the code replacement library
that contains your addition operation entry.
3 For each Product block, set the block parameter Multiplication to the value
Matrix(*).
4 In the Model Explorer, configure the Signal Attributes for the In1, In2, and In3
source blocks. For In1 and In2, set Port dimensions to [3 3]. Set the Data type
to double. For In3, set Port dimensions to [3 1]. Set the Data type to double.
5 Generate code and a code generation report.
6 Review the code replacements.
Related Examples
• “Define Code Replacement Mappings”
• “Review and Test Code Replacements”
• “Small Matrix Operation to Processor Code Replacement”
• “Matrix Multiplication Operation to MathWorks BLAS Code Replacement”
• “Data Alignment for Code Replacement”
• “Remap Operator Output to Function Input”
• “Customize Matching and Replacement Process for Operators”
• “Develop a Code Replacement Library”
• “Quick Start Library Development”
21-175
21 Code Replacement Customization for Simulink Models
More About
• “What Is Code Replacement?”
• “What Is Code Replacement Customization?”
• “Code You Can Replace From Simulink Models”
• “Code Replacement Match and Replacement Process”
• “Code Replacement Libraries”
• “Code Replacement Terminology”
21-176
Remap Operator Output to Function Input
For example, for a sum operation, the code generator produces code similar to:
add8_Y.Out1 = u8_add_u8_u8(add8_U.In1, add8_U.In2);
If you remap the output to the first input, the code generator produces code similar to:
u8_add_u8_u8(&add8_Y.Out1;, add8_U.In1, add8_U.In2);
The following table definition file for a sum operation remaps operator output y1 as the
first function input argument.
21-177
21 Code Replacement Customization for Simulink Models
6 Create conceptual arguments y1, u1, and u2. This example uses calls to the
getTflArgFromString and addConceptualArg functions to create and add the
arguments.
arg = getTflArgFromString(hTable, 'y1', 'uint8');
arg.IOType = 'RTW_IO_OUTPUT';
addConceptualArg(op_entry, arg);
% Set y1 as first input arg, mark IOType as output, and use pointer type
arg=getTflArgFromString(hTable, 'y1', 'uint8*');
arg.IOType = 'RTW_IO_OUTPUT';
op_entry.Implementation.addArgument(arg);
8 Add the entry to a code replacement table with a call to the addEntryfunction.
addEntry(hTable, op_entry);
21-178
Remap Operator Output to Function Input
Related Examples
• “Define Code Replacement Mappings”
• “Review and Test Code Replacements”
• “Develop a Code Replacement Library”
• “Quick Start Library Development”
More About
• “What Is Code Replacement?”
• “What Is Code Replacement Customization?”
• “Code You Can Replace From Simulink Models”
• “Code Replacement Libraries”
• “Code Replacement Terminology”
21-179
21 Code Replacement Customization for Simulink Models
The example modifies a fixed-point addition replacement such that the implementation
function passes in the fraction lengths of the input and output data types as arguments.
Create a class folder using the name of your derived class, such as
@TflCustomOperationEntry. Verify that the class folder is on the MATLAB search
path or in your current working folder.
In the class folder, create and save the following class definition
file, TflCustomOperationEntry.m. This file defines the class
TflCustomOperationEntry, which is derived from the base class
RTW.TflCOperationEntryML.
• ent is the return handle, which is returned either as empty (indicating that the
match failed) or as a TflCOperationEntry handle.
• hThis is the handle to this object.
• hCSO is a handle to an object created by the code generator for querying the library for
a replacement.
• The remaining arguments are the number of bits for various data types of the current
target.
21-180
Customize Matching and Replacement Process for Operators
The do_match method adds required additional match criteria that the base class does
not provide. the method makes required modifications to the implementation signature.
In this case, the do_match method can rely on the base class for checking word size
and signedness. do_match must match only the number of conceptual arguments to the
value 3 (two inputs and one output) and the bias for each argument to the value 0. If the
code generator finds a match, do_match sets the return handle, removes slope and bias
wildcards from the conceptual arguments (the match is for specific slope and bias values),
and writes fraction-length values for the inputs and output into replacement function
arguments 3, 4, and 5.
You can create and add the three additional implementation function arguments
for passing fraction lengths in the class definition or in each code replacement entry
definition that instantiates this class. This example creates the arguments, adds them
to a code replacement table definition file, and sets them to specific values in the class
definition code.
classdef TflCustomOperationEntry < RTW.TflCOperationEntryML
methods
function ent = do_match(hThis, ...
hCSO, ... %#ok
targetBitPerChar, ... %#ok
targetBitPerShort, ... %#ok
targetBitPerInt, ... %#ok
targetBitPerLong) %#ok
% DO_MATCH - Create a custom match function. The base class
% checks the types of the arguments prior to calling this
% method. This will check additional data and perhaps modify
% the implementation function.
% The base class checks word size and signedness. Slopes and biases
% have been wildcarded, so the only additional checking to do is
% to check that the biases are zero and that there are only three
% conceptual arguments (one output, two inputs)
ent = []; % default the return to empty, indicating the match failed
21-181
21 Code Replacement Customization for Simulink Models
Create code replacement entries that instantiate your custom entry class. For this
example, create and save a code replacement table that contains a single operator entry,
an entry generator for unsigned 32-bit fixed-point addition operations, with arbitrary
fraction-length values on the inputs and the output. This entry instantiates the derived
class from the previous step.
If you want to replace all word sizes and signedness attributes (not just 32-bit and
unsigned), you can use the same derived class, but not the same entry, because you
cannot wildcard the WordLength and IsSigned arguments. For example, to support
uint8, int8, uint16, int16, and int32, you must add five other distinct entries.
Similarly, to use different implementation functions for saturation and rounding
modes other than overflow and round to floor, you must add entries for those match
permutations.
This table entry creates and adds three implementation arguments to hold the
fraction-length values for the inputs and output. Alternatively, the entry can omit
those argument definitions. Instead the do_match method of the derived class
TflCustomOperationEntry can create and add the three implementation arguments.
When the number of additional implementation arguments required can vary based on
compile-time information, use the alternative approach.
21-182
Customize Matching and Replacement Process for Operators
6 Create conceptual arguments y1, u1, and u2. This example uses calls to the
createAndAddConceptualArg function to create and add an argument with one
function call.
createAndAddConceptualArg(op_entry, 'RTW.TflArgNumeric', ...
'Name', 'y1', ...
'IOType', 'RTW_IO_OUTPUT', ...
'CheckSlope', false, ...
'CheckBias', false, ...
'DataType', 'Fixed', ...
'Scaling', 'BinaryPoint', ...
'IsSigned', false, ...
'WordLength', 32);
21-183
21 Code Replacement Customization for Simulink Models
% Add 3 fraction-length args. Actual values are set during code generation.
createAndAddImplementationArg(op_entry, 'RTW.TflArgNumericConstant', ...
'Name', 'fl_in1', ...
'IOType', 'RTW_IO_INPUT', ...
'IsSigned', false, ...
'WordLength', 32, ...
'FractionLength', 0, ...
'Value', 0);
21-184
Customize Matching and Replacement Process for Operators
8 Add the entry to a code replacement table with a call to the addEntryfunction.
addEntry(hTable, op_entry);
1 Create a model that includes one or more unsigned 32-bit fixed-point addition
operations.
2 In the block parameters for the Add blocks, set Integer rounding mode to Floor
and select Saturate on integer overflow.
3 Configure the model with the following settings:
21-185
21 Code Replacement Customization for Simulink Models
Related Examples
• “Define Code Replacement Mappings”
• “Review and Test Code Replacements”
• “Develop a Code Replacement Library”
• “Quick Start Library Development”
More About
• “Code Replacement Match and Replacement Process”
• “What Is Code Replacement?”
• “What Is Code Replacement Customization?”
• “Code You Can Replace From Simulink Models”
• “Code Replacement Libraries”
• “Code Replacement Terminology”
21-186
Fixed-Point Operator Code Replacement
The following table maps common ways to match fixed-point operator code replacement
entries with the associated fixed-point parameters that you specify in a code replacement
table definition file.
21-187
21 Code Replacement Customization for Simulink Models
21-188
Fixed-Point Operator Code Replacement
example, 1.0).
• NetFixedExponent: Specify the
fixed exponent (E) part of the net
slope, F2 (for example, -3.0).
E
createAndAddConceptualArg
function:
21-189
21 Code Replacement Customization for Simulink Models
• RelativeScalingFactorE:
Specify the fixed exponent (E) part
of the relative scaling factor, F2 (for
E
example, -3.0).
createAndAddConceptualArg
function:
createAndAddConceptualArg
function:
21-190
Fixed-Point Operator Code Replacement
V = V% = SQ + B
Addition
The operation V0 = V1 + V2 implies that
ÊS ˆ ÊS ˆ Ê B + B2 - B0 ˆ
Q0 = Á 1 ˜ Q1 + Á 2 ˜ Q2 + Á 1 ˜
Ë S0 ¯ Ë S0 ¯ Ë S0 ¯
If an addition replacement function is defined such that the scaling on the operands and
sum are equal and the net bias
21-191
21 Code Replacement Customization for Simulink Models
Ê B1 + B2 - B0 ˆ
Á ˜
Ë S0 ¯
is zero (for example, a function s8_add_s8_s8 that adds two signed 8-bit
values and produces a signed 8-bit result), then the operator entry must set the
operator entry parameters SlopesMustBeTheSame and MustHaveZeroNetBias
to true. (For parameter descriptions, see the reference page for the function
setTflCOperationEntryParameters.)
Subtraction
The operation V0 = V1 − V2 implies that
ÊS ˆ ÊS ˆ Ê B1 - B2 - B0 ˆ
Q0 = Á 1 ˜ Q1 - Á 2 ˜ Q2 + Á ˜
Ë S0 ¯ Ë S0 ¯ Ë S0 ¯
If a subtraction replacement function is defined such that the scaling on the operands
and difference are equal and the net bias
Ê B1 - B2 - B0 ˆ
Á ˜
Ë S0 ¯
is zero (for example, a function s8_sub_s8_s8 that subtracts two signed 8-bit
values and produces a signed 8-bit result), then the operator entry must set the
operator entry parameters SlopesMustBeTheSame and MustHaveZeroNetBias
to true. (For parameter descriptions, see the reference page for the function
setTflCOperationEntryParameters.)
Multiplication
There are different ways to specify multiplication replacements. The most direct way is to
specify an exact match of the input and output types. This is feasible if a model contains
only a few (known) slope and bias combinations. Use the TflCOperationEntry class
21-192
Fixed-Point Operator Code Replacement
and specify the exact values of slope and bias on each argument. For scenarios where
there are numerous slope/bias combinations, it is not feasible to specify each value with a
different entry. Use a net slope entry or create a custom entry.
It is common to replace all multiplication operations that have a net slope of 1.0 with
a function that performs C-style multiplication. For example, to replace all signed 8-
bit multiplications that have a net scaling of 1.0 with the s8_mul_s8_u8_ replacement
function, the operator entry must define a net slope factor, F2E. You specify the values
for F and E using operator entry parameters NetSlopeAdjustmentFactor and
NetFixedExponent. (For parameter descriptions, see the reference page for the
function setTflCOperationEntryParameters.) For the s8_mul_s8_u8 function, set
NetSlopeAdjustmentFactor to 1 and NetFixedExponent to 0.0.
Division
There are different ways to specify division replacements. The most direct way is to
specify an exact match of the input and output types. This is feasible if a model contains
only a few (known) slope and bias combinations. For this, use the TflCOperationEntry
class and specify the exact values of slope and bias on each argument. For scenarios
where there are numerous slope/bias combinations, it is not feasible to specify each
value with a different entry. For this, use a net slope entry or create a custom entry (see
“Customize Matching and Replacement Process for Functions”).
21-193
21 Code Replacement Customization for Simulink Models
ÊSQ ˆ
S0Q0 = Á 1 1 ˜
Ë S2Q2 ¯
ÊQ ˆ
Q0 = S n Á 1 ˜
Ë Q2 ¯
where Sn is the net slope.
It is common to replace all division operations that have a net slope of 1.0 with
a function that performs C-style division. For example, to replace all signed 8-
bit divisions that have a net scaling of 1.0 with the s8_mul_s8_u8_ replacement
function, the operator entry must define a net slope factor, F2E. You specify the values
for F and E using operator entry parameters NetSlopeAdjustmentFactor and
NetFixedExponent. (For parameter descriptions, see the reference page for the function
setTflCOperationEntryParameters.) For the s16_netslope0p5_div_s16_s16
function, you would set NetSlopeAdjustmentFactor to 1 and NetFixedExponent to
0.0.
ÊS ˆ
Q0 = Á 1 ˜ Q1
Ë S0 ¯
Q0 = S nQ1
Shift
The shift left or shift right operation V0 = (V1 / 2n) implies, for binary-point-only scaling,
that
21-194
Fixed-Point Operator Code Replacement
ÊSQ ˆ
S0Q0 = Á 1 n 1 ˜
Ë 2 ¯
Ê S ˆ ÊQ ˆ
Q0 = Á 1 ˜ + Á n1 ˜
Ë S0 ¯ Ë 2 ¯
ÊQ ˆ
Q0 = S n Á n1 ˜
Ë2 ¯
Related Examples
• “Define Code Replacement Mappings”
• “Binary-Point-Only Scaling Code Replacement”
• “Slope Bias Scaling Code Replacement”
• “Net Slope Scaling Code Replacement”
• “Equal Slope and Zero Net Bias Code Replacement”
• “Data Type Conversions (Casts) and Operator Code Replacement”
• “Shift Left Operations and Code Replacement”
• “Data Alignment for Code Replacement”
• “Remap Operator Output to Function Input”
• “Customize Matching and Replacement Process for Operators”
• “Develop a Code Replacement Library”
• “Quick Start Library Development”
More About
• “What Is Code Replacement?”
• “What Is Code Replacement Customization?”
• “Code You Can Replace From Simulink Models”
• “Code Replacement Match and Replacement Process”
• “Code Replacement Libraries”
• “Code Replacement Terminology”
21-195
21 Code Replacement Customization for Simulink Models
21-196
Binary-Point-Only Scaling Code Replacement
This example creates a code replacement entry for multiplication of fixed-point data
types. You specify arguments using binary-point-only scaling. The example defines the
function mapping programmatically. Alternatively, you can use the Code Replacement
Tool to define the same mapping.
hTable = RTW.TflTable;
3 Create the entry for the operator mapping with a call to the
RTW.TflCOperationEntry function.
op_entry = RTW.TflCOperationEntry;
4 Set operator entry parameters with a call to the
setTflCOperationEntryParameters function. The parameters specify the
type of operation as multiplication, the saturation mode as saturate on overflow,
rounding modes as unspecified, and the name of the replacement function as
s32_mul_s16_s16_binarypoint.
setTflCOperationEntryParameters(op_entry, ...
'Key', 'RTW_OP_MUL', ...
'Priority', 90, ...
'SaturationMode', 'RTW_SATURATE_ON_OVERFLOW', ...
'RoundingModes', {'RTW_ROUND_UNSPECIFIED'}, ...
'ImplementationName', 's32_mul_s16_s16_binarypoint', ...
'ImplementationHeaderFile', 's32_mul_s16_s16_binarypoint.h', ...
'ImplementationSourceFile', 's32_mul_s16_s16_binarypoint.c');
5 Create conceptual arguments y1, u1, and u2. This example uses calls to the
createAndAddConceptualArg function to create and add an argument with one
function call. Each argument specifies that the data type is fixed-point, the mode is
binary-point-only scaling, and its derived slope and bias values must exactly match
the call-site slope and bias values. The output argument is 32 bits, signed, with a
21-197
21 Code Replacement Customization for Simulink Models
fraction length of 28. The input arguments are 16 bits, signed, with fraction lengths
of 15 and 13.
createAndAddConceptualArg(op_entry, 'RTW.TflArgNumeric',...
'Name', 'y1', ...
'IOType', 'RTW_IO_OUTPUT', ...
'CheckSlope', true, ...
'CheckBias', true, ...
'DataTypeMode', 'Fixed-point: binary point scaling', ...
'IsSigned', true, ...
'WordLength', 32, ...
'FractionLength', 28);
createAndAddImplementationArg(op_entry, 'RTW.TflArgNumeric',...
'Name', 'u1', ...
'IOType', 'RTW_IO_INPUT', ...
'IsSigned', true, ...
'WordLength', 16, ...
'FractionLength', 0);
21-198
Binary-Point-Only Scaling Code Replacement
createAndAddImplementationArg(op_entry, 'RTW.TflArgNumeric',...
'Name', 'u2', ...
'IOType', 'RTW_IO_INPUT', ...
'IsSigned', true, ...
'WordLength', 16, ...
'FractionLength', 0);
7 Add the entry to a code replacement table with a call to the addEntryfunction.
addEntry(hTable, op_entry);
1 Create a model.
Related Examples
• “Define Code Replacement Mappings”
21-199
21 Code Replacement Customization for Simulink Models
More About
• “What Is Code Replacement?”
• “What Is Code Replacement Customization?”
• “Code You Can Replace From Simulink Models”
• “Code Replacement Match and Replacement Process”
• “Code Replacement Libraries”
• “Code Replacement Terminology”
21-200
Slope Bias Scaling Code Replacement
This example creates a code replacement entry for division of fixed-point data types. You
specify arguments using slope bias scaling. The example defines the function mapping
programmatically. Alternatively, you can use the Code Replacement Tool to define the
same mapping.
hTable = RTW.TflTable;
3 Create the entry for the operator mapping with a call to the
RTW.TflCOperationEntry function.
op_entry = RTW.TflCOperationEntry;
4 Set operator entry parameters with a call to the
setTflCOperationEntryParameters function. The parameters specify the
type of operation as division, the saturation mode as saturate on overflow,
rounding modes as round to ceiling, and the name of the replacement function as
s16_div_s16_s16_slopebias.
setTflCOperationEntryParameters(op_entry, ...
'Key', 'RTW_OP_DIV', ...
'Priority', 90, ...
'SaturationMode', 'RTW_SATURATE_ON_OVERFLOW', ...
'RoundingModes', {'RTW_ROUND_CEILING'}, ...
'ImplementationName', 's16_div_s16_s16_slopebias', ...
'ImplementationHeaderFile', 's16_div_s16_s16_slopebias.h', ...
'ImplementationSourceFile', 's16_div_s16_s16_slopebias.c');
5 Create conceptual arguments y1, u1, and u2. This example uses calls to the
createAndAddConceptualArg function to create and add an argument with one
function call. Each argument specifies that the data type is fixed-point, the mode
is slope bias scaling, and its specified slope and bias values must exactly match the
call-site slope and bias values. The output argument and input arguments are 16
bits, signed, each with specific slope bias specifications.
21-201
21 Code Replacement Customization for Simulink Models
createAndAddImplementationArg(op_entry, 'RTW.TflArgNumeric',...
'Name', 'u1', ...
'IOType', 'RTW_IO_INPUT', ...
'IsSigned', true, ...
'WordLength', 16, ...
'FractionLength', 0);
21-202
Slope Bias Scaling Code Replacement
createAndAddImplementationArg(op_entry, 'RTW.TflArgNumeric',...
'Name', 'u2', ...
'IOType', 'RTW_IO_INPUT', ...
'IsSigned', true, ...
'WordLength', 16, ...
'FractionLength', 0);
7 Add the entry to a code replacement table with a call to the addEntryfunction.
addEntry(hTable, op_entry);
1 Create a model.
21-203
21 Code Replacement Customization for Simulink Models
Related Examples
• “Define Code Replacement Mappings”
• “Review and Test Code Replacements”
• “Fixed-Point Operator Code Replacement”
• “Binary-Point-Only Scaling Code Replacement”
• “Net Slope Scaling Code Replacement”
• “Equal Slope and Zero Net Bias Code Replacement”
• “Data Type Conversions (Casts) and Operator Code Replacement”
• “Shift Left Operations and Code Replacement”
• “Data Alignment for Code Replacement”
• “Remap Operator Output to Function Input”
• “Customize Matching and Replacement Process for Operators”
• “Develop a Code Replacement Library”
• “Quick Start Library Development”
More About
• “What Is Code Replacement?”
• “What Is Code Replacement Customization?”
• “Code You Can Replace From Simulink Models”
• “Code Replacement Match and Replacement Process”
• “Code Replacement Libraries”
• “Code Replacement Terminology”
21-204
Net Slope Scaling Code Replacement
This example creates a code replacement entry for division of fixed-point data types,
using wrap on overflow saturation mode and a net slope. The example defines the
function mapping programmatically. Alternatively, you can use the Code Replacement
Tool to define the same mapping.
hTable = RTW.TflTable;
3 Create the entry for the operator mapping with a call to the
RTW.TflCOperationEntryGenerator_Netslope function, which provides
access to the fixed-point parameters NetSlopeAdjustmentFactor and
NetFixedExponent.
wv = [16,32];
for iy = 1:2
for inum = 1:2
for iden = 1:2
hTable = getDivOpEntry(hTable, ...
fixdt(1,wv(iy)),fixdt(1,wv(inum)),fixdt(1,wv(iden)));
end
end
end
%---------------------------------------------------------
function hTable = getDivOpEntry(hTable,dty,dtnum,dtden)
%---------------------------------------------------------
21-205
21 Code Replacement Customization for Simulink Models
funcStr = sprintf('user_div_%s_%s_%s',...
typeStrFunc(dty),...
typeStrFunc(dtnum),...
typeStrFunc(dtden));
op_entry = RTW.TflCOperationEntryGenerator_NetSlope;
setTflCOperationEntryParameters(op_entry, ...
'Key', 'RTW_OP_DIV', ...
'Priority', 90, ...
'SaturationMode', 'RTW_WRAP_ON_OVERFLOW',...
'RoundingModes', {'RTW_ROUND_UNSPECIFIED'},...
'NetSlopeAdjustmentFactor', 1.0, ...
'NetFixedExponent', 0.0, ...
'ImplementationName', funcStr, ...
'ImplementationHeaderFile', [funcStr,'.h'], ...
'ImplementationSourceFile', [funcStr,'.c']);
5 Create conceptual arguments y1, u1, and u2. This example uses calls to the
createAndAddConceptualArg function to create and add an argument with
one function call. Specify each argument as fixed-point and signed. Also, for each
argument, specify that code replacement request processing does not check for an
exact match to the call-site slope and bias values.
createAndAddConceptualArg(op_entry, ...
'RTW.TflArgNumeric', ...
'Name', 'y1',...
'IOType', 'RTW_IO_OUTPUT',...
'CheckSlope', false,...
'CheckBias', false,...
'DataTypeMode', 'Fixed-point: slope and bias scaling',...
'IsSigned', dty.Signed,...
'WordLength', dty.WordLength,...
'Bias', 0);
createAndAddConceptualArg(op_entry, ...
'RTW.TflArgNumeric',...
'Name', 'u1', ...
'IOType', 'RTW_IO_INPUT',...
'CheckSlope', false,...
'CheckBias', false,...
21-206
Net Slope Scaling Code Replacement
createAndAddConceptualArg(op_entry, ...
'RTW.TflArgNumeric', ...
'Name', 'u2', ...
'IOType', 'RTW_IO_INPUT',...
'CheckSlope', false,...
'CheckBias', false,...
'DataTypeMode', 'Fixed-point: slope and bias scaling',...
'IsSigned', dtden.Signed,...
'WordLength', dtden.WordLength,...
'Bias', 0);
7 Add the entry to a code replacement table with a call to the addEntryfunction.
addEntry(hTable, op_entry);
8 Define functions that determine the data type word length.
%-------------------------------------------------------------
function str = typeStrFunc(dt)
%-------------------------------------------------------------
if dt.Signed
sstr = 's';
else
sstr = 'u';
end
str = sprintf('%s%d',sstr,dt.WordLength);
%-------------------------------------------------------------
function str = typeStrBase(dt)
%-------------------------------------------------------------
if dt.Signed
21-207
21 Code Replacement Customization for Simulink Models
sstr = ;
else
sstr = 'u';
end
str = sprintf('%sint%d',sstr,dt.WordLength);
This example creates a code replacement entry for division of fixed-point data types,
using the ceiling rounding mode and a net slope scaling factor. The example defines the
function mapping programmatically. Alternatively, you can use the Code Replacement
Tool to define the same mapping.
setTflCOperationEntryParameters(op_entry, ...
'Key', 'RTW_OP_DIV', ...
'Priority', 90, ...
'SaturationMode', 'RTW_WRAP_ON_OVERFLOW', ...
'RoundingModes', {'RTW_ROUND_CEILING'}, ...
21-208
Net Slope Scaling Code Replacement
5 Create conceptual arguments y1, u1, and u2. This example uses calls to the
createAndAddConceptualArg function to create and add an argument with one
function call. Specify each argument as fixed-point, 16 bits, and signed. Also, for each
argument, specify that code replacement request processing does not check for an
exact match to the call-site slope and bias values.
createAndAddConceptualArg(op_entry, 'RTW.TflArgNumeric', ...
'Name', 'y1', ...
'IOType', 'RTW_IO_OUTPUT', ...
'CheckSlope', false, ...
'CheckBias', false, ...
'DataType', 'Fixed', ...
'IsSigned', true, ...
'WordLength', 16);
21-209
21 Code Replacement Customization for Simulink Models
createAndAddImplementationArg(op_entry, 'RTW.TflArgNumeric',...
'Name', 'u1', ...
'IOType', 'RTW_IO_INPUT', ...
'IsSigned', true, ...
'WordLength', 16, ...
'FractionLength', 0);
createAndAddImplementationArg(op_entry, 'RTW.TflArgNumeric',...
'Name', 'u2', ...
'IOType', 'RTW_IO_INPUT', ...
'IsSigned', true, ...
'WordLength', 16, ...
'FractionLength', 0);
7 Add the entry to a code replacement table with a call to the addEntryfunction.
addEntry(hTable, op_entry);
1 Create a model.
21-210
Net Slope Scaling Code Replacement
Related Examples
• “Define Code Replacement Mappings”
• “Review and Test Code Replacements”
• “Fixed-Point Operator Code Replacement”
• “Binary-Point-Only Scaling Code Replacement”
• “Slope Bias Scaling Code Replacement”
• “Equal Slope and Zero Net Bias Code Replacement”
• “Data Type Conversions (Casts) and Operator Code Replacement”
• “Shift Left Operations and Code Replacement”
• “Data Alignment for Code Replacement”
• “Remap Operator Output to Function Input”
• “Customize Matching and Replacement Process for Operators”
• “Develop a Code Replacement Library”
• “Quick Start Library Development”
More About
• “What Is Code Replacement?”
• “What Is Code Replacement Customization?”
• “Code You Can Replace From Simulink Models”
• “Code Replacement Match and Replacement Process”
• “Code Replacement Libraries”
• “Code Replacement Terminology”
21-211
21 Code Replacement Customization for Simulink Models
This example creates a code replacement entry for addition of fixed-point data types.
Slopes must be equal and net bias must be zero across the operator inputs and output.
The example defines the function mapping programmatically. Alternatively, you can use
the Code Replacement Tool to define the same mapping.
hTable = RTW.TflTable;
3 Create the entry for the operator mapping with a call to the
RTW.TflCOperationEntryGenerator function, which provides access to the fixed-
point parameters SlopesMustBeTheSame and MustHaveZeroNetBias.
op_entry = RTW.TflCOperationEntryGenerator;
4 Set operator entry parameters with a call to the
setTflCOperationEntryParameters function. The parameters specify
the type of operation as addition, the saturation mode as saturation
off, rounding modes as unspecified, and the name of the replacement
function as u16_add_SameSlopeZeroBias. SlopesMustBeTheSame and
MustHaveZeroNetBias are set to true, indicating that slopes must be equal and
net bias must be zero across the addition inputs and output.
setTflCOperationEntryParameters(op_entry, ...
'Key', 'RTW_OP_ADD', ...
'Priority', 90, ...
'SaturationMode', 'RTW_WRAP_ON_OVERFLOW', ...
'RoundingModes', {'RTW_ROUND_UNSPECIFIED'}, ...
'SlopesMustBeTheSame', true, ...
'MustHaveZeroNetBias', true, ...
'ImplementationName', 'u16_add_SameSlopeZeroBias', ...
'ImplementationHeaderFile', 'u16_add_SameSlopeZeroBias.h', ...
'ImplementationSourceFile', 'u16_add_SameSlopeZeroBias.c');
21-212
Equal Slope and Zero Net Bias Code Replacement
5 Create conceptual arguments y1, u1, and u2. This example uses calls to the
createAndAddConceptualArg function to create and add an argument with one
function call. Each argument is specified as 16 bits and unsigned. Each argument
specifies that code replacement request processing does not check for an exact match
to the call-site slope and bias values.
createAndAddConceptualArg(op_entry, 'RTW.TflArgNumeric', ...
'Name', 'y1', ...
'IOType', 'RTW_IO_OUTPUT', ...
'CheckSlope', false, ...
'CheckBias', false, ...
'IsSigned', false, ...
'WordLength', 16);
createAndAddImplementationArg(op_entry, 'RTW.TflArgNumeric',...
'Name', 'u1', ...
'IOType', 'RTW_IO_INPUT', ...
'IsSigned', false, ...
'WordLength', 16, ...
'FractionLength', 0);
createAndAddImplementationArg(op_entry, 'RTW.TflArgNumeric',...
21-213
21 Code Replacement Customization for Simulink Models
7 Add the entry to a code replacement table with a call to the addEntryfunction.
addEntry(hTable, op_entry);
1 Create a model.
• Verify that Output data type is set to its default, Inherit via internal
rule.
• Set Integer rounding mode to Zero.
3 Configure the model with the following settings:
Related Examples
• “Define Code Replacement Mappings”
21-214
Equal Slope and Zero Net Bias Code Replacement
More About
• “What Is Code Replacement?”
• “What Is Code Replacement Customization?”
• “Code You Can Replace From Simulink Models”
• “Code Replacement Match and Replacement Process”
• “Code Replacement Libraries”
• “Code Replacement Terminology”
21-215
21 Code Replacement Customization for Simulink Models
This example creates a code replacement entry that replaces int32 to int16
data type conversion (cast) operations. The example defines the function mapping
programmatically. Alternatively, you can use the Code Replacement Tool to define the
same mapping.
21-216
Data Type Conversions (Casts) and Operator Code Replacement
7 Add the entry to a code replacement table with a call to the addEntryfunction.
addEntry(hLib, hEnt);
This example creates a code replacement entry to replace data type conversions (casts)
of fixed-point data types by using a net slope. The example defines the function mapping
programmatically. Alternatively, you can use the Code Replacement Tool to define the
same mapping.
hTable = RTW.TflTable;
3 Create the entry for the operator mapping with a call to the
RTW.TflCOperationEntryGenerator_Netslope function, which provides
access to the fixed-point parameters NetSlopeAdjustmentFactor and
NetFixedExponent
op_entry = RTW.TflCOperationEntryGenerator_NetSlope;
21-217
21 Code Replacement Customization for Simulink Models
InFL = 2;
InWL = 16;
InSgn = true;
OutFL = 4;
OutWL = 32;
OutSgn = true;
setTflCOperationEntryParameters(op_entry, ...
'Key', 'RTW_OP_CAST', ...
'Priority', 50, ...
'SaturationMode', 'RTW_SATURATE_ON_OVERFLOW', ...
'RoundingModes', {'RTW_ROUND_FLOOR'}, ...
'NetSlopeAdjustmentFactor', 1.0, ...
'NetFixedExponent', (OutFL - InFL), ...
'ImplementationName', 'my_fxp_cast', ...
'ImplementationHeaderFile', 'some_hdr.h', ...
'ImplementationSourceFile', 'some_hdr.c');
5 Create conceptual arguments y1 and u1. This example uses calls to the
createAndAddConceptualArg function to create and add an argument with one
function call. Each argument is specified as fixed-point and signed. Each argument
specifies that code replacement request processing does not check for an exact match
to the call-site slope and bias values.
createAndAddConceptualArg(op_entry, 'RTW.TflArgNumeric', ...
'Name', 'y1', ...
'IOType', 'RTW_IO_OUTPUT', ...
'CheckSlope', false, ...
'CheckBias', false, ...
'DataTypeMode', 'Fixed-point: binary point scaling', ...
'IsSigned', OutSgn, ...
'WordLength', OutWL, ...
'FractionLength',OutFL);
21-218
Data Type Conversions (Casts) and Operator Code Replacement
createAndAddImplementationArg(op_entry, 'RTW.TflArgNumeric',...
'Name', 'u1', ...
'IOType', 'RTW_IO_INPUT', ...
'IsSigned', InSgn, ...
'WordLength', InWL, ...
'FractionLength', 0);
7 Add the entry to a code replacement table with a call to the addEntryfunction.
addEntry(hTable, op_entry);
Related Examples
• “Define Code Replacement Mappings”
• “Fixed-Point Operator Code Replacement”
• “Binary-Point-Only Scaling Code Replacement”
• “Slope Bias Scaling Code Replacement”
• “Net Slope Scaling Code Replacement”
• “Equal Slope and Zero Net Bias Code Replacement”
• “Shift Left Operations and Code Replacement”
• “Data Alignment for Code Replacement”
• “Remap Operator Output to Function Input”
• “Customize Matching and Replacement Process for Operators”
• “Develop a Code Replacement Library”
• “Quick Start Library Development”
More About
• “What Is Code Replacement?”
21-219
21 Code Replacement Customization for Simulink Models
21-220
Shift Left Operations and Code Replacement
This example creates a code replacement entry to replace shift left operations for int16
data. The example defines the function mapping programmatically. Alternatively, you
can use the Code Replacement Tool to define the same mapping.
21-221
21 Code Replacement Customization for Simulink Models
arg.IOType = 'RTW_IO_OUTPUT';
addConceptualArg(op_entry, arg);
op_entry.Implementation.setReturn(arg);
7 Create the int8 argument as conceptual and implementation argument u2. This
example uses calls to the getTflArgFromString and addConceptualArg
functions to create the conceptual argument and add it to the entry. This argument
specifies the number of bits to shift the previous input argument. Because the
argument type is not relevant, the example disables type checking by setting the
CheckType property to false. Convenience method addArgument specifies the
argument as implementation input argument.
arg = getTflArgFromString(hTable, 'u2', 'int8');
arg.CheckType = false;
addConceptualArg(op_entry, arg);
op_entry.Implementation.addArgument(arg);
This example creates a code replacement entry to replace shift left operations
for fixed-point data using a net slope. The example defines the function mapping
programmatically. Alternatively, you can use the Code Replacement Tool to define the
same mapping.
21-222
Shift Left Operations and Code Replacement
2 Create a table to contain the entry with a call to the RTW.TflTable function.
hTable = RTW.TflTable;
3 Create the entry for the operator mapping with a call to the
RTW.TflCOperationEntryGenerator_Netslope function. This function
provides access to the fixed-point parameters NetSlopeAdjustmentFactor and
NetFixedExponent.
op_entry = RTW.TflCOperationEntryGenerator_NetSlope;
4 Set operator entry parameters with a call to the
setTflCOperationEntryParameters function. The parameters specify the type
of operation as shift left, the saturation mode as saturate on overflow, rounding
modes as toward negative infinity, and the name of the replacement function as
my_fxp_shift_left. NetSlopeAdjustmentFactor and NetFixedExponent
specify the F and E parts of the net slope F2 .
E
InFL = 2;
InWL = 16;
InSgn = true;
OutFL = 4;
OutWL = 32;
OutSgn = true;
setTflCOperationEntryParameters(op_entry, ...
'Key', 'RTW_OP_SL', ...
'Priority', 50, ...
'SaturationMode', 'RTW_SATURATE_ON_OVERFLOW', ...
'RoundingModes', {'RTW_ROUND_FLOOR'}, ...
'NetSlopeAdjustmentFactor', 1.0, ...
'NetFixedExponent', (OutFL - InFL),...
'ImplementationName', 'my_fxp_shift_left', ...
'ImplementationHeaderFile', 'some_hdr.h', ...
'ImplementationSourceFile', 'some_hdr.c');
5 Create conceptual arguments y1 and u1. This example uses calls to the
createAndAddConceptualArg function to create and add an argument with one
function call. Each argument is specified as fixed-point and signed. Each argument
specifies that code replacement request processing does not check for an exact match
to the call-site slope and bias values.
createAndAddConceptualArg(op_entry, 'RTW.TflArgNumeric', ...
'Name', 'y1', ...
'IOType', 'RTW_IO_OUTPUT', ...
'CheckSlope', false, ...
'CheckBias', false, ...
'DataTypeMode', 'Fixed-point: binary point scaling', ...
'IsSigned', OutSgn, ...
'WordLength', OutWL, ...
'FractionLength',OutFL);
21-223
21 Code Replacement Customization for Simulink Models
7 Create the int8 argument as conceptual and implementation argument u2. This
example uses calls to the getTflArgFromString and addConceptualArg
functions to create the conceptual argument and add it to the entry. This argument
specifies the number of bits to shift the previous input argument. Because the
argument type is not relevant, type checking is disabled by setting the CheckType
property to false. Convenience method addArgument specifies the argument as
implementation input argument.
arg = getTflArgFromString(hTable, 'u2', 'uint8');
arg.CheckType = false;
addConceptualArg(op_entry, arg);
op_entry.Implementation.addArgument(arg);
8 Add the entry to a code replacement table with a call to the addEntryfunction.
addEntry(hTable, op_entry);
Related Examples
• “Define Code Replacement Mappings”
21-224
Shift Left Operations and Code Replacement
More About
• “What Is Code Replacement?”
• “What Is Code Replacement Customization?”
• “Code You Can Replace From Simulink Models”
• “Code Replacement Match and Replacement Process”
• “Code Replacement Libraries”
• “Code Replacement Terminology”
21-225
21-226
22
22-2
What Is Code Replacement Customization?
Related Examples
• “Quick Start Library Development”
• “Develop a Code Replacement Library”
More About
• “What Is Code Replacement?”
• “Code You Can Replace from MATLAB Code”
• “Code Replacement Libraries”
• “Code Replacement Terminology”
• “Code Replacement Customization Limitations”
22-3
22 Code Replacement Customization for MATLAB Code
Math Functions
When generating C/C++ code from MATLAB code, depending on code replacement
libraries available in your development environment, you can configure the code
generator to replace instances of the following math functions with application-specific
implementations.
Function Data Type Support Scalar, Vector, Matrix Real, Complex Support
Support
abs1 Floating point Scalar Real
acos Floating point Scalar Real
Vector Complex
Matrix Complex input/complex output
Real input/complex output
acosd Floating point Scalar Real
Vector Complex
Matrix
acot Floating point Scalar Real
Vector Complex
Matrix
acotd Floating point Scalar Real
22-4
Code You Can Replace from MATLAB Code
Function Data Type Support Scalar, Vector, Matrix Real, Complex Support
Support
Vector Complex
Matrix
acoth Floating point Scalar Real
Vector Complex
Matrix
acsc Floating point Scalar Real
Vector Complex
Matrix
acscd Floating point Scalar Real
Vector Complex
Matrix
acsch Floating point Scalar Real
Vector Complex
Matrix
asec Floating point Scalar Real
Vector Complex
Matrix
asecd Floating point Scalar Real
Vector Complex
Matrix
asech Floating point Scalar Real
Vector Complex
Matrix
asin Floating point Scalar Real
Vector Complex
Matrix Complex input/complex output
Real input/complex output
asind Floating point Scalar Real
Vector Complex
Matrix
22-5
22 Code Replacement Customization for MATLAB Code
Function Data Type Support Scalar, Vector, Matrix Real, Complex Support
Support
atan Floating point Scalar Real
Vector Complex
Matrix Complex input/complex output
Real input/complex output
atan2 Floating point Scalar Real
Vector
Matrix
atan2d Floating point Scalar Real
Vector
Matrix
atand Floating point Scalar Real
Vector Complex
Matrix
cos Floating point Scalar Real
Vector Complex
Matrix Complex input/complex output
Real input/complex output
ceil • Floating-point • Floating-point • Floating-point
• Scalar • Scalar • Scalar
cosd Floating point Scalar Real
Vector Complex
Matrix
cosh Floating point Scalar Real
Vector Complex
Matrix Complex input/complex output
Real input/complex output
cot Floating point Scalar Real
Vector Complex
Matrix
cotd Floating point Scalar Real
Vector Complex
Matrix
22-6
Code You Can Replace from MATLAB Code
Function Data Type Support Scalar, Vector, Matrix Real, Complex Support
Support
coth Floating point Scalar Real
Vector Complex
Matrix
csc Floating point Scalar Real
Vector Complex
Matrix
cscd Floating point Scalar Real
Vector Complex
Matrix
csch Floating point Scalar Real
Vector Complex
Matrix
exp Floating point Scalar Real
fix Floating point Scalar Real
floor • Floating-point • Floating-point • Floating-point
• Scalar • Scalar • Scalar
hypot Floating point Scalar Real
Vector
Matrix
ldexp Floating point Scalar Real
log Floating point Scalar Real
Vector Complex
Matrix
log10 Floating point Scalar Real
Vector Complex
Matrix
log2 Floating point Scalar Real
Vector Complex
Matrix
max Integer Scalar Real
Floating point
22-7
22 Code Replacement Customization for MATLAB Code
Function Data Type Support Scalar, Vector, Matrix Real, Complex Support
Support
min Integer Scalar Real
Floating point
pow Floating point Scalar Real
rem Floating point Scalar Real
round Floating point Scalar Real
sec Floating point Scalar Real
Vector Complex
Matrix
secd Floating point Scalar Real
Vector Complex
Matrix
sech Floating point Scalar Real
Vector Complex
Matrix
sign Floating point Scalar Real
sin Floating point Scalar Real
Vector Complex
Matrix Complex input/complex output
Real input/complex output
sind Floating point Scalar Real
Vector Complex
Matrix
sinh Floating point Scalar Real
Vector Complex
Matrix Complex input/complex output
Real input/complex output
sqrt Floating point Scalar Real
tan Floating point Scalar Real
Vector Complex
Matrix Complex input/complex output
Real input/complex output
22-8
Code You Can Replace from MATLAB Code
Function Data Type Support Scalar, Vector, Matrix Real, Complex Support
Support
tand Floating point Scalar Real
Vector Complex
Matrix
tanh Floating point Scalar Real
Vector Complex
Matrix Complex input/complex output
Real input/complex output
1
Wrap on integer overflow only
Memory Functions
Depending on code replacement libraries available in your development environment,
you can configure the code generator to replace instances of the following memory
functions with application-specific implementations.
Function Data Type Support Scalar, Vector, Matrix Real, Complex Support
Support
memcmp Void pointer (void*) Scalar Real
Vector Complex
Matrix
memcpy Void pointer (void*) Scalar Real
Vector Complex
Matrix
memset Void pointer (void*) Scalar Real
Vector Complex
Matrix
memset2zero Void pointer (void*) Scalar Real
Vector Complex
Matrix
Some target processors provide optimized functions to set memory to zero. Use the code
replacement library programming interface to replace the memset2zero function with
more efficient target-specific functions.
Operators
22-9
22 Code Replacement Customization for MATLAB Code
When generating C/C++ code from MATLAB code, depending on code replacement
libraries available in your development environment, you can configure the code
generator to replace instances of the following operators with application-specific
implementations.
Mixed data type support indicates you can specify different data types of different inputs.
22-10
Code You Can Replace from MATLAB Code
22-11
22 Code Replacement Customization for MATLAB Code
Related Examples
• “Quick Start Library Development”
• “Develop a Code Replacement Library”
22-12
Code You Can Replace from MATLAB Code
More About
• “What Is Code Replacement?”
• “What Is Code Replacement Customization?”
• “Code Replacement Libraries”
• “Code Replacement Terminology”
• “Code Replacement Customization Limitations”
22-13
22 Code Replacement Customization for MATLAB Code
1 Creates and partially populates a code replacement entry object with the function or
operator name or key and conceptual arguments.
2 Uses the entry object to query the configured code replacement library for a
conceptual representation match. The code generator searches the tables in a code
replacement library for a match in the order that the tables appear in the library.
When searching for a match, the code generator takes into account:
Related Examples
• “Customize Matching and Replacement Process for Functions”
• “Customize Matching and Replacement Process for Operators”
More About
• “Code Replacement Libraries”
• “Code Replacement Terminology”
22-14
Code Replacement Customization Limitations
Related Examples
• “Review and Test Code Replacements”
• “Specify Build Information for Replacement Code”
• “Replace MATLAB Functions with Custom Code Using coder.replace”
• “Develop a Code Replacement Library”
• “Quick Start Library Development”
More About
• “Code Replacement Libraries”
• “Code Replacement Terminology”
22-15
22 Code Replacement Customization for MATLAB Code
Related Examples
• “Replace MATLAB Functions with Custom Code Using coder.replace”
More About
• “What Is Code Replacement?”
• “What Is Code Replacement Customization?”
• “Code You Can Replace from MATLAB Code”
• “Code Replacement Libraries”
• “Code Replacement Terminology”
• “Code Replacement Customization Limitations”
22-16
Quick Start Library Development
Prerequisites
• MATLAB
• MATLAB Coder
• Embedded Coder
• C compiler
For instructions on installing MathWorks products, see the “Installation Guide”. If you
have installed MATLAB and want to see what other MathWorks products are installed,
in the Command Window, enter ver.
1 In the Code Replacement Tool window, select File > New table.
2 In the right pane, name the table crl_table_sinfcn and click Apply. Later, when
you save the table, the tool saves it with the file name crl_table_sinfcn.m.
22-17
22 Code Replacement Customization for MATLAB Code
Create a table entry that maps a sin function with double input and double output to
a custom implementation function.
1 In the left pane, select table crl_table_sinfcn. Then, select File > New entry >
Function. The new entry appears in the middle pane, initially without a name.
2 In the middle pane, select the new entry.
3 In the right pane, on the Mapping Information tab, from the Function menu,
select sin.
4 Leave Algorithm set to Unspecified, and leave parameters in the Conceptual
function group set to default values.
5 In the Replacement function group, name the replacement function sin_dbl.
6 Leave the remaining parameters in the Replacement function group set to default
values.
22-18
Quick Start Library Development
7 Click Apply. The tool updates the Function signature preview to reflect the
specified replacement function name.
8 Scroll to the bottom of the Mapping Information tab and click Validate entry.
The tool validates your entry.
22-19
22 Code Replacement Customization for MATLAB Code
22-20
Quick Start Library Development
1 On the Build Information tab, for the Implementation header file parameter,
enter sin_dbl.h.
2 Leave the remaining parameters set to default values.
3 Click Apply.
4 Optionally, you can revalidate the entry. Return to the Mapping Information tab
and click Validate entry.
Create an entry that maps a sin function with single input and double output to
a custom implementation function named sin_sgl. Create the entry by copying and
pasting the sin_dbl entry.
22-21
22 Code Replacement Customization for MATLAB Code
2 If the tool reports errors, fix them, and rerun the validation. Repeat fixing and
validating errors until the tool does not report errors. The following figure shows a
validation report.
Save the code replacement table to a MATLAB file in your working folder. Select File >
Save table. By default, the tool uses the table name to name the file. For this example,
the tool saves the table in the file crl_table_sinfcn.m.
Consider reviewing the MATLAB code for your code replacement table definition. After
using the tool to create an initial version of a table definition file, you can update,
enhance, or copy the file in a text editor.
To review it, in MATLAB or another text editor, open the file crl_table_sinfcn.m.
Before you can use your code replacement table, you must register it as part of a code
replacement library. Use the Code Replacement Tool to generate a registration file.
1 In the Code Replacement Tool, select File > Generate registration file.
2 In the Generate registration file dialog box, edit the dialog box fields to match the
following figure, and then click OK.
22-22
Quick Start Library Development
3 In the Select location dialog box, specify a location for the registration file. The
location must be on the MATLAB path or in the current working folder. Save the file.
The tool saves the file as rtwTargetInfo.m.
RTW.TargetRegistry.getInstance('reset');
Apply your code replacement library. Verify that the code generator makes code
replacements that you expect.
1 Check for errors. At the command line, invoke the table definition file . For example:
tbl = crl_table_sinfcn
tbl =
Version: '1.0'
ReservedSymbols: []
StringResolutionMap: []
AllEntries: [2x1 RTW.TflCFunctionEntry]
EnableTrace: 1
If an error exists in the definition file, the invocation triggers a message to appear.
Fix the error and try again.
2 Use the Code Replacement Viewer to check your code replacement entries. For
example:
In the viewer, select entries in your table and verify that the content is what you
expect. The viewer can help you detect issues such as:
22-23
22 Code Replacement Customization for MATLAB Code
function y = my_sin_fnc(x)
y = sin(x);
end
4 Create a project and name it my_sin_func.prj.
5 Add the function that includes a call to the sin function as an entry-point file and
define the input types. For example, add my_sin_func.m.
6 Configure the code generator to use the code replacement library that you created. In
the Project Settings dialog box, on the Hardware tab, set the Code replacement
library parameter to Sin Function Example.
7 Configure the code generation report for code replacement analysis. On the
Debugging tab, select:
22-24
Quick Start Library Development
The report indicates that the code generator found a match and applied the
replacement code for the function sin_dbl.
11 Review the code replacements. In the report, under Function replacements,
click the MATLAB function that triggered the replacement, my_sin_func.m.
The MATLAB Editor opens and highlights the function call that triggers the code
replacement.
22-25
22 Code Replacement Customization for MATLAB Code
Related Examples
• “Develop a Code Replacement Library”
More About
• “What Is Code Replacement?”
• “What Is Code Replacement Customization?”
• “Code You Can Replace from MATLAB Code”
• “Code Replacement Libraries”
• “Code Replacement Terminology”
• “Code Replacement Customization Limitations”
22-26
Identify Code Replacement Requirements
In this section...
“Mapping Information Requirements” on page 22-37
“Build Information Requirements” on page 22-38
“Registration Information Requirements” on page 22-38
• Math operation
• Function
• BLAS operation
• CBLAS operation
• Net slope fixed-point operation
• Semaphore or mutex functions
• Do you want to change the inline or nonfinite behavior for functions?
• What specific functions and operations do you want to replace?
• What input and output arguments does the function or operator that you are
replacing take? For each argument, what is the data type, complexity, and
dimensionality?
• What does the prototype for your replacement code look like?
22-27
22 Code Replacement Customization for MATLAB Code
• What is the data type, complexity, and dimensionality of each argument and
return value?
22-28
Identify Code Replacement Requirements
general TI device library as the base library for a more specific TI C28x device
library.
• Do you need to specify data alignment for the library? What data alignments are
required? For each specification, what type of alignment is required and for what
programming language?
Related Examples
• “Develop a Code Replacement Library”
• “Quick Start Library Development”
More About
• “What Is Code Replacement?”
• “What Is Code Replacement Customization?”
• “Code You Can Replace from MATLAB Code”
• “Code Replacement Libraries”
• “Code Replacement Terminology”
• “Code Replacement Customization Limitations”
22-29
22 Code Replacement Customization for MATLAB Code
• Common entries
• Entries for TI devices
• Entries for TI C6xx devices
• Entries specific to the TI C67x device
• If support files, such as header files, additional source files, and dynamically linked
libraries are not in your current working folder, note their location. You need to
specify the paths for such files.
Related Examples
• “Develop a Code Replacement Library”
• “Quick Start Library Development”
More About
• “What Is Code Replacement?”
• “What Is Code Replacement Customization?”
• “Code You Can Replace from MATLAB Code”
• “Code Replacement Libraries”
• “Code Replacement Terminology”
22-30
Define Code Replacement Mappings
The following table lists situations to help you decide when to use each approach.
Situation Approach
Defining mappings for the first Code Replacement Tool.
time.
Rapid prototyping mappings. Code Replacement Tool to quickly generate, register,
and test mappings.
Developing a mapping as a Code Replacement Tool to generate definition code
template or starting point for that you can copy and modify.
defining similar mappings.
Modifying a registration file, MATLAB Editor to update the programming interface
including copying and pasting directly.
content.
Defining mappings that specify Programming interface.
attributes not available from
the Code Replacement Tool
(for example, sets of algorithm
parameters).
22-31
22 Code Replacement Customization for MATLAB Code
The Custom button is available only for ERT-based targets. Although an Embedded
Coder license is not required to create a custom code replacement library, you must
have an Embedded Coder license to use a such a library.
By default, the tool displays, left to right, a root pane, a list pane, and a dialog pane. You
can manipulate the display:
• Drag boundaries to widen, narrow, shorten, or lengthen panes, and to resize table
columns.
• Select View > Show dialog pane to hide or display the rightmost pane.
• Click a table column heading to sort the table based on contents of the selected
column.
• Right-click a table column heading and select Hide to remove the column from the
display. (You cannot hide the Name column.)
1 In the Code Replacement Tool window, select File > New table.
22-32
Define Code Replacement Mappings
2 In the right pane, name the table and click Apply. Later, when you save the table,
the tool uses the table name that you specify to name the file. For example, if you
enter the name my_sinfcn, the tool names the file my_sinfcn.m.
Create one or more table entries. Each entry maps the conceptual representation of a
function or operator to your implementation representation. The information that you
enter depends on the type of entry you create. You must enter the following information:
1 In the left pane, select the table to which you want to add the entry.
2 Select File > New entry > entry-type, where entry-type is one of:
• Math Operation
• Function
• BLAS Operation
• CBLAS Operation
• Net Slope Fixed Point Operation
• Semaphore entry
• Customization entry
The new entry appears in the middle pane, initially without a name.
3 In the middle pane, select the new entry.
4 In the right pane, on the Mapping Information tab, from the Function or
Operation menu, select the function or operation that you want the code generator
to replace. Regardless of the entry type, you must make a selection from this menu.
Your selection determines what other information you specify.
With the exception of customization entries, you also specify information for your
replacement function prototype. You can also specify implementation attributes,
such as the rounding modes to apply.
5 If prompted, specify additional entry information that you want the code generator
to use when searching for a match. For example, when you select an addition or
subtraction operation, the tool prompts you to specify an algorithm (Cast before
operation or Cast after operation).
6 Review the conceptual argument information that the tool populates for the function
or operation. Conceptual input and output arguments represent arguments for
22-33
22 Code Replacement Customization for MATLAB Code
If you do not want the data types for your implementation to be the same as the
conceptual argument types, clear the Make the conceptual and implementation
argument types the same check box. For example, most ANSI-C functions
operate on and return double data. Clear the check box if want to map a conceptual
representation of the function, such as sin, which specifies an argument and
return value of type single (single sin(single)), to an implementation
representation that specifies an argument and return value of type double (double
sin(double). In this case, the code generator produces the following code:
y = (single) sin(u1);
If you select Custom for a function entry, specify only conceptual argument
information.
7 Specify the name and argument information for your replacement function. As you
enter the information and click Apply, the tool updates the Function signature
preview.
8 Specify additional implementation attributes that apply. For example, depending on
the type and name of the entry that you specify, the tool prompts you to specify:
The Code Replacement Tool provides a way to validate the syntax of code replacement
tables and table entries as you define them. If the tool finds validation errors, you can
address them and retry the validation. Repeat the process until the tool does not report
errors.
To... Do...
Validate table entries Select an entry, scroll to the bottom of the Mapping
Information tab, and click Validate entry.
22-34
Define Code Replacement Mappings
To... Do...
Alternatively, select one or more entries, right-click,
and select Validate entries.
Validate a table Select the table. Then, select Actions > Validate
table.
Save a Table
If you open multiple tables, you can manage the tables together. For example, use the
tool to:
22-35
22 Code Replacement Customization for MATLAB Code
1 Create a table definition file that contains a function definition. For example:
function hTable = crl_table_sinfcn()
2 Within the function body, create the table by calling the function RTW.TflTable.
hTable = RTW.TflTable;
For each function or operator that you want the code generator to replace, map
a conceptual representation of the function or operator to an implementation
representation as a table entry.
1 Within the body of a table definition file, create a code replacement entry object. Call
one of the following functions:
22-36
Define Code Replacement Mappings
For example:
hEnt = RTW.TflCFunctionEntry;
You can combine steps of creating the entry, setting entry parameters, creating
conceptual and implementation arguments, and adding the entry to a table with a
single function call to registerCFunctionEntry, registerCPPFunctionEntry, or
registerCPromotableMacroEntry if you are creating an entry for a function and the
function implementation meets the following criteria:
• Implementation argument names and order match the names and order of
corresponding conceptual arguments.
• Input arguments are of the same type.
• The return and input argument names follow the code generator’s default naming
conventions:
For example:
Set entry parameters, such as the priority, algorithm information, and implementation
(replacement) function name. Call the function listed in the following table for the entry
type that you created.
22-37
22 Code Replacement Customization for MATLAB Code
To see a list of the parameters that you can set, at the command line, create a new entry
and omit the semicolon at the end of the command. For example:
hEnt = RTW.TflCFunctionEntry
hEnt =
22-38
Define Code Replacement Mappings
RoundingModes: {'RTW_ROUND_UNSPECIFIED'}
TypeConversionMode: 'RTW_EXPLICIT_CONVERSION'
AcceptExprInput: 1
SideEffects: 0
UsageCount: 0
RecordedUsageCount: 0
Description: ''
StoreFcnReturnInLocalVar: 0
TraceManager: [1x1 RTW.TflTraceManager]
ans =
HeaderFile: ''
SourceFile: ''
HeaderPath: ''
SourcePath: ''
Return: []
StructFieldMap: []
Name: ''
Arguments: [0x1 handle]
ArgumentDescriptor: []
For example, to set entry parameters for the sin function and name your replacement
function sin_dbl, use the following function call:
setTflCFunctionEntryParameters(hEnt, ...
'Key', 'sin', ...
'ImplementationName', 'sin_dbl');
Create conceptual arguments and add them to the entry’s array of conceptual arguments.
22-39
22 Code Replacement Customization for MATLAB Code
1 Identify whether the argument is for input or output, the name, and data type. If you
do not know what arguments to specify for a supported function or operation, use the
Code Replacement Tool to find them. For example, to find the conceptual arguments
for the sin function, open the tool, create a table, create a function entry, and in the
Function menu select sin.
2 Create and add the conceptual argument to an entry. You can choose a method from
the methods listed in this table.
If Then
You want simpler code or Call the function createAndAddConceptualArg. For
want to explicitly specify example:
whether the argument
is scalar or nonscalar createAndAddConceptualArg(hEnt, ...
(vector or matrix).
'RTW.TflArgNumeric', ...
'Name', 'y1',...
'IOType', 'RTW_IO_OUTPUT',...
'DataTypeMode', 'double');
The following code shows the conceptual output and input argument definitions for the
sin function:
% Conceptual Args
22-40
Define Code Replacement Mappings
Create implementation arguments for the C or C++ replacement function and add them
to the entry.
• When replacing code, the code generator uses the argument names to determine how
it passes data to the implementation function.
• For function replacements, the order of implementation argument names must match
the order of the conceptual argument names.
• For operator replacements, the order of implementation argument names do not
have to match the order of the conceptual argument names. For example, for an
operator replacement for addition, y1=u1+u2, the conceptual arguments are y1, u1,
and u2, in that order. If the signature of your implementation function is t myAdd(t
u2, t u1), where t is a valid C type, based on the argument name matches, the
code generator passes the value of the first conceptual argument, u1, to the second
implementation argument of myAdd. The code generator passes the value of the
second conceptual argument, u2, to the first implementation argument of myAdd.
• For operator replacements, you can remap operator output arguments to
implementation function input arguments.
1 Identify whether the argument is for input or output, the name, and the data type.
2 Create and add the implementation argument to an entry. You can choose a method
from the methods listed in this table.
If Then
You want to populate Call the function
implementation copyConceptualArgsToImplementation. For example:
arguments as copies
of previously created copyConceptualArgsToImplementation(hEnt);
matching conceptual
arguments
22-41
22 Code Replacement Customization for MATLAB Code
If Then
You want to create and Call functions createAndSetCImplementationReturn
add implementation andcreateAndAddImplementationArg . For example:
arguments individually,
or vary argument createAndSetCImplementationReturn(hEnt,
attributes, while 'RTW.TflArgNumeric', ...
'Name', 'y1', ...
maintaining conceptual 'IOType', 'RTW_IO_OUTPUT', ...
argument order 'IsSigned', true, ...
'WordLength', 32, ...
'FractionLength', 0);
createAndAddImplementationArg(op_entry,
'RTW.TflArgNumeric',...
'Name', 'u1', ...
'IOType', 'RTW_IO_INPUT',...
'IsSigned', true,...
'WordLength', 32, ...
'FractionLength', 0 );
22-42
Define Code Replacement Mappings
If Then
You want to minimize Create the argument with a call to the function
the amount of code, getTflArgFromString. Then, use the convenience
or specify constant method setReturn or addArgument to specify whether
arguments to pass to an argument is a return value or argument and to add
the implementation the argument to the entry’s array of implementation
function arguments. For example:
arg = getTflArgFromString(hEnt, 'y1','double');
arg.IOType = 'RTW_IO_OUTPUT';
hEnt.Implementation.setReturn(arg);
22-43
22 Code Replacement Customization for MATLAB Code
The following code shows the implementation output and input argument definitions
for the sin function:
% Implementation Args
arg = hEnt.getTflArgFromString('y1','double');
arg.IOType = 'RTW_IO_OUTPUT';
hEnt.Implementation.setReturn(arg);
arg = hEnt.getTflArgFromString('u1','double');
hEnt.Implementation.addArgument(arg);
addEntry(hTable, hEnt);
Validate an Entry
After you create or modify a code replacement table entry, validate it by invoking it at
the MATLAB command line. For example:
hTbl = crl_table_sinfcn
hTbl =
RTW.TflTable
Version: '1.0'
AllEntries: [2x1 RTW.TflCFunctionEntry]
ReservedSymbols: []
StringResolutionMap: []
If the table includes errors, MATLAB reports them. The following examples shows how
MATLAB reports a typo in a data type name:
hTbl = crl_table_sinfcn
22-44
Define Code Replacement Mappings
Save a Table
Save the table definition file. Use the name of the table definition function to name the
file, for example, crl_table_sinfcn.m.
Related Examples
• “Identify Code Replacement Requirements”
• “Prepare for Code Replacement Library Development”
• “Specify Build Information for Replacement Code”
• “Register Code Replacement Mappings”
• “Develop a Code Replacement Library”
• “Quick Start Library Development”
• “Math Function Code Replacement”
• “Memory Function Code Replacement”
• “Specify In-Place Code Replacement”
• “Replace MATLAB Functions with Custom Code Using coder.replace”
• “Reserved Identifiers and Code Replacement”
• “Customize Matching and Replacement Process for Functions”
• “Scalar Operator Code Replacement”
• “Addition and Subtraction Operator Code Replacement”
• “Small Matrix Operation to Processor Code Replacement”
• “Matrix Multiplication Operation to MathWorks BLAS Code Replacement”
• “Matrix Multiplication Operation to ANSI/ISO C BLAS Code Replacement”
• “Remap Operator Output to Function Input”
• “Customize Matching and Replacement Process for Operators”
• “Fixed-Point Operator Code Replacement”
• “Binary-Point-Only Scaling Code Replacement”
• “Slope Bias Scaling Code Replacement”
• “Net Slope Scaling Code Replacement”
• “Equal Slope and Zero Net Bias Code Replacement”
• “Data Type Conversions (Casts) and Operator Code Replacement”
22-45
22 Code Replacement Customization for MATLAB Code
More About
• “Code You Can Replace from MATLAB Code”
• “Code Replacement Libraries”
• “Code Replacement Terminology”
• “Code Replacement Customization Limitations”
22-46
Specify Build Information for Replacement Code
The following table lists situations to help you decide when to use each approach.
Situation Approach
Creating code replacement Code Replacement Tool.
entries for the first time.
You used the Code Replacement Code Replacement Tool to quickly specify the build
Tool to create the entries for information.
which the build information
applies.
Rapid prototyping entries. Code Replacement Tool to quickly generate, register,
and test entries.
Developing an entry to use as Code Replacement Tool to generate entry code that
a template or starting point for you can copy and modify.
defining similar entries.
22-47
22 Code Replacement Customization for MATLAB Code
Situation Approach
Modifying existing mappings. MATLAB Editor to update the programming interface
directly.
• If you use the programming interface, paths that you specify can include tokens.
A token is a variable defined as a string or cell array of strings in the MATLAB
workspace that you enclose with dollar signs ($variable$). The code generator
evaluates and replaces a token with the defined value. For example, consider the
path $myfolder$\folder1, where myfolder is a string variable defined in the
MATLAB workspace as 'd:\work\source\module1'. The code generator generates
the custom path as d:\work\source\module1\folder1.
• If an entry uses header, source, or object files that reside in a folder other than the
build folder, you must copy the files to the build folder before the code generator can
build the code. The Code Replacement Tool and programming information provide a
way to specify this copy operation.
Field Specify
Implementation header file File name and extension for the header file
the code generator needs to generate the
replacement code. For example, sin_dbl.h.
22-48
Specify Build Information for Replacement Code
Field Specify
Implementation source file File name and extension for the C or C++ source
file the code generator needs to generate the
replacement code. For example, sin_dbl.c.
Additional header files/include Paths and file names for additional header
paths files the code generator needs to generate
the replacement code. For example, C:\libs
\headerFiles and C:\libs\headerFiles
\common.h.
Additional source files/ paths Paths and file names for additional source
files the code generator needs to generate
the replacement code. For example, C:
\libs\srcFiles and C:\libs\srcFiles
\common.c.
Additional object files/ paths Paths and file names for additional object files
the linker needs to build the replacement code.
For example, C:\libs\objFiles and C:
\libs\objFiles\common.obj.
Additional link flags Flags the linker needs to generate an executable
file for the replacement code.
Additional compile flags Flags the compiler needs to generate object code
for the replacement code.
Copy files to build directory Whether the code generator needs to copy
header, source, or object files from an external
location to the build folder before building the
replacement code.
6 Click Apply.
7 Select the Mapping Information tab. Scroll to the bottom of that table and click
Validate entry. The tool validates the changes that you made to the entry.
8 Save the table that includes the entry that you just modified.
22-49
22 Code Replacement Customization for MATLAB Code
1 Identify or create the code replacement entry that you want to specify the build
information.
2 Determine what information to specify.
3 Specify your build information.
Specify Action
Implementation Use one of the following:
header file
• Set properties ImplementationHeaderFile
and ImplementationHeaderPath in a call
to setTflCFunctionEntryParameters,
setTflCOperationEntryParameters, or
setTflCSemaphoreEntryParameters. For example:
setTflCFunctionEntryParameters(hEnt, ...
'ImplementationHeaderFile', 'sin_dbl.h', ...
'ImplementationHeaderPath', 'D:/lib/headerFiles'
'Key', 'sin', ...
'ImplementationName', 'sin_dbl');
• Set argument headerFile in a call to
registerCFunctionEntry, registerCPPFunctionEntry, or
registerCPromotableMacroEntry
Implementation Set properties ImplementationSourceFile
source file and ImplementationSourcePath in a call
to setTflCFunctionEntryParameters,
setTflCOperationEntryParameters, or
setTflCSemaphoreEntryParameters. For example:
setTflCFunctionEntryParameters(hEnt, ...
'ImplementationHeaderFile', 'sin_dbl.c', ...
'ImplementationHeaderPath', 'D:/lib/sourceFiles'
'Key', 'sin', ...
'ImplementationName', 'sin_dbl');
22-50
Specify Build Information for Replacement Code
Specify Action
Additional header For each file, specify the file name and path in calls to the functions
files/include paths addAdditionalHeaderFile and addAdditionalIncludePath. For
example:
libdir = fullfile('$(MATLAB_ROOT)','..', '..', 'lib');
hEnt = RTW.TflCFunctionEntry;
addAdditionalHeaderFile(hEnt, 'common.h');
addAdditionalIncludePath(hEnt, fullfile(libdir, 'include'));
Additional source For each file, specify the file name and path in calls to the functions
files/paths addAdditionalSourceFile and addAdditionalSourcePath. For
example:
libdir = fullfile('$(MATLAB_ROOT)','..', '..', 'lib');
hEnt = RTW.TflCFunctionEntry;
addAdditionalSourceFile(hEnt, 'common.c');
addAdditionalSourcePath(hEnt, fullfile(libdir, 'src'));
Additional object For each file, specify the file name and path in calls to the functions
files/paths addAdditionalLinkObj and addAdditionalLinkObjPath. For
example:
libdir = fullfile('$(MATLAB_ROOT)','..', '..', 'lib');
hEnt = RTW.TflCFunctionEntry;
addAdditionalLinkObj(hEnt, 'sin.o');
addAdditionalLinkObjPath(hEnt, fullfile(libdir, 'bin'));
Compile flags Set the entry property AdditionalCompileFlags to a cell array of strings
representing the required compile flags. For example:
hEnt = RTW.TflCFunctionEntry;
22-51
22 Code Replacement Customization for MATLAB Code
Specify Action
Link flags Set the entry property AdditionalLinkFlags to a cell array of strings
representing the required link flags. For example:
hEnt = RTW.TflCFunctionEntry;
setTflCFunctionEntryParameters(hEnt, ...
'ImplementationHeaderFile', 'sin_dbl.h', ...
'ImplementationHeaderPath', 'D:/lib/headerFiles'
'Key', 'sin', ...
'ImplementationName', 'sin_dbl'
'GenCallback', 'RTW.copyFileToBuildDir');
• Set argument genCallback in a call to
registerCFunctionEntry, registerCPPFunctionEntry,
or registerCPromotableMacroEntry to
'RTW.copyFileToBuildDir'.
After generating the C or C++ code, the code generator calls the function
RTW.copyFileToBuildDir. The specified files are then available for the
remaining steps of the build process.
4 Save the table that includes the entry that you added or modified.
The following example defines a table entry for an optimized multiplication function
that takes signed 32-bit integers and returns a signed 32-bit integer, taking saturation
into account. Multiplications in the generated code are replaced with calls to the
optimized function. The optimized function does not reside in the build folder. For the
code generator to access the files, they must be copied into the build folder to be compiled
and linked into the application.
The table entry specifies the source and header file names and paths. To request the
copy operation, the table entry sets the genCallback to 'RTW.copyFileToBuildDir'
in the call to the setTflCOperationEntryParameters function. In this example,
22-52
Specify Build Information for Replacement Code
the header file s32_mul.h contains an inlined function that invokes assembly
functions contained in s32_mul.s. If a match occurs for the table entry, the function
RTW.copyFileToBuildDir copies the specified source and header files to the build
folder.
function hTable = make_my_crl_table
hTable = RTW.TflTable;
op_entry = RTW.TflCOperationEntry;
setTflCOperationEntryParameters(op_entry, ...
'Key', 'RTW_OP_MUL', ...
'Priority', 100, ...
'SaturationMode', 'RTW_SATURATE_ON_OVERFLOW', ...
'RoundingModes', {'RTW_ROUND_UNSPECIFIED'}, ...
'ImplementationName', 's32_mul_s32_s32_sat', ...
'ImplementationHeaderFile', 's32_mul.h', ...
'ImplementationSourceFile', 's32_mul.s', ...
'ImplementationHeaderPath', {fullfile('$(MATLAB_ROOT)','crl')}, ...
'ImplementationSourcePath', {fullfile('$(MATLAB_ROOT)','crl')}, ...
'GenCallback', 'RTW.copyFileToBuildDir');
.
.
.
addEntry(hTable, op_entry);
op_entry = RTW.TflCOperationEntry;
setTflCOperationEntryParameters(op_entry, ...
'Key', 'RTW_OP_ADD', ...
'Priority', 90, ...
'SaturationMode', 'RTW_SATURATE_UNSPECIFIED', ...
'RoundingModes', {'RTW_ROUND_UNSPECIFIED'}, ...
'ImplementationName', 's32_add_s32_s32', ...
'ImplementationHeaderFile', 's32_add_s32_s32.h', ...
'ImplementationSourceFile', 's32_add_s32_s32.c'...
'GenCallback', 'RTW.copyFileToBuildDir');
addAdditionalHeaderFile(op_entry, 'all_additions.h');
addAdditionalIncludePath(op_entry, fullfile(libdir, 'include'));
addAdditionalSourceFile(op_entry, 'all_additions.c');
addAdditionalSourcePath(op_entry, fullfile(libdir, 'src'));
22-53
22 Code Replacement Customization for MATLAB Code
addAdditionalLinkObj(op_entry, 'addition.o');
addAdditionalLinkObjPath(op_entry, fullfile(libdir, 'bin'));
.
.
.
addEntry(hTable, op_entry);
Related Examples
• “Identify Code Replacement Requirements”
• “Prepare for Code Replacement Library Development”
• “Define Code Replacement Mappings”
• “Register Code Replacement Mappings”
• “Develop a Code Replacement Library”
• “Quick Start Library Development”
More About
• “What Is Code Replacement Customization?”
• “Code Replacement Libraries”
• “Code Replacement Terminology”
• “Code Replacement Customization Limitations”
22-54
Register Code Replacement Mappings
The following table lists situations when you might consider one approach over the other.
If... Then...
Registering a code replacement Use the Code Replacement Tool.
table for the first time
You used the Code Replacement Use the Code Replacement Tool to quickly register the
Tool to create the table table.
Rapid prototyping code Use the Code Replacement Tool to quickly generate,
replacement register, and test entries.
Creating registration file to use Use the Code Replacement Tool to generate code that
as a template or starting point you can copy and modify.
for defining similar registration
files
22-55
22 Code Replacement Customization for MATLAB Code
If... Then...
Modifying existing registration Use the MATLAB Editor to update the registration
files file.
Defining multiple code Use the MATLAB Editor to create a new or extend an
replacement libraries in one existing registration file.
registration file
Defining code replacement Use the MATLAB Editor to create a new or extend an
library hierarchy in a existing registration file.
registration file
1 After you validate and save a code replacement table, select File > Generate
registration file to open the Generate registration file dialog box.
22-56
Register Code Replacement Mappings
For... Specify...
Registry name String naming the code replacement library. For example,
Sin Function Example.
Table list Strings naming one or more code replacement tables to
include in the library. Specify each table as one of the
following:
You can specify multiple tables. If you do, separate the table
specifications with a comma. For example:
crl_table_sinfcn, c:/work_crl/crl_table_muldiv
For... Specify...
Description Text string that describes the purpose and content of the
library.
Target HW device Strings naming one or more hardware devices the code
replacement library supports. Separate names with a
comma. To support all device types, enter an asterisk (*). For
example, TI C28x, TI C62x.
Base CRL String naming a code replacement library that you want to
serve as a base library for the library you are registering.
Use this field to specify library hierarchies. For example,
you can specify a general TI device library as the base
library for a more specific TI C28x device library.
22-57
22 Code Replacement Customization for MATLAB Code
For... Specify...
Generate data Flag that enables data alignment specification.
alignment
specification
The basic workflow for creating a registration file programmatically consists of the
following steps:
function rtwTargetInfo(cm)
cm.registerTargetInfo(@loc_register_tfl);
this(1) = RTW.TflRegistry;
this(1).Name = 'crl-name';
this(1).TableList = {'table',...};
For... Replace...
this(1).Name = 'crl-name'; crl-name with a string naming the code
replacement library. For example, Sin
Function Example.
this(1).TableList = table with a string that identifies the code
{'table',...}; replacement table that contains your code
replacement entries. Specify a table as one of
the following:
22-58
Register Code Replacement Mappings
For... Replace...
• Name of a table file on the MATLAB search
path
• Absolute path to a table file
• Path to a table file relative to
$(MATLAB_ROOT)
For... Replace...
this(1).Description = text with a string that describes the purpose
'text' and content of the library.
this(1).TargetHWDeviceType device-type with a string that names a
= {'device-type',...} hardware device the code replacement library
supports. You can specify multiple device
types. Separate device types with a comma. For
example, TI C28x, TI C62x. To support all
device types, enter an asterisk (*).
this(1).BaseTfl = 'base- base-lib with a string that names a code
lib' replacement library that you want to serve as a
base library for the library you are registering.
Use this field to specify library hierarchies.
For example, you can specify a general TI
device library as the base library for a TI
C28x device library.
22-59
22 Code Replacement Customization for MATLAB Code
For example:
function rtwTargetInfo(cm)
cm.registerTargetInfo(@loc_register_tfl);
this(1) = RTW.TflRegistry;
this(1).Name = 'Sin Function Example';
this(1).TableList = {'crl_table_sinfcn'};
this(1).TargetHWDeviceType = {'*'};
this(1).Description = 'Example - sin function replacement';
2 Save the file with the name rtwTargetInfo.m.
3 Place the file on the MATLAB path. When the file is on the MATLAB path, the code
generator reads the file after starting and applies the customizations during the
current MATLAB session.
sl_refresh_customizations
cm.registerTargetInfo(@locCrlRegFcn);
22-60
Register Code Replacement Mappings
cm.registerTargetInfo(@locCrlRegFcn);
22-61
22 Code Replacement Customization for MATLAB Code
Related Examples
• “Define Code Replacement Mappings”
• “Specify Build Information for Replacement Code”
• “Develop a Code Replacement Library”
• “Quick Start Library Development”
• “Deploy Code Replacement Library”
More About
• “What Is Code Replacement?”
• “What Is Code Replacement Customization?”
• “Code Replacement Libraries”
• “Code Replacement Terminology”
22-62
Review and Test Code Replacements
ans =
MATLAB displays errors that it finds. In the following example, MATLAB detects a typo
in a data type name.
isvalid(crl_table_sinfcn)
22-63
22 Code Replacement Customization for MATLAB Code
1 Open the viewer. At the MATLAB command line, enter the following command,
where table is the name of the code replacement table you want to review:
RTW.viewTfl(table)
For example,
RTW.viewTfl(crl_table_sinfcn)
2 Select entries in the table and verify that the display of the contents meets your
expectations. For example:
22-64
Review and Test Code Replacements
1 Open the viewer. At the MATLAB command line, enter the following command,
where library is the name of the code replacement library you want to review:
RTW.viewTfl('library')
For example:
RTW.viewTfl('Sin Function Example')
22-65
22 Code Replacement Customization for MATLAB Code
• You might need to refresh the library registration information. Initiate a refresh
with the following command:
RTW.TargetRegistry.getInstance('reset')
2 Select your library and examine and compare its tables. Common problems that you
can detect include:
• Relative order of tables in the library is not correct (by default, the tool displays
tables in search order)
• Table entry problems as listed in the previous section
• Check the Code Replacement Report section of the code generation report for expected
replacements
• Trace code replacements
The Code Replacement Report details the code replacement library functions that
the code generator uses for code replacements during code generation. It provides a
mapping between each replacement instance and the line of MATLAB code that triggered
the replacement. The Code Replacements report is not available for generated MEX
functions.
1 Identify an existing or create a new MATLAB function for which you want the code
generator to replace code. For example:
function y = my_sin_fnc(x)
y = sin(x);
end
2 On the project Build tab, set the Output type to generate a library or executable.
3 Click More Settings to open the Project Settings dialog block.
4 Configure the code generator to use your code replacement library. On the
Hardware tab, set the Code replacement library parameter to the name of your
library. For example, Sin Function Example.
22-66
Review and Test Code Replacements
5 Configure the code generation report. On the Debugging tab, set the Always
create a code generation report, Code replacements, and Automatically
launch a report if one is generated parameters.
6 Configure the code generator to generate code only. On the Build tab, set the
Generate code only parameter. You want to review your code replacements in the
generated code before building an executable.
7 Click Build to generate replacement code and a report.
8 Open the Code Replacements Report section of the code generation report. That
report lists the replacement functions that the code generator used, and provides a
mapping between each replacement instance and the MATLAB code that triggered
the replacement.
22-67
22 Code Replacement Customization for MATLAB Code
• Click the link that opens the Code Replacement Viewer. In the viewer, review
code replacement hits and misses.
Code replacement can behave differently than you expect. To verify code replacements,
first inspect the generated code, as described in “Review and Trace Code Replacements
Generated Using a Code Replacement Library” on page 22-66.
• “View Cache Hits and Misses Using Viewer Trace Information” on page 22-68
• “View Cache Hits and Misses Using Command-Line” on page 22-69
For models that consist of model hierarchies, you must generate code for and review
the trace information of each referenced model separately (stand alone). Logged cache
hit and miss information captured in the Code Replacement Viewer is valid for the
last model for which code was generated only. The code generator overwrites logged
information as you generate code for each model in the hierarchy.
When debugging a code replacement table entry, you can use hit and miss information
in the Code Replacement Viewer to help determine why the code generator did not use a
replacement function in the generated code.
1 On the project Build tab, set the Output type to generate a library or executable.
2 Configure the code generator to use your code replacement library. In a project, on
the Hardware tab, set the Code Replacement Library parameter to the name of
your library.
22-68
Review and Test Code Replacements
3 Configure the code generation report. In a project, on the Build > More Settings
> Debugging tab, set the Always create a code generation report, Code
replacements, and Automatically launch a report if one is generated
parameters.
4 Generate replacement code and a report. A complete rebuild of code is required to
display cache hits and misses.
5 Open the Code Replacements Report section of the code generation report. Click
the link for opening the Code Replacement Viewer.
6 In the left pane of the viewer, select the code replacement table you want to examine.
In the middle pane, the viewer lists information for entries in the table, including
a usage count, which is the number of times the table entry was matched and its
replacement function used during code generation.
7 In the middle pane, select the table entry to examine. In the right pane, the viewer
displays General Information and Trace Information about the table entry.
8 In the right pane, select the Trace Information tab. The Trace Information tab
lists Hit Source Locations and Miss Source Locations. The display provides
links to each source location (the source for which code replacement was considered)
and, for misses, lists a Miss Reason. If an expected replacement does not occur,
you can use the hit and miss information to modify the match criteria in the code
replacement table entry.
To display the code replacement cache hits and misses logged during the most recent
code generation session in the command window, use the following command:
>> crl=get_param('model', 'TargetFcnLibHandle')
Field Description
HitCache Table containing code replacement entries that were matched
during a code generation session. These entries represent function
implementations that should appear in the generated code.
MissCache Table containing code replacement entries that failed to match during a
code generation session. These entries are created by the code generation
process for the purpose of querying the library to locate a registered
implementation.
22-69
22 Code Replacement Customization for MATLAB Code
In the following example, the most recent code generation session logged one cache hit
and zero cache misses. You can examine the logged HitCache entry using its table index.
a=get_param('my_sin_func','TargetFcnLibHandle')
a =
RTW.TflControl
Version: '1.0'
HitCache: [2x1 RTW.TflCFunctionEntry]
MissCache: []
TLCCallList: [0x1 handle]
TflTables: [10x1 RTW.TflTable]
TargetHWWordLengths: '8,16,32,32'
SupportNonFinite: 1
TLCSupported: 1
Recording: 0
LoadedLibrary: 'Sin Function Example'
TargetCharacteristics: [1x1 RTW.TargetCharacteristics]
CurrentHWDevice: 'Specified'
a.HitCache(1)
ans =
22-70
Review and Test Code Replacements
EntryInfo: []
GenCallback: ''
GenFileName: ''
SaturationMode: 'RTW_SATURATE_UNSPECIFIED'
RoundingModes: {'RTW_ROUND_UNSPECIFIED'}
TypeConversionMode: 'RTW_EXPLICIT_CONVERSION'
AcceptExprInput: 0
SideEffects: 0
UsageCount: 3
RecordedUsageCount: 0
Description: ''
StoreFcnReturnInLocalVar: 0
TraceManager: [1x1 RTW.TflTraceManager]
Related Examples
• “Choose a Code Replacement Library”
• “Replace Code Generated from MATLAB Code”
• “Code Generation Reports”
• “Tracing Between Generated C Code and MATLAB Code”
• “Code Verification Through Software-in-the-Loop and Processor-in-the-Loop
Execution”
• “Code Generation Workflow”
• “Program Builds”
• “Develop a Code Replacement Library”
• “Quick Start Library Development”
More About
• “Code Replacement Libraries”
• “Code Replacement Terminology”
• “Code Replacement Customization Limitations”
22-71
22 Code Replacement Customization for MATLAB Code
1 Move your code replacement table files to an area that is on the MATLAB search
path and that is accessible to and shared by other users.
2 Move the rtwTargetInfo.m registration file, to an area that is on the MATLAB
search path and that is accessible to and shared by other users. If you are deploying
a library to a folder in a development environment that already contains a
rtwTargetInfo.m file, copy the registration code from your code replacement
library version of rtwTargetInfo.m and paste it into the shared version of that file.
3 Register the library customizations or restart MATLAB.
4 Verify that the libraries are available for configuring the code generator and that
code replacements occur as expected.
5 Inform users that the libraries are available and provide direction on when and how
to apply them.
Related Examples
• “Review and Test Code Replacements”
• “Develop a Code Replacement Library”
More About
• “What Is Code Replacement?”
• “What Is Code Replacement Customization?”
• “Code Replacement Libraries”
• “Code Replacement Terminology”
22-72
Math Function Code Replacement
hTable = RTW.TflTable;
3 Create an entry for the function mapping with a call to the
RTW.TflCFunctionEntry function.
5 Create conceptual arguments y1 and u1. This example uses calls to the
createAndAddConceptualArg function to create and add an argument with one
function call.
createAndAddConceptualArg(fcn_entry, 'RTW.TflArgNumeric', ...
'Name', 'y1',...
'IOType', 'RTW_IO_OUTPUT',...
'DataTypeMode', 'double');
22-73
22 Code Replacement Customization for MATLAB Code
copyConceptualArgsToImplementation(fcn_entry);
7 Add the entry to a code replacement table with a call to the addEntryfunction.
addEntry(hTable, fcn_entry);
Related Examples
• “Define Code Replacement Mappings”
• “Specify In-Place Code Replacement”
• “Reserved Identifiers and Code Replacement”
• “Customize Matching and Replacement Process for Functions”
• “Develop a Code Replacement Library”
• “Quick Start Library Development”
More About
• “Code You Can Replace from MATLAB Code”
• “Code Replacement Terminology”
22-74
Memory Function Code Replacement
5 Create conceptual arguments y1, u1, u2, and u3. This example uses calls to the
getTflArgFromString and addConceptualArg functions to create and add the
arguments.
arg = getTflArgFromString(hTable, 'y1', 'void*');
arg.IOType = 'RTW_IO_OUTPUT';
addConceptualArg(fcn_entry, arg);
22-75
22 Code Replacement Customization for MATLAB Code
7 Add the entry to a code replacement table with a call to the addEntryfunction.
addEntry(hTable, fcn_entry);
Related Examples
• “Define Code Replacement Mappings”
• “Specify In-Place Code Replacement”
• “Reserved Identifiers and Code Replacement”
• “Customize Matching and Replacement Process for Functions”
• “Develop a Code Replacement Library”
• “Quick Start Library Development”
More About
• “Code You Can Replace from MATLAB Code”
• “Code Replacement Terminology”
22-76
Specify In-Place Code Replacement
In this section...
“In-Place Code Replacement” on page 22-77
“Argument Specification Requirements” on page 22-77
“Interactive Argument Replacement Specification with Code Replacement Tool” on page
22-77
“Programmatic Argument Replacement Specification” on page 22-81
When you generate C or C++ code from MATLAB code, the code generator supports
in-place function argument code replacement. When you interactively create a code
replacement table entry with the Code Replacement Tool, you can specify in-place
function argument replacement. You can also specify in-place function argument
replacement programmatically with the Code Replacement Library API.
22-77
22 Code Replacement Customization for MATLAB Code
function x = customFunction(x)
% Function that updates the input and returns it as an output
coder.replace('-errorifnoreplacement');
x = sin(x);
2 In the Code Replacement Tool, add a new table, select that table, and add a new
function entry. For more information, see “Define Code Replacement Mappings”.
3 On the Mapping Information tab, select Custom for the Function parameter.
4 In the function-name text box, name the custom function. For this example, type
the name customFunction.
5 Under the Conceptual arguments list box, click + to add two arguments. By
default, the tool creates an output argument y1 and an input argument u1, both of
type double.
6 In the Replacement function > Function prototype section, type the name
custom_function_inplace_impl in the Name text box.
7 Under the Function arguments list box, click + to add two function
implementation arguments. By default, the tool creates an output argument y1 and
an input argument u1, both of type double.
8 For each input argument that you want to specify as in-place with a corresponding
output argument, in the Argument properties box, select the Pointer check box.
The Argument properties section of the dialog box expands to include an In-place
argument drop-down list. For this example, in the Function arguments list, select
input argument u1, and then select the Pointer check box.
22-78
Specify In-Place Code Replacement
9 From the In-place argument list, select y1, the output argument for the code
replacement mapping. The Function arguments list box is updated to show
possible in-place argument mappings.
22-79
22 Code Replacement Customization for MATLAB Code
10 Select and delete one of the two possible argument mappings. For this example,
delete the mapping y1<-->u1.
11 In the Function signature preview box, if the function signature appears as
expected, click Apply. Otherwise, make adjustments, and then click Apply. The
function signature for this example, appears as
1 Register the table that contains the entry in a code replacement library.
2 Configure the code generator to use a code replacement library and to include the
Code Replacements Report in the code generation report.
3 Generate the replacement code and a code generation report.
4 Review the code replacements.
22-80
Specify In-Place Code Replacement
• Sets the name of the implementation argument to the same name as the
corresponding conceptual argument.
• Associates the corresponding implementation argument with the argument property
ArgumentForInPlaceUse.
function y = customFunction(x)
% Function that updates the input and returns it as an output
coder.replace('-errorifnoreplacement');
x = sin(x);
2 Define a function for the definition.
hTable = RTW.TflTable;
4 Create an entry for the function mapping with a call to the
RTW.TflCFunctionEntry function.
hEnt = RTW.TflCFunctionEntry;
5 Set function entry parameters with a call to the
setTflCFunctionEntryParameters function.
setTflCFunctionEntryParameters(hEnt, ...
'Key', 'customFunction', ...
'Priority', 100, ...
'ImplementationName', 'custom_function_inplace_impl', ...
'SideEffects', true);
6 Create conceptual arguments y1 and u1. This example uses calls to the
getTflArgFromString and addConceptualArg functions to create and add the
arguments.
arg = getTflArgFromString(hEnt, 'y1','double');
arg.IOType = 'RTW_IO_OUTPUT';
addConceptualArg(hEnt, arg);
22-81
22 Code Replacement Customization for MATLAB Code
7 Create the implementation arguments and add them to the entry. This example uses
calls to the getTflArgFromString function to create implementation arguments
that map to arguments in the replacement function prototype: output argument
y1 and input argument u1. For each argument, the example uses the convenience
method setReturn or addArgument to specify whether an argument is a return
value or argument. For each argument, this example adds the argument to the entry
array of implementation arguments.
addEntry(hLib, hEnt);
1 Register the table that contains the entry in a code replacement library.
2 Configure the code generator to use a code replacement library and to include the
Code Replacements Report in the code generation report.
3 Generate the replacement code and a code generation report.
4 Review the code replacements.
Related Examples
• “Define Code Replacement Mappings”
• “Develop a Code Replacement Library”
• “Quick Start Library Development”
More About
• “Code You Can Replace from MATLAB Code”
• “Code Replacement Terminology”
22-82
Specify In-Place Code Replacement
22-83
22 Code Replacement Customization for MATLAB Code
• MATLAB Coder
• MATLAB code in a Simulink MATLAB Function block
Related Examples
• “Define Code Replacement Mappings”
• “Register Code Replacement Mappings”
• “Develop a Code Replacement Library”
• “Quick Start Library Development”
More About
• “Code You Can Replace from MATLAB Code”
• “Code Replacement Terminology”
22-84
Replace MATLAB Functions with Custom Code Using coder.replace
22-85
22 Code Replacement Customization for MATLAB Code
To view a list of reserved identifiers for the code replacement library that you
use to generate code, specify the name of the library in a call to the function
RTW.TargetRegistry.getInstance.getTflReservedIdentifiers. For example:
crl_ids = RTW.TargetRegistry.getInstance.getTflReservedIdentifiers('GNU99 (GNU)')
In a code replacement table, the code generator registers each function implementation
name defined by a table entry as a reserved identifier. You can register additional
reserved identifiers for the table on a per-header-file basis. Providing additional reserved
identifiers can help prevent duplicate symbols and other identifier-related compile and
link issues.
You can register up to four reserved identifier structures in a code replacement table.
You can associate one set of reserved identifiers with a code replacement library, while
the other three (if present) must be associated with ANSI C. The following example
shows a reserved identifier structure that specifies two identifiers and the associated
header file.
d{1}.LibraryName = 'ANSI_C';
d{1}.HeaderInfos{1}.HeaderName = 'math.h';
d{1}.HeaderInfos{1}.ReservedIds = {'y0', 'y1'};
The code generator adds the identifiers to the list of reserved identifiers and honors them
during the build procedure.
Related Examples
• “Define Code Replacement Mappings”
• “Register Code Replacement Mappings”
• “Develop a Code Replacement Library”
• “Quick Start Library Development”
22-86
Reserved Identifiers and Code Replacement
More About
• “What Is Code Replacement Customization?”
• “Code Replacement Terminology”
22-87
22 Code Replacement Customization for MATLAB Code
• Preset match criteria to identify functions and operators for which application-specific
implementations should replace default implementations
• Preset replacement function signatures
However, preset match criteria and preset replacement function signatures might not
completely meet your function and operator replacement needs. For example,
When you need to add extra logic into the code replacement matching and replacement
process, you can create custom code replacement table entries. Custom entries allow you
to specify additional match criteria and/or modify the replacement function signature to
meet application needs.
a Add additional match criteria not provided by the base class. The base class
provides a match based on argument number, argument name, signedness, word
size, slope (if not specified with wildcards), bias (if not specified with wildcards),
math modes such as saturation and rounding, and operator or function key. For
example, you can accept a match only when additional size or range conditions
are met.
b Modify the implementation signature by adding additional arguments or setting
constant input argument values. For example, you can inject a constant value,
22-88
Customize Matching and Replacement Process for Functions
During code generation, the code replacement matching process first tries to match
function or operator call sites with the base class of your derived entry class. If a match is
found, the software calls your do_match method to execute your additional match logic
(if any) and your replacement function customizations (if any).
Related Examples
• “Define Code Replacement Mappings”
• “Register Code Replacement Mappings”
• “Develop a Code Replacement Library”
• “Quick Start Library Development”
More About
• “What Is Code Replacement?”
• “What Is Code Replacement Customization?”
• “Code Replacement Match and Replacement Process”
• “Code Replacement Terminology”
22-89
22 Code Replacement Customization for MATLAB Code
hTable = RTW.TflTable;
3 Create an entry for the operator mapping with a call to the
RTW.TflCOperationEntry function.
5 Create conceptual arguments y1, u1, and u2. This example uses calls to the
getTflArgFromString and addConceptualArg functions to create and add the
arguments.
arg = getTflArgFromString(hTable, 'y1', 'uint8');
arg.IOType = 'RTW_IO_OUTPUT';
addConceptualArg(op_entry, arg);
22-90
Scalar Operator Code Replacement
7 Add the entry to a code replacement table with a call to the addEntryfunction.
addEntry(hTable, op_entry);
Related Examples
• “Define Code Replacement Mappings”
• “Addition and Subtraction Operator Code Replacement”
• “Remap Operator Output to Function Input”
• “Customize Matching and Replacement Process for Operators”
• “Develop a Code Replacement Library”
• “Quick Start Library Development”
More About
• “What Is Code Replacement?”
• “What Is Code Replacement Customization?”
• “Code You Can Replace from MATLAB Code”
• “Code Replacement Match and Replacement Process”
• “Code Replacement Libraries”
• “Code Replacement Terminology”
22-91
22 Code Replacement Customization for MATLAB Code
In this section...
“Algorithm Options” on page 22-92
“Interactive Specification with Code Replacement Tool” on page 22-93
“Programmatic Specification” on page 22-93
“Algorithm Classification” on page 22-93
“Limitations” on page 22-95
Algorithm Options
When creating a code replacement table entry for an addition or subtraction operator,
first determine the type of algorithm that your library function implements.
• Cast-after-operation (CAO) — The algorithm computes the ideal result of the addition
or subtraction operation of the two inputs. The algorithm then type casts the result
to the output data type. Loss occurs during the type cast. This algorithm behaves
similarly to the C language except when the signedness of the operands does not
match. For example, when you add a signed long operand to an unsigned long
operand, standard C language rules convert the signed long operand to an unsigned
long operand. The result is a value that is not ideal.
22-92
Addition and Subtraction Operator Code Replacement
Programmatic Specification
Create a code replacement table file, as a MATLAB function, that describes
the addition or subtraction code replacement table entry. In the call to
setTflCOperationEntryParameters, set at least these parameters:
This example sets parameters for a code replacement operator entry for a cast-after-
operation implementation of a uint8 addition.
op_entry = RTW.TflCOperationEntry;
setTflCOperationEntryParameters(op_entry, ...
'Key', 'RTW_OP_ADD', ...
'EntryInfoAlgorithm', 'RTW_CAST_AFTER_OP', ...
'ImplementationName', 'u8_add_u8_u8');
Algorithm Classification
During code generation, the code generator examines addition and subtraction
operations, including adjacent type cast operations, to determine the type of algorithm
to compute the expression result. Based on the data types in the expression and the type
of the accumulator (type used to hold the result of the addition or subtraction operation),
the code generator uses these rules.
Input 1 Data Input 2 Data Accumulator Data Output Data Type Classification
Type Type Type
double double double double CBO, CAO
22-93
22 Code Replacement Customization for MATLAB Code
Input 1 Data Input 2 Data Accumulator Data Output Data Type Classification
Type Type Type
double double double single —
double double single double —
double double single single CBO
double single double double CBO, CAO
double single double single —
double single single double —
double single single single CBO
single single single single CBO, CAO
single single single double —
single single double single —
single single double double CBO, CAO
• Floating-point and fixed-point types on the immediate addition or subtraction
operation
Algorithm Conditions
CBO One of the following is true:
Algorithm Conditions
CBO At least one of the following is true:
22-94
Addition and Subtraction Operator Code Replacement
Algorithm Conditions
CAO Net bias is zero and the data types in the expression have equal slope
adjustment factors. For more information on net bias, see “Addition” or
“Subtraction” in “Fixed-Point Operator Code Replacement” (for MATLAB
code) or “Fixed-Point Operator Code Replacement” (for Simulink
models).
In many cases, the numerical result of a CBO operation is equal to that of a CAO
operation. For example, if the input and output types are such that the operation
produces the ideal result, as in the case of int8 + int8 —> int16. To maximize the
probability of code replacement occurring in such cases, set the algorithm to cast-after-
operation.
Limitations
• The code generator does not replace operations with nonzero net bias.
• When classifying an operation as a CAO operation, the code generator includes the
adjacent casts in the expression when the expression involves only fixed-point types.
Otherwise, the code generator classifies and replaces only the immediate addition or
subtraction operation. Casts that the code generator excludes from the classification
appear in the generated code.
• To enable the code generator to include multiple cast operations, which follow an
addition or subtraction of fixed-point data, in the classification of an expression, the
rounding mode must be simplest or floor. Consider the expression y=(cast A)
(cast B)(u1+u2). If the rounding mode of (cast A), (cast B), and the addition
operator (+) are set to simplest or floor, the code generator takes into account
(cast A) and (cast B) when classifying the expression and performing the
replacement only.
Related Examples
• “Define Code Replacement Mappings”
• “Remap Operator Output to Function Input”
• “Customize Matching and Replacement Process for Operators”
• “Develop a Code Replacement Library”
• “Quick Start Library Development”
22-95
22 Code Replacement Customization for MATLAB Code
More About
• “What Is Code Replacement?”
• “What Is Code Replacement Customization?”
• “Code You Can Replace from MATLAB Code”
• “Code Replacement Match and Replacement Process”
• “Code Replacement Libraries”
• “Code Replacement Terminology”
22-96
Small Matrix Operation to Processor Code Replacement
5 Create conceptual arguments y1, u1, and u2. This example uses calls to the
createAndAddConceptualArg function to create and add an argument with one
function call. To specify a matrix argument in the function call, use the argument
class RTW.TflArgMatrix. Sspecify the base type and the dimensions for which the
22-97
22 Code Replacement Customization for MATLAB Code
argument is valid. The first table entry specifies [2 2] and the second table entry
specifies [3 3].
% Specify operands and result
createAndAddConceptualArg(op_entry, 'RTW.TflArgMatrix', ...
'Name', 'y1', ...
'IOType', 'RTW_IO_OUTPUT', ...
'BaseType', 'double', ...
'DimRange', [2 2]);
createAndAddConceptualArg(op_entry, 'RTW.TflArgMatrix',...
'Name', 'u1', ...
'BaseType', 'double', ...
'DimRange', [2 2]);
createAndAddConceptualArg(op_entry, 'RTW.TflArgMatrix',...
'Name', 'u2', ...
'BaseType', 'double', ...
'DimRange', [2 2]);
7 Add the entry to a code replacement table with a call to the addEntryfunction.
addEntry(hTable, op_entry);
8 Create the entry for the second operator mapping.
% Create table entry for matrix_sum_3x3_double
op_entry = RTW.TflCOperationEntry;
setTflCOperationEntryParameters(op_entry, ...
'Key', 'RTW_OP_ADD', ...
'Priority', 30, ...
'SaturationMode', 'RTW_WRAP_ON_OVERFLOW', ...
'ImplementationName', 'matrix_sum_3x3_double', ...
'ImplementationHeaderFile', 'MatrixMath.h', ...
'ImplementationSourceFile', 'MatrixMath.c', ...
22-98
Small Matrix Operation to Processor Code Replacement
addEntry(hTable, op_entry);
Related Examples
• “Define Code Replacement Mappings”
• “Matrix Multiplication Operation to MathWorks BLAS Code Replacement”
• “Matrix Multiplication Operation to ANSI/ISO C BLAS Code Replacement”
• “Remap Operator Output to Function Input”
• “Customize Matching and Replacement Process for Operators”
22-99
22 Code Replacement Customization for MATLAB Code
More About
• “What Is Code Replacement?”
• “What Is Code Replacement Customization?”
• “Code You Can Replace from MATLAB Code”
• “Code Replacement Match and Replacement Process”
• “Code Replacement Libraries”
• “Code Replacement Terminology”
22-100
Matrix Multiplication Operation to MathWorks BLAS Code Replacement
22-101
22 Code Replacement Customization for MATLAB Code
6 Create conceptual arguments y1, u1, and u2. This example uses calls to the
createAndAddConceptualArg function to create and add an argument with
one function call. To specify a matrix argument in the function call, use the
argument class RTW.TflArgMatrix and specify the base type and the dimensions
for which the argument is valid. This type of table entry supports a range of
dimensions specified in the format [Dim1Min Dim2Min ... DimNMin; Dim1Max
Dim2Max ... DimNMax]. For example, [2 2; inf inf] means a two-dimensional
matrix of size 2x2 or larger. The conceptual output argument for the dgemm32 entry
for matrix/matrix multiplication replacement specifies dimensions [2 2; inf
inf], while the conceptual output argument for the dgemv32 entry for matrix/vector
multiplication replacement specifies dimensions [2 1; inf 1].
% Specify operands and result
createAndAddConceptualArg(op_entry, 'RTW.TflArgMatrix', ...
'Name', 'y1', ...
'IOType', 'RTW_IO_OUTPUT', ...
22-102
Matrix Multiplication Operation to MathWorks BLAS Code Replacement
arg = RTW.TflArgCharConstant('TRANSA');
% Possible values for PassByType property are
% RTW_PASSBY_AUTO, RTW_PASSBY_POINTER,
% RTW_PASSBY_VOID_POINTER, RTW_PASSBY_BASE_POINTER
arg.PassByType = 'RTW_PASSBY_POINTER';
op_entry.Implementation.addArgument(arg);
arg = RTW.TflArgCharConstant('TRANSB');
arg.PassByType = 'RTW_PASSBY_POINTER';
op_entry.Implementation.addArgument(arg);
22-103
22 Code Replacement Customization for MATLAB Code
op_entry.Implementation.addArgument(arg);
8 Add the entry to a code replacement table with a call to the addEntryfunction.
addEntry(hTable, op_entry);
9 Create the entry for the second mapping.
% Create table entry for dgemv32
op_entry = RTW.TflBlasEntryGenerator;
if ispc
22-104
Matrix Multiplication Operation to MathWorks BLAS Code Replacement
libExt = 'lib';
elseif ismac
libExt = 'dylib';
else
libExt = 'so';
end
setTflCOperationEntryParameters(op_entry, ...
'Key', 'RTW_OP_MUL', ...
'Priority', 100, ...
'ImplementationName', 'dgemv32', ...
'ImplementationHeaderFile', 'blascompat32.h', ...
'ImplementationHeaderPath', fullfile('$(MATLAB_ROOT)','extern','include'), ...
'AdditionalLinkObjs', {['libmwblascompat32.' libExt]}, ...
'AdditionalLinkObjsPaths', {LibPath},...
'SideEffects', true);
arg = RTW.TflArgCharConstant('TRANS');
arg.PassByType = 'RTW_PASSBY_POINTER';
op_entry.Implementation.addArgument(arg);
22-105
22 Code Replacement Customization for MATLAB Code
op_entry.Implementation.addArgument(arg);
addEntry(hTable, op_entry);
Related Examples
• “Define Code Replacement Mappings”
• “Small Matrix Operation to Processor Code Replacement”
22-106
Matrix Multiplication Operation to MathWorks BLAS Code Replacement
More About
• “What Is Code Replacement?”
• “What Is Code Replacement Customization?”
• “Code You Can Replace from MATLAB Code”
• “Code Replacement Match and Replacement Process”
• “Code Replacement Libraries”
• “Code Replacement Terminology”
22-107
22 Code Replacement Customization for MATLAB Code
hTable = RTW.TflTable;
3 Define the path for the CBLAS function library. For example:
LibPath = fullfile(matlabroot, 'toolbox', 'rtw', 'rtwdemos', 'crl_demo');
22-108
Matrix Multiplication Operation to ANSI/ISO C BLAS Code Replacement
6 Create conceptual arguments y1, u1, and u2. This example uses calls to the
createAndAddConceptualArg function to create and add an argument with
one function call. To specify a matrix argument in the function call, use the
argument class RTW.TflArgMatrix and specify the base type and the dimensions
for which the argument is valid. This type of table entry supports a range of
dimensions specified in the format [Dim1Min Dim2Min ... DimNMin; Dim1Max
Dim2Max ... DimNMax]. For example, [2 2; inf inf] means a two-dimensional
matrix of size 2x2 or larger. The conceptual output argument for the dgemm32 entry
for matrix/matrix multiplication replacement specifies dimensions [2 2; inf
inf]. The conceptual output argument for the dgemv32 entry for matrix/vector
multiplication replacement specifies dimensions [2 1; inf 1].
% Specify operands and result
createAndAddConceptualArg(op_entry, 'RTW.TflArgMatrix', ...
'Name', 'y1', ...
'IOType', 'RTW_IO_OUTPUT', ...
'BaseType', 'double', ...
'DimRange', [2 2; inf inf]);
createAndAddConceptualArg(op_entry, 'RTW.TflArgMatrix', ...
'Name', 'u1', ...
'BaseType', 'double', ...
'DimRange', [2 2; inf inf]);
createAndAddConceptualArg(op_entry, 'RTW.TflArgMatrix', ...
'Name', 'u2', ...
'BaseType', 'double', ...
'DimRange', [1 1; inf inf]);
22-109
22 Code Replacement Customization for MATLAB Code
% use integer. (This will cause problems with C++ code generation,
% so for C++, use a wrapper function to cast each int to the
% corresponding enumeration type.)
%
% When a match occurs, the code generator computes the
% values for M, N, K, LDA, LDB, and LDC and insert them into the
% generated code.
22-110
Matrix Multiplication Operation to ANSI/ISO C BLAS Code Replacement
op_entry.Implementation.addArgument(arg);
8 Add the entry to a code replacement table with a call to the addEntryfunction.
addEntry(hTable, op_entry);
9 Create the entry for the second mapping.
% Create table entry for cblas_dgemv
op_entry = RTW.TflCBlasEntryGenerator;
setTflCOperationEntryParameters(op_entry, ...
'Key', 'RTW_OP_MUL', ...
'Priority', 100, ...
'ImplementationName', 'cblas_dgemv', ...
'ImplementationHeaderFile', 'cblas.h', ...
'ImplementationHeaderPath', LibPath, ...
'AdditionalIncludePaths', {LibPath}, ...
'GenCallback', 'RTW.copyFileToBuildDir', ...
'SideEffects', true);
22-111
22 Code Replacement Customization for MATLAB Code
addEntry(hTable, op_entry);
To test this example, create a model that uses two Product blocks. For example:
1 Create a model that includes two Product blocks, such as the following:
22-112
Matrix Multiplication Operation to ANSI/ISO C BLAS Code Replacement
• On the Solver pane, select a fixed-step, discrete solver with a fixed-step size such
as 0.1.
• On the Code Generation pane, select an ERT-based system target file.
• On the Code Generation > Interface pane, select the code replacement library
that contains your addition operation entry.
3 For each Product block, set the block parameter Multiplication to the value
Matrix(*).
4 In the Model Explorer, configure the Signal Attributes for the In1, In2, and In3
source blocks. For In1 and In2, set Port dimensions to [3 3] and set the Data
type to double. For In3, set Port dimensions to [3 1] and set the Data type to
double.
5 Generate code and a code generation report.
6 Review the code replacements.
Related Examples
• “Define Code Replacement Mappings”
• “Small Matrix Operation to Processor Code Replacement”
• “Matrix Multiplication Operation to MathWorks BLAS Code Replacement”
• “Remap Operator Output to Function Input”
• “Customize Matching and Replacement Process for Operators”
• “Develop a Code Replacement Library”
• “Quick Start Library Development”
More About
• “What Is Code Replacement?”
22-113
22 Code Replacement Customization for MATLAB Code
22-114
Remap Operator Output to Function Input
For example, for a sum operation, the code generator produces code similar to:
add8_Y.Out1 = u8_add_u8_u8(add8_U.In1, add8_U.In2);
If you remap the output to the first input, the code generator produces code similar to:
u8_add_u8_u8(&add8_Y.Out1;, add8_U.In1, add8_U.In2);
The following table definition file for a sum operation remaps operator output y1 as the
first function input argument.
22-115
22 Code Replacement Customization for MATLAB Code
6 Create conceptual arguments y1, u1, and u2. This example uses calls to the
getTflArgFromString and addConceptualArg functions to create and add the
arguments.
arg = getTflArgFromString(hTable, 'y1', 'uint8');
arg.IOType = 'RTW_IO_OUTPUT';
addConceptualArg(op_entry, arg);
% Set y1 as first input arg, mark IOType as output, and use pointer type
arg=getTflArgFromString(hTable, 'y1', 'uint8*');
arg.IOType = 'RTW_IO_OUTPUT';
op_entry.Implementation.addArgument(arg);
8 Add the entry to a code replacement table with a call to the addEntryfunction.
addEntry(hTable, op_entry);
To test this example, create a model that uses an Add block. For example:
22-116
Remap Operator Output to Function Input
Related Examples
• “Define Code Replacement Mappings”
• “Develop a Code Replacement Library”
• “Quick Start Library Development”
More About
• “What Is Code Replacement?”
• “What Is Code Replacement Customization?”
• “Code You Can Replace from MATLAB Code”
• “Code Replacement Libraries”
• “Code Replacement Terminology”
22-117
22 Code Replacement Customization for MATLAB Code
The example modifies a fixed-point addition replacement such that the implementation
function passes in the fraction lengths of the input and output data types as arguments.
Create a class folder using the name of your derived class, such as
@TflCustomOperationEntry. Verify that the class folder is on the MATLAB search
path or in your current working folder.
In the class folder, create and save the following class definition
file, TflCustomOperationEntry.m. This file defines the class
TflCustomOperationEntry, which is derived from the base class
RTW.TflCOperationEntryML.
• ent is the return handle, which is returned either as empty (indicating that the
match failed) or as a TflCOperationEntry handle.
• hThis is the handle to this object.
• hCSO is a handle to an object created by the code generator for querying the library for
a replacement.
• The remaining arguments are the number of bits for various data types of the current
target.
The do_match method adds required additional match criteria that the base class does
not provide. the method makes required modifications to the implementation signature.
22-118
Customize Matching and Replacement Process for Operators
In this case, the do_match method can rely on the base class for checking word size
and signedness. do_match must match only the number of conceptual arguments to the
value 3 (two inputs and one output) and the bias for each argument to the value 0. If the
code generator finds a match, do_match sets the return handle, removes slope and bias
wildcards from the conceptual arguments (the match is for specific slope and bias values),
and writes fraction-length values for the inputs and output into replacement function
arguments 3, 4, and 5.
You can create and add the three additional implementation function arguments
for passing fraction lengths in the class definition or in each code replacement entry
definition that instantiates this class. This example creates the arguments, adds them
to a code replacement table definition file, and sets them to specific values in the class
definition code.
classdef TflCustomOperationEntry < RTW.TflCOperationEntryML
methods
function ent = do_match(hThis, ...
hCSO, ... %#ok
targetBitPerChar, ... %#ok
targetBitPerShort, ... %#ok
targetBitPerInt, ... %#ok
targetBitPerLong) %#ok
% DO_MATCH - Create a custom match function. The base class
% checks the types of the arguments prior to calling this
% method. This will check additional data and perhaps modify
% the implementation function.
% The base class checks word size and signedness. Slopes and biases
% have been wildcarded, so the only additional checking to do is
% to check that the biases are zero and that there are only three
% conceptual arguments (one output, two inputs)
ent = []; % default the return to empty, indicating the match failed
22-119
22 Code Replacement Customization for MATLAB Code
Create code replacement entries that instantiate your custom entry class. For this
example, create and save a code replacement table that contains a single operator entry,
an entry generator for unsigned 32-bit fixed-point addition operations, with arbitrary
fraction-length values on the inputs and the output. This entry instantiates the derived
class from the previous step.
If you want to replace all word sizes and signedness attributes (not just 32-bit and
unsigned), you can use the same derived class, but not the same entry, because you
cannot wildcard the WordLength and IsSigned arguments. For example, to support
uint8, int8, uint16, int16, and int32, you must add five other distinct entries.
Similarly, to use different implementation functions for saturation and rounding
modes other than overflow and round to floor, you must add entries for those match
permutations.
This table entry creates and adds three implementation arguments to hold the
fraction-length values for the inputs and output. Alternatively, the entry can omit
those argument definitions. Instead the do_match method of the derived class
TflCustomOperationEntry can create and add the three implementation arguments.
When the number of additional implementation arguments required can vary based on
compile-time information, use the alternative approach.
22-120
Customize Matching and Replacement Process for Operators
6 Create conceptual arguments y1, u1, and u2. This example uses calls to the
createAndAddConceptualArg function to create and add an argument with one
function call.
createAndAddConceptualArg(op_entry, 'RTW.TflArgNumeric', ...
'Name', 'y1', ...
'IOType', 'RTW_IO_OUTPUT', ...
'CheckSlope', false, ...
'CheckBias', false, ...
'DataType', 'Fixed', ...
'Scaling', 'BinaryPoint', ...
'IsSigned', false, ...
'WordLength', 32);
22-121
22 Code Replacement Customization for MATLAB Code
% Add 3 fraction-length args. Actual values are set during code generation.
createAndAddImplementationArg(op_entry, 'RTW.TflArgNumericConstant', ...
'Name', 'fl_in1', ...
'IOType', 'RTW_IO_INPUT', ...
'IsSigned', false, ...
'WordLength', 32, ...
'FractionLength', 0, ...
'Value', 0);
22-122
Customize Matching and Replacement Process for Operators
'FractionLength', 0, ...
'Value', 0);
8 Add the entry to a code replacement table with a call to the addEntryfunction.
addEntry(hTable, op_entry);
Related Examples
• “Define Code Replacement Mappings”
• “Develop a Code Replacement Library”
• “Quick Start Library Development”
More About
• “Code Replacement Match and Replacement Process”
• “What Is Code Replacement?”
• “What Is Code Replacement Customization?”
• “Code You Can Replace from MATLAB Code”
• “Code Replacement Libraries”
• “Code Replacement Terminology”
22-123
22 Code Replacement Customization for MATLAB Code
The following table maps common ways to match fixed-point operator code replacement
entries with the associated fixed-point parameters that you specify in a code replacement
table definition file.
22-124
Fixed-Point Operator Code Replacement
22-125
22 Code Replacement Customization for MATLAB Code
example, 1.0).
• NetFixedExponent: Specify the
fixed exponent (E) part of the net
slope, F2 (for example, -3.0).
E
createAndAddConceptualArg
function:
22-126
Fixed-Point Operator Code Replacement
• RelativeScalingFactorE:
Specify the fixed exponent (E) part
of the relative scaling factor, F2 (for
E
example, -3.0).
createAndAddConceptualArg
function:
createAndAddConceptualArg
function:
22-127
22 Code Replacement Customization for MATLAB Code
V = V% = SQ + B
Addition
The operation V0 = V1 + V2 implies that
ÊS ˆ ÊS ˆ Ê B + B2 - B0 ˆ
Q0 = Á 1 ˜ Q1 + Á 2 ˜ Q2 + Á 1 ˜
Ë S0 ¯ Ë S0 ¯ Ë S0 ¯
If an addition replacement function is defined such that the scaling on the operands and
sum are equal and the net bias
22-128
Fixed-Point Operator Code Replacement
Ê B1 + B2 - B0 ˆ
Á ˜
Ë S0 ¯
is zero (for example, a function s8_add_s8_s8 that adds two signed 8-bit
values and produces a signed 8-bit result), then the operator entry must set the
operator entry parameters SlopesMustBeTheSame and MustHaveZeroNetBias
to true. (For parameter descriptions, see the reference page for the function
setTflCOperationEntryParameters.)
Subtraction
The operation V0 = V1 − V2 implies that
ÊS ˆ ÊS ˆ Ê B1 - B2 - B0 ˆ
Q0 = Á 1 ˜ Q1 - Á 2 ˜ Q2 + Á ˜
Ë S0 ¯ Ë S0 ¯ Ë S0 ¯
If a subtraction replacement function is defined such that the scaling on the operands
and difference are equal and the net bias
Ê B1 - B2 - B0 ˆ
Á ˜
Ë S0 ¯
is zero (for example, a function s8_sub_s8_s8 that subtracts two signed 8-bit
values and produces a signed 8-bit result), then the operator entry must set the
operator entry parameters SlopesMustBeTheSame and MustHaveZeroNetBias
to true. (For parameter descriptions, see the reference page for the function
setTflCOperationEntryParameters.)
Multiplication
There are different ways to specify multiplication replacements. The most direct way is to
specify an exact match of the input and output types. This is feasible if a model contains
only a few (known) slope and bias combinations. Use the TflCOperationEntry class
22-129
22 Code Replacement Customization for MATLAB Code
and specify the exact values of slope and bias on each argument. For scenarios where
there are numerous slope/bias combinations, it is not feasible to specify each value with a
different entry. Use a net slope entry or create a custom entry.
It is common to replace all multiplication operations that have a net slope of 1.0 with
a function that performs C-style multiplication. For example, to replace all signed 8-
bit multiplications that have a net scaling of 1.0 with the s8_mul_s8_u8_ replacement
function, the operator entry must define a net slope factor, F2E. You specify the values
for F and E using operator entry parameters NetSlopeAdjustmentFactor and
NetFixedExponent. (For parameter descriptions, see the reference page for the
function setTflCOperationEntryParameters.) For the s8_mul_s8_u8 function, set
NetSlopeAdjustmentFactor to 1 and NetFixedExponent to 0.0.
Division
There are different ways to specify division replacements. The most direct way is to
specify an exact match of the input and output types. This is feasible if a model contains
only a few (known) slope and bias combinations. For this, use the TflCOperationEntry
class and specify the exact values of slope and bias on each argument. For scenarios
where there are numerous slope/bias combinations, it is not feasible to specify each
value with a different entry. For this, use a net slope entry or create a custom entry (see
“Customize Matching and Replacement Process for Functions”).
22-130
Fixed-Point Operator Code Replacement
ÊSQ ˆ
S0Q0 = Á 1 1 ˜
Ë S2Q2 ¯
ÊQ ˆ
Q0 = S n Á 1 ˜
Ë Q2 ¯
where Sn is the net slope.
It is common to replace all division operations that have a net slope of 1.0 with
a function that performs C-style division. For example, to replace all signed 8-
bit divisions that have a net scaling of 1.0 with the s8_mul_s8_u8_ replacement
function, the operator entry must define a net slope factor, F2E. You specify the values
for F and E using operator entry parameters NetSlopeAdjustmentFactor and
NetFixedExponent. (For parameter descriptions, see the reference page for the function
setTflCOperationEntryParameters.) For the s16_netslope0p5_div_s16_s16
function, you would set NetSlopeAdjustmentFactor to 1 and NetFixedExponent to
0.0.
ÊS ˆ
Q0 = Á 1 ˜ Q1
Ë S0 ¯
Q0 = S nQ1
Shift
The shift left or shift right operation V0 = (V1 / 2n) implies, for binary-point-only scaling,
that
22-131
22 Code Replacement Customization for MATLAB Code
ÊSQ ˆ
S0Q0 = Á 1 n 1 ˜
Ë 2 ¯
Ê S ˆ ÊQ ˆ
Q0 = Á 1 ˜ + Á n1 ˜
Ë S0 ¯ Ë 2 ¯
ÊQ ˆ
Q0 = S n Á n1 ˜
Ë2 ¯
Related Examples
• “Define Code Replacement Mappings”
• “Binary-Point-Only Scaling Code Replacement”
• “Slope Bias Scaling Code Replacement”
• “Net Slope Scaling Code Replacement”
• “Equal Slope and Zero Net Bias Code Replacement”
• “Data Type Conversions (Casts) and Operator Code Replacement”
• “Shift Left Operations and Code Replacement”
• “Remap Operator Output to Function Input”
• “Customize Matching and Replacement Process for Operators”
• “Develop a Code Replacement Library”
• “Quick Start Library Development”
More About
• “What Is Code Replacement?”
• “What Is Code Replacement Customization?”
• “Code You Can Replace from MATLAB Code”
• “Code Replacement Match and Replacement Process”
• “Code Replacement Libraries”
• “Code Replacement Terminology”
22-132
Fixed-Point Operator Code Replacement
22-133
22 Code Replacement Customization for MATLAB Code
This example creates a code replacement entry for multiplication of fixed-point data
types. You specify arguments using binary-point-only scaling. The example defines the
function mapping programmatically. Alternatively, you can use the Code Replacement
Tool to define the same mapping.
hTable = RTW.TflTable;
3 Create the entry for the operator mapping with a call to the
RTW.TflCOperationEntry function.
op_entry = RTW.TflCOperationEntry;
4 Set operator entry parameters with a call to the
setTflCOperationEntryParameters function. The parameters specify the
type of operation as multiplication, the saturation mode as saturate on overflow,
rounding modes as unspecified, and the name of the replacement function as
s32_mul_s16_s16_binarypoint.
setTflCOperationEntryParameters(op_entry, ...
'Key', 'RTW_OP_MUL', ...
'Priority', 90, ...
'SaturationMode', 'RTW_SATURATE_ON_OVERFLOW', ...
'RoundingModes', {'RTW_ROUND_UNSPECIFIED'}, ...
'ImplementationName', 's32_mul_s16_s16_binarypoint', ...
'ImplementationHeaderFile', 's32_mul_s16_s16_binarypoint.h', ...
'ImplementationSourceFile', 's32_mul_s16_s16_binarypoint.c');
5 Create conceptual arguments y1, u1, and u2. This example uses calls to the
createAndAddConceptualArg function to create and add an argument with one
function call. Each argument specifies that the data type is fixed-point, the mode is
binary-point-only scaling, and its derived slope and bias values must exactly match
the call-site slope and bias values. The output argument is 32 bits, signed, with a
22-134
Binary-Point-Only Scaling Code Replacement
fraction length of 28. The input arguments are 16 bits, signed, with fraction lengths
of 15 and 13.
createAndAddConceptualArg(op_entry, 'RTW.TflArgNumeric',...
'Name', 'y1', ...
'IOType', 'RTW_IO_OUTPUT', ...
'CheckSlope', true, ...
'CheckBias', true, ...
'DataTypeMode', 'Fixed-point: binary point scaling', ...
'IsSigned', true, ...
'WordLength', 32, ...
'FractionLength', 28);
createAndAddImplementationArg(op_entry, 'RTW.TflArgNumeric',...
'Name', 'u1', ...
'IOType', 'RTW_IO_INPUT', ...
'IsSigned', true, ...
'WordLength', 16, ...
'FractionLength', 0);
22-135
22 Code Replacement Customization for MATLAB Code
createAndAddImplementationArg(op_entry, 'RTW.TflArgNumeric',...
'Name', 'u2', ...
'IOType', 'RTW_IO_INPUT', ...
'IsSigned', true, ...
'WordLength', 16, ...
'FractionLength', 0);
7 Add the entry to a code replacement table with a call to the addEntryfunction.
addEntry(hTable, op_entry);
Related Examples
• “Define Code Replacement Mappings”
• “Fixed-Point Operator Code Replacement”
• “Slope Bias Scaling Code Replacement”
• “Net Slope Scaling Code Replacement”
• “Equal Slope and Zero Net Bias Code Replacement”
• “Data Type Conversions (Casts) and Operator Code Replacement”
• “Shift Left Operations and Code Replacement”
• “Remap Operator Output to Function Input”
• “Customize Matching and Replacement Process for Operators”
• “Develop a Code Replacement Library”
• “Quick Start Library Development”
More About
• “What Is Code Replacement?”
• “What Is Code Replacement Customization?”
• “Code You Can Replace from MATLAB Code”
• “Code Replacement Match and Replacement Process”
• “Code Replacement Libraries”
• “Code Replacement Terminology”
22-136
Slope Bias Scaling Code Replacement
This example creates a code replacement entry for division of fixed-point data types. You
specify arguments using slope bias scaling. The example defines the function mapping
programmatically. Alternatively, you can use the Code Replacement Tool to define the
same mapping.
hTable = RTW.TflTable;
3 Create the entry for the operator mapping with a call to the
RTW.TflCOperationEntry function.
op_entry = RTW.TflCOperationEntry;
4 Set operator entry parameters with a call to the
setTflCOperationEntryParameters function. The parameters specify the
type of operation as division, the saturation mode as saturate on overflow,
rounding modes as round to ceiling, and the name of the replacement function as
s16_div_s16_s16_slopebias.
setTflCOperationEntryParameters(op_entry, ...
'Key', 'RTW_OP_DIV', ...
'Priority', 90, ...
'SaturationMode', 'RTW_SATURATE_ON_OVERFLOW', ...
'RoundingModes', {'RTW_ROUND_CEILING'}, ...
'ImplementationName', 's16_div_s16_s16_slopebias', ...
'ImplementationHeaderFile', 's16_div_s16_s16_slopebias.h', ...
'ImplementationSourceFile', 's16_div_s16_s16_slopebias.c');
5 Create conceptual arguments y1, u1, and u2. This example uses calls to the
createAndAddConceptualArg function to create and add an argument with one
function call. Each argument specifies that the data type is fixed-point, the mode
is slope bias scaling, and its specified slope and bias values must exactly match the
call-site slope and bias values. The output argument and input arguments are 16
bits, signed, each with specific slope bias specifications.
22-137
22 Code Replacement Customization for MATLAB Code
createAndAddImplementationArg(op_entry, 'RTW.TflArgNumeric',...
'Name', 'u1', ...
'IOType', 'RTW_IO_INPUT', ...
'IsSigned', true, ...
'WordLength', 16, ...
'FractionLength', 0);
22-138
Slope Bias Scaling Code Replacement
createAndAddImplementationArg(op_entry, 'RTW.TflArgNumeric',...
'Name', 'u2', ...
'IOType', 'RTW_IO_INPUT', ...
'IsSigned', true, ...
'WordLength', 16, ...
'FractionLength', 0);
7 Add the entry to a code replacement table with a call to the addEntryfunction.
addEntry(hTable, op_entry);
Related Examples
• “Define Code Replacement Mappings”
• “Fixed-Point Operator Code Replacement”
• “Binary-Point-Only Scaling Code Replacement”
• “Net Slope Scaling Code Replacement”
• “Equal Slope and Zero Net Bias Code Replacement”
• “Data Type Conversions (Casts) and Operator Code Replacement”
• “Shift Left Operations and Code Replacement”
• “Remap Operator Output to Function Input”
• “Customize Matching and Replacement Process for Operators”
• “Develop a Code Replacement Library”
• “Quick Start Library Development”
More About
• “What Is Code Replacement?”
• “What Is Code Replacement Customization?”
• “Code You Can Replace from MATLAB Code”
• “Code Replacement Match and Replacement Process”
• “Code Replacement Libraries”
• “Code Replacement Terminology”
22-139
22 Code Replacement Customization for MATLAB Code
This example creates a code replacement entry for division of fixed-point data types,
using wrap on overflow saturation mode and a net slope. The example defines the
function mapping programmatically. Alternatively, you can use the Code Replacement
Tool to define the same mapping.
hTable = RTW.TflTable;
3 Create the entry for the operator mapping with a call to the
RTW.TflCOperationEntryGenerator_Netslope function, which provides
access to the fixed-point parameters NetSlopeAdjustmentFactor and
NetFixedExponent.
wv = [16,32];
for iy = 1:2
for inum = 1:2
for iden = 1:2
hTable = getDivOpEntry(hTable, ...
fixdt(1,wv(iy)),fixdt(1,wv(inum)),fixdt(1,wv(iden)));
end
end
end
%---------------------------------------------------------
function hTable = getDivOpEntry(hTable,dty,dtnum,dtden)
%---------------------------------------------------------
22-140
Net Slope Scaling Code Replacement
funcStr = sprintf('user_div_%s_%s_%s',...
typeStrFunc(dty),...
typeStrFunc(dtnum),...
typeStrFunc(dtden));
op_entry = RTW.TflCOperationEntryGenerator_NetSlope;
setTflCOperationEntryParameters(op_entry, ...
'Key', 'RTW_OP_DIV', ...
'Priority', 90, ...
'SaturationMode', 'RTW_WRAP_ON_OVERFLOW',...
'RoundingModes', {'RTW_ROUND_UNSPECIFIED'},...
'NetSlopeAdjustmentFactor', 1.0, ...
'NetFixedExponent', 0.0, ...
'ImplementationName', funcStr, ...
'ImplementationHeaderFile', [funcStr,'.h'], ...
'ImplementationSourceFile', [funcStr,'.c']);
5 Create conceptual arguments y1, u1, and u2. This example uses calls to the
createAndAddConceptualArg function to create and add an argument with
one function call. Specify each argument as fixed-point and signed. Also, for each
argument, specify that code replacement request processing does not check for an
exact match to the call-site slope and bias values.
createAndAddConceptualArg(op_entry, ...
'RTW.TflArgNumeric', ...
'Name', 'y1',...
'IOType', 'RTW_IO_OUTPUT',...
'CheckSlope', false,...
'CheckBias', false,...
'DataTypeMode', 'Fixed-point: slope and bias scaling',...
'IsSigned', dty.Signed,...
'WordLength', dty.WordLength,...
'Bias', 0);
createAndAddConceptualArg(op_entry, ...
'RTW.TflArgNumeric',...
'Name', 'u1', ...
'IOType', 'RTW_IO_INPUT',...
'CheckSlope', false,...
'CheckBias', false,...
22-141
22 Code Replacement Customization for MATLAB Code
createAndAddConceptualArg(op_entry, ...
'RTW.TflArgNumeric', ...
'Name', 'u2', ...
'IOType', 'RTW_IO_INPUT',...
'CheckSlope', false,...
'CheckBias', false,...
'DataTypeMode', 'Fixed-point: slope and bias scaling',...
'IsSigned', dtden.Signed,...
'WordLength', dtden.WordLength,...
'Bias', 0);
7 Add the entry to a code replacement table with a call to the addEntryfunction.
addEntry(hTable, op_entry);
8 Define functions that determine the data type word length.
%-------------------------------------------------------------
function str = typeStrFunc(dt)
%-------------------------------------------------------------
if dt.Signed
sstr = 's';
else
sstr = 'u';
end
str = sprintf('%s%d',sstr,dt.WordLength);
%-------------------------------------------------------------
function str = typeStrBase(dt)
%-------------------------------------------------------------
if dt.Signed
22-142
Net Slope Scaling Code Replacement
sstr = ;
else
sstr = 'u';
end
str = sprintf('%sint%d',sstr,dt.WordLength);
This example creates a code replacement entry for division of fixed-point data types,
using the ceiling rounding mode and a net slope scaling factor. The example defines the
function mapping programmatically. Alternatively, you can use the Code Replacement
Tool to define the same mapping.
setTflCOperationEntryParameters(op_entry, ...
'Key', 'RTW_OP_DIV', ...
'Priority', 90, ...
'SaturationMode', 'RTW_WRAP_ON_OVERFLOW', ...
'RoundingModes', {'RTW_ROUND_CEILING'}, ...
22-143
22 Code Replacement Customization for MATLAB Code
5 Create conceptual arguments y1, u1, and u2. This example uses calls to the
createAndAddConceptualArg function to create and add an argument with one
function call. Specify each argument as fixed-point, 16 bits, and signed. Also, for each
argument, specify that code replacement request processing does not check for an
exact match to the call-site slope and bias values.
createAndAddConceptualArg(op_entry, 'RTW.TflArgNumeric', ...
'Name', 'y1', ...
'IOType', 'RTW_IO_OUTPUT', ...
'CheckSlope', false, ...
'CheckBias', false, ...
'DataType', 'Fixed', ...
'IsSigned', true, ...
'WordLength', 16);
22-144
Net Slope Scaling Code Replacement
createAndAddImplementationArg(op_entry, 'RTW.TflArgNumeric',...
'Name', 'u1', ...
'IOType', 'RTW_IO_INPUT', ...
'IsSigned', true, ...
'WordLength', 16, ...
'FractionLength', 0);
createAndAddImplementationArg(op_entry, 'RTW.TflArgNumeric',...
'Name', 'u2', ...
'IOType', 'RTW_IO_INPUT', ...
'IsSigned', true, ...
'WordLength', 16, ...
'FractionLength', 0);
7 Add the entry to a code replacement table with a call to the addEntryfunction.
addEntry(hTable, op_entry);
Related Examples
• “Define Code Replacement Mappings”
• “Fixed-Point Operator Code Replacement”
• “Binary-Point-Only Scaling Code Replacement”
• “Slope Bias Scaling Code Replacement”
• “Equal Slope and Zero Net Bias Code Replacement”
• “Data Type Conversions (Casts) and Operator Code Replacement”
• “Shift Left Operations and Code Replacement”
• “Remap Operator Output to Function Input”
• “Customize Matching and Replacement Process for Operators”
• “Develop a Code Replacement Library”
• “Quick Start Library Development”
More About
• “What Is Code Replacement?”
• “What Is Code Replacement Customization?”
• “Code You Can Replace from MATLAB Code”
• “Code Replacement Match and Replacement Process”
• “Code Replacement Libraries”
• “Code Replacement Terminology”
22-145
22 Code Replacement Customization for MATLAB Code
22-146
Equal Slope and Zero Net Bias Code Replacement
This example creates a code replacement entry for addition of fixed-point data types.
Slopes must be equal and net bias must be zero across the operator inputs and output.
The example defines the function mapping programmatically. Alternatively, you can use
the Code Replacement Tool to define the same mapping.
hTable = RTW.TflTable;
3 Create the entry for the operator mapping with a call to the
RTW.TflCOperationEntryGenerator function, which provides access to the fixed-
point parameters SlopesMustBeTheSame and MustHaveZeroNetBias.
op_entry = RTW.TflCOperationEntryGenerator;
4 Set operator entry parameters with a call to the
setTflCOperationEntryParameters function. The parameters specify
the type of operation as addition, the saturation mode as saturation
off, rounding modes as unspecified, and the name of the replacement
function as u16_add_SameSlopeZeroBias. SlopesMustBeTheSame and
MustHaveZeroNetBias are set to true, indicating that slopes must be equal and
net bias must be zero across the addition inputs and output.
setTflCOperationEntryParameters(op_entry, ...
'Key', 'RTW_OP_ADD', ...
'Priority', 90, ...
'SaturationMode', 'RTW_WRAP_ON_OVERFLOW', ...
'RoundingModes', {'RTW_ROUND_UNSPECIFIED'}, ...
'SlopesMustBeTheSame', true, ...
'MustHaveZeroNetBias', true, ...
'ImplementationName', 'u16_add_SameSlopeZeroBias', ...
'ImplementationHeaderFile', 'u16_add_SameSlopeZeroBias.h', ...
'ImplementationSourceFile', 'u16_add_SameSlopeZeroBias.c');
22-147
22 Code Replacement Customization for MATLAB Code
5 Create conceptual arguments y1, u1, and u2. This example uses calls to the
createAndAddConceptualArg function to create and add an argument with one
function call. Each argument is specified as 16 bits and unsigned. Each argument
specifies that code replacement request processing does not check for an exact match
to the call-site slope and bias values.
createAndAddConceptualArg(op_entry, 'RTW.TflArgNumeric', ...
'Name', 'y1', ...
'IOType', 'RTW_IO_OUTPUT', ...
'CheckSlope', false, ...
'CheckBias', false, ...
'IsSigned', false, ...
'WordLength', 16);
createAndAddImplementationArg(op_entry, 'RTW.TflArgNumeric',...
'Name', 'u1', ...
'IOType', 'RTW_IO_INPUT', ...
'IsSigned', false, ...
'WordLength', 16, ...
'FractionLength', 0);
createAndAddImplementationArg(op_entry, 'RTW.TflArgNumeric',...
22-148
Equal Slope and Zero Net Bias Code Replacement
7 Add the entry to a code replacement table with a call to the addEntryfunction.
addEntry(hTable, op_entry);
Related Examples
• “Define Code Replacement Mappings”
• “Fixed-Point Operator Code Replacement”
• “Binary-Point-Only Scaling Code Replacement”
• “Slope Bias Scaling Code Replacement”
• “Net Slope Scaling Code Replacement”
• “Data Type Conversions (Casts) and Operator Code Replacement”
• “Shift Left Operations and Code Replacement”
• “Remap Operator Output to Function Input”
• “Customize Matching and Replacement Process for Operators”
• “Develop a Code Replacement Library”
• “Quick Start Library Development”
More About
• “What Is Code Replacement?”
• “What Is Code Replacement Customization?”
• “Code You Can Replace from MATLAB Code”
• “Code Replacement Match and Replacement Process”
• “Code Replacement Libraries”
• “Code Replacement Terminology”
22-149
22 Code Replacement Customization for MATLAB Code
This example creates a code replacement entry that replaces int32 to int16
data type conversion (cast) operations. The example defines the function mapping
programmatically. Alternatively, you can use the Code Replacement Tool to define the
same mapping.
22-150
Data Type Conversions (Casts) and Operator Code Replacement
7 Add the entry to a code replacement table with a call to the addEntryfunction.
addEntry(hLib, hEnt);
You can use code replacement entries to replace code that the code generator produces for
data type conversion (cast) operations.
This example creates a code replacement entry to replace data type conversions (casts)
of fixed-point data types by using a net slope. The example defines the function mapping
programmatically. Alternatively, you can use the Code Replacement Tool to define the
same mapping.
hTable = RTW.TflTable;
3 Create the entry for the operator mapping with a call to the
RTW.TflCOperationEntryGenerator_Netslope function, which provides
access to the fixed-point parameters NetSlopeAdjustmentFactor and
NetFixedExponent
op_entry = RTW.TflCOperationEntryGenerator_NetSlope;
4 Set operator entry parameters with a call to the
setTflCOperationEntryParameters function. The parameters specify the
type of operation as cast, the saturation mode as saturate on overflow, rounding
modes as toward negative infinity, and the name of the replacement function as
my_fxp_cast. NetSlopeAdjustmentFactor and NetFixedExponent specify the
F and E parts of the net slope F2 .
E
InFL = 2;
InWL = 16;
InSgn = true;
OutFL = 4;
22-151
22 Code Replacement Customization for MATLAB Code
OutWL = 32;
OutSgn = true;
setTflCOperationEntryParameters(op_entry, ...
'Key', 'RTW_OP_CAST', ...
'Priority', 50, ...
'SaturationMode', 'RTW_SATURATE_ON_OVERFLOW', ...
'RoundingModes', {'RTW_ROUND_FLOOR'}, ...
'NetSlopeAdjustmentFactor', 1.0, ...
'NetFixedExponent', (OutFL - InFL), ...
'ImplementationName', 'my_fxp_cast', ...
'ImplementationHeaderFile', 'some_hdr.h', ...
'ImplementationSourceFile', 'some_hdr.c');
5 Create conceptual arguments y1 and u1. This example uses calls to the
createAndAddConceptualArg function to create and add an argument with one
function call. Each argument is specified as fixed-point and signed. Each argument
specifies that code replacement request processing does not check for an exact match
to the call-site slope and bias values.
createAndAddConceptualArg(op_entry, 'RTW.TflArgNumeric', ...
'Name', 'y1', ...
'IOType', 'RTW_IO_OUTPUT', ...
'CheckSlope', false, ...
'CheckBias', false, ...
'DataTypeMode', 'Fixed-point: binary point scaling', ...
'IsSigned', OutSgn, ...
'WordLength', OutWL, ...
'FractionLength',OutFL);
createAndAddImplementationArg(op_entry, 'RTW.TflArgNumeric',...
22-152
Data Type Conversions (Casts) and Operator Code Replacement
7 Add the entry to a code replacement table with a call to the addEntryfunction.
addEntry(hTable, op_entry);
Related Examples
• “Define Code Replacement Mappings”
• “Fixed-Point Operator Code Replacement”
• “Binary-Point-Only Scaling Code Replacement”
• “Slope Bias Scaling Code Replacement”
• “Net Slope Scaling Code Replacement”
• “Equal Slope and Zero Net Bias Code Replacement”
• “Shift Left Operations and Code Replacement”
• “Remap Operator Output to Function Input”
• “Customize Matching and Replacement Process for Operators”
• “Develop a Code Replacement Library”
• “Quick Start Library Development”
More About
• “What Is Code Replacement?”
• “What Is Code Replacement Customization?”
• “Code You Can Replace from MATLAB Code”
• “Code Replacement Match and Replacement Process”
• “Code Replacement Libraries”
• “Code Replacement Terminology”
22-153
22 Code Replacement Customization for MATLAB Code
This example creates a code replacement entry to replace shift left operations for int16
data. The example defines the function mapping programmatically. Alternatively, you
can use the Code Replacement Tool to define the same mapping.
hTable = RTW.TflTable;
3 Create the entry for the operator mapping with a call to the
RTW.TflCOperationEntry function.
op_entry = RTW.TflCOperationEntry;
4 Set operator entry parameters with a call to the
setTflCOperationEntryParameters function. The parameters specify the type of
operation as shift left and the name of the replacement function as my_shift_left.
setTflCOperationEntryParameters(op_entry, ...
'Key', 'RTW_OP_SL', ...
'Priority', 50, ...
'ImplementationName', 'my_shift_left', ...
'ImplementationHeaderFile', 'some_hdr.h', ...
'ImplementationSourceFile', 'some_hdr.c');
22-154
Shift Left Operations and Code Replacement
7 Create the int8 argument as conceptual and implementation argument u2. This
example uses calls to the getTflArgFromString and addConceptualArg
functions to create the conceptual argument and add it to the entry. This argument
specifies the number of bits to shift the previous input argument. Because the
argument type is not relevant, the example disables type checking by setting the
CheckType property to false. Convenience method addArgument specifies the
argument as implementation input argument.
arg = getTflArgFromString(hTable, 'u2', 'int8');
arg.CheckType = false;
addConceptualArg(op_entry, arg);
op_entry.Implementation.addArgument(arg);
You can use code replacement entries to replace code that the code generator produces for
shift (<<) operations.
This example creates a code replacement entry to replace shift left operations
for fixed-point data using a net slope. The example defines the function mapping
programmatically. Alternatively, you can use the Code Replacement Tool to define the
same mapping.
22-155
22 Code Replacement Customization for MATLAB Code
InFL = 2;
InWL = 16;
InSgn = true;
OutFL = 4;
OutWL = 32;
OutSgn = true;
setTflCOperationEntryParameters(op_entry, ...
'Key', 'RTW_OP_SL', ...
'Priority', 50, ...
'SaturationMode', 'RTW_SATURATE_ON_OVERFLOW', ...
'RoundingModes', {'RTW_ROUND_FLOOR'}, ...
'NetSlopeAdjustmentFactor', 1.0, ...
'NetFixedExponent', (OutFL - InFL),...
'ImplementationName', 'my_fxp_shift_left', ...
'ImplementationHeaderFile', 'some_hdr.h', ...
'ImplementationSourceFile', 'some_hdr.c');
5 Create conceptual arguments y1 and u1. This example uses calls to the
createAndAddConceptualArg function to create and add an argument with one
function call. Each argument is specified as fixed-point and signed. Each argument
specifies that code replacement request processing does not check for an exact match
to the call-site slope and bias values.
createAndAddConceptualArg(op_entry, 'RTW.TflArgNumeric', ...
'Name', 'y1', ...
'IOType', 'RTW_IO_OUTPUT', ...
'CheckSlope', false, ...
'CheckBias', false, ...
'DataTypeMode', 'Fixed-point: binary point scaling', ...
'IsSigned', OutSgn, ...
'WordLength', OutWL, ...
'FractionLength',OutFL);
22-156
Shift Left Operations and Code Replacement
7 Create the int8 argument as conceptual and implementation argument u2. This
example uses calls to the getTflArgFromString and addConceptualArg
functions to create the conceptual argument and add it to the entry. This argument
specifies the number of bits to shift the previous input argument. Because the
argument type is not relevant, type checking is disabled by setting the CheckType
property to false. Convenience method addArgument specifies the argument as
implementation input argument.
arg = getTflArgFromString(hTable, 'u2', 'uint8');
arg.CheckType = false;
addConceptualArg(op_entry, arg);
op_entry.Implementation.addArgument(arg);
8 Add the entry to a code replacement table with a call to the addEntryfunction.
addEntry(hTable, op_entry);
Related Examples
• “Define Code Replacement Mappings”
• “Fixed-Point Operator Code Replacement”
• “Binary-Point-Only Scaling Code Replacement”
• “Slope Bias Scaling Code Replacement”
• “Net Slope Scaling Code Replacement”
• “Equal Slope and Zero Net Bias Code Replacement”
• “Data Type Conversions (Casts) and Operator Code Replacement”
22-157
22 Code Replacement Customization for MATLAB Code
More About
• “What Is Code Replacement?”
• “What Is Code Replacement Customization?”
• “Code You Can Replace from MATLAB Code”
• “Code Replacement Match and Replacement Process”
• “Code Replacement Libraries”
• “Code Replacement Terminology”
22-158
Performance
23
Configuration
23-2
Configure Code Optimizations
The following table includes optimization parameters on the Optimization > Signals
and Parameters pane:
23-3
23 Configuration
23-4
Specify Global Variable Localization
Some of the global variables that the code generator can localize include:
1 In the Configuration Parameters dialog box, on the Code Generation pane, in the
System target file box, specify an ERT target.
2 Verify that the OptimizeBlockIOStorage parameter is set to ‘on’:
>> get_param(gcs,'OptimizeBlockIOStorage')
ans =
on
3 Verify that AdvancedOptControl is not set to ‘-SLCI’:
>> get_param(gcs,'AdvancedOptControl')
ans =
''
4 Set the storage class for signals to Auto.
The code generator does not localize global variables for MATLAB system objects or
AUTOSAR.
23-5
23 Configuration
Before generating and deploying code, you should become familiar with the options on
the Hardware Implementation pane of the Configuration Parameters dialog box. See
“Hardware Implementation Pane” in the Simulink documentation and “Platform Options
for Development and Deployment” in the Simulink Coder documentation for full details
on the Hardware Implementation pane.
You can use the rtwdemo_targetsettings demo model to determine some implementation-
dependent characteristics of your C or C++ compiler, as well as characteristics of your
target hardware. By using this model in conjunction with your target development
system and debugger, you can observe the behavior of the code as it executes on the
target. You can then use this information to configure the Hardware Implementation
parameters of your model.
23-6
Use External Mode with the ERT Target
This section discusses external mode options that may be of special interest to embedded
systems designers. The next figure shows the Data Exchange subpane of the
Configuration Parameters dialog box, Interface pane, with External mode selected.
Memory Management
Consider the Memory management option Static memory allocation before
generating external mode code for an embedded target. Static memory allocation is
generally desirable, as it reduces overhead and promotes deterministic performance.
When you select the Static memory allocation option, static external mode
communication buffers are allocated in the target application. When Static memory
allocation is deselected, communication buffers are allocated dynamically (with
malloc) at run time.
This enhancement lets you generate external mode code that is free of storage definitions
of double or float data type, and allows your code to run on integer-only processors
23-7
23 Configuration
If you intend to generate pure integer code with External mode on, note the following
requirements:
• All trigger signals must be of data type int32. Use a Data Type Conversion block if
needed.
• When pure integer code is generated, the simulation stop time specified in the Solver
options is ignored. To specify a stop time, run your target application from the
MATLAB command line and use the -tf option. (See “Run the External Program” in
the Simulink Coder documentation.) If you do not specify this option, the application
executes indefinitely (as if the stop time were inf).
When executing pure integer target applications, the stop time specified by the -tf
command line option is interpreted as the number of base rate ticks to execute, rather
than as an elapsed time in seconds. The number of ticks is computed as
stop time in seconds / base rate step size in seconds
23-8
24
• Whether the generated code meets real-time requirements of your target hardware.
• Code sections that require performance improvements.
The following tasks represent a general workflow that uses code execution profiling:
• If the algorithm code easily meets the requirements, consider enhancing your
algorithm to exploit available processing power.
• If the code cannot be executed in real time, look for ways to reduce execution
time.
Identify the tasks that require the most time. For these tasks, investigate
whether trade-offs between functionality and speed are possible.
To find information about code execution profiling with Simulink products, use the
following table.
24-2
Execution Profiling for Generated Code
24-3
24 Code Execution Profiling
24-4
Code Execution Profiling for SIL and PIL
Use the execution time profile to check whether your code runs in real time on your
target hardware:
• If code execution overruns, look for ways to reduce execution time. For example:
Note: Tasks are main entry points into the generated code. For example, the step
function for a sample rate or the model_initialize function.
The software collects execution time measurements in a variable that you specify. See
“Configure Code Execution Profiling for SIL and PIL” on page 24-6.
See “View and Compare Code Execution Times” on page 24-10 and “Analyze Code
Execution Data” on page 24-16.
24-5
24 Code Execution Profiling
1 In your top model, open the Configuration Parameters dialog box, and select the
Code Generation > Verification pane.
2 Select the Measure task execution time check box.
3 If you also want function execution times, select the Measure function execution
times check box. For information about how you apply this setting to atomic
subsystems and model reference hierarchies, see “Execution Profiling for Atomic
Subsystems and Model Reference Hierarchies” on page 24-8.
4 In the Workspace variable field, specify a name. When you run the simulation,
the software generates a variable with this name in the MATLAB base workspace.
The variable contains the execution time measurements, and is an object of type
coder.profile.ExecutionTime.
If you select the Data Import/Export > Save simulation output as single object
check box, the software creates the variable in the Simulink.SimulationOutput
object that you specify.
5 From the Save options drop-down list, select one of the following:
• Summary data only — If you want to generate only a report and reduce
memory usage, for example, during a long simulation. See “View and Compare
Code Execution Times” on page 24-10.
• All measurement and analysis data — Allows you to generate a
report and store execution time profiles in the base workspace. After the
simulation, you can use methods from the coder.profile.ExecutionTime and
coder.profile.ExecutionTimeSection classes to retrieve execution time
measurements for every call to each profiled section of code that occurs during the
simulation. See “Analyze Code Execution Data” on page 24-16.
6 Click OK.
For a PIL simulation, you must configure a hardware-specific timer. When you set up the
connectivity configuration for your target, create a timer object. See “Create PIL Target
Connectivity Configuration”. This action is not required for a SIL simulation.
If you select All measurement and analysis data from the Save options drop-
down list, the generated report displays Simulation Data Inspector icons . When you
24-6
Configure Code Execution Profiling for SIL and PIL
click one of these icons, the software imports simulation results into the Simulation Data
Inspector. You can then plot execution times and manage and compare plots from various
simulations. See “View and Compare Code Execution Times” on page 24-10.
For details about automatically importing simulation data into the Simulation Data
Inspector, see “Validate System Behavior”.
24-7
24 Code Execution Profiling
To generate function execution data for atomic subsystems in the top model, on the Code
Generation > Verification pane, you must select the Measure task execution time
and Measure function execution times check boxes.
Note: In the generated code, the software wraps each function call with measurement
probes except when:
• The call site cannot be wrapped because of expression folding (see “Minimize
Computations and Storage for Intermediate Results”).
• The call site is located in the shared utility code (see “Sharing Utility Code”).
You might not want to generate profiles for specific subsystems. To disable code
execution profiling for a subsystem in the top model:
24-8
Execution Profiling for Atomic Subsystems and Model Reference Hierarchies
1 In the top model, open the Configuration Parameters dialog box, and select the Code
Generation > Verification pane.
2 Select the Measure task execution time check box.
3 For each Model block that you want to profile, select Measure function execution
times only at the reference level for which you require function execution data.
For example, consider a top model that has Model block A, which in turn contains Model
block B.
If you want to generate execution times for functions from model B, select Measure task
execution time for the top model and Measure function execution times for model
B.
Note: By default, the Model block parameter, Code under test is set to Model
reference. If this block parameter is set to Top model, the configuration parameter
Measure task execution time for the top model and the referenced model must be the
same. Otherwise, the software produces an error.
If your top model has a PIL block, the execution profiling settings that apply to the PIL
block are the settings from the original model that you used to create the PIL block. See
“Use a SIL or PIL Block”. The execution profiling settings of your top model do not apply
to the PIL block.
24-9
24 Code Execution Profiling
24-10
View and Compare Code Execution Times
When you run a SIL simulation, the software generates the variable
executionProfile in the MATLAB base workspace.
Note: If you select the Data Import/Export > Save simulation output as
single object check box, the software creates the variable in your specified
Simulink.SimulationOutput object.
>> report(executionProfile)
24-11
24 Code Execution Profiling
Part 1 provides a summary. Part 2 contains information about profiled code sections.
You can expand and collapse profiled sections in Part 2 by clicking [+] and [–]
respectively. The following graphic shows fully expanded sections.
You can go to a profiled code section in the Generated Code view of the Code Generation
Report. In the Code Execution Profiling Report, on a code section row, click the icon .
For example, if you click the icon in the rtwdemo_sil_topmodel_initialize row, you
see the measurement probes around the call site in the SIL test harness.
24-12
View and Compare Code Execution Times
By default, the report displays time in nanoseconds (10-9 seconds). You can specify the
time unit and numeric display format. For example, to display time in microseconds (10-6
seconds), use the following command:
>>report(executionProfile,'Units', 'Seconds', 'ScaleFactor', '1e-06', 'NumericFormat', '%0.3f')
The report displays time in seconds only if the timer is calibrated, that is, the number
of timer ticks per second is known. On a Windows machine, the software automatically
determines this value for a SIL simulation. On a Linux machine, you must manually
calibrate the timer. For example, if your processor speed is 1 GHz, specify the number of
timer ticks per second:
>>executionProfile.TimerTicksPerSecond = 1e9;
For more information, see “Analyze Code Execution Data” on page 24-16.
To display measured execution times for a task or function, click the Simulation Data
Inspector icon on the corresponding row. You can use the Simulation Data Inspector
to manage and compare plots from various simulations.
24-13
24 Code Execution Profiling
For information, see “Inspect Signal Data with Simulation Data Inspector”.
Note: To observe how code sections are invoked over the execution timeline, use the
timeline function.
The following table describes the information provided in the code section profiles.
Column Description
Model Name of task, top model, subsystem, or Model block. Click the link
to go to the model.
With a task, the sample period and sample offset are listed next
to the task name. For example, rtwdemo_sil_topmodel_step
[0.1 0] indicates that the sample period is 0.1 seconds and the
sample offset is 0.
Maximum Maximum time between start and end of function execution.
Execution Time Includes time spent in child functions.
Average Execution Average time between start and end of execution. Includes time
Time spent in child functions.
Maximum Self Longest time spent in function. Excludes time spent in child
Time functions.
Average Self Time Average time spent in function. Excludes time spent in child
functions.
Calls Number of calls made to task or function.
Icon that you click in the Code Execution Profiling Report to see
the profiled code section in the Generated Code view of the Code
Generation Report. Code section can be a task or function.
24-14
View and Compare Code Execution Times
Column Description
Icon that you click to display measured execution times with
Simulation Data Inspector.
24-15
24 Code Execution Profiling
To get the total number of code sections that have profiling data, use the Sections
method.
>> no_of_Sections = myExecutionProfile.Sections
no_of_Sections =
2
>>
To get the coder.profile.ExecutionTimeSection object for a profiled code section,
use the method Sections.
>> FirstSectionProfile = myExecutionProfile.Sections(1)
coder.profile.ExecutionTimeTaskSection
coder.profile.ExecutionTimeTaskSection
24-16
Analyze Code Execution Data
>>
name_of_section =
rtwdemo_sil_topmodel_step [0.1 0]
>>
If the timer is uncalibrated and you know the timer rate, for example 2.2 GHz, you can
use the coder.profile.ExecutionTime method TimerTicksPerSecond to calibrate
the timer:
>> myExecutionProfile.TimerTicksPerSecond(2.2e9)
>> SecondSectionProfile = myExecutionProfile.Sections(2);
>>
24-17
24 Code Execution Profiling
For execution time measurements greater than 232 ticks, the counter wraps. (If you
are profiling a real-time, multi-core application, the software reduces the effective
measurement range of the timer to accommodate synchronization discrepancies in the
recording of timer values for different cores.) Counter wrapping occurs when the actual
execution time is very long. Counter wrapping results in a measured execution time that
is shorter than expected.
Hardware-Specific Timer
If your target configuration does not already specify a timer, you must specify one. To
specify a timer, you must create a timer object that provides details of the hardware-
specific timer and associated source files:
• For SIL simulation, the timer word length is determined by your MEX compiler. The
word length is 64 bits, unless your selected MEX compiler is Lcc. In this case, the
word length is 32 bits.
• For PIL simulation, you can specify an 8-, 16-, 32-, or 64-bit timer.
24-18
Tips and Limitations
of instrumentation. For example, with a real-time system, there can be task context
switches due to preemption. These context switches are not explicitly instrumented.
To record the start and end of each task, the software must infer context switches from
instrumentation. As a result, the software reports behavior that is an estimate. The
estimate is subject to error because of incomplete instrumentation within the kernel.
In some cases, when the software cannot accurately determine behavior, the software
generates a warning:
Warning: Analysis unsuccessful for one or more profiling data points. ...
For example, the software might generate this warning when not all mutex take system
calls (associated with rate transitions) are instrumented. In the case of Simulink Real-
Time, this situation might arise if you generate code for a model reference hierarchy
without enabling function profiling for all referenced models (set_param(model,
'CodeProfilingInstrumentation', 'on'). If a mutex take system call is not
instrumented, a task context switch might occur that is not visible to the execution
profiling analysis.
In other cases, although the software cannot accurately determine behavior, the software
does not generate a warning.
24-19
24-20
25
Use the execution time profile to check whether your code runs within the required time
on your target hardware:
Note: SIL and PIL execution supports multiple entry-point functions. An entry-point
function can call another entry-point function as a subfunction. However, the software
generates execution time profiles only for functions that are called at the entry-point
level. The software does not generate execution time profiles for entry-point functions
that are called as subfunctions by other entry-point functions.
25-2
Generate Execution Time Profile
config.CodeExecutionProfiling = true;
For information about setting up a SIL or PIL execution, see “Code Verification”.
25-3
25 Code Execution Profiling for MATLAB Coder
Click the clear kalman01_sil link. The software terminates the execution process
and displays a new link.
### Stopping SIL execution for 'kalman01'
Execution profiling report: report(getCoderExecutionProfile('kalman01'))
Click the report link. The software opens the Code Execution Profiling Report.
The first section provides a summary. The second section contains information about
profiled code sections.
25-4
View Execution Time Profile
By default, the report displays time in nanoseconds (10-9 seconds). You can specify the
time unit and numeric display format. For example, to display time in microseconds (10-6
seconds), use the “report” command:
executionProfile=getCoderExecutionProfile('kalman01'); % Create workspace var
report(executionProfile, ...
'Units', 'Seconds', ...
'ScaleFactor', '1e-06', ...
'NumericFormat', '%0.3f')
The report displays time in seconds only if the timer is calibrated, that is, the number of
timer ticks per second is established. On a Windows machine, the software determines
this value for a SIL simulation. On a Linux machine, you must manually calibrate the
timer. For example, if your processor speed is 1 GHz, specify the number of timer ticks
per second:
executionProfile.TimerTicksPerSecond = 1e9;
For more information, see “Analyze Execution Time Data” on page 25-7.
To display measured execution times for a function, click the Simulation Data Inspector
icon on the corresponding row. You can use the Simulation Data Inspector to manage
and compare plots from various executions. For information, see “Inspect Signal Data
with Simulation Data Inspector”.
The following table lists the information provided in the code section profiles.
Column Description
Section Name of function from which code is generated.
Maximum Maximum time between start and end of function execution.
Execution Time Includes time spent in child functions.
Average Execution Average time between start and end of execution. Includes time
Time spent in child functions.
Maximum Self Longest time spent in function. Excludes time spent in child
Time functions.
Average Self Time Average time spent in function. Excludes time spent in child
functions.
Calls Number of calls made to function.
25-5
25 Code Execution Profiling for MATLAB Coder
Column Description
Icon that you click to display the profiled code section in the
Command Window.
Icon that you click to display measured execution times with
Simulation Data Inspector.
25-6
Analyze Execution Time Data
In the following example, you run a SIL execution and apply supplied methods to
execution time data.
src_dir = ...
fullfile(docroot,'toolbox','coder','examples','kalman');
copyfile(fullfile(src_dir,'kalman01.m'), '.')
copyfile(fullfile(src_dir,'test01_ui.m'), '.')
copyfile(fullfile(src_dir,'plot_trajectory.m'), '.')
copyfile(fullfile(src_dir,'position.mat'), '.')
For a description of the Kalman estimator, see “C Code Generation at the Command
Line”.
config = coder.config('lib');
config.GenerateReport = true; % HTML report
Configure the object for SIL and enable execution time profiling.
config.VerificationMode = 'SIL';
config.CodeExecutionProfiling = true;
Generate library code for the kalman01 MATLAB function and the SIL interface.
Run the MATLAB test file test01_ui with kalman01_sil. kalman01_sil is the
SIL interface for kalman01.
25-7
25 Code Execution Profiling for MATLAB Coder
Terminate the SIL execution process. Click the link clear kalman01_sil.
executionProfile=getCoderExecutionProfile('kalman01');
3
Extract code sections
Use the Sections method.
allSections = executionProfile.Sections
The software displays the number of code sections and a list of properties.
allSections =
Name
Number
ExecutionTimeInTicks
SelfTimeInTicks
TurnaroundTimeInTicks
TotalExecutionTimeInTicks
TotalSelfTimeInTicks
TotalTurnaroundTimeInTicks
MaximumExecutionTimeInTicks
MaximumExecutionTimeCallNum
MaximumSelfTimeInTicks
25-8
Extract execution time data from specific code section
MaximumSelfTimeCallNum
MaximumTurnaroundTimeInTicks
MaximumTurnaroundTimeCallNum
NumCalls
ExecutionTimeInSeconds
Time
4
Extract execution time data from specific code section
Specify the code section that you want to examine.
secondSectionProfile = executionProfile.Sections(2)
The software displays profile data for the code section.
secondSectionProfile =
Name: 'kalman01'
Number: 2
ExecutionTimeInTicks: [1x300 uint64]
SelfTimeInTicks: [1x300 uint64]
TurnaroundTimeInTicks: [1x300 uint64]
TotalExecutionTimeInTicks: 6641016
TotalSelfTimeInTicks: 6641016
TotalTurnaroundTimeInTicks: 6641016
MaximumExecutionTimeInTicks: 48864
MaximumExecutionTimeCallNum: 158
MaximumSelfTimeInTicks: 48864
MaximumSelfTimeCallNum: 158
MaximumTurnaroundTimeInTicks: 48864
MaximumTurnaroundTimeCallNum: 158
NumCalls: 300
ExecutionTimeInSeconds: [1x300 double]
Time: [300x1 double]
You can extract specific properties, for example, the name of a profiled function.
nameOfSection = secondSectionProfile.Name
The software displays the name.
nameOfSection =
kalman01
25-9
25 Code Execution Profiling for MATLAB Coder
The following table lists the information that you can extract from each code section.
Property Description
Name Name of entry-point function
Number Code section number
ExecutionTimeInTicksVector of execution times, measured in timer ticks.
Each element contains the difference between the timer
reading at the start and at the end of the code section.
The data type is the same data type as the data type of
the timer used on the target, which allows you to infer the
maximum range of the timer measurements.
SelfTimeInTicks Vector of timer tick numbers. Each element contains the
number of ticks recorded for the code section, excluding
the time spent in calls to child functions.
Vector of timer tick numbers. Each element contains the
TurnaroundTimeInTicks
number of ticks recorded between the start and the finish
of the code section. Unless the code is preempted, this
number is the same number as the execution time.
Total number of timer ticks recorded for the code section
TotalExecutionTimeInTicks
over the entire execution.
TotalSelfTimeInTicksTotal number of timer ticks recorded for the profiled code
section over the entire execution. However, this number
excludes the time spent in calls to child functions.
Total number of timer ticks recorded between the start
TotalTurnaroundTimeInTicks
and the finish of the profiled code section over the entire
execution. Unless the code is preempted, this number is
the same as the total execution time.
Maximum number of timer ticks recorded for a single
MaximumExecutionTimeInTicks
invocation of the code section over the execution.
Number of call in which
MaximumExecutionTimeCallNum
MaximumExecutionTimeInTicks occurs.
Maximum number of timer ticks recorded for a single code
MaximumSelfTimeInTicks
section invocation, but excluding the time spent in calls to
child functions.
25-10
Extract execution time data from specific code section
Property Description
Number of call in which MaximumSelfTimeInTicks
MaximumSelfTimeCallNum
occurs.
Maximum number of timer ticks recorded between
MaximumTurnaroundTimeInTicks
the start and the finish of a single invocation of the
profiled code section over the execution. Unless the code
is preempted, this time is the same as the maximum
execution time.
Number of call in which
MaximumTurnaroundTimeCallNum
MaximumTurnaroundTimeInTicks occurs.
NumCalls Total number of calls to the code section over the entire
execution.
Vector of execution times, measured in seconds. Each
ExecutionTimeInSeconds
element contains the difference between the timer reading
at the start and at the end of the code section. Produced
only if TimerTicksPerSecond is set.
Time Vector of execution time measurements for the code
section.
25-11
25-12
26
In this section...
“Minimize Global Data Access” on page 26-3
“Use Global to Hold Temporary Results” on page 26-8
To tune your application and choose tradeoffs for execution speed and memory usage, you
can choose a global variable reference optimization for the generated code.
In the Configuration Parameters dialog box, select Optimization > Signals and
Parameters. In the Optimize global data access drop-down list, three parameter
options control global variable usage optimizations.
• None. Use default optimizations. This choice works well for most models. The code
generator balances the use of local and global variables. It generates code which
balances RAM and ROM consumption and execution speed.
• Use global to hold temporary results. Reusing global variables improves
code efficiency and readability. This optimization reuses global variables, which
results in fewer variables defined by the code generator. It reduces RAM and ROM
consumption and data copies.
• Minimize global data access. Using local variables to cache global data reduces
ROM consumption by reducing code size in certain cases, such as when the global
variables are scalars. This optimization improves execution speed because the
code uses fewer instructions for local variable references than for global variable
references.
26-2
Optimize Global Variable Usage
• None
Use default optimizations. This choice works well for most models. The code generator
balances the use of local and global variables. It produces balanced optimizations of
RAM and ROM consumption and execution speed.
• Minimize global data access
Minimize the use of global variables by using local variables to hold intermediate
values. This optimization reduces ROM and RAM consumption by reducing code size
in certain cases, such as when the global variables are scalars.
Minimizing the use of global variables by using local variables interacts with stack
usage control. For example, stack size can determine the number of local and global
variables that the code generator can allocate in the generated code. For more
information, see “Customize Stack Space Allocation” and “Control Signal Storage” on
page 26-18.
Example Model
26-3
26 Data Copy Reduction
In the Configuration Parameters dialog box, on the Optimization > Signals and
Parameters pane, verify that the Signal Storage Reuse check box is selected. From
the Optimize global data access list, select None.
Generate Code
The code assigns values to the global vector rtY.Out1 in each case statement without
using a local variable. This assignment improves ROM and RAM consumption and
26-4
Optimize Global Variable Usage
reduces data copies. The code places the value in the destination variable for each
assignment instead of copying the value at the end.
switch ((int32_T)rtU.In1) {
case 1:
/* Outport: '<Root>/Out1' incorporates:
* Constant: '<Root>/Constant'
*/
rtY.Out1 = 1.0;
break;
case 2:
/* Outport: '<Root>/Out1' incorporates:
* Constant: '<Root>/Constant1'
*/
rtY.Out1 = 2.0;
break;
case 3:
/* Outport: '<Root>/Out1' incorporates:
* Constant: '<Root>/Constant2'
*/
rtY.Out1 = 3.0;
break;
default:
/* Outport: '<Root>/Out1' incorporates:
* Constant: '<Root>/Constant3'
*/
rtY.Out1 = 4.0;
break;
}
In the Static Code Metrics Report, examine the Global Variables section.
1 In the Code Generation report window, click Static Code Metrics Report.
2 Scroll down to the Global Variables section.
3 Click [+] before each variable to expand it.
26-5
26 Data Copy Reduction
Enable Optimization
On the Optimization > Signals and Parameters pane, from the Optimize global
data access list, select Minimize global data access. Click Apply.
In the rtwdemo_optimize_global.c listing, the code assigns the constant value to the
local variable tmp_Out1 in each case statement. The last statement in the code listing
copies the value of tmp_Out1 to the global variable rtY.Out1. Fewer global variable
references result in fewer instructions and improved execution speed.
switch ((int32_T)rtU.In1) {
case 1:
/* Outport: '<Root>/Out1' incorporates:
* Constant: '<Root>/Constant'
*/
tmp_Out1 = 1.0;
break;
26-6
Optimize Global Variable Usage
case 2:
/* Outport: '<Root>/Out1' incorporates:
* Constant: '<Root>/Constant1'
*/
tmp_Out1 = 2.0;
break;
case 3:
/* Outport: '<Root>/Out1' incorporates:
* Constant: '<Root>/Constant2'
*/
tmp_Out1 = 3.0;
break;
default:
/* Outport: '<Root>/Out1' incorporates:
* Constant: '<Root>/Constant3'
*/
tmp_Out1 = 4.0;
break;
}
/* Outport: '<Root>/Out1' */
rtY.Out1 = tmp_Out1;
}
In the Static Code Metrics Report, examine the Global Variables section.
26-7
26 Data Copy Reduction
As a result of minimizing global data accesses, the total number of reads and writes for
global variables has decreased from 5 to 2.
• None
Use default optimizations. This choice works well for most models. The code generator
balances the use of local and global variables. It generates code which balances RAM
and ROM consumption and execution speed.
• Use global to hold temporary results
Maximize use of global variables. Reusing global variables improves code efficiency
and readability. This optimization reuses global variables, which results in fewer
variables defined by the code generator, reducing RAM and ROM consumption and
data copies.
Example Model
Set up the configuration for the model. In the Configuration Parameters dialog box, on
the Optimization > Signals and Parameters pane, verify that the Signal Storage
Reuse check box is selected. From the Optimize global data access list, select None.
Generate Code
26-8
Optimize Global Variable Usage
2 Click Apply.
3 Click Generate Code.
The code assigns values to the local vector rtb_Assignment. The last statement copies
the values in the local vector rtb_Assignment to the global vector rtY.Out1. Fewer
global variable references result in improved execution speed. The code uses more
instructions for global variable references than for local variable references.
rtb_Assignment[1] = rtU.In1;
In the Static Code Metrics Report, examine the Global Variables section.
1 In the Code Generation report window, click Static Code Metrics Report.
26-9
26 Data Copy Reduction
Enable Optimization
On the Optimization > Signals and Parameters pane, from the Optimize global
data access list, select Use global to hold temporary results. Click Apply.
The code assigns values to the global vector rtY.Out1 without using a local variable.
This assignment improves ROM and RAM consumption and reduces data copies. The
code places the value in the destination variable for each assignment instead of copying
the value at the end.
rtY.Out1[1] = rtU.In1;
26-10
Optimize Global Variable Usage
In the Static Code Metrics Report, examine the Global Variables section.
As a result of using global variables to hold local results, the total number of reads and
writes for global variables has increased from 2 to 5. This optimization reduces data
copies by reusing global variables.
26-11
26 Data Copy Reduction
This example shows the results of enabling the Reuse global block outputs
parameter.
Example Model
26-12
Reuse Block Outputs in the Generated Code
1 In the Configuration Parameters dialog box, on the Optimization > Signals and
Parameters pane, verify that Signal Storage Reuse is selected.
2 Clear Reuse global block outputs.
3 On the Code Generation > Report pane select Static code metrics.
Generate Code
26-13
26 Data Copy Reduction
The total number of reads and writes for global variables is 8. The total size in bytes is
28.
Enable Optimization
On the Optimization > Signals and Parameters pane, select Reuse global block
outputs. Click Apply.
The code generator reduces two statements to one statement and three global variables
to two global variables. This optimization reduces ROM and RAM consumption and
improves execution speed.
rtY.Out1 += rtU.In1;
26-14
Reuse Block Outputs in the Generated Code
The optimization reduces the total number of reads and writes for global variables from 8
to 5 and the total size in bytes from 28 to 20.
For more information, see “Optimize Global Variable Usage” on page 26-2.
26-15
26 Data Copy Reduction
Consider the model in the following block diagram. The signal exportedSig has
exportedGlobal storage class.
In the default case, the output of the Gain block is written to the signal storage location,
exportedSig. The code generator does not generate code or data for the Out1 block,
which has become a virtual block.
/* Gain Block: <Root>/Gain */
exportedSig = rtb_PulseGen * VirtOutPortLogOFF_P.Gain_Gain;
The following code fragment was generated with MAT-file logging enabled. The output
port is represented as a member of the external outputs vector VirtOutPortLogON_Y.
The Gain block output value is copied to exportedSig and to the external outputs
vector.
/* Gain Block: <Root>/Gain */
exportedSig = rtb_PulseGen * VirtOutPortLogON_P.Gain_Gain;
Data maintenance in the external outputs vector can be significant for smaller models
that perform benchmarks.
You can force root output ports to be stored in the external outputs vector (regardless of
the setting of MAT-file logging) by setting the TLC variable FullRootOutputVector
to 1. Add the statement
26-16
Virtualized Output Ports Optimization
%assign FullRootOutputVector = 1
to the Embedded Coder system target file. Alternatively, you can enter the assignment
from the MATLAB command line using the set_param command, the model parameter
TLCOptions, and the TLC option -a. For more information, see “Specify TLC Options”
and “Configure TLC”.
For more information on how to control signal storage in generated code, see “Signals”.
26-17
26 Data Copy Reduction
You can choose to store signals in global memory space or locally in functions, in stack
variables. For more information, see “Signals”.
If you want to store signals in stack space, you must enable the Enable local block
outputs option.
1 In the Configuration Parameters dialog box, select Optimization > Signals and
Parameters. Select Signal storage reuse.
2 Select the Enable local block outputs option. Click Apply.
26-18
Signal Reuse for Root-Level Model Inputs and Outputs
1 Choose one root-level input signal and one root-level output signal. Assign them the
same name. The name is used for the reused variable name in the generated code.
Specify that the signal name must resolve to a Simulink.Signal object.
2 Create a Simulink.Signal object and specify the same name as you chose for the
signals in the previous step. Set the storage class to Custom. Set the custom storage
class to Reusable or to a custom storage class that you derived from Reusable.
Verify that Is Reusable is set to Yes.
In some cases, code generation creates an extra buffer to satisfy requested buffer use for
the specified signal.
When you run an executable produced by code generation, and you reuse a root I/O pair,
it is important that when the root input value is zero that the root output value is also
zero. If the output value is nonzero and you reuse the signals, then the results from the
simulation can differ from the results produced by the executable.
26-19
26 Data Copy Reduction
1 In the Configuration Parameters dialog box, on the Code Generation pane, set
System target file to ert.tlc.
2 Select Generate code only.
3 Click Apply.
4 Click Generate Code.
In the rtwdemo_merge.h header file the code generator declares these variables: In1,
In2, In3, and Out1, for a total of four variables.
26-20
Signal Reuse for Root-Level Model Inputs and Outputs
Enable Optimization
1 Choose a pair of root-level input and outputs. For this example, choose In1 for the
root-level input and Out1 for the root-level output.
2 For the input signal:
a Right-click the signal line. From the context menu, choose Properties.
b Set Signal name to mysig. Press Tab.
c Select Signal name must resolve to Simulink signal object.
d Click OK.
3 Repeat step 2 for the corresponding output signal.
The model, after being configured, with the root I/O signals labelled with Reuse,
looks like this:
26-21
26 Data Copy Reduction
4 Create a reusable signal object. Call it mysig, to match the name of the input and
output signals. In the Command Window, enter:
mysig=Simulink.Signal;
mysig.CoderInfo.StorageClass = 'Custom';
mysig.CoderInfo.CustomStorageClass = 'Reusable';
In the rtwdemo_merge.h header file, the code generator declares In2, In3, and
mysig, resulting in three variables.
/* External inputs (root inport signals with auto storage) */
typedef struct {
real32_T In2; /* '<Root>/In2' */
real32_T In3; /* '<Root>/In3' */
} ExtU_rtwdemo_merge_T;
...
With reuse, the number of variables created and referenced is reduced by half. Each
input/output signal pair results in one variable rather than two.
26-22
Signal Reuse for Root-Level Model Inputs and Outputs
More About
• “Introduction to Custom Storage Classes”
• “Simulink Package Custom Storage Classes”
• “Signal Objects”
26-23
26-24
27
Execution Speed
These options (both off by default) control whether internal data (block states and block
outputs) and external data (root inports and outports whose value is zero) are initialized.
Initializing the internal and external data whose value is zero is a precaution and your
application might not require it. Many embedded application environments initialize
RAM to zero at startup, making generation of initialization code redundant.
However, be aware that if you select Remove internal state zero initialization,
memory might not be in a known state each time the generated code begins execution. If
you turn the option on, running a model (or a generated S-function) multiple times can
result in different answers for each run.
This behavior is sometimes desirable. For example, you can turn on Remove internal
state zero initialization if you want to test the behavior of your design during a warm
boot (that is, a restart without full system reinitialization).
In cases where you have turned on Remove internal state zero initialization but still
want to get the same answer on every run from a S-function generated by the Embedded
Coder software, you can use either of the following MATLAB commands before each run:
clear SFcnName
clear mex
A related option, Use memset to initialize floats and doubles, lets you control the
representation of zero used during initialization. See “Use memset to initialize floats and
doubles to 0.0” in the Simulink reference documentation.
Note that the code still initializes data structures whose value is not zero when Remove
internal state zero initialization and Remove root level I/O zero initialization
are selected.
27-2
Generate Pure Integer Code If Possible
27-3
27 Execution Speed
Note also that code generated to support MAT-file logging invokes malloc, which may be
undesirable for your application.
27-4
Simplify Multiply Operations In Array Indexing
int32_T i;
int32_T i_0;
int32_T i_1;
27-5
27 Execution Speed
After selecting the Simplify array indexing parameter and building the model again, a
multiply operation in the array index, [(i_0 + 5 * i_1) + 70 * i], is replaced with
[(i_0 + tmp_1) + tmp]. The generated code is now:
int32_T i;
int32_T i_0;
int32_T i_1;
int32_T tmp;
int32_T tmp_0;
int32_T tmp_1;
tmp = 0;
tmp_0 = 0;
for (i = 0; i < 2; i++) {
tmp_1 = 0;
for (i_1 = 0; i_1 < 3; i_1++) {
27-6
Simplify Multiply Operations In Array Indexing
tmp_1 += 5;
}
tmp += 70;
tmp_0 += 15;
}
tmp = 0;
tmp_0 = 0;
for (i = 0; i < 2; i++) {
tmp_1 = 0;
for (i_1 = 0; i_1 < 2; i_1++) {
for (i_0 = 0; i_0 < 5; i_0++) {
ex_arrayindex_Y.Out[((i_0 + tmp_1) + tmp) + 15] =
ex_arrayindex_P.Constant2_Value[(i_0 + tmp_1) + tmp_0];
}
tmp_1 += 5;
}
tmp += 70;
tmp_0 += 10;
}
tmp = 0;
tmp_0 = 0;
for (i = 0; i < 2; i++) {
tmp_1 = 0;
for (i_1 = 0; i_1 < 9; i_1++) {
for (i_0 = 0; i_0 < 5; i_0++) {
ex_arrayindex_Y.Out[((i_0 + tmp_1) + tmp) + 25] =
ex_arrayindex_P.Constant3_Value[(i_0 + tmp_1) + tmp_0];
}
tmp_1 += 5;
}
tmp += 70;
tmp_0 += 45;
27-7
27 Execution Speed
27-8
28
Memory Usage
• “Optimize Generated Code Using Specified Minimum and Maximum Values” on page
28-2
• “Reduce Global Variables in Nonreusable Subsystem Functions” on page 28-8
28 Memory Usage
When you select the Optimize using specified minimum and maximum values
configuration parameter, the software uses the minimum and maximum values to derive
range information for downstream signals in the model. It then uses this derived range
information to determine if it is possible to streamline the generated code. For example,
by:
28-2
How to Enable Simulation Range Checking
simulation. You can simulate your model with simulation range checking enabled. If
errors or warnings occur, fix these issues before generating code.
For more information, see “Optimize using the specified minimum and maximum
values” in the Simulink documentation.
28-3
28 Memory Usage
First, generate code without taking into account the minimum and maximum values for
the inputs to the Sum and Gain blocks or the minimum and maximum values for the
Gain block parameter to see the code generated without the optimization.
rtwdemo_minmax
2 Double-click the View Optimization Configuration button.
On the Code generation panel, note that the Optimize using specified
minimum and maximum values parameter is cleared.
3 Double-click the Generate Code button.
The generated code for this model includes a branch for each of the Relational
Operator block inputs.
void rtwdemo_minmax_step(void)
{
if (U1 + U2 <= k * U3) {
rtY.Out1 = (U1 + U2) + U3;
} else {
rtY.Out1 = U1 * U2 * U3;
}
}
Next, enable the optimization and generate code for the model again, this time taking
into account the design minimum and maximum values for the inputs to the Sum and
Gain blocks and the minimum and maximum values for the Gain block parameter.
28-4
How to Enable Simulation Range Checking
Note that:
• The minimum value of the first input to the Relational Operator block is 50 because
this value is the minimum output from the Sum block.
• The maximum value of the second input to the Relational Operator block is 40
because this value is the maximum output of the Gain block.
Therefore, the output of the Relational Operator block is false, and the output of the
Switch block is always the product of the three inputs.
28-5
28 Memory Usage
4 In the left pane of the report, click the rtwdemo_minmax.c link and inspect the
generated code. Using the minimum and maximum values, the software optimized
the generated code by eliminating the conditional statement.
void rtwdemo_minmax_step(void)
{
rtY.Out1 = U1 * U2 * U3;
}
Limitations
• This optimization does not take into account minimum and maximum values for:
• Merge block inputs. To work around this issue, use a Simulink.Signal object on
the Merge block output and specify the range on this object.
• Bus elements.
• Conditionally-executed subsystem (such as a triggered subsystem) block outputs
that are directly connected to an Outport block.
Polyspace Code Prover automatically captures some minimum and maximum values
specified in the MATLAB workspace, for example, for Simulink.Signal and
Simulink.Parameter objects. In this example, to provide range information to the
Polyspace software, use a Simulink.Signal object on the input of the division and
specify a range that does not include zero.
Polyspace Code Prover stores these values in a Data Range Specification (DRS) file.
However, they do not capture all minimum and maximum values in your Simulink
model. To provide additional minimum and maximum information to Polyspace, you
can manually define a DRS file.
28-6
How to Enable Simulation Range Checking
• If you are using double-precision data types and the Code Generation > Interface
> Support non-finite numbers configuration parameter is selected, this
optimization does not occur.
• If your model contains multiple instances of a reusable subsystem and each instance
uses input signals with different minimum and maximum values, this optimization
might result in different generated code for each subsystem so code reuse does not
occur. Without this optimization, code is generated once for the subsystem and shares
this code among the multiple instances of the subsystem.
• The Model Advisor Check safety-related optimization settings check generates a
warning if this option is selected. For many safety-critical applications, removing dead
code automatically is unacceptable because doing so might make code untraceable.
For more information, see “Check safety-related optimization settings”.
28-7
28 Memory Usage
Global variables can increase memory requirements and reduce execution speed. To
reduce global RAM for a nonreusable subsystem, you can generate a function interface
that passes data through arguments instead of global variables. The Subsystem block
parameter “Function interface” provides this option. To compare the outputs for the
Function interface options, first generate a function for a subsystem with a void-
void interface, and then generate a function with arguments.
In the code generation report, in rtwdemo_roll.c, the generated code for subsystem
RollAngleReference contains a void-void function definition:
void rtwdemo_roll_RollAngleReference(void)
28-8
Reduce Global Variables in Nonreusable Subsystem Functions
{
...
}
In the static code metrics report, navigate to Global Variables. With the void-void
option, the number of bytes for global variables is 59.
Next, generate the same function with the Allow arguments option to compare the
results.
In the code generation report, in rtwdemo_roll.c, the generated code for subsystem
RollAngleReference now has arguments:
28-9
28 Memory Usage
28-10
Verification
29
Code Tracing
• Code element hyperlinks (indicated with underlining) that you can use to trace
through and toggle between generated source and header files.
• Tags in code comments that identify blocks from which lines of code are generated.
29-2
Format of Traceability Tags
The code generator documents the tags for a model in the comments section of the
generated header file model.h. For example, the following comment appears in the
header file for model, foo, that has a subsystem Outer and a nested subsystem Inner:
The following code shows a tag comment adjacent to a line of code. This code is generated
from a Gain block within a subsystem one level below the root level of the source model:
/* Gain: '<S1>/Gain' */
dead_gain_B.temp0 *= (dead_gain_P.s1_Gain_Gain);
29-3
29 Code Tracing
1 Open the model and make sure it is configured for an ERT target.
2 In the Configuration Parameters dialog box, on the Code Generation > Report
pane, select Create code generation report. The parameter is selected by default.
When selected, this parameter enables and selects Open report automatically and
Code-to-model.
3 Build or generate code for the model. An HTML code generation report is displayed.
4 In the HTML report window, click hyperlinks to highlight source blocks. For
example, generate an HTML report for model rtwdemo_hyperlinks. In the
generated code for the model step function in rtwdemo_hyperlinks.c, click the
first UnitDelay block hyperlink.
29-4
Trace Code to Model Objects Using Hyperlinks
29-5
29 Code Tracing
3 Select Model-to-code.
This parameter:
• Enables the Configure button, which opens a dialog box for loading existing
trace information.
• Enables and selects parameters for customizing the content of a traceability
report.
4 Build or generate code for the model. An HTML code generation report is displayed.
5 In the model window, right-click a model object.
29-6
Trace Model Objects to Generated Code
6 In the context menu, select C/C++ Code > Navigate to C/C++ Code. In the
HTML code generation report, you see the first instance of highlighted code that is
generated for the model object. In the left pane of the report, numbers that appear
to the right of generated file names indicate the total number of highlighted lines
in each file. The following figure shows the result of tracing the Unit Delay block in
model rtwdemo_hyperlinks.
At the top of the code window, use the navigation toolbar to move forward and
backward through multiple instances of highlighted lines. Use the navigation
sidebar to go directly to a line of code.
If you close and reopen a model, the Navigate to Code context menu option might not
be available because Embedded Coder cannot find a build folder for your model in the
current working folder. Do one of the following:
• Reset the current working folder to the parent folder of the existing build folder.
• Select Model-to-code and rebuild the model. Rebuilding the model regenerates the
build folder into the current working folder.
29-7
29 Code Tracing
• Click Configure and in the Model-to-code navigation dialog box, reload the existing
trace information.
29-8
Reload Existing Traceability Information
1 In the Configuration Parameters dialog box, click Code Generation > Report >
Configure. The Model-to-code navigation dialog box opens.
2 In the Build folder field, type or browse to the build folder that contains the
existing traceability information.
If you close and reopen a model, the Navigate to Code context menu option might not
be available. This occurs because Embedded Coder cannot find a build folder for your
model in the current working folder. To fix this without having to reset the current
working folder or rebuild the model, do the following:
4 Click Apply or OK. This loads traceability information from the earlier build into
your Simulink session, provided that you selected Model-to-code for the build.
5 Right-click a model object and select C/C++ Code > Navigate to C/C++ Code to
open the context menu and trace a model object to corresponding code.
29-9
29 Code Tracing
If you select all parameters, you get a complete mapping between model elements and
the generated code.
The following figure shows the top section of the traceability report generated by
selecting all traceability content parameters for model rtwdemo_hyperlinks.
29-10
Customize Traceability Reports
29-11
29 Code Tracing
To do this, go to the Traceability Report section of the HTML code generation report
and click the Generate Traceability Matrix button.
When you click the button, a Generate Traceability Matrix dialog box appears. Use this
dialog to select an existing matrix file to update or specify a new matrix file to create.
Optionally, you can use this dialog to select and order the columns that appear in the
generated matrix. For more information, see “Generating a Traceability Matrix” in either
the “DO Qualification Kit documentation” or the “IEC Certification Kit documentation”.
29-12
Traceability Limitations
Traceability Limitations
The following limitations apply to reports generated by Embedded Coder software.
• Under the following conditions, model-to-code traceability is disabled for a block if the
block name contains:
• Virtual subsystems
• Masked subsystems
• Nonvirtual subsystems for which code has been optimized away
If you cannot trace a subsystem at subsystem level, you might be able to trace
individual blocks within the subsystem.
29-13
29-14
30
Component Verification
30-2
Goals of Component Verification
Regardless of your goal, you must integrate required external drivers and scheduling
software. To achieve real-time execution, you must integrate the real-time scheduling
software.
30-3
30 Component Verification
Algorithm model
Output
Actuators
Communication Comm drivers
interfaces drivers Generated
algorithm
code Special
interfaces
Included Special
legacy device
code drivers
Input
Sensors
drivers
Tuning
Scheduler/operating system
and support utilities
30-4
Simplifying Code Integration and Maximizing Code Efficiency
The following figure shows a mix of ANSI C/C++ code with code that is optimized for a
target environment.
Controller model
Output
Actuators
Communication Comm drivers
interfaces drivers Generated
algorithm
code Special
interfaces
Included Special
target device
optimized drivers
Input
Sensors code
drivers
Tuning
Scheduler/operating system
and support utilities
30-5
30 Component Verification
1 Integrate external code, for example, for device drivers and a scheduler, with the
generated C or C++ code for your component model. For more information, see
“Insert S-Function Code” in the Simulink Coder documentation. For more specific
references that depend on your verification goals, see the following table.
For See
ANSI C/C++ code integration “Integrate C Functions Using Legacy Code
Tool” in the Simulink documentation. Also, open
rtwdemos and navigate to the Custom Code
folder.
Mixed code integration • “Export Function-Call Subsystems” and
example rtwdemo_exporting_functions
• “Function Prototype Control”, “C++
Class Interface Control”, and example
rtwdemo_fcnprotoctrl
• “What Is Code Replacement?”, “What Is Code
Replacement Customization?”, and example
rtwdemo_crl_script
2 Simulate the integrated component model.
3 Generate code for the integrated component model.
4 Connect to data interfaces for the generated C code data structures. See “Data
Interchange Using the C API” and “ASAP2 Data Measurement and Calibration”
in the Simulink Coder documentation. Also see examples rtwdemo_capi and
rtwdemo_asap2.
5 Customize and control the build process, if required. See “Customize Post-Code-
Generation Build Processing” in the Simulink Coder documentation, and example
rtwdemo_buildinfo .
6 Create a zip file that contains generated code files, static files, and dependent data
to build the generated code in an environment other than your host computer. See
“Relocate Code to Another Development Environment”, in the Simulink Coder
documentation, and example rtwdemo_buildinfo.
30-6
31
This single build approach is more time consuming to set up, but makes it easier to get
the complete application running in the target environment.
The following figure shows code generated for an algorithm being built into a complete
system executable for the target environment.
31-2
About Real-Time Software Component Verification
Algorithm model
Output
Actuators
Communication Comm drivers
interfaces drivers Generated
algorithm
code Special
interfaces
Optional Special
target device
optimized drivers
Input
Sensors code
drivers
Tuning
Scheduler/operating system
and support utilities
31-3
31 Component Verification With a Real-Time Target Environment
For... See...
ANSI C/C++ code integration “Integrate C Functions Using Legacy Code
Tool” in the Simulink documentation. Also, open
rtwdemos and navigate to the Custom Code
folder.
Mixed code integration • “Export Function-Call Subsystems” and
example rtwdemo_exporting_functions
• “Function Prototype Control”, “C++
Class Interface Control”, and example
rtwdemo_fcnprotoctrl
• and example rtwdemo_crl_script
31-4
Real-Time Software Component Testing
31-5
31-6
32
A SIL simulation involves compiling and running production source code on your
host computer to verify the source code. SIL provides a convenient alternative to
processor-in-the-loop (PIL) simulation as no target hardware (for example, an evaluation
board or instruction set simulator) is required. For examples of SIL verification, see
rtwdemo_sil_pil_script.
A PIL simulation involves cross-compiling and running production object code on a target
processor or an equivalent instruction set simulator.
For more information, see “Choose a SIL or PIL Approach” on page 32-7.
• Ability to compare the output of regular simulation modes, for example, Normal or
Accelerator, against the output of SIL and PIL simulation modes.
• Easy switching between regular simulation, SIL, and PIL modes.
You can model and test your embedded software component in Simulink and then reuse
your test suites across simulation and compiled production code. This approach avoids
the time-consuming process of leaving the Simulink software environment and verifying
production code on a separate test infrastructure.
32-2
About SIL and PIL Simulations
For information about how you verify the configuration of your model for a SIL or PIL
simulation, see “Check the SIL or PIL Configuration”.
Situation Use
You want to reuse test vectors developed for Normal mode SIL and PIL
simulation to verify numerical output of generated (or legacy) code.
For example, reusing test cases generated by Simulink Design
Verifier™. See “What Is Test Case Generation?” in the Simulink
Design Verifier documentation.
You want to collect metrics for generated code: SIL and PIL
32-3
32 Numerical Equivalence Checking
Situation Use
• Investigate effects of compiler settings and optimizations, for
example, deviation from ANSI C overflow behavior.
Note: The SIL and PIL simulation modes are not designed for reducing model simulation
times. If you want to speed up the simulation of your model, use the Rapid Accelerator
mode. For more information, see:
• “Acceleration”
Through a communication channel, Simulink sends stimulus signals to the code on the
host or target processor for each sample interval of the simulation:
• For a top model, Simulink uses stimulus signals from the base or model workspace.
• If you have designated only part of the model to simulate in SIL/PIL mode, then a
part of the model remains in Simulink without the use of code generation. Typically,
you configure this part of the model to provide test vectors for the software executing
on the hardware. This part of the model can represent other parts of the algorithm or
the environment model in which the algorithm operates.
When the host/target processor receives signals from Simulink, the processor executes
the SIL/PIL algorithm for one sample step. The SIL/PIL algorithm returns output signals
computed during this step to Simulink through a communication channel. One sample
32-4
About SIL and PIL Simulations
cycle of the simulation is complete, and Simulink proceeds to the next sample interval.
The process repeats and the simulation progresses. SIL/PIL simulations do not run in
real time. In each sample period, Simulink and the object code exchange I/O data.
32-5
32 Numerical Equivalence Checking
To decide which verification approach you want to use, see “Choose a SIL or PIL
Approach” on page 32-7 .
32-6
Choose a SIL or PIL Approach
• A and B are existing components for which code has previously been generated and
tested.
• C, a referenced model, and D, a subsystem, are new components.
• Verify code from all components together. See “Verify Top Model Code” on page
32-8.
• Verify new components separately (before verifying code from all components). See
“Verify Referenced Model Code” on page 32-9 and “Verify Subsystem Code” on
page 32-9.
For some forms of code verification, you require a test harness model. The test harness
model:
32-7
32 Numerical Equivalence Checking
• Generates test vectors or stimulus inputs that feed the block under test.
• Makes it possible for you to observe or capture output from the block.
The block under test is a Model block. The Sine Wave block generates the input for the
Model block. Through the Scope block, you can observe the output from the Model block.
For examples that use the various approaches to SIL/PIL code verification, see
rtwdemo_sil_pil_script.
For information about running top-model SIL/PIL, Model block SIL/PIL, and SIL/PIL
block simulations, see “Configure a SIL or PIL Simulation” on page 32-10.
• Top-model SIL/PIL:
32-8
Choose a SIL or PIL Approach
For information about how you create a SIL or PIL block, see “Use a SIL or PIL Block” on
page 32-13.
32-9
32 Numerical Equivalence Checking
In this section...
“Top-Model SIL or PIL Simulation” on page 32-10
“Model Block SIL or PIL Simulation” on page 32-12
“Use a SIL or PIL Block” on page 32-13
“Check the SIL or PIL Configuration” on page 32-14
Note: This option is available only if the model is configured for an ERT or
AUTOSAR target. See “Code Generation Pane: General” and “Export AUTOSAR
Component XML and C Code” for configuration information.
3 If you have not already done so, in the Configuration Parameters dialog box, on the
Data Import/Export pane:
• In the Input check box and field, specify stimulus signals (or test vectors) for
your top model.
• Configure logging for model outputs, using either output logging or signal
logging:
32-10
Configure a SIL or PIL Simulation
4 If you are configuring a SIL simulation, specify the portable word sizes option. This
option allows you to switch seamlessly between the SIL and PIL modes. Select
Code Generation > Verification > Enable portable word sizes. See “Configure
Hardware Implementation Settings for SIL” on page 32-25.
5 If required, configure:
Note: On a Windows operating system, the Windows Firewall might block your SIL
simulation. To allow the SIL simulation, use the Windows Security Alert dialog box . For
example, in Windows 7, click Allow access.
You cannot:
• Close the model while the simulation is running. To interrupt the simulation, in the
Command Window, press Ctrl+C.
• Alter the model during the simulation. You can move blocks and lines as long as it
does not alter the behavior of the model.
You can run a top-model SIL or PIL simulation using the command sim(model).The
software supports the sim command options SrcWorkspace and DstWorkspace for only
the following values:
• SrcWorkspace — 'base'
• DstWorkspace — 'base' or 'current'
For more information on the sim command and its options, see “Run Simulation Using
the sim Command”.
For information about how a simulation behaves when the top model contains a Model
block (and this Model block is a parent Model block containing Model blocks at lower
levels of its reference hierarchy), see “Simulation Mode Override Behavior in Model
Reference Hierarchy” on page 32-21.
32-11
32 Numerical Equivalence Checking
For a PIL simulation, you control the way code compiles and executes in the target
environment through connectivity configurations. See “Create PIL Target Connectivity
Configuration” on page 32-35.
If you select Top model, the software displays the block label (SIL: Top).
6 If you are configuring a SIL simulation, specify the portable word sizes option. This
option allows you to switch seamlessly between the SIL and PIL modes. Select
Code Generation > Verification > Enable portable word sizes. See “Configure
Hardware Implementation Settings for SIL” on page 32-25.
7 If required, configure:
32-12
Configure a SIL or PIL Simulation
• Code execution profiling for your Model block, by configuring execution profiling
for the top model. See “Configure Code Execution Profiling for SIL and PIL”.
• Creation of code generation report and static code metrics. See “View Test
Harness in Code Generation Report” on page 32-43.
8 Start the simulation.
Note: On a Windows operating system, the Windows Firewall might block your SIL
simulation. To allow the SIL simulation, use the Windows Security Alert dialog box . For
example, in Windows 7, click Allow access.
For a PIL simulation, you control the way code compiles and executes in the target
environment through connectivity configurations. See “Create PIL Target Connectivity
Configuration” on page 32-35.
32-13
32 Numerical Equivalence Checking
Note: On a Windows operating system, the Windows Firewall might block your SIL
simulation. To allow the SIL simulation, use the Windows Security Alert dialog box . For
example, in Windows 7, click Allow access.
You cannot create a SIL or PIL block if you do one of the following:
For a PIL simulation, you control the way code compiles and executes in the target
environment through connectivity configurations. See “Create PIL Target Connectivity
Configuration” on page 32-35.
For an example of how you can use the SIL block in testing, see
rtwdemo_sil_pil_script.
Note:
• To execute the model in the target environment, you might need to make additional
modifications to the configuration parameter values or the model.
32-14
Configure a SIL or PIL Simulation
• Do not use referenced configuration sets in models that you are changing
using cgv.Config. If the model uses a referenced configuration
set, update the model with a copy of the configuration set. Use the
Simulink.ConfigSetRef.getRefConfigSet method. For more information, see
Simulink.ConfigSetRef in the Simulink documentation.
• If you use cgv.Config on a model that executes a callback function, the callback
function might change configuration parameter values each time the model loads. The
callback function might revert changes that cgv.Config made. When this change
occurs, the model might no longer be set up for SIL or PIL. For more information, see
“Callbacks for Customized Model Behavior”.
Tip
• You can change the configuration parameter values and save the model.
When you construct the object, include the 'SaveModel', 'on' property
name and value pair.
2 Determine and change the configuration parameter values that the object
recommends using the configModel method. For example:
c.configModel();
3 Display a report of the changes that configModel makes. For example:
c.displayReport();
32-15
32 Numerical Equivalence Checking
32-16
Top Model Simulation Using SIL or PIL
• Simulink generates and executes code that uses the same code interface produced by
the standalone build process. See “Code Interfaces for SIL and PIL” on page 32-23.
• You can load data from the MATLAB workspace to specify stimulus signals, and
you can log output signals, which allows you to verify object code generated from a
complete model without creating a separate test harness model. Running the SIL or
PIL simulation is a simple operation.
You can use the Model block approach as an alternative to top-model SIL or PIL
simulation. See “Choose a SIL or PIL Approach” on page 32-7.
For the top-model SIL/PIL approach, Simulink creates a hidden wrapper model. When
you run a top-model SIL simulation, the software generates code for the model and
creates a hidden wrapper model to call this code at each time step.
As a result, in some circumstances, logged signals might have a _wrapper suffix. See
“Top-Model Root-Level Logging Limitations”.
During a SIL/PIL simulation, the software can generate warnings that refer to the
hidden wrapper model. For example:
Warning: The model 'modelName_wrapper' has the 'Configuration Parameters' ...
32-17
32 Numerical Equivalence Checking
You can switch easily between the simulation modes. This feature allows you to verify
the generated code by executing the referenced model as compiled code on the host
computer or target platform. You can model and test your embedded software component
in Simulink and reuse your regression test suites across simulation and compiled object
code. With this capability, you can avoid the time-consuming process of leaving the
Simulink software environment to run tests on object code compiled for your production
hardware.
32-18
Referenced Model Simulation Using SIL or PIL
32-19
32 Numerical Equivalence Checking
• Enable internal signal logging for top-model or Model block SIL or PIL, but check the
limitations. See “Internal Signal Logging Support”.
• Manually route the signal to the top level.
• Use global data stores to access internal signals:
1 Inside the component, connect a Data Store Write block to the required signal.
2 Outside the component, use a Data Store Read block to access the signal value.
For more information on signal support, see “I/O Support” on page 32-56.
32-20
Simulation Mode Override Behavior in Model Reference Hierarchy
Note: You can view your model hierarchy in the Model Dependency Viewer. In the
Referenced Model Instances view, the software displays Model blocks differently to
indicate their simulation modes, for example, Normal, Accelerator, SIL, and PIL. In this
view, the software does not indicate the simulation mode of the top model.
You can specify the simulation mode of a top model to be Normal, Accelerator, Rapid
Accelerator, SIL, or PIL. With a Model block, you can specify all modes except Rapid
Accelerator. The configured simulation mode of a Model block can be overridden by the
parent simulation mode. The following table shows how the software determines the
effective simulation mode of a Model block in the hierarchy.
• Equivalent – Both parent and child Model block run in the same simulation mode.
• Compatible – If the simulation mode of the top model or parent block is Normal, then
the software simulates the child block in the mode specified for it.
• Error – The simulation produces an error. For example, if a top model or parent
Model block has simulation mode Accelerator but contains a child block in SIL or
PIL mode, then running a simulation produces an error: the Accelerator mode cannot
override the SIL and PIL mode of child blocks. This behavior avoids the risk of “false
positives”, that is, the simulation of a model in Accelerator mode will not lead to the
32-21
32 Numerical Equivalence Checking
conclusion that generated source or object code of child Model blocks has been tested
or verified.
• Override – The simulation mode of the top model or parent Model block overrides the
simulation mode of the child block. For example, if a top model or parent Model block
that is configured for a SIL simulation contains a child Model block with simulation
mode Normal or Accelerator, then the software simulates the child block in SIL mode.
This override behavior:
• Allows a Model block in the reference hierarchy to have the SIL or PIL mode.
• Makes lower-level referenced models execute in SIL or PIL mode if you simulate
the top model or parent Model block in SIL or PIL mode. You do not have to switch
manually the simulation mode of every model component in the hierarchy.
Note: For a model reference hierarchy that consists of multiple sub-hierarchies, if the
top-model simulation mode is Normal, the software can run only one sub-hierarchy in
PIL mode. For example, if your Normal mode top model contains multiple Model blocks,
you can specify the PIL mode for only one of the Model blocks.
32-22
Code Interfaces for SIL and PIL
In this section...
“Code Interface for Top-Model SIL or PIL” on page 32-23
“Code Interface for Model Block SIL or PIL” on page 32-24
You generate standalone code when you perform, for example, a top-model or right-click
subsystem build for a single deployable component. You can compile and link standalone
code into a standalone executable or integrate it with other code. For more information
on the standalone code interface, see “Entry-Point Functions and Scheduling”.
When you generate code for a referenced model hierarchy, the software generates
standalone executable code for the top model, and a library module called a model
reference target for each referenced model. When the code executes, the standalone
executable invokes the applicable model reference targets to compute the referenced
model outputs. For more information, see “Build Model Reference Targets”.
Note: If you intend to integrate automatically generated code with legacy code, use
standalone code because the standalone code interface is documented. See “Entry-Point
Functions and Scheduling”.
32-23
32 Numerical Equivalence Checking
When you run a top-model SIL or PIL simulation, the software calls the standalone code
for the model if it already exists. The software generates the standalone code if it does
not exist.
• Top model — The software generates the standalone code interface for the model.
When you run a simulation, the software calls the standalone code for the model if it
already exists. The software generates the standalone code if it does not exist.
• Model reference — The software generates the model reference code interface.
When you run a simulation with a Model block in SIL or PIL mode, the software calls
the model reference target for the Model block if it already exists, or generates the
model reference target. If the model reference target does not yet exist, there are
three ways to generate it:
slbuild('model','ModelReferenceRTWTargetOnly')
32-24
Configure Hardware Implementation Settings for SIL
For information about test and production targets, “Platform Options for Development
and Deployment” in the Simulink Coder documentation.
To configure a model to use portable word sizes, set the following model configuration
parameters.
Parameter Setting
Hardware Implementation > Test hardware Selected
> Test hardware is the same as production
hardware
32-25
32 Numerical Equivalence Checking
Parameter Setting
Code Generation > Verification > Enable Selected
portable word sizes
When you generate code for a model with the preceding parameter settings, the code
generator conditionalizes data type definitions:
For example, in the following generated code, the first two lines define types for SIL
simulation on a host system. The bold lines define types for target deployment.
When you compile generated code that supports portable word sizes for SIL testing, pass
the definition PORTABLE_WORDSIZES to the compiler.
For example:
-DPORTABLE_WORDSIZES
To build the same code for target deployment, compile the code without the
PORTABLE_WORDSIZES definition.
32-26
Configure Hardware Implementation Settings for SIL
Consider the case where your target uses code that the host cannot compile. When
you switch from the PIL mode to the SIL mode and try to simulate the model, you see
compilation errors. You might be able to work around this problem by adding the source
code files to the SkipForSil group in the build information object RTW.BuildInfo. The
SIL build on the host platform does not compile source files present in the SkipForSil
group. For information about how you add source code files to a group in the build
information object, see:
The following limitations apply when using portable word sizes in SIL simulation:
• Numerical results might differ between generated code executing in a SIL simulation
and generated code executing on the production hardware under one of the following
conditions:
• Your model contains blocks implemented in TLC, for which C integral promotion
in expressions might behave differently between the MATLAB host and the
production hardware target. Normal and PIL simulation results will match, but
SIL simulation results might be different.
• Your production hardware implements rounding to Floor for signed integer
division, and divisions in your model use rounding mode Floor or Simplest.
Normal and PIL simulation results will match, but SIL simulation results might
be different.
• The precision of floating-point operations differs between the MATLAB host and
the production hardware target. In this case, Normal and SIL simulation results
will match, but PIL simulation results might be different.
• You use custom code with the Stateflow product. In this case, type conversion
statements will not be inserted into the custom code, which might be required to
achieve target overflow behavior on the host. Normal and PIL simulation results
will match, but SIL simulation results might be different.
• Compilation warnings might occur for code generated using portable word sizes if all
of the following conditions exist:
32-27
32 Numerical Equivalence Checking
• The combination of MATLAB host and production hardware target word sizes
causes rtwtypes.h to redefine the word sizes using preprocessor macros. For
example, when the production hardware has a 16-bit int data type and the
MATLAB host has a 16-bit short data type, int16_T is redefined to be short on
the host and int on the target.
• The data types are used in pointer arguments to function calls.
• The called functions are host-based precompiled functions (not compiled using
rtwtypes.h).
Under these conditions, the compiler typically issues a warning similar to the
following:
warning: passing argument 2 of 'frexp' from incompatible pointer type
Executing the generated code on the MATLAB host could lead to memory corruption.
For example, the function "double frexp (double value, int *exp);" expects
'int *' as the second argument, for which 'int16_T *' is passed in the generated
code. But on the MATLAB host, int16_T is redefined to short, and during SIL
execution, frexp will attempt to write 4 bytes to a 2 byte location.
A potential workaround for the SIL workflow is to provide a custom code replacement
library for functions that write to address locations obtained through pointer
arguments. In the above example, the function frexp is called by the reciprocal
square root operation (rSqrt) and rSqrt is replaceable using a code replacement
library. Therefore, you can provide a custom version of rSqrt to support SIL
execution. The replacement function would perform the change in memory allocation
for the data accessed by the pointer variable, perhaps by introducing a temporary
variable and transferring the data to and from that variable. For more information,
see “What Is Code Replacement?” and “What Is Code Replacement Customization?”.
Test Hardware
Use this approach only if you need to work around a limitation of portable word sizes.
To configure a model for test hardware, set the following model configuration
parameters.
32-28
Configure Hardware Implementation Settings for SIL
Parameter Setting
Code Generation > Verification > Enable Not selected
portable word sizes
Hardware Implementation > Test hardware Not selected
> Test hardware is the same as production
hardware
Hardware Implementation > Test hardware Generic
> Device vendor
Hardware Implementation > Test hardware MATLAB Host Computer
> Device type
For an example of how to configure a model to maintain bit-true agreement between host
simulation and target deployment, and generate code that is portable between the host
and target systems, see rtwdemo_sil_hardware_config.
Production hardware
You can use this approach only when the production hardware settings match your host
computer architecture.
Parameters Settings
Code Generation > Verification > Enable Not selected.
portable word sizes
Hardware Implementation > Test hardware Selected.
> Test hardware is the same as production
hardware
Hardware Implementation > Production Select settings that match your host
hardware section parameters computer architecture.
32-29
32 Numerical Equivalence Checking
Note: You can perform SIL debugging only if your Microsoft Visual C++ or GNU GCC
compiler is supported by the Simulink product family. For more information, see
supported compilers.
To enable your debugger for a SIL simulation, on the Configuration Parameters >
Code Generation > Verification pane, select the Enable source-level debugging
for SIL simulations check box.
If your top model has Model blocks where the Code under test block parameter is
set to Top model, then the Enable source-level debugging for SIL simulations
parameters for the top model and referenced models must have the same settings.
Otherwise, the software produces an error.
When you run the SIL simulation, for example on a Windows computer, your model.c or
model.cpp file opens in the Microsoft Visual Studio IDE with debugger breakpoints at
the start of the model_initialize and model_step functions.
32-30
Debug Code During SIL Simulations
You can now use the debugger features to observe code behavior. For example, you can
step through code and examine variables.
The SIL simulation runs to completion and the Microsoft Visual Studio IDE closes
automatically.
Note: In the Microsoft Visual Studio IDE, if you select Debug > Stop Debugging, the
SIL simulation times out with the following error message:
The timeout of 1 seconds for receiving data from the rtiostream interface
has been exceeded. There are multiple possible causes for this failure.
...
...
32-31
32 Numerical Equivalence Checking
To run a PIL verification, the software must first determine which of the available
connectivity configurations to use. The software looks for a connectivity configuration
that is compatible with the model under test. If the software finds multiple or no
compatible connectivity configurations, the software generates an error message with
information about resolving the problem.
32-32
PIL Customization for Target Environment
• Building the processor-in-the loop (PIL) application, an executable for the target
hardware
• Downloading, starting, and stopping the application on the target
• Communicating between Simulink and the target
The following diagram shows the components of the target connectivity PIL API.
32-33
32 Numerical Equivalence Checking
defines the signature of target-side and host-side functions that must be implemented by
this driver code.
The API is independent of the physical layer that sends the data. Possible physical layers
include RS232, Ethernet, or Controller Area Network (CAN).
A full rtiostream implementation requires both host-side and target-side drivers. Code
generation software includes host-side drivers for the default TCP/IP implementation as
well as a version for serial communications. To use:
• The TCP/IP rtiostream communications channel, you must provide, or obtain from
a third party, target-specific TCP/IP device drivers.
• The serial communications channel, you must provide, or obtain from a third party,
target-specific serial device drivers.
For other communication channels and platforms, the code generation software does not
provide default implementations. You must provide both the host-side and the target-side
drivers.
• rtIOStreamOpen
• rtIOStreamSend
• rtIOStreamRecv
• rtIOStreamClose
32-34
Create PIL Target Connectivity Configuration
Note: Each time you modify a connectivity implementation, close and reopen the models
to refresh them.
See also:
32-35
32 Numerical Equivalence Checking
• Reduces time for integrating custom hardware that does not have built-in
rtiostream support.
• Reduces time for testing custom rtiostream drivers.
• Helps analyze the performance of custom rtiostream drivers.
The test suite has two parts. One part of the test suite runs on the target.
Note: After building the target application, download it to the target and run it.
To launch this part, compile and link the following files, which are in matlabroot/
toolbox/coder/rtiostream/src/rtiostreamtest.
• rtiostreamtest.c
• rtiostreamtest.h
• rtiostream.h (located at matlabroot/rtw/c/src/)
• rtiostream implementation under investigation (for example,
rtiostream_tcpip.c)
• main.c
To run the MATLAB part of the test suite, invoke rtiostreamtest. The syntax is as
follows:
rtiostreamtest(connection,param1,param2)
32-36
Create PIL Target Connectivity Configuration
• param1 and param2 have different values depending on the value of connection.
• If connection is 'tcp', then param1 and param2 are hostname and port,
respectively. For example, rtiostreamtest('tcp', 'localhost', 2345).
• If connection is 'serial', then param1 and param2 are COM port and baud
rate, respectively. For example, rtiostreamtest('serial', 'COM1', 9600).
You can run the MATLAB part of the test suite as follows:
rtiostreamtest('tcp','localhost','2345')
An output in the following format appears in the MATLAB window:
32-37
32 Numerical Equivalence Checking
32-38
Create PIL Target Connectivity Configuration
With other rtiostream implementations, for example, serial, the Simulink side of the
rtiostream connection will open without waiting for the target to be fully initialized.
In this case, you must make your Launcher implementation wait until the target
application is fully initialized. Use one of the following approaches to synchronize your
host and target:
• Add a pause at the end of the Launcher implementation that makes the Launcher
wait until target initialization is complete.
• In the Launcher implementation, use third-party downloader or debugger APIs that
wait until target initialization is complete.
• Implement a handshaking mechanism in the Launcher / rtiostream
implementation to confirm that target initialization is complete.
1 Open the Code Replacement Tool. In the Command Window, enter crtool.
2 Create a new code replacement table. Select File > New table.
3 Create a new function entry. Under Tables List, right-click the new table. Then,
from the context-menu, select New entry > Function.
4 In the middle view, select the new unnamed function.
5 On the Mapping Information pane:
32-39
32 Numerical Equivalence Checking
The default value is 0. In this case, the software reports time measurements in
terms of ticks, not seconds.
d In the Name field, specify a replacement function name, for example, MyTimer.
e Click Apply.
You must save the table in a location that is on the MATLAB search
path. For example, you can save this file in the folder for your subclass of
rtw.connectivity.Config.
32-40
Create PIL Target Connectivity Configuration
The software stores your timer information as a code replacement library table.
8 Assuming you save the table as MyCrlTable.m, in your subclass of
rtw.connectivity.Config, add the following line:
setTimer(this, MyCrlTable)
For more information, see “What Is Code Replacement?” and “What Is Code Replacement
Customization?”.
• rtwdemo_custom_pil_script
This example shows you how to create a custom PIL implementation using the
target connectivity APIs. You can examine the code that configures the build process
to support PIL, a downloading and execution tool, and a communication channel
between host and target. Follow the steps in the example to activate a full host-based
PIL configuration.
• rtwdemo_rtiostream_script
This example shows you how to implement a communication channel for use with the
Embedded Coder product and your embedded target. This communication channel
enables exchange of data between different processes. PIL simulation requires
exchange of data between the Simulink software running on your host computer and
deployed code executing on target hardware.
The rtiostream interface provides a generic communication channel that you can
implement in the form of target connectivity drivers for a range of connection types.
32-41
32 Numerical Equivalence Checking
The example shows how to configure your own target-side driver for TCP/IP, to
operate with the default host-side TCP/IP driver. The default TCP/IP communications
allow high-bandwidth communication between host and target, which you can use for
transferring data such as video.
Note: If you customize the rtiostream TCP/IP implementation for your PIL
simulations, you must turn off Nagle's algorithm for the server side of the
connection. If Nagle's algorithm is not turned off, your PIL simulations might run
at a significantly slower speed. The matlabroot/rtw/c/src/rtiostream/
rtiostreamtcpip/rtiostream_tcpip.c file shows how you can turn off Nagle's
algorithm:
/* Disable Nagle's Algorithm*/
option = 1;
sockStatus = setsockopt(lFd,IPPROTO_TCP,TCP_NODELAY,(char*)&option,sizeof(option));
For your custom TCP/IP implementation, you might have to modify this code.
The example also shows how to implement custom target connectivity drivers,
for example, using serial, CAN, or USB for both host and target sides of the
communication channel.
32-42
View Test Harness in Code Generation Report
This feature is not supported for simulations that you run with the PIL block.
To configure the creation of a code generation report and static code metrics, on the
Configuration Parameters > Code Generation > Report pane, select the Create
code generation report and Static code metrics check boxes. Then click OK. For
more information about:
At the end of the simulation, the software displays test harness files and the
corresponding static code metrics in the code generation report.
32-43
32 Numerical Equivalence Checking
The software displays the test harness files in the Interface files category.
Note: You must not use files from the SIL/PIL test harness in code development as these
files can change over releases. Use supplied APIs for code development.
32-44
SIL and PIL Simulation Support and Limitations
The following tables summarize the support provided for top-model SIL and PIL, Model
block SIL and PIL and the SIL or PIL block. “Yes” indicates a supported feature.
Information on selected aspects of SIL and PIL is also provided, especially unsupported
features and limitations.
32-45
32 Numerical Equivalence Checking
Code Source Code Interface Top-Model SIL/PIL Model Block SIL/PIL SIL/PIL Block
Issues” on page
32-51.
Model block Model reference No, but you can Yes. See No, but you can
target include Model “Conditionally include Model
blocks inside your Executed Subsystem” blocks inside your
top model. on page 32-47. model.
Enabled/ Standalone No No Yes
Triggered
subsystem
Exported Export N/A N/A Yes
function-call Functions
subsystem
Export-function Export Yes Yes N/A
model Functions
Legacy code Custom See “Custom Code See “Custom Code See “Custom Code
Interfaces” on Interfaces” on page Interfaces” on page
page 32-47. 32-47. 32-47.
MATLAB Coder MATLAB Coder See “Custom Code See “Custom Code See “Custom Code
Interfaces” on Interfaces” on page Interfaces” on page
page 32-47. 32-47. 32-47.
For more information, see “Code Interfaces for SIL and PIL” on page 32-23.
• The Model Variants block does not support the block parameter CodeUnderTest.
The software behaves as if CodeUnderTest is set to 'Model reference'. To work
around this limitation, use the Variant Subsystem block. Through this block, you
can incorporate Model blocks for which CodeUnderTest is set to 'Top model'.
• Because model arguments do not apply to a top model, when the Code under test
block parameter is set to Top model, the software does not support the Model
arguments block parameter.
• Conditional execution does not apply to a top model. If a Model block is set up to
execute conditionally and the Code under test block parameter is set to 'Top
model', the software produces an error when you run a SIL or PIL simulation.
32-46
SIL and PIL Simulation Support and Limitations
• For sample time independent models, you must set Configuration Parameters
> Solver > Periodic sample time constraint to Ensure sample time
independent.
• Simulation results from top-model code and model reference code might differ when
a root-level Inport is connected to a root-level Outport by a signal that has a signal
object with an initial value.
For top-model code, the software associates the signal object with the Inport.
The software might apply the initial value for the signal object to the Inport. See
“Initialization Behavior Summary for Signal Objects”.
For model reference code, the software associates the signal object with the Outport.
The software does not apply the initial value for the signal object to the Inport.
• You place your Model block (in either SIL or PIL simulation mode) in a conditionally
executed subsystem and the referenced model is multirate (that is, has multiple
sample times). Single rate referenced models (with only a single sample time) are not
affected.
• Your Model block (in either SIL or PIL simulation mode) has blocks that depend on
absolute time and is conditionally executed.
MathWorks does not provide direct SIL/PIL support for code interfaces such as legacy
code and MATLAB Coder. However, you can incorporate these interfaces into Simulink
as an S-function (for example, using the Legacy Code Tool, S-Function Builder, or
handwritten code), and then verify them using SIL/PIL.
SIL/PIL does not check the Simulink Coder error status of the generated code under test.
This error status flags exceptional conditions during execution of the generated code.
The Simulink Coder error status can also be set by blocks in the model (for example,
custom blocks developed by a user). It is a limitation that SIL/PIL cannot check this error
status and report back errors.
32-47
32 Numerical Equivalence Checking
Block Support
Blocks Supported Top-Model SIL/PIL Model Block SIL/PIL SIL/PIL Block
Within SIL/PIL
Component
Driver blocks Yes, but not Yes, but not recommended. Yes, but not
recommended. recommended.
Function Caller Yes Yes No. Use the Model
block block SIL/PIL
approach, with the
Code under test block
parameter set to Top
model.
MATLAB Function Yes Yes Yes
block
Model block Yes Yes Yes
Merge blocks Yes Yes. Cannot connect SIL/PIL Yes. Cannot connect
outputs to Merge blocks. See SIL/PIL outputs to
“Merge Block Issue” on page Merge blocks. See
32-49. “Merge Block Issue” on
page 32-49.
Scope blocks, and No No No
all types of run-time
display.
32-48
SIL and PIL Simulation Support and Limitations
If you connect SIL/PIL outputs to a Merge block, you see an error because S-function
memory is not reusable.
During a top-model SIL/PIL simulation, the software places the model in a compiled
state – see model. This action might result in a conflict over global resources between the
model and the generated SIL/PIL code. In this case, you might see differences between
Normal mode and SIL/PIL simulation outputs.
For example, you might see this limitation with a model that uses UDP blocks from
the DSP System Toolbox. These blocks open UDP sockets, which can lead to resource
contention between the model and the generated SIL/PIL code.
SIL/PIL does not support the callbacks (model or block ) StartFcn and StopFcn.
32-49
32 Numerical Equivalence Checking
32-50
SIL and PIL Simulation Support and Limitations
SIL/PIL requires a code interface description file, which is generated during the code
generation process for the component under test. If the code interface description file is
missing, the SIL/PIL simulation cannot proceed and you see an error reporting that the
file does not exist. This error can occur if you select the unsupported option Classic call
interface in your configuration parameters. Do not select this option.
32-51
32 Numerical Equivalence Checking
There are three ways that PIL simulation can introduce algebraic loops that do not exist
for a normal simulation:
If you generate code for a virtual subsystem, code generation treats the subsystem
as atomic and generates the code accordingly. The resulting code can change the
execution behavior of your model, for example, by applying algebraic loops, and introduce
inconsistencies to the simulation behavior.
This option is not compatible with the Minimize algebraic loop occurrences
option (in the Subsystem Parameters dialog box and Model Referencing pane of the
Configuration Parameters dialog box). This option allows code generation to remove
algebraic loops by partitioning generated code between output and update functions to
avoid direct feedthrough.
Algebraic Loops Caused by SIL/PIL Scheduling Limitations
The S-function scheduling mechanism that the software uses to execute the SIL/PIL
component has the following limitations:
32-52
SIL and PIL Simulation Support and Limitations
• Separate output and update functions in the SIL/PIL component are executed from
the mdlOutputs S-function callback.
These limitations mean that SIL/PIL can introduce algebraic loops that do not exist
in normal simulation, and you might get incorrect results. If this happens, you see a
warning or error about the introduced algebraic loop and SIL/PIL results can differ from
simulation results. You do not see a warning or error if Configuration Parameters >
Diagnostics > Algebraic loop is set to none.
A workaround is to break the algebraic loop by inserting a Unit Delay block so that the
algebraic loop does not occur. You can then use SIL/PIL.
You can use Simulink signal logging with the SIL and PIL simulation modes, with both
top-model SIL or PIL and Model block (referenced model) SIL or PIL. This feature allows
you to:
• Collect signal logging outputs (e.g., logsout) during SIL and PIL simulations.
• Log the internal signals and the root-level outputs of a SIL or PIL component.
• Manage the SIL and PIL signal logging settings using the Simulink Signal Logging
Selector.
• Compare logged signals between normal, SIL, and PIL simulations, for example,
using the Simulation Data Inspector.
SIL or PIL signal logging requires the following model configuration settings:
• On the Data Import/Export pane of the Configuration Parameters dialog box, set
Signal logging format to Dataset.
• On the Code Generation > Interface pane of the Configuration Parameters dialog
box, set Interface to C API.
The C API is used to determine the addresses of the internal signals that need to be
logged. See also “Internal Signal Logging Limitations” on page 32-53.
• The C API requires that support for floating-point numbers is selected (see
Configuration Parameters > Code Generation > Interface > Support >
floating-point numbers).
32-53
32 Numerical Equivalence Checking
• Only signals that are included in the C API are logged during SIL/PIL simulation.
You might need to configure signals as test points (see Signal Properties > Test
point) to check that they are observable in the generated code.
• Logging of signals in models referenced by the SIL/PIL component is not supported.
Only signals within the top level of the SIL/PIL component are logged.
• Virtual signals (e.g. MUX) are not supported.
• Buses are not supported.
• Custom storage classes are not supported.
• Continuous, asynchronous and triggered sample times are not supported.
• Logging of Stateflow States and Local Data is not supported.
• Variable-size signals, Function-call signals, and Action signals: error for normal
simulation and warning for SIL/PIL.
• State port signals: error for normal simulation; no warning for SIL/PIL.
• Signals feeding merge blocks are not supported for logging in normal simulation but
are logged in SIL/PIL mode. The logged values during SIL/PIL will be the same as the
logged values for the output of the merge block.
• Under the following circumstances, top-model Normal simulation logs data at a
periodic rate, but top-model SIL/PIL simulation logs data at the constant rate:
To avoid this behavior, select Inline parameters to log at constant rate in all
simulation modes.
Top-model SIL/PIL supports signal logging for signals connected to root-level inports and
outports. Both ModelDataLogs and Dataset signal logging formats are supported, and
the C API is not required. Root-level logging has the following limitations:
• The characteristics of the logged data such as data type and dimensions match the
characteristics of the root-level inports and outports rather than the characteristics of
the connected signal.
32-54
SIL and PIL Simulation Support and Limitations
In some cases, there can be differences in data type and dimensions between the
signal being logged and the root inport or outport that the signal is connected to.
Consider the following examples.
• If a signal being logged has matrix dimensions [1x5] but the outport connected
to the signal has vector dimensions (5), then the data logged during a SIL or PIL
simulation has vector dimensions (5).
• If a signal being logged has scalar dimensions but the outport connected to the
signal has matrix dimensions [1x1], then the data logged during a SIL or PIL
simulation has matrix dimensions [1x1].
• Signals connected to duplicated inports are not logged during SIL/PIL simulation. No
warning is issued.
During normal simulation, signals connected directly to duplicated inports are logged.
• The Signal Logging Selector / DataLoggingOverride override mechanism is not
supported.
• There is no support for signals that are not named.
• The Normal and SIL/PIL simulations for a top model produce logged bus signals with
names that are different when all of the following conditions apply:
• For signal logging, if you specify the signal logging format to be ModelDataLogs,
the software adds _wrapper to the block path for signals in logsout. For
example:
>> logsout.SignalLogging
Name: 'SignalLogging'
BlockPath: 'sillogging_wrapper/sillogging'
PortIndex: 1
SignalName: 'SignalLogging'
ParentName: 'SignalLogging'
TimeInfo: [1x1 Simulink.TimeInfo]
Time: [11x1 double]
Data: [11x1 double]
32-55
32 Numerical Equivalence Checking
If the Simulation Data Inspector is recording data, the software adds _wrapper to
the run name.
To avoid this behavior, use the Dataset signal logging format. See
“Simulink.SimulationData.Dataset”.
• For output logging, if the save format is Structure or Structure with time
and you run the sim command without specifying the single-output format, the
software adds _wrapper to the block name for signals in yout. For example:
>> yout.signals
ans =
values: [11x1 double]
dimensions: 1
label: 'SignalLogging'
blockName: 'sillogging_wrapper/OutputLogging'
If the save format is Array, the software does not add the suffix.
To avoid this behavior, run command-line simulations with the sim command
specifying the single-output format. See “Run Simulation Using the sim
Command”.
To run SIL/PIL simulations with C++ class code, you must set External I/O access to
None.
I/O Support
I/O Top-Model SIL/PIL Model Block SIL/PIL SIL/PIL Block
Tunable parameters N/A Yes. See “Tunable N/A
(Model reference Parameters and SIL/PIL”
arguments) on page 32-59.
Tunable parameters No Yes. See “Tunable Yes. See “Tunable
(Workspace Parameters and SIL/PIL” Parameters and SIL/PIL”
variables) on page 32-59. on page 32-59.
Virtual buses No Yes Yes
Nonvirtual buses Yes, but see “Top- Yes Yes
Model SIL/PIL Bus
32-56
SIL and PIL Simulation Support and Limitations
32-57
32 Numerical Equivalence Checking
32-58
SIL and PIL Simulation Support and Limitations
You can tune parameters during a SIL/PIL mode simulation the same way that you tune
parameters during a Normal mode simulation.
For more information, see “Global Tunable Parameters” and “Using Model Arguments” in
the Simulink documentation.
32-59
32 Numerical Equivalence Checking
The following table summarizes SIL/PIL support for tunable workspace parameters.
Limitations
During a SIL/PIL simulation, the software cannot define, initialize, or tune the following
types of tunable workspace parameters. The software produces warnings or errors.
During a SIL/PIL block simulation, the software supports the tuning of tunable
workspace parameters but not tunable block dialog parameters. You can view the list of
tunable workspace parameters through the Function Block Parameters dialog box of the
SIL/PIL block.
For C++ class code, SIL/PIL tunable workspace parameters can be tuned provided you do
not use the following settings together:
32-60
SIL and PIL Simulation Support and Limitations
For top-model SIL/PIL and the SIL/PIL block, consider the case where all of the following
conditions apply:
• Code Generation > Interface > Code interface packaging is set to Reusable
function.
• Optimization > Signals and Parameters > Inline parameters is not selected.
• The model contains parameters with storage class Auto or SimulinkGlobal.
If the SIL/PIL component cannot dynamically initialize tunable parameters in the rtP
model parameter structure, the software produces an error message like the following:
Parameter Dialog:InitialOutput in 'rtwdemo_sil_topmodel/CounterTypeA/count'
is part of the imported "rtP" structure in the generated code but cannot be
initialized by SIL or PIL. To avoid this error, make sure the parameter
corresponds to a tunable base workspace variable with a storage class such
as SimulinkGlobal and is supported for dynamic parameter initialization /
tuning with SIL/PIL.
SIL/PIL supports fixed-point data types that are wider than 32 bits. For example:
• For 64-bit data type support, the data type must be representable as long or
long long on the MATLAB host and the target. Otherwise, the software uses the
multiword fixed-point approach, which SIL/PIL does not support.
• 32-bit Windows does not support 64-bit long or long long data types. In this
case, the software uses the multiword fixed-point approach, which SIL/PIL does not
support.
• The software does not support the 40-bit long data type of the TI’s C6000™ target.
Through the Configuration > Hardware Implementation pane, you can enable
support for the 64-bit long long data type. However, for data types with widths
between 33 and 40 bits (inclusive), the software implements the data types using the
40-bit long data type, which SIL/PIL does not support.
32-61
32 Numerical Equivalence Checking
SIL/PIL supports global data stores. However, with components that are not export-
function models, top-model SIL/PIL and SIL/PIL block simulations that access global
data stores must be single rate. Otherwise, the software produces an error.
You can use, for example, signals, parameters, and data stores that specify storage
classes with imported data definitions.
Top-Model SIL/PIL and SIL/PIL Block
Top-model SIL/PIL and the SIL/PIL block do not define imported signals that are
internal with respect to the component or models referenced by the component.
Top-model SIL/PIL and the SIL/PIL block automatically define storage for imported data
associated with:
• Signals at the root level of the component (on the I/O boundary)
• Global data stores
• Parameters
Top-model SIL/PIL and the SIL/PIL block do not define storage for other imported data.
You must define the storage through custom code included by the component under test
or through the PIL rtw.pil.RtIOStreamApplicationFramework API. For example,
the SIL/PIL application does not define storage for imported data associated with:
The SIL/PIL application automatically defines storage for imported data associated with:
• Signals at the root level of the component (on the I/O boundary)
• Parameters. See Tunable Parameters and SIL/PIL Limitations.
• Global data stores
Note: Model block SIL/PIL does not define imported signals that are internal with
respect to the component or models referenced by the component.
32-62
SIL and PIL Simulation Support and Limitations
A limitation is that SIL/PIL does not define storage for other imported data storage. You
must define the storage through custom code included by the component under test or
through the PIL rtw.pil.RtIOStreamApplicationFramework API. For example, the
PIL application does not define imported data storage for data associated with:
The software supports the GetSet custom storage class for all types of SIL and PIL
simulations. The SIL/PIL test harness automatically provides C definitions of the Get
and Set functions that are used during SIL/PIL simulations. In addition, the software
supports only scalar signals, parameters and global data stores.
If you use a data store, signal, or parameter implementation that SIL/PIL does not
support, you might see errors like the following:
The following data interfaces have
implementations that are not supported by SIL or PIL.
data interfaces can be global data stores, inports, outports or parameters.
You see this error message because the model output port has been optimized through
virtual output port optimization. See “Virtualized Output Ports Optimization”. The error
occurs because the properties (for example, data type, dimensions) of the signal or signals
entering the virtual root output port have been modified by routing the signals in one of
the following ways:
Note: Dimension changes from scalar (1) to matrix [1x1], and, matrix [1x1] to
scalar (1), can lead to this error. Furthermore, it is difficult to inspect the model for
32-63
32 Numerical Equivalence Checking
such changes because the Display > Signal & Ports > Signal Dimensions feature
does not distinguish between (1) and [1x1] dimensions. The software shows both
signals as scalar signals. Check your model and workspace objects carefully and see
that scalar dimensions are specified consistently.
The following model causes this error by changing the output port signal data type.
SIL/PIL treats variable-size signals at the I/O boundary of the SIL/PIL component as
fixed-size signals, which can lead to errors during propagation of signal sizes. To avoid
such errors, use only fixed-size signals at the I/O boundary of the SIL/PIL component.
There might be cases where no error occurs during propagation of signal sizes. In these
cases, the software treats variable-size input signals as zero-size signals.
Data Type Overrides Unavailable for Most Blocks in Embedded Targets and Desktop Targets
When you attempt to perform a datatype override on a block, you might get an error
message similar to the following example:
32-64
SIL and PIL Simulation Support and Limitations
Fixed-Point Tool data type overrides are not available for blocks in Simulink Coder >
Desktop Targets and Embedded Coder > Embedded Targets libraries that support
fixed-point data types.
The software does not support replacement data type names that you define for the built-
in data type boolean if these names map to either the int or uint built-in data type.
The software does not support grounded or unconnected signals at the outputs of a top
model.
For top-model SIL/PIL, set the Simulation > Configuration Parameters >
Diagnostics > Connectivity+Mux blocks used to create bus signals parameter to
error. For details, see “Prevent Bus and Mux Mixtures”.
The PIL block supports mux signals, except mixed data-type mux signals that expand
into individual signals during a right-click subsystem build. You see an error for
unsupported cases.
When you start a top-model SIL/PIL simulation, the software regenerates code if it
detects changes to your model. The software detects changes by using a checksum for the
model. However, the software does not detect changes that you make to:
Therefore, if you make these changes, you must build (Ctrl-B) your model again before
starting the next PIL simulation.
If your model has function-call subsystems and you export a subsystem that has
context-dependent inputs (for example, feedback signals), then the results of a SIL/
32-65
32 Numerical Equivalence Checking
PIL simulation with the generated code might not match the results of the Normal
mode simulation of your model. One approach to make SIL/PIL and Normal mode
simulations yield identical results is to use “Function-Call Feedback Latch” blocks in
your model. This approach allows you to make context-dependent inputs become context-
independent.
PIL requires that, in the Simulink Configuration Parameters dialog box, you configure
the right Hardware Implementation settings for the target environment. You must
also specify byte ordering for targets.
Warning If you do not specify the correct Hardware Implementation, the PIL
simulation fails, displaying undefined behavior.
32-66
SIL and PIL Simulation Support and Limitations
PIL supports only data types that have the same size on the host and the target at the
PIL I/O boundary.
The data types used at the PIL I/O boundary are restricted based on the following rule:
PIL supports the data type only if the data-type size on the host (Simulink) is the same
as the data-type size on the target.
32-67
32 Numerical Equivalence Checking
32-68
Programmatic Code Generation Verification
Note: CGV helps you verify the numerical equivalence of results for a given set of inputs.
CGV can detect numerical deviations for the given set of inputs only. The completeness of
the input data that you provide to CGV determines the validity of the results.
• Configure your model for SIL or PIL simulation. For more information, see “Configure
a SIL or PIL Simulation” on page 32-10.
• Use the cgv.Config class of the CGV API to verify the model configuration for SIL
or PIL simulation. For more information, see “Check the SIL or PIL Configuration”.
• Configure your model for code generation. For more information, see “Application
Objectives”.
• Save your model. If you modify a model without saving it, CGV might issue an error.
32-69
32 Numerical Equivalence Checking
• Set up the tests for the first execution environment. For example, simulation.
• Use “run (cgv.CGV)” to run the tests for the first execution environment.
• Set up the tests for the second execution environment. For example, top-model PIL.
• Use cgv.CGV.run to run the tests for the second execution environment.
• Use “getOutputData (cgv.CGV)” to get the output data for each execution
environment.
• Use “getSavedSignals (cgv.CGV)” to display the signal names in the output data.
(optional)
• Build a list of signal names for input to other cgv.CGV methods. (optional)
• Use “createToleranceFile (cgv.CGV)” to create a file correlating tolerance information
with output signal names. (optional)
• Use “compare (cgv.CGV)” to compare the output signals of the first and second
execution environments for numerical equivalence.
The first task for verifying numerical equivalence is to check the configuration of your
model.
32-70
Programmatic Code Generation Verification
3 Use the “cgv.Config class” to create a cgv.Config object. Specify parameters that
check and modify configuration parameter values and save the model for top-model
SIL mode of execution.
cgvCfg = cgv.Config('rtwdemo_cgv', 'connectivity', 'sil', 'SaveModel', 'on');
4 Use the “configModel (cgv.Config)” method to review your model configuration and to
change the settings to configure your model for SIL. When 'connectivity' is set
to 'sil', the system target file is automatically set to 'ert.tlc'. If you specified
the parameter/value pair, ('SaveModel', 'on') when you created the cgvCfg
object, the cgv.Config.configModel method saves the model.
Note: CGV runs on models that are open. If you modify a model without saving it,
CGV might issue an error.
Use the CGV API to execute the model in two modes. The two modes in this example are
normal mode simulation and SIL mode. In each execution of the model, the CGV object
for each mode captures the output data and writes the data to a file.
1 If you have not already done so, follow the steps described in “Configure the Model”
on page 32-70.
2 Create a cgv.CGV object that specifies the rtwdemo_cgv model in normal mode
simulation.
cgvSim = cgv.CGV(cgvModel, 'connectivity', 'sim');
Note: When the top model is set to Normal simulation mode, the CGV API sets
referenced models in PIL mode to Accelerator mode.
3 Provide the input file to the cgvSim object.
32-71
32 Numerical Equivalence Checking
4 Before execution of the model, specify the MATLAB files to execute or MAT-files to
load. This step is optional.
cgvSim.addPostLoadFiles({[cgvModel '_init.m']});
5 Specify a location where the object writes all output data and metadata files for
execution. This step is optional.
cgvSim.setOutputDir('cgv_output');
After setting up and running the test, compare the outputs by doing the following:
1 If you have not already done so, configure and test the model, as described in
“Configure the Model” on page 32-70 and “Execute the Model” on page 32-71.
2 Test that the execution result of the model:
32-72
Programmatic Code Generation Verification
if ~result1 || ~result2
error('Execution of model failed.');
end
3 Use the “getOutputData (cgv.CGV)” method to get the output data from the cgv.CGV
objects.
simData = cgvSim.getOutputData(1);
silData = cgvSil.getOutputData(1);
5 Using the list of signals, build a list of signals in a cell array of strings. The signal
list can contain a number of signals.
signalList = {'simData.ErrorsInjected.Data'};
7 Compare the output data signals. By default, the “compare (cgv.CGV)” method looks
at all signals which have a common name between both executions. If a tolerance
file is present, cgv.CGV.compare uses the associated tolerance for a specific signal
during comparison; otherwise the tolerance is zero. In this example, the 'Plot'
parameter is set to 'mismatch'. Therefore, only mismatched signals produce a plot.
[matchNames, ~, mismatchNames, ~] = ...
cgv.CGV.compare(simData, silData, 'Plot', 'mismatch', ...
'Tolerancefile', 'localtol');
32-73
32 Numerical Equivalence Checking
The lower plot displays the numeric difference between the results.
After setting up and running the test, compare the outputs of individual signals by doing
the following:
32-74
Programmatic Code Generation Verification
1 If you have not already done so, configure and test the model, as described in
“Configure the Model” on page 32-70 and “Execute the Model” on page 32-71.
2 Use the “getOutputData (cgv.CGV)” method to get the output data from the
cgv.CGV objects.
simData = cgvSim.getOutputData(1);
silData = cgvSil.getOutputData(1);
3 Use the “getSavedSignals (cgv.CGV)” method to display the output data signal
names. Build a list of specific signal names in a cell array of strings. The signal list
can contain number of signals.
cgv.CGV.getSavedSignals(simData);
signalList = {'simData.BusOutputs.hi1.mid0.lo1.Data', ...
'simData.BusOutputs.hi1.mid0.lo2.Data', 'simData.Vector.Data(:,3)'};
4 Use the specified signals as input to the “compare (cgv.CGV)” method to compare the
signals from separate runs.
[matchNames, ~, mismatchNames, ~] = ...
cgv.CGV.compare(simData, silData, 'Plot', 'mismatch', ...
'signals', signalList);
fprintf( '%d Signals match, %d Signals mismatch\n', ...
length(matchNames), length(mismatchNames));
if ~isempty(mismatchNames)
disp( 'Mismatched Signal Names:');
disp(mismatchNames);
end
At the MATLAB command line, the result is:
3 Signals match, 0 Signals mismatch
1 If you have not already done so, configure and test the model, as described in
“Configure the Model” on page 32-70 and “Execute the Model” on page 32-71.
2 Use the “getOutputData (cgv.CGV)” method to get the output data from the
cgv.CGV objects.
simData = cgvSim.getOutputData(1);
3 Use the “getSavedSignals (cgv.CGV)” method to display the output data signal
names. Build a list of specific signal names in a cell array of strings. The signal list
can contain number of signals.
cgv.CGV.getSavedSignals(simData);
32-75
32 Numerical Equivalence Checking
signalList = {'simData.Vector.Data(:,1)'};
4 Use the specified signal list as input to the “plot (cgv.CGV)” method to compare the
signals from separate runs.
[signalNames, signalFigures] = cgv.CGV.plot(simData, ...
'Signals', signalList);
32-76
33
In SIL execution, through a MATLAB SIL interface, the software compiles and runs
library code on your host computer. In PIL execution, through a MATLAB PIL interface,
the software cross-compiles and runs production object code on a target processor or an
equivalent instruction set simulator. Before you run a PIL execution, you must set up a
PIL connectivity configuration for your target.
In step 4, you verify code that is generated for execution within MATLAB. However,
this code is different from the standalone code generated for libraries. In step 6, with an
Embedded Coder license, you use SIL or PIL execution to verify the standalone code.
Feature See
SIL execution • “Software-in-the-Loop Execution
Through Project Interface” on page
33-4
• “Software-in-the-Loop Execution From
Command Line” on page 33-6
33-2
Code Verification Through Software-in-the-Loop and Processor-in-the-Loop Execution
Feature See
PIL target connectivity configuration • “PIL Customization for Target
Environment” on page 33-12
• “Create PIL Target Connectivity
Configuration” on page 33-15
• “Processor-in-the-Loop Execution From
Command Line” on page 33-24
PIL execution • “Processor-in-the-Loop Execution
Through Project Interface” on page
33-22
• “Processor-in-the-Loop Execution From
Command Line” on page 33-24
Code generation, MEX functions, and • “MATLAB Code Analysis”
libraries • “Generating Code”
• “Deployment”
33-3
33 Software-in-the-Loop Execution for MATLAB Coder
To set up and run a SIL execution for a project through the MATLAB Coder project
interface:
1 From the MATLAB apps gallery, open your MATLAB Coder project. For example,
kalman_filter.prj. For information about creating a project, see “C Code
Generation Using the Project Interface”.
2 Click the Build tab.
3 Under Settings:
a In the Output file field, use the default value. For example, kalman01.
b From the Output type drop-down list, select C/C++ Static Library or C/C+
+ Dynamic Library.
c Clear the Generate code only check box.
d Click More Settings.
4 In the Project Settings dialog box:
33-4
Software-in-the-Loop Execution Through Project Interface
c If required, enable your debugger for SIL execution. From the All Settings >
Advanced > Enable source-level debugging for SIL drop-down list, select
Yes.
d Click Close.
5 Under Software-in-the-Loop Verification:
a In the Test file field, specify the test file that calls the original MATLAB
functions, for example, test01_ui.m.
b By default, the Redirect entry-point calls to generated library check box is
selected. Otherwise, select this check box.
6 To start the SIL execution, click Run.
The software:
Verify that the output of the SIL execution matches the output from your original
MATLAB function.
7 To terminate the SIL execution process, click Terminate verification.
Note: On a Windows operating system, the Windows Firewall might block the SIL
execution. To allow the SIL execution, use the Windows Security Alert dialog box. For
example, in Windows 7, click Allow access.
33-5
33 Software-in-the-Loop Execution for MATLAB Coder
To terminate the SIL execution, use the clear function_sil or clear mex
command.
The following example shows how you can set up and run a SIL execution from the
command line.
src_dir = ...
fullfile(docroot,'toolbox','coder','examples','kalman');
copyfile(fullfile(src_dir,'kalman01.m'), '.')
copyfile(fullfile(src_dir,'test01_ui.m'), '.')
33-6
Configure SIL execution
copyfile(fullfile(src_dir,'plot_trajectory.m'), '.')
copyfile(fullfile(src_dir,'position.mat'), '.')
For a description of the Kalman estimator in this example, see “C Code Generation
at the Command Line”.
2
Configure SIL execution
a From your working folder, create a coder.EmbeddedCodeConfig object.
config = coder.config('lib');
config.GenerateReport = true; % Optional, documents code in HTML report
b Configure the object for SIL.
config.VerificationMode = 'SIL';
config.SILDebugging = true;
3
Generate code and run SIL execution
a Generate library code for the kalman01 MATLAB function and the SIL
interface.
Verify that the output of this run matches the output from the original kalman01.m
function.
33-7
33 Software-in-the-Loop Execution for MATLAB Coder
Note: On a Windows operating system, the Windows Firewall might block the SIL
execution. To allow the SIL execution, use the Windows Security Alert dialog box.
For example, in Windows 7, click Allow access.
4
Debug code during SIL execution
If you enable the Microsoft Visual Studio debugger, then running the test file opens
the Microsoft Visual Studio IDE with debugger breakpoints at the start of the
kalman01_initialize and kalman01 functions.
You can use the debugger features to observe code behavior. For example, you can
step through code and examine variables.
33-8
Code Debugging During SIL Execution
Note: You can perform SIL debugging only if your Microsoft Visual C++ or GNU GCC
compiler is supported by the MATLAB product family. For more information, see
supported compilers.
For information about enabling the debugger from the command line, see “SIL Execution
of Code Generated for a Kalman Estimator” on page 33-6.
When you run the SIL execution, for example on a Windows computer, your user_fn.c
or user_fn.cpp file opens in the Microsoft Visual Studio IDE with debugger
breakpoints at the start of the user_fn_initialize and user_fn functions.
33-9
33 Software-in-the-Loop Execution for MATLAB Coder
You can now use the debugger features to observe code behavior. For example, you can
step through code and examine variables.
Note: If you select Debug > Stop Debugging, the SIL execution times out with the
following error message:
Communications error: failed to send data to the target. There might be
multiple reasons for this failure.
33-10
Code Debugging During SIL Execution
...
...
33-11
33 Software-in-the-Loop Execution for MATLAB Coder
To run a PIL verification, the software must first determine which of the available
connectivity configurations to use. The software looks for a connectivity configuration
that is compatible with the code under test. If the software finds multiple or no
compatible connectivity configurations, the software generates an error message with
information about resolving the problem.
33-12
PIL Customization for Target Environment
The API is independent of the physical layer that sends the data. Possible physical layers
include RS232, Ethernet, or Controller Area Network (CAN).
33-13
33 Software-in-the-Loop Execution for MATLAB Coder
A full rtiostream implementation requires both host-side and target-side drivers. Code
generation software includes host-side drivers for the default TCP/IP implementation as
well as a version for serial communications. To use:
• The TCP/IP rtiostream communications channel, you must provide, or obtain from
a third party, target-specific TCP/IP device drivers.
• The serial communications channel, you must provide, or obtain from a third party,
target-specific serial device drivers.
For other communication channels and platforms, the code generation software does not
provide default implementations. You must provide both the host-side and the target-side
drivers.
• rtIOStreamOpen
• rtIOStreamSend
• rtIOStreamRecv
• rtIOStreamClose
33-14
Create PIL Target Connectivity Configuration
In this section...
“Create a Connectivity API Implementation” on page 33-15
“Test an rtiostream Driver” on page 33-16
“Synchronize Host and Target” on page 33-38
“Specify Hardware Timer” on page 33-19
“Register a Connectivity API Implementation” on page 33-41
For information about creating a subclass, see “Creating Subclasses — Syntax and
Techniques” in MATLAB documentation.
33-15
33 Software-in-the-Loop Execution for MATLAB Coder
• Reduces time for integrating custom hardware that does not have built-in
rtiostream support.
• Reduces time for testing custom rtiostream drivers.
• Helps analyze the performance of custom rtiostream drivers.
The test suite has two parts. One part of the test suite runs on the target.
Note: After building the target application, download it to the target and run it.
To launch this part, compile and link the following files, which are in matlabroot/
toolbox/coder/rtiostream/src/rtiostreamtest.
• rtiostreamtest.c
• rtiostreamtest.h
• rtiostream.h (located at matlabroot/rtw/c/src/)
• rtiostream implementation under investigation (for example,
rtiostream_tcpip.c)
• main.c
To run the MATLAB part of the test suite, invoke rtiostreamtest. The syntax is as
follows:
rtiostreamtest(connection,param1,param2)
• If connection is 'tcp', then param1 and param2 are hostname and port,
respectively. For example, rtiostreamtest('tcp', 'localhost', 2345).
33-16
Create PIL Target Connectivity Configuration
• If connection is 'serial', then param1 and param2 are COM port and baud
rate, respectively. For example, rtiostreamtest('serial', 'COM1', 9600).
You can run the MATLAB part of the test suite as follows:
rtiostreamtest('tcp','localhost','2345')
An output in the following format appears in the MATLAB window:
33-17
33 Software-in-the-Loop Execution for MATLAB Coder
33-18
Create PIL Target Connectivity Configuration
With other rtiostream implementations, for example, serial, the MATLAB side of the
rtiostream connection will open without waiting for the target to be fully initialized.
In this case, you must make your Launcher implementation wait until the target
application is fully initialized. Use one of the following approaches to synchronize your
host and target:
• Add a pause at the end of the Launcher implementation that makes the Launcher
wait until target initialization is complete.
• In the Launcher implementation, use third-party downloader or debugger APIs that
wait until target initialization is complete.
• Implement a handshaking mechanism in the Launcher / rtiostream
implementation to confirm that target initialization is complete.
1 Open the Code Replacement Tool. In the Command Window, enter crtool.
2 Create a new code replacement table. Select File > New table.
3 Create a new function entry. Under Tables List, right-click the new table. Then,
from the context-menu, select New entry > Function.
4 In the middle view, select the new unnamed function.
5 On the Mapping Information pane:
33-19
33 Software-in-the-Loop Execution for MATLAB Coder
The default value is 0. In this case, the software reports time measurements in
terms of ticks, not seconds.
d In the Name field, specify a replacement function name, for example, MyTimer.
e Click Apply.
You must save the table in a location that is on the MATLAB search
path. For example, you can save this file in the folder for your subclass of
rtw.connectivity.Config.
33-20
Create PIL Target Connectivity Configuration
The software stores your timer information as a code replacement library table.
8 Assuming you save the table as MyCrlTable.m, in your subclass of
rtw.connectivity.Config, add the following line:
setTimer(this, MyCrlTable)
For more information, see “What Is Code Replacement?” and “What Is Code Replacement
Customization?”.
• rtw.connectivity.ConfigRegistry
• “Processor-in-the-Loop Execution From Command Line”
33-21
33 Software-in-the-Loop Execution for MATLAB Coder
Before you run a PIL execution, you must specify a target connectivity configuration. In
“Processor-in-the-Loop Execution From Command Line” on page 33-24, steps 1 and 2
of the example, PIL Execution of Code Generated for a Kalman Estimator, show how you
can set up and register a connectivity configuration for host-based PIL.
To set up and run a PIL execution for a project through the MATLAB Coder project
interface:
1 From the MATLAB apps gallery, open your MATLAB Coder project. For example,
kalman_filter.prj. For information about creating a project, see “C Code
Generation Using the Project Interface”.
2 Click the Build tab.
3 Under Settings:
a In the Output file field, use the default value. For example, kalman01.
b From the Output type drop-down list, select C/C++ Static Library or C/C+
+ Dynamic Library.
c Clear the Generate code only check box.
d Click More Settings.
4 In the Project Settings dialog box:
a Click Hardware.
b Specify your device vendor and type, which must match the target hardware
settings specified in the rtwTargetInfo.m file of your target connectivity
configuration. For example, for host-based PIL:
a In the Test file field, specify the test file that calls the original MATLAB
functions, for example, test01_ui.m.
33-22
Processor-in-the-Loop Execution Through Project Interface
The software:
Verify that the output of the PIL execution matches the output from your original
MATLAB function.
7 To terminate the PIL execution process, click Terminate verification.
33-23
33 Software-in-the-Loop Execution for MATLAB Coder
To terminate the PIL execution, use the clear function_pil or clear mex
command.
The following example shows how you can set up and run a host-based PIL execution
from the command line.
33-24
Create a target connectivity API implementation
coder.mypil.Utils.UpdateClassName(...
'./+mypil/ConnectivityConfig.m',...
'coder.mypil',...
'mypil');
d Check that you now have a folder +mypil in the current folder, which
includes three files, Launcher.m, TargetApplicationFramework.m, and
ConnectivityConfig.m.
dir './+mypil'
e Review the code that starts the PIL application. The mypil.Launcher class
configures a tool for starting the PIL executable. Open this class in the editor.
edit(which('mypil.Launcher'))
Review the content of this file. For example, consider the setArgString
method. This method allows additional command line parameters to be supplied
to the application. These parameters can include a TCP/IP port number. For
an embedded processor implementation, you might have to hard code these
settings.
f The class mypil.ConnectivityConfig configures target connectivity.
edit(which('mypil.ConnectivityConfig'))
Review the content of this file. For example:
rtiostreamtcpip_dir=fullfile(matlabroot,'rtw','c','src','rtiostream',...
'rtiostreamtcpip');
edit(fullfile(rtiostreamtcpip_dir,'rtiostream_tcpip.c'))
Scroll down to the end of this file. The file contains a TCP/IP implementation
of the functions rtIOStreamOpen, rtIOStreamSend, andrtIOStreamRecv.
33-25
33 Software-in-the-Loop Execution for MATLAB Coder
These functions are required for target communication with the host. For each
of these functions, you must provide an implementation that is specific to your
target hardware and communication channel.
edit(which('mypil.TargetApplicationFramework'))
The file specifies additional files to include in the build.
2
Register a target connectivity configuration
Use an rtwTargetInfo.m file to:
a Insert the following code into your rtwTargetInfo.m file, and save the file in
the current working folder or in a folder that is on the MATLAB search path:
function rtwTargetInfo(tr)
% Register PIL connectivity config: mypil.ConnectivityConfig
tr.registerTargetInfo(@loc_createConfig);
% local function
function config = loc_createConfig
33-26
Copy MATLAB code for Kalman estimator
RTW.TargetRegistry.getInstance('reset');
3
Copy MATLAB code for Kalman estimator
Copy the MATLAB code to your working folder.
src_dir = ...
fullfile(docroot,'toolbox','coder','examples','kalman');
copyfile(fullfile(src_dir,'kalman01.m'), '.')
copyfile(fullfile(src_dir,'test01_ui.m'), '.')
copyfile(fullfile(src_dir,'plot_trajectory.m'), '.')
copyfile(fullfile(src_dir,'position.mat'), '.')
For a description of the Kalman estimator in this example, see “C Code Generation
at the Command Line”.
4
Configure the PIL execution
a Create a coder.EmbeddedCodeConfig object.
config = coder.config('lib');
b Configure the object for PIL.
config.VerificationMode = 'PIL';
c Specify production hardware, which must match one of the test hardware
settings in rtwTargetInfo.m.
config.HardwareImplementation.ProdHWDeviceType =...
'Generic->32-bit x86 compatible';
33-27
33 Software-in-the-Loop Execution for MATLAB Coder
5
Generate code and run PIL execution
a Generate library code for the kalman01 MATLAB function and the PIL
interface.
codegen('-config', config, '-args', {zeros(2,1)}, 'kalman01');
The software creates the following output folders:
33-28
SIL/PIL Execution Support and Limitations
Feature Supported
Static library Yes
Output types Dynamic library Yes
Executable No
Languages C Yes
C++ Yes
Inputs Yes
Outputs Yes
Constant inputs Yes
Global data No
Interface types Constant global Yes
data
Reentrant code Yes
Multiple entry Yes
points
Basic types Yes
Enumerated types Yes
Structures Yes
Complex data Yes
Data types Fixed-point data Yes
Multiword fixed- SIL only
point data
char arrays Yes
Empty values Yes
Scalars Yes
Fixed-size arrays Yes
Size
Static variable-size Yes
arrays
33-29
33 Software-in-the-Loop Execution for MATLAB Coder
Feature Supported
Dynamic variable- No
size size arrays
33-30
34
Code Coverage
• LDRA Testbed® from LDRA Software Technology. For information about installing
and using this tool, go to www.ldra.com.
The software supports LDRA Testbed code coverage for SIL and PIL. For information
about PIL support, see “PIL Support for LDRA Testbed” on page 34-16.
The software supports BullseyeCoverage code coverage for SIL and, in certain cases,
PIL. For information about PIL support, see “PIL Support for BullseyeCoverage” on
page 34-17.
For more information, see “Code Coverage Tool Support” on page 34-15.
For information about setting up code coverage and viewing results, see:
34-2
Configure SIL and PIL Code Coverage
1 Select Simulation > Model Configuration Parameters > Code Generation >
Verification.
2 From the Code coverage tool drop-down list, select a tool, for example,
BullseyeCoverage or LDRA Testbed.
3 Click Configure Coverage to open the Code Coverage Settings dialog box.
4 In the Installation folder field, specify the location where your coverage tool is
installed. If you click Browse, the Select Installation Folder dialog box opens,
which allows you to navigate to the folder where your coverage tool is installed. The
software detects and displays the tool version.
• Code coverage for this model — Generate coverage data for the current (top)
model.
• Code coverage for referenced models — Generate data for models referenced
by the current (top) model.
If your top model has Model blocks where the Code under test block parameter is
set to Top model, then the top model and referenced models must have the same
settings for these parameters. Otherwise, the software produces an error.
5 Click OK. You return to the Verification pane.
6 To view cumulative code coverage results within a code generation report, in the
Configuration Parameters > Code Generation > Report pane, select the
following check boxes:
34-3
34 Code Coverage
• The evaluation of cumulative code coverage begins from the point when you last
added a new file to the existing set of source files. For example, existing code coverage
results are deleted when you:
• Run a simulation with a new model using the existing code generation folder.
• Run a simulation that results in additional source code files being instrumented.
• If you switch between SIL and PIL simulations of a model, the software generates
separate cumulative code coverage results for the SIL and PIL simulations.
For a model in a reference hierarchy, the software does not support simultaneous
function execution time measurement and code coverage.
34-4
View Code Coverage Information at the End of SIL or PIL Simulations
If you specified the LDRA Testbed, you see three links in the Command Window:
### Starting SIL simulation for component: rtwdemo_sil_topmodel
### Stopping SIL simulation for component: rtwdemo_sil_topmodel
### Starting analysis of coverage data
### Use the following links to view code coverage results:
LDRA Testbed GUI
LDRA Testbed Code Coverage Overview Report
HTML code generation report with code coverage annotations
### Completed code coverage analysis
>>
To:
34-5
34 Code Coverage
For information about using this report, refer to the LDRA Testbed documentation.
• View summary data and code annotations with coverage information in the
code generation report, click the third link. See “Code Coverage Summary and
Annotations” on page 34-10.
If you specified the BullseyeCoverage tool, you see two links in the Command Window:
### Starting SIL simulation for component: rtwdemo_sil_topmodel
### Stopping SIL simulation for component: rtwdemo_sil_topmodel
### Processing code coverage data
### Use the following links to view code coverage results:
BullseyeCoverage browser (coverage for last run)
HTML code generation report (cumulative coverage)
34-6
View Code Coverage Information at the End of SIL or PIL Simulations
To:
• View the coverage report using the BullseyeCoverage Browser, click the first link.
The BullseyeCoverage Browser shows coverage data for instrumented files associated
with your latest top-model simulation. The coverage data shown in the browser is not
cumulative and pertains only to the most recent simulation. For information about
the BullseyeCoverage Browser, go to www.bullseye.com.
• View summary data and code annotations with coverage information in the
code generation report, click the second link. See “Code Coverage Summary and
Annotations” on page 34-10.
34-7
34 Code Coverage
1 Using get_param, retrieve the object containing coverage settings for the current
model, for example, gcs.
>> covSettings = get_param(gcs, 'CodeCoverageSettings')
covSettings =
cov.CodeCoverageSettings handle
Package: cov
Properties:
TopModelCoverage: 'on'
ReferencedModelCoverage: 'off'
CoverageTool: 'BullseyeCoverage'
If LDRA Testbed is the specified code coverage tool, then the property
CoverageTool is 'LDRA Testbed'.
ans =
cov.CodeCoverageSettings
3 Turn on coverage for referenced models.
>> covSettings.ReferencedModelCoverage='on';
34-8
Configure Code Coverage Programmatically
5 Assuming you have installed the BullseyeCoverage tool, specify the installation path.
>> cov.BullseyeCoverage.setPath('C:\Program Files\BullseyeCoverage')
34-9
34 Code Coverage
The code generation report also allows you to navigate easily between blocks in your
model and the corresponding sections in the source code. For more information, see
“Trace Model Objects to Generated Code” and “Trace Code to Model Objects Using
Hyperlinks”.
The software provides LDRA Testbed annotations in the code generation report to help
you to review code coverage.
34-10
Code Coverage Summary and Annotations
Note: Do not use the code generation report alone to verify that you have achieved your
coverage goals. You must refer to the LDRA Testbed Report. See “View Code Coverage
Information at the End of SIL or PIL Simulations” on page 34-5.
This example shows three kinds of annotations. On lines 134, 139, 140, and 141, the
annotation indicates that statement coverage for each of these lines of code is not
complete.
This tooltip indicates that only one branch destination is covered. The code within
the curly brackets, which starts at column 45 of line 134, is not executed. As the if
statement on line 139 lies within this code, the corresponding annotation => states that
the branch is not covered.
The following table describes the LDRA Testbed code annotations that you might see in a
code generation report produced by a SIL and PIL simulations.
Annotation
Code feature What happened during simulation
symbol
Function name returned through this exit
Fcn
point.
Function
Function name never returned through this
=>
exit point.
=> Condition not encountered.
Branch/condition =>t Condition evaluated true only.
=>f Condition evaluated false only.
34-11
34 Code Coverage
Annotation
Code feature What happened during simulation
symbol
tf Condition evaluated both true and false.
=> Branch never encountered.
Branch to at least one destination covered and
Branch/decision =>b branch to at least one other destination not
covered.
b Branch fully exercised.
Condition did not independently affect outcome
Modified Condition/ =>mc
of decision.
Decision Coverage
(MC/DC) Condition independently affected outcome of
mc
decision.
Statements associated with line covered.
Statement Not all statements associated with line
covered.
Code that is Zero coverage — probes within source code
reformatted by LDRA =>Σ line or files included by source code line not
Testbed and does not exercised.
match the original Coverage probes within source code line or any
source code. For =>Σ
included file partially exercised.
example, source
code with #include Coverage probes within source code line or
statements to include included files fully exercised.
other files, and source
code with #define
statements for macros. Σ
For detailed coverage
information, refer to
the LDRA Testbed
report.
BullseyeCoverage Information
The cumulative coverage data in a code generation report is derived from instrumented
files associated with your latest top-model simulation and coverage data collected from
34-12
Code Coverage Summary and Annotations
simulations with other top models that share referenced models with your current top
model.
This example shows two kinds of annotations. At line 41, TF indicates that the if
decision had both true and false outcomes during the simulation. At line 52, =>F
indicates that the if decision was false only during the simulation.
The following table describes the BullseyeCoverage code annotations that you might see
in a code generation report produced by a SIL simulation.
Annotation
Code feature What happened during simulation
symbol
=> Decision not executed.
Decision
TF Decision evaluated both true and false.
34-13
34 Code Coverage
Annotation
Code feature What happened during simulation
symbol
=>T Decision evaluated true only.
=>F Decision evaluated false only.
=> Function not called.
Function
Fcn Function called.
=> Switch command not used.
Switch label
Sw Switch command used.
Decision or condition was constant, which did not
Constant k
allow any variation in coverage.
=> Condition not encountered.
tf Condition evaluated both true and false.
Condition
=>t Condition evaluated true only.
=>f Condition evaluated false only.
=> Try block never completed.
Try
Try Try block covered.
=> Catch block not covered.
Catch
Cat Catch block covered.
34-14
Code Coverage Tool Support
34-15
34 Code Coverage
For LDRA Testbed version 9.1.1, MathWorks instrumentation files are located in the
LDRA Testbed installation folder, for example:
• C:\LDRA_Toolsuite\Compiler_spec\MathWorks\MathWorks_Cinstr.DAT
• C:\LDRA_Toolsuite\Compiler_spec\MathWorks\MathWorks_CPPINSTR.DAT
There are minor differences in the code coverage information collected during SIL and
PIL simulations. In particular, with PIL, the software does not explicitly show function
exit point coverage. However, you can infer the coverage of function exit points by
examining statement coverage.
34-16
Code Coverage for PIL
If code coverage is not available when you run the PIL application on your target
hardware, you might be able to collect code coverage measurements by running the PIL
application on an instruction set simulator that supports direct file I/O with the host file
system.
34-17
34 Code Coverage
Note: For both SIL and PIL, the Watcom compiler is not supported. If you specify this
compiler, an error appears when you build your model.
For information on how to specify a compiler, see “Compiler or IDE Selection and
Configuration”.
34-18
Tips and Limitations
Whenever you build a model, the code coverage settings of the model must be consistent
with source files that you previously built in the shared utilities folder. Otherwise, the
software reports that code in the shared utilities folder is inconsistent with the current
model configuration and must be rebuilt. For example, if you run a SIL simulation for a
model with code coverage enabled and then run a SIL simulation for another model with
code coverage disabled, the software must rebuild all source files in the shared utilities
folder.
To configure the BullseyeCoverage tool to provide code coverage data for inline macros:
34-19
34 Code Coverage
4 Click OK.
5 Rerun your simulation.
Alternatively, you can add the text -macro to the BullseyeCoverage configuration file.
For more information, go to www.bullseye.com/help/ref_covc.html.
You do not see information for individual probes on each line. The displayed summary
information has an associated annotation tooltip:
0 out of N coverage probes were exercised (detailed breakdown unavailable)
34-20
Tips and Limitations
34-21
34-22
Embedded IDEs and Embedded Targets
35
35-2
36
Model Setup
In this section...
“Block Selection” on page 36-2
“Configure Target Hardware Resources” on page 36-3
“Configuration Parameters” on page 36-5
“Model Reference” on page 36-12
Block Selection
You can create models for targeting the same way you create other Simulink models—by
combining standard blocks and C-MEX S-functions.
Avoid using blocks that do not generate code, including the following blocks.
36-2
Model Setup
This “Configure Target Hardware Resources” on page 36-3 section applies to the
following IDEs:
36-3
36 Project and Build Configurations for Embedded Targets
Configure the parameters under the Target Hardware Resources tab of your Simulink
model for a specific tool chain and target hardware. Doing so updates other parameters
in the Configuration Parameters dialog to the default values for the software build tool
chain and target hardware you are using.
Note: The Target Preferences (Removed) block has been removed from the Simulink
block libraries for the Embedded Coder and Simulink Coder products.
Parameters in the Target Preferences block have been moved to the Target Hardware
Resources tab.
To configure your Simulink model for a specific tool chain and target hardware:
The dialog displays a Coder Target pane under the Code Generation pane.
4 Select the Coder Target pane.
5 Select the Target Hardware Resources tab.
6 Set the following parameters to match the tool chain and target hardware you are
using:
• IDE/Tool Chain
• Board
• Processor
36-4
Model Setup
7 Review the other parameters under the Target Hardware Resources tab.
8 Click Apply, and save the changes to your model.
Configuration Parameters
• “What are Configuration Parameters?” on page 36-5
• “Setting Model Configuration Parameters” on page 36-5
The Configuration Parameters dialog specifies the values for a model's active
configuration set. These parameters determine the type of solver used, the import and
export settings, and other values that determine how the model runs.
To set the Configuration Parameters to the right values for you to generate code from
your model, see “Configure Parameters Under the Target Hardware Resources Tab” on
page 36-4. This action initializes the model Configuration Parameters to the right
default values for you to generate code. You can then use the Configuration Parameters
dialog to make further modifications to the values. You can generate buildable code using
these default values.
The following subsections provide a quick overview of the panes and parameters with
which you are most likely to interact.
36-5
36 Project and Build Configurations for Embedded Targets
36-6
Model Setup
• Run-Time — Set options for run-time operations, like the build action
• Vendor Tool Chain — Set compiler, linker, and system stack size options
• Code Generation — Configure your code generation requirements
• Link Automation — Export an IDE link handle object, such as IDE_Obj, to your
MATLAB workspace
• Diagnostics — Determine how the code generation process responds when you use
source code replacement in the Custom Code pane.
Select Project to create an IDE project, or select Makefile to create a makefile build
script.
36-7
36 Project and Build Configurations for Embedded Targets
Build action
Your selection for Build action determines what happens when you click Build or press
Ctrl+B. Your selection tells Simulink Coder software when to stop the code generation
and build process.
To run your model on the processor, select Build_and_execute. This selection is the
default build action.
The actions are cumulative—each action performs an additional step relative to the
preceding action on the list.
If you set Build format to Project, select one of the following options:
• Create_project — Directs Simulink Coder software to start the IDE and populate
a new project with the files from the build process. This option offers a convenient way
to build projects in the IDE.
• Archive_library — Directs Simulink Coder software to create an archive library
for this model. Use this option when you plan to use the model in a model reference
application. Model reference requires that you archive your the IDE projects for
models that you use in model referencing.
• Build — Builds the executable file, but does not download the file to the target
hardware.
• Build_and_execute — Directs Simulink Coder software to build, download, and
run your generated code as an executable on your target hardware.
• Create_processor_in_the_loop_project — Directs code generation process to
create PIL algorithm object code as part of the project build. This option requires an
Embedded Coder license.
If you set Build format to Makefile, select one of the following options:
36-8
Model Setup
Overrun notification
To enable the overrun indicator, choose one of three ways for the target to respond to an
overrun condition in your model:
Function name
When you select Call_custom_function from the Overrun notification list, you
enable this option. Enter the name of the function the target should use to notify you
that an overrun condition occurred. The function must exist in your code on the target
hardware.
Configuration
The Configuration parameter defines sets of build options that apply to the files
generated from your model.
The Release and Debug option apply build settings that are defined by your compiler.
For more information, refer to your compiler documentation.
To determine the degree of optimization provided by the optimizing compiler, enter the
optimization level to apply to files in your project. For details about the compiler options,
refer to your IDE documentation. When you create new projects, the coder product does
not set optimization flags.
With Texas Instruments Code Composer Studio 3.3 and Analog Devices VisualDSP++,
the user interface displays Get From IDE and Reset buttons next to this parameter. If
you have an active project open in the IDE, you can click Get From IDE to import the
compiler option setting from the current project in the IDE. To reset the compiler option
to the default value, click Reset.
36-9
36 Project and Build Configurations for Embedded Targets
To specify the options provided by the linker during link time, you enter the linker
options as a string. For details about the linker options, refer to your IDE documentation.
When you create new projects, the coder product does not set linker options.
With Texas Instruments Code Composer Studio 3.3 and Analog Devices VisualDSP++,
the user interface displays Get From IDE and Reset buttons next to this parameter. If
you have an active project open in the IDE, you can click Get From IDE to import the
linker options string from the current project in the IDE. To clear the linker options, click
Reset.
System stack size (MAUs)
Enter the amount of memory that is available for allocating stack data, measured in
minimum addressable units (MAU). Block output buffers are placed on the stack until
the stack memory is fully allocated. After that, the output buffers go in global memory.
An MAU is typically 1 byte, but its size can vary by target hardware.
This parameter is used in targets to allocate the stack size for the generated application.
For example, with embedded processors that are not running an operating system, this
parameter determines the total stack space that can be used for the application. For
operating systems, this value specifies the stack space allocated per thread.
This parameter also applies to the “Maximum stack size (bytes)” parameter, located in
the Optimization > Signals and Parameters pane.
System heap size (MAUs)
Set the default heap size that the target hardware reserves for dynamic memory
allocation.
The target hardware uses this heap for functions like printf() and system services code.
To enable the real-time execution profile capability, select Profile real-time execution.
With this selected, the build process instruments your code to provide performance
36-10
Model Setup
profiling at the task level or for atomic subsystems. When you run your code, the
executed code reports the profiling information in an HTML report.
Link Automation
When you build a model for a target, the coder product automatically creates or uses an
existing IDE link handle object (named IDE_Obj, by default) to connect to your IDE.
Although IDE_Obj is a handle for a specific instance of the IDE, it also contains
information about the IDE instance to which it refers, such as the target the IDE
accesses. In this pane, the Export IDE link handle to base workspace option lets you
instruct the coder product to export the object to your MATLAB workspace, giving it the
name you assign in IDE link handle name.
You can also use the IDE link handle object to interact with the IDE using IDE
Automation Interface commands.
Maximum time allowed to build project (s)
Specifies how long the software waits for the IDE to build the software.
Maximum time allowed to complete IDE operation (s)
Specifies how long the software waits for IDE functions, such as read or write, to
return completion messages. If you do not specify a timeout, the default value is 10
seconds.
Export IDE link handle to base workspace
Directs the software to export the IDE_Obj object to your MATLAB workspace.
IDE link handle name
Specifies the name of the IDE_Obj object that the build process creates.
Source file replacement
Selects the diagnostic action to take if the software detects conflicts when you replace
source code with custom code. The diagnostic message responds to both source file
replacement in the Configuration Parameters under Code Generation > Coder Target
parameters and under Code Generation > Custom Code.
The following settings define the messages you see and how the code generation process
responds:
36-11
36 Project and Build Configurations for Embedded Targets
The build operation continues if you select warning and the software detects custom
code replacement problems. You see warning messages as the build progresses.
Select error the first time you build your project after you specify custom code to use.
The error messages can help you diagnose problems with your custom code replacement
files. Use none when the replacement process works and you do not want to see multiple
messages during your build.
Model Reference
The idelink_ert.tlc and idelink_grt.tlc system target files provide support for
generating code from models that use Model Reference. A referenced model will generate
an archive library.
If your top-model uses a reference model that does not have the Build action set to
Archive_library, the build process automatically changes the Build action to
Archive_library and issues a warning about the change.
Use the same Coder Target pane settings in Configuration Parameters for the models in
the model hierarchy.
36-12
IDE Projects
IDE Projects
In this section...
“Support for Third Party Products” on page 36-13
“Code Generation and Build” on page 36-13
In your model, click Build Model . The software performs the actions
you selected for Build action in the model Configuration Parameters, under Code
Generation > Coder Target.
The IDE Project Generator component provides or supports the following features for
developing IDE projects and generating code:
• Automatically create IDE projects for your generated code during the code generation
process.
• Customize code generation using options in the model Configuration Parameters.
• Configure the automatic project build process.
• Automatically download and run your generated projects on your target hardware.
IDE Project Generator automatically creates and uses an IDE link handle object to
communicate with your IDE and target hardware.
36-13
36 Project and Build Configurations for Embedded Targets
To create the IDE link handle object, IDE Project Generator uses one of the following
constructor functions:
For a command line example of how to use a constructor function, see the corresponding
reference page for each function.
36-14
Makefiles for Software Build Tool Chains
Overview
You can use makefiles instead of IDE projects during the automated software build
process. This approach is described in “Using Makefiles to Generate and Build Software”
on page 36-18.
The XMakefile feature lets you choose the configuration of a specific software build
tool chain to use during the automated build process. The configuration contains paths
and settings for your make utility, compiler, linker, archiver, pre-build, post-build, and
execute tools.
You can choose one built-in configuration described in “Supported Tool Chains in
Embedded Coder” on page 36-16 and “Available XMakefile Configurations” on page
36-16.
You can also create a new configuration for a new tool chain, as described in “Creating a
New XMakefile Configuration” on page 36-21.
Your requirements for specific features may determine whether you choose makefiles or
IDE projects. See “Feature Support” on page 36-18.
36-15
36 Project and Build Configurations for Embedded Targets
Embedded Coder includes support for the following IDEs and tool chains.
Simulink Coder includes support for other IDEs and tool chains. See .
The following list describes the configurations in the XMakefile dialog that this product
supports:
36-16
Makefiles for Software Build Tool Chains
36-17
36 Project and Build Configurations for Embedded Targets
For more information about supported versions of third-party software, see “Support for
Third Party Products” on page 36-13
Feature Support
With makefiles, you cannot use features that rely on direct communications between
your MathWorks software and third-party IDEs.
Update your model Configuration Parameters to use a makefile instead of an IDE when
you build software from the model:
1 Configure your model for your IDE, tool chain, and target hardware, as described in
“Configure Target Hardware Resources” on page 36-3.
2 In the Configuration Parameters dialog, under the Code Generation tab, select
Coder Target.
3 Set Build format to Makefile. For more information, see “Build format” on page
36-7.
4 Set Build action to Build_and_execute. For more information, see “Build action”
on page 36-8.
36-18
Makefiles for Software Build Tool Chains
2 Set the Template parameter to the option that matches the Configuration
parameter.
Note: In most cases, the only option for Template is gmake. However, if you have
installed a Support Package, Template can have multiple options.
3 For Configuration, select the option that describes your software build toolchain
and target platform. Click Apply.
Note: Changing some elements of the XMakefile dialog disables other elements until you
apply the changes. Click Apply or OK after changing:
• Template
• Configurations
• User Templates
• User Configurations
36-19
36 Project and Build Configurations for Embedded Targets
• Tool Directories
Note: With the XMakefile User Configuration dialog, if you have an Embedded Coder
license and do not have a Simulink Coder license, the Configuration list includes two
unsupported options: gcc_target or msvs_host. Disregard those two configurations.
Choose one of the other configurations.
This action creates a makefile and performs the other actions you specified in Build
action.
36-20
Makefiles for Software Build Tool Chains
Use mapped network drives instead of UNC paths to specify directory locations.
Using UNC paths with compilers that do not support them causes build errors.
Overview
This example shows you how to add support for a software development toolchain to the
XMakefile utility. This example uses the Intel Compiler and an IDE.
Note: To specify directory locations, use mapped network drives instead of UNC paths.
UNC paths cause build errors with compilers that do not support them.
Create a Configuration
When you click New, the new configuration inherits values and behavior from
the current configuration. To create a configuration for the Intel Compiler, clone a
configuration from one of these configurations: montavista_arm and gcc_target.
36-21
36 Project and Build Configurations for Embedded Targets
A pop-up dialog prompts you for the name of the new configuration. Enter
intel_compiler and click OK.
The dialog displays a new configuration called intel_compiler, based on the previous
configuration.
36-22
Makefiles for Software Build Tool Chains
Adjust the compiler, linker, and archiver settings of the newly created configuration.
This example assumes the location of the Intel compiler is C:\Program Files\Intel
\Compiler\.
Make Utility
You do not need to make changes. This configuration uses the gmake tool that ships with
MATLAB.
Compiler
36-23
36 Project and Build Configurations for Embedded Targets
Linker
Archiver
For Archiver, enter the location of the archiver, xilib.exe. Confirm that File
extensions for library files includes .lib.
36-24
Makefiles for Software Build Tool Chains
Other tabs
For this example, ignore the remaining tabs. In other circumstances, you can use them to
configure additional build actions. In a later step of this example, you will configure the
software to automatically build and run the generated code.
36-25
36 Project and Build Configurations for Embedded Targets
Configure the summdiff model for use with an IDE. Follow the steps in “Configure
Target Hardware Resources” on page 36-3, set the IDE/Tool Chain parameter, set
Board to Custom, and Processor to Intel x86/Pentium.
On the Tool Chain Automation page, set Operating System to None or select Windows.
Click OK.
Open the Configuration Parameters for the summdiff model by pressing Ctrl+E. Set
Build format to Makefile and Build action to Build_and_execute.
Build the model by pressing Ctrl+B. The MATLAB Command Window displays
something like:
### TLC code generation complete.
### Creating HTML report file sumdiff_codegen_rpt.html
### Creating project: c:\temp\IntelTest\sumdiff_idenameide\sumdiff.mk
### Project creation done.
### Building project...
### Build done.
### Downloading program: c:\temp\IntelTest\sumdiff_idenameide\sumdiff
### Download done.
36-26
Makefiles for Software Build Tool Chains
A command window comes up showing the running model. Terminate the generated
executable by pressing Ctrl+C.
Active
Template
Set the Template parameter to the option that matches the Configuration parameter.
Note: In most cases, the only option for Template is gmake. However, if you have
installed a Support Package, Template can have multiple options.
36-27
36 Project and Build Configurations for Embedded Targets
The template defines the syntax rules for writing the contents of the makefile or
buildfile. The default template is gmake, which works with the GNU make utility.
To add templates to this parameter, save them as .mkt files to the location specified by
the User Templates parameter. For more information, see “User Templates” on page
36-29.
Configuration
Select the configuration that best describes your toolchain and target hardware.
You cannot edit or delete the configurations provided by MathWorks. You can, however,
edit and delete the configurations that you create.
Use the New button to create an editable copy of the currently selected configuration.
Note: Use mapped network drives instead of UNC paths to specify directory locations.
Using UNC paths with compilers that do not support them causes build errors.
When you open the XMakefile User Configuration dialog, the software verifies that each
configuration provided by MathWorks contains valid paths to the executable files it uses.
If the paths are valid, the configuration is operational. If the paths are not valid, the
configuration is not operational.
36-28
Makefiles for Software Build Tool Chains
User Templates
Set the path of the folder to which you can add template files. Saving templates files with
the .mkt extension to this folder adds them to the Templates options.
User Configurations
Set the location of configuration files you create with the New button.
Make Utility
Make utility
Define the command-line arguments to pass to the make utility. For more information,
consult the third-party documentation for your make utility.
Optional include
Compiler
Compiler
36-29
36 Project and Build Configurations for Embedded Targets
Arguments
Define the command-line arguments to pass to the compiler. For more information,
consult the third-party documentation for your compiler.
Source
Define the file name extension for the source files. Use commas to separate multiple file
extensions.
Header
Define the file name extension for the header files. Use commas to separate multiple file
extensions.
Object
Linker
Linker
Define the command-line arguments to pass to the linker. For more information, consult
the third-party documentation for your linker.
File extensions for library files
Define the file name extension for the file library files. Use commas to separate multiple
file extensions.
Generated output file extension
Define the file name extension for the generated libraries or executables.
36-30
Makefiles for Software Build Tool Chains
Archiver
Archiver
Define the command-line arguments to pass to the archiver. For more information,
consult the third-party documentation for your archiver.
Generated output file extension
Pre-build
Select this check box to define a prebuild tool that runs before the compiler.
Prebuild tool
Set the path and file name of the prebuild tool executable.
Arguments
Define the command-line arguments to pass to the prebuild tool. For more information,
consult the third-party documentation for your prebuild tool.
36-31
36 Project and Build Configurations for Embedded Targets
Post-build
Select this check box to define a postbuild tool that runs after the compiler or linker.
Postbuild tool
Set the path and file name of the postbuild tool executable.
Arguments
Define the command-line arguments to pass to the postbuild tool. For more information,
consult the third-party documentation for your postbuild tool.
Execute
Select this check box to use the generated derivative as the execute tool when the build
process is complete. Uncheck it to specify a different tool. The default value, echo, simply
displays a message that the build process is complete.
Note: On the Linux operating system, multirate multitasking executables require root
privileges to schedule POSIX threads with real-time priority. If you are using makefiles
to build multirate multitasking executables on your Linux development system, you
36-32
Makefiles for Software Build Tool Chains
cannot use Execute tool to run the executable. Instead, use the Linux command, sudo,
to run the executable.
Execute tool
Set the path and file name of the execute tool executable or built-in command.
Arguments
Define the command-line arguments to pass to the execute tool. For more information,
consult the third-party documentation for your execute tool.
Tool Directories
Installation
Use the Tool Directories tab to change the toolchain path of an operational configuration.
For example, if you installed two versions of a vendor build tool in separate folders, you
can use the Installation path to change which one the configuration uses.
36-33
36-34
37
Overview
Verification consists broadly of running generated code on a processor and verifying that
the code does what you intend. Embedded Coder provides processor-in-the-loop (PIL)
simulation to meet this need. PIL compares the numeric output of your model under
simulation with the numeric output of your model running as an executable on a target
hardware.
With PIL, you run your generated code on a target hardware or instruction set simulator.
To verify your generated code, you compare the output of model simulation modes,
such as Normal or Accelerator, with the output of the generated code running on the
processor. You can switch between simulation and PIL modes. This flexibility allows
you to verify the generated code by executing the model as compiled code in the target
environment. You can model and test your embedded software component in Simulink
and then reuse your regression test suites across simulation and compiled object code.
This process avoids the time-consuming process of leaving the Simulink software
environment to run tests again on object code compiled for the production hardware.
When you use makefiles with PIL, use the “model block PIL” approach. With makefiles,
the other two approaches, “top-model PIL” and “PIL block”, and are not supported.
37-2
PIL Simulation for IDE and Toolchain Targets
PIL Approaches
• “Model Block PIL” on page 37-3
• “Top-Model PIL” on page 37-4
• “PIL Block” on page 37-5
• Verify code generated for referenced models (model reference code interface).
• Provide a test harness model (or a system model) to generate test vector or stimulus
inputs.
• Switch a model block between normal, SIL, or PIL simulation modes.
To perform a model block PIL simulation, start with a top-model that contains a model
block. The top-model serves as a test harness, providing inputs and outputs for the model
block. The model block references the model you plan to run on target hardware. During
PIL simulation, the referenced model runs on the target hardware.
For more information about using the model block, see “Model Variants” and “Model
Reference”.
By default, your MathWorks software uses the IDE debugger for PIL communications
with the target hardware. To achieve faster communications, consider using one of the
alternatives presented in “Communications” on page 37-7.
1 Create and share a configuration reference between the top model and the referenced
model, as described in “Share a Configuration for Multiple Models”.
2 Right-click the Model block, and select ModelReference Parameters.
3 When the software displays the Function Block Parameters: Model dialog box,
set Simulation mode to Processor-in-the-loop (PIL) and click OK.
4 Open the model block.
5 In the referenced model (model block) Configuration Parameters (Ctrl+E), under
Code Generation > Coder Target, set Build action set to Archive_library.
This action avoids a warning when you start the simulation.
6 Save the changes to both models.
37-3
37 Verification and Profiling Generated Code
7 In the top-model menu bar, select Simulation > Run. This action builds the
referenced model in the model block, downloads it to your target hardware, and runs
the PIL simulation.
Note: In the top-model Configuration Parameters (Ctrl+E), under Code Generation >
Coder Target, leave Build action set to Build_and_execute. Do not change Build
action to Create_Processor_In_the_Loop_Project.
Top-Model PIL
Configure your model to generate the PIL executable from your model:
37-4
PIL Simulation for IDE and Toolchain Targets
A new Simulink Editor opens with the new PIL model block in it. The third-party
IDE compiles and links the PIL executable file. Follow the progress of the build
process in the MATLAB Command Window.
PIL Block
• Verify code generated for a top-model (standalone code interface) or subsystem (right-
click build standalone code interface).
• Represent a component running in SIL or PIL mode. The test harness model or a
system model provides test vector or stimulus inputs.
Preparing Your Model to Generate a PIL Block
Start with a model that contains the algorithm blocks you want to verify on the processor
as compiled object code. To create a PIL application and PIL block from your algorithm
subsystem, follow these steps:
For information about how to convert your process to a subsystem, refer to “Creating
Subsystems” in Using Simulink or in the online Help system.
3 Open the newly created subsystem.
4 Configure your subsystem to run on target hardware, as described in “Configure
Target Hardware Resources” on page 36-3.
37-5
37 Verification and Profiling Generated Code
After you create your subsystem, set the Configuration Parameters for your model to
enable the model to generate a PIL block.
Configure your model to enable it to generate PIL algorithm code and a PIL block from
your subsystem:
1 From the model menu bar, select Simulation > Model Configuration
Parameters. This action opens the Configuration Parameters dialog box.
2 In the Configuration Parameters dialog box, select Code Generation.
3 Set System Target File to idelink_ert.tlc.
4 From the list of panes under Code Generation, choose Coder Target.
5 Set Build format to Project.
6 Set Build action to Create_processor_in_the_loop_project.
7 Click OK to close the Configuration Parameters dialog box.
1 Right-click the masked subsystem in your model and select C/C++ Code > Build
This Subsystem from the context menu.
A new Simulink Editor opens and the new PIL block appears in it. The third-party
IDE compiles and links the PIL executable file.
This step builds the PIL algorithm object code and a PIL block that corresponds to
the subsystem, with the same inputs and outputs. Follow the progress of the build
process in the MATLAB Command Window.
2 Copy the new PIL block from the new model to your model. To simulate the
subsystem processes concurrently, place it parallel to your masked subsystem.
Otherwise, replace the subsystem with the PIL block.
To see a PIL block in a parallel masked subsystem, search the product help for
Getting Started with Application Development and select the example that matches
your IDE.
37-6
PIL Simulation for IDE and Toolchain Targets
Note: Models can have multiple PIL blocks for different subsystems. They cannot have
more than one PIL block for the same subsystem. Including multiple PIL blocks for the
same subsystem causes errors and inaccurate results.
Communications
• “TCP/IP” on page 37-8
• “Additional Steps for TI C6000 Processors” on page 37-9
• “Serial Communication Interface (SCI) for Texas Instruments C2000” on page
37-9
• “IDE Debugger” on page 37-11
Choose one of the following communication methods for transferring code and data
during PIL simulations:
37-7
37 Verification and Profiling Generated Code
TCP/IP
You can use TCP/IP for PIL communications with target hardware running:
• Linux
• Texas Instruments DSP/BIOS
• Wind River VxWorks
Using TCP/IP for PIL communications is typically faster than using a debugger,
particularly for large data sets, such as with video and audio applications.
It also works well when you build an application on a remote Linux target using the
remoteBuild function.
• Top-model PIL
• Model block PIL
1 Set up a PIL simulation according to the PIL approach you have chosen.
2 In the MATLAB Command Window, use setpref to specify the IP address of the
PIL server (servername).
If you are running the PIL server on a remote target, specify the IP address of the
target hardware. For example:
setpref('MathWorks_Embedded_IDE_Link_PIL_Preferences','servername','144.212.109.114');
If you are running PIL server locally, on your host Windows or Linux system, enter
'localhost' instead of an IP address:
37-8
PIL Simulation for IDE and Toolchain Targets
setpref('MathWorks_Embedded_IDE_Link_PIL_Preferences','servername','localhost');
3 Specify the TCP/IP port number to use for PIL data communication. Use one of the
free ports in your system. For example:
setpref('MathWorks_Embedded_IDE_Link_PIL_Preferences','portnum', 17025);
To disable PIL communications over TCP/IP, change the value to false. This action
automatically enables PIL communications over an IDE debugger, if an IDE is
available.
5 Open the Configuration Parameters in your model. On the Coder Target pane, set
the Operating System parameter to the operating system your target hardware is
running.
Note: You cannot use TCP/IP for PIL when the value of Operating System is None.
6 Regenerate the code or PIL block.
To determine the IP address assigned to the PIL server on the C6000 target:
1 Enter an arbitrary IP address the first time you specify the IP address.
2 Build and run the code for your model.
3 In the CCS command window, observe the actual IP address assigned to the C6000
processor by the DHCP server.
4 Enter the actual IP address the second time you specify the IP address.
37-9
37 Verification and Profiling Generated Code
You can use SCI for processor-in-the-loop (PIL) simulations with Texas Instruments
C2000 processors that support Serial Communications Interface (SCI). For other targets,
configure PIL to communicate through TCP/IP or an IDE debugger.
SCI typically provides faster communications than an IDE debugger, particularly for
large data sets.
1 Set up a PIL simulation according to the PIL approach you have chosen. For more
information, see “PIL Approaches” on page 37-3.
2 In the MATLAB Command Window, use setpref to specify the Configuration
Parameters:
a Select the SCI port on your host computer for communicating with the target
hardware. For example, to use COM1, enter the following command:
setpref('MathWorks_Embedded_IDE_Link_PIL_Preferences', 'COMPort','COM1');
b Set the baud rate of the SCI port. For example, if both the host computer and
the target support 11,5200 baud, enter:
setpref('MathWorks_Embedded_IDE_Link_PIL_Preferences','BaudRate', 115200);
3 Configure the serial communications settings on your host computer to match the
preceding values. For example, in Windows 7:
a Open the Windows Device Manager. (Press the Windows key on your keyboard
and search for “Device Manager”.)
b Expand Ports (COM & LPT1).
c Right-click the communications port you previously specified in MATLAB, such
as Communications Port (COM1), and select Properties.
d Go to the Port Settings tab, and match the value of Bits per second with the
baud rate you previously specified in MATLAB. This value should match the
baud rate you set in MATLAB. For example, 'BaudRate',115200.
4 Regenerate the code or PIL block.
Note: In serial PIL simulation, the changes that you make to the BaudRate or
COMPort parameters in MathWorks_Embedded_IDE_Link_PIL_Preferences are not
detected, if the following conditions are met:
37-10
PIL Simulation for IDE and Toolchain Targets
To apply your COM port or baudrate changes, either change the value in the
Configuration Parameters >Model Referencing >Rebuild option to Always, or
resave the model to force a new build of the PIL application.
Note: If you change the following parameters while using TCP/IP or serial
communication for PIL, the software does not regenerate the PIL and communication
code.
To work around this issue, remove the slprj folder, generated code, and the generated
MEX file. Then, regenerate the PIL code.
See “Performing a Model Block PIL Simulation via SCI Using Makefiles” on page
37-13
IDE Debugger
To enable PIL communications over an IDE debugger, disable PIL communications over
TCP/IP and SCI by entering the following commands:
setpref('MathWorks_Embedded_IDE_Link_PIL_Preferences','enabletcpip',false);
setpref('MathWorks_Embedded_IDE_Link_PIL_Preferences','enableserial',false);
Using IDE debugger for PIL communication only works when you build your code from
IDE projects. Using IDE debugger for PIL communication does not work with builds from
makefiles.
37-11
37 Verification and Profiling Generated Code
Configuring Breakpoints
You can enter the following static API method to pause after loading the application and
manually configure breakpoints:
rtw.connectivity.Launcher.setStartApplicationPause(pauseAmount)
• This method tells the MATLAB session to pause immediately after the PIL launcher
starts the PIL application.
• pauseAmount is a pause time in seconds. To disable the pause, enter 0.
When you do not specify a pause, the software displays the following message:
### To pause during PIL application start, run: >> rtw.connectivity.Launcher.
setStartApplicationPause(120)
The default pause is 120 sec. You can change this value.
When you specify a pause, a Start PIL Application Pause message box appears and
displays following message:
Pausing during PIL application start for 120s (click OK to continue).
To disable this pause, see the hyperlink in the MATLAB command window.
37-12
PIL Simulation for IDE and Toolchain Targets
Note The pause command is to make sure that the automatic download of PIL completes,
before the model starts executing.
Prerequisites
Follow the board vendor’s instructions for setting up a Texas Instruments C2000-based
board that supports SCI. Connect the board to your host computer using a serial cable.
1 Enter fuelsys_pil in MATLAB. This action opens the fuelsys_pil model with the
title, “Verifying the Fixed-Point Fuel Control System”.
2 Configure fuelsys_pil. Follow the steps in “Configure Target Hardware
Resources” on page 36-3 setting:
37-13
37 Verification and Profiling Generated Code
If you are working with CCSv4/5, you do not need to configure the model to use
makefiles. Initializing the configuration parameters for CCSv4/5 automatically sets
Build format to Makefile.
1 In the fuelsys_pil, copy the fuelsys_ctr model and paste it into the vacant space
below. Connect it to the input/output signals provided.
37-14
PIL Simulation for IDE and Toolchain Targets
8 In the Code Generation > Interface pane, clear the Software environment
absolute time check box.
9 In the Code Generation > Coder Target pane, set the Run time Build action
parameter to Archive library.
10 Save the changes to your model, and leave the model open.
11 Open the top model, fuelsys_pil. Open the Configuration Parameters dialog box, in
the Solver pane, verify that the Type parameter is set to Fixed-step, and reset
Solver to ode3 (Bogacki-Shampine).
Note: For information other PIL approaches, see “PIL Approaches” on page 37-3.
2 Configure the serial communications settings on your host computer to match the
preceding values. For example, in Windows 7:
a Open the Windows Device Manager. (Press the Windows key on your keyboard
and search for “Device Manager”.)
b Expand Ports (COM & LPT1).
37-15
37 Verification and Profiling Generated Code
Set up the xmakefile for CCSv4/5 as described in the section “Using Makefiles with Code
Composer Studio 4/5”.
1 Make sure the SD F28335 eZdsp board is connected to your host computer via serial
and USB cables and powered up.
2 Add the required pause in seconds, using the following command in the MATLAB
command prompt:
Definitions
PIL Algorithm
PIL Application
The executable application that runs on the processor platform. Your coder product
creates a PIL application by augmenting your algorithmic code with the PIL execution
framework. The PIL execution framework code compiles as part of your embedded
application.
The PIL execution framework code includes the string.h header file so that the PIL
application can use the memcpy function. The PIL application uses memcpy to exchange
data between the Simulink model and the simulation processor.
37-16
PIL Simulation for IDE and Toolchain Targets
PIL Block
When you build a subsystem from a model for PIL, the process creates a PIL block
optimized for PIL simulation. When you run the simulation, the PIL block acts as the
interface between the model and the PIL application running on the processor. The PIL
block inherits the signal names and shape from the source subsystem in your model.
Inheritance is convenient for copying the PIL block into the model to replace the original
subsystem for simulation.
Constraints
When using PIL in your models, keep in mind the following constraints:
• Models can have multiple PIL blocks for different subsystems. They cannot have more
than one PIL block for the same subsystem. Including multiple PIL blocks for the
same subsystem causes errors and inaccurate results.
• A model can contain a single model block running PIL mode.
• A model can contain a subsystem PIL block or a model block in PIL mode, but not
both.
Refer to “PIL Feature Support and Limitations” for general information about using the
PIL block with embedded link products.
With Texas Instruments CCS, PIL with DSP/BIOS Enabled Does Not Support System Stack
Profiling
Enabling DSP/BIOS for Texas Instruments processors disables the stack profiling option.
To use stack profiling with PIL, open the Target Hardware Resources pane in model
Configuration Parameters, and set the Operating System parameter to None. For
help opening the Target Hardware Resources pane, see “Configure Target Hardware
Resources” on page 36-3.
37-17
37 Verification and Profiling Generated Code
To use PIL, set System target file in the Configuration Parameters > Code Generation
pane to idelink_ert.tlc.
37-18
Code Execution Profiling for IDE and Toolchain Targets
You can use this profiling for generated code in the following cases:
• Code Generation > System target file is ert.tlc and Code Generation >
Target hardware is not None, for example, ARM Cortex-A9 (QEMU) or ARM
Cortex-M3 (QEMU).
• Code Generation > System target file is idelink_ert.tlc
Stack Profiling
With stack profiling, you can determine how generated code uses the processor system
stack. Using the profile method, you can initialize and test the size and usage of the
37-19
37 Verification and Profiling Generated Code
stack. See “Perform Stack Profiling with IDE and Toolchain Targets” on page 37-27.
This information can help you optimize both the size of the stack and how your code uses
the stack.
You can use this profiling for generated code in the following cases:
• Code Generation > System target file is ert.tlc and Code Generation >
Target hardware is not None, for example, ARM Cortex–A9 (QEMU) or ARM
Cortex–M3 (QEMU).
• Code Generation > System target file is idelink_ert.tlc
Note: Stack profiling is not supported on embedded targets that run an operating system
or RTOS.
To provide stack profiling, profile writes a known pattern to the addresses in the
stack. After you run your application for a while, and then stop your application,
profile examines the contents of the stack addresses. profile counts each address
that does not contain the known pattern. The total number of addresses that have been
used, compared to the total number of addresses that you allocated, becomes the stack
usage profile. This profile process does not determine how often your application changes
an address.
You can profile the stack with the manually written code in a project and the code that
you generate from a model.
When you use profile to initialize and test the stack operation, the software returns
a report that contains information about stack size, usage, addresses, and direction.
With this information, you can modify your code to use the stack efficiently. The
following program listing shows the stack usage results from running an application on a
simulator.
profile(IDE_Obj,'stack','report')
37-20
Code Execution Profiling for IDE and Toolchain Targets
endAddress: [1535 0]
stackSize: 1024 MAUs
growthDirection: ascending
The following table describes the entries in the report.
37-21
37 Verification and Profiling Generated Code
In this section...
“Execution Profiling During Standalone Execution” on page 37-22
“Execution Profiling During PIL Simulation” on page 37-25
You can perform profiling by task or subsystem. A profiling sample represents a task or
subsystem execution instance. Each sample requires two memory locations, one for the
start time and one for the end time. Therefore, you must specify a buffer size that is twice
the number of required profiling samples. Sample collection begins with the start of code
execution and ends when the buffer is full.
Task Profiling
37-22
Perform Execution Time Profiling for IDE and Toolchain Targets
Click Build Model on the model toolstrip. This action builds, loads,
and runs your code on the processor.
2 To stop the running program, select Debug > Halt in the IDE or use IDE_obj.halt
from the MATLAB command line. Gathering profiling data from a running program
can yield inaccurate results.
3 At the MATLAB command prompt, enter
profile(IDE_Obj,'execution','report')
to view the MATLAB software graphic of the execution report and the HTML
execution report.
For more information about other reporting options, see the product help for the
profile function.
The following profiling plot is from an application that runs with three rates — the
base rate and two slower rates. Gaps in the Sub-Rate 2 task bars indicate preempted
operations.
Subsystem Profiling
To configure a model for subsystem execution profiling:
1 Configure your model for your IDE, tool chain, and target hardware, as described in
“Configure Target Hardware Resources” on page 36-3.
37-23
37 Verification and Profiling Generated Code
2 On the Coder Target pane, set Build format to Project and set Build action to
Build_and_execute.
3 Select Profile real-time execution.
4 In the Profile by list, select Atomic subsystems.
5 Specify Number of profiling samples to collect, the size of the buffer that stores
execution data. Enter a value that is twice the number of profiling samples you
require.
6 Click OK.
Click Build Model on the model toolstrip. This action builds, loads,
and runs your code on the processor.
2 To stop the running program, select Debug > Halt in the IDE or use
IDE_obj.halt from the MATLAB command line. Gathering profiling data from a
running program can yield inaccurate results.
3 At the MATLAB command prompt, enter:
profile(IDE_Obj, 'execution','report')
to view the MATLAB software graphic of the execution report and the HTML
execution report.
The following profiling plot is from an application with three subsystems — For
Iterator Subsystem, For Iterator Subsystem1, and Idle Task Subsystem.
37-24
Perform Execution Time Profiling for IDE and Toolchain Targets
1 Configure a model for PIL simulation, as described in “PIL Simulation for IDE and
Toolchain Targets” on page 37-2.
2 In your model, select Simulation > Model Configuration Parameters.
3 In the Configuration Parameters dialog box, select Code Generation, and then
Verification.
4 Select the Measure task execution time check box.
5 Provide a valid MATLAB variable name in the Workspace edit box. The software
uses this name when it creates the coder.profile.ExecutionTime object.
6 Click OK to close the Configuration Parameters dialog box.
37-25
37 Verification and Profiling Generated Code
7 Run the PIL simulation, as described in “PIL Simulation for IDE and Toolchain
Targets” on page 37-2.
After halting the PIL simulation, you can view or analyze the data in the
coder.profile.ExecutionTime object. For more information, see:
Depending on the target, the execution profile data is measured in seconds or timer ticks.
Targets Units
Texas Instruments C2000, C5000, and C6000 processors with Code Seconds
Composer Studio IDE
Texas Instruments C6000 processors running DSP/BIOS with Code Timer Ticks
Composer Studio IDE
Analog Devices Blackfin, SHARC, and TigerSHARC processors Timer Ticks
with VisualDSP++ IDE
ARM processors running Wind River VxWorks Timer Ticks
37-26
Perform Stack Profiling with IDE and Toolchain Targets
1 Load an application.
2 Set up the stack to enable profiling.
3 Run your application.
4 Request the stack profile information.
Follow these steps to profile the stack as your application interacts with it. This
particular example uses Texas Instruments Code Composer Studio 3.3. However, you can
generalize from this example to another supported IDE.
The following example shows how to set up and profile the stack. The IDE link handle
object, IDE_Obj, must exist in your MATLAB workspace and your application must be
loaded on your processor. This example comes from a TI C6713 simulator.
profile(IDE_Obj,'stack','setup') % Set up processor stack
%by write A5 to the stack addresses.
37-27
37 Verification and Profiling Generated Code
growthDirection: ascending
run(IDE_Obj)
halt(IDE_Obj)
profile(IDE_Obj,'stack','report') % Request stack use report.
37-28
38
For more information about replacing code, using code replacement libraries that
MathWorks provides, see “What Is Code Replacement?” and “Replace Code Generated
from Simulink Models”. For information about developing code replacement libraries, see
“What Is Code Replacement Customization?” and “Develop a Code Replacement Library”.
Use the following process to evaluate the effects of applying a processor-specific code
replacement library when you generate code:
38-2
Replace Code for Embedded Targets
6 Compare the profile report from running your application with the processor-specific
library selected to the profile results in the first report with no code replacement
library selected.
For an example of verifying the code optimization, search help for "Optimizing Embedded
Code via Code Replacement Library" and select the example that matches your IDE.
38-3
38-4
39
Set Up
Before you use Embedded Coder with Code Composer Studio (CCS IDE) for the
first time, use the checkEnvSetup function to check for third-party tools and set
environment variables. Run checkEnvSetup again whenever you configure CCS IDE to
interact with a new board or processor, or upgrade the related third-party tools.
To verify that CCSv3 is installed on your machine and has at least one board configured,
enter
ccsboardinfo
in the MATLAB Command Window. With CCS installed and configured, MATLAB
software returns information about the boards that CCS recognizes on your machine, in a
form similar to the following listing.
Board Board Proc Processor Processor
Num Name Num Name Type
--- -------------------------------- --- -------------
1 C6xxx Simulator (Texas Instrum .0 6701 TMS320C6701
0 C6x13 DSK (Texas Instruments) 0 CPU TMS320C6x1x
If MATLAB software does not return information about the boards, open your CCS
installation and use the Setup Utility in CCS to configure at least one board.
As a final test, start CCS to verify that it runs. For Embedded Coder to operate with
CCS, the CCS IDE must be able to run on its own.
39-2
Code Composer Studio
In this section...
“Using Code Composer Studio with Embedded Coder Software” on page 39-3
“Default Project Configuration” on page 39-3
Executing code generated from Simulink Coder software on a particular target requires
that you tailor the code to the specific hardware target. Target-specific code includes
I/O device drivers and interrupt service routines (ISRs). The software must use CCS
to compile and link the generated source code in order to load and execute on a TI
DSP. To help you to build an executable, Embedded Coder software uses Embedded
Coder software to start the code building process within CCS. After you download your
executable to your target and run it, the code runs wholly on the target hardware. You
can access the running process only from the CCS debugging tools or across a link using
Embedded Coder software. A wide range of Texas Instruments DSPs are supported:
• TI’s C2000™
• TI’s C5000™
• TI’s C6000
39-3
39 Working with Texas Instruments Code Composer Studio 3.3 IDE
The default settings for CustomMW are the same as the Release project configuration in
CCS, except for the compiler options.
Your CCS documentation provides complete details on the compiler build options. You
can change the individual settings or the build configuration within CCS.
39-4
Getting Started
Getting Started
In this section...
“Overview” on page 39-5
“Verifying Your Code Composer Studio Installation” on page 39-8
Overview
• “IDE Automation Interface” on page 39-6
• “IDE Project Generator” on page 39-7
• “Verification” on page 39-7
Embedded Coder software enables you to use MATLAB functions to communicate with
Code Composer Studio software and with information stored in memory and registers
on a processor. With the ticcs objects, you can transfer information to and from Code
Composer Studio software and with the embedded objects you get information about
data and functions stored in your signal processor memory and registers, as well as
information about functions in your project.
Embedded Coder lets you build, test, and verify automatically generated code using
MATLAB, Simulink, Simulink Coder, and the Code Composer Studio integrated
development environment. You can use Embedded Coder to verify code executing within
the Code Composer Studio software environment using a model in Simulink software.
This processor-in-the-loop testing environment uses code automatically generated from
Simulink models by Embedded Coder software. A range of Texas Instruments targets are
supported:
• TI’s C2000
• TI’s C5000
• TI’s C6000
With Embedded Coder , you can use MATLAB software and Simulink software to
interactively analyze, profile and debug processor-specific code execution behavior within
CCS. In this way, Embedded Coder automates deployment of the complete embedded
software application and makes it easy for you to assess possible differences between the
model simulation and processor code execution results.
39-5
39 Working with Texas Instruments Code Composer Studio 3.3 IDE
• IDE Project Generator—add embedded framework code to the C code generated from
Simulink models, and package as a complete IDE project
• IDE Automation Interface—use functions in the MATLAB command window to access
and manipulate data and files in the IDE and on the processor
• Verification—verify how your programs run on your processor
With Embedded Coder, you create objects that connect MATLAB software to Code
Composer Studio software.
Note Embedded Coder uses objects. You work with them the way you use other MATLAB
objects. You can set and get their properties, and use their methods to change them or
manipulate them and the IDE to which they refer.
The next sections describe briefly the components of Embedded Coder software.
The IDE Automation Interface component is a collection of methods that use the Code
Composer Studio API to communicate between MATLAB software and Code Composer
Studio. With the interface, you can do the following:
The IDE Automation Interface provides an application program interface (API) between
MATLAB software and Code Composer Studio. Using the API, you can create new
39-6
Getting Started
projects, open projects, transfer data to and from memory on the processor, add files to
projects, and debug your code.
The IDE Project Generator component is a collection of methods that use the Code
Composer Studio API to create projects in Code Composer Studio and generate code with
Embedded Coder. With the interface, you can do the following:
Automatically create and build projects for code generated by Embedded Coder.
• Customize code generation
Use Embedded Coder with a Embedded Coder system target file (STF) to generate
processor-specific and optimized code.
• Customize the build process
• Automate code download and debugging
Rapidly and effortlessly debug generated code in the Code Composer Studio software
debugger, using either the instruction set simulator or real hardware.
• Create and build CCS projects from Simulink software models. IDE Project Generator
uses Simulink Coder software or Embedded Coder software to build projects that
work with C2000 software, C5000™ software, and C6000 software processors.
• Highly customized code generation with the system target file idelink_ert.tlc
and idelink_grt.tlc that enable you to use the Configuration Parameters in your
model to customize your generated code.
• Automate the process of building and downloading your code to the processor, and
running the process on your hardware.
Verification
39-7
39 Working with Texas Instruments Code Composer Studio 3.3 IDE
in the MATLAB Command Window. With CCS installed and configured, MATLAB
software returns information about the boards that CCS recognizes on your machine, in a
form similar to the following listing.
Board Board Proc Processor Processor
Num Name Num Name Type
--- -------------------------------- --- -------------
1 C6xxx Simulator (Texas Instrum .0 6701 TMS320C6701
0 C6x13 DSK (Texas Instruments) 0 CPU TMS320C6x1x
If MATLAB software does not return information about boards, open your CCS
installation and use the Setup Utility in CCS to configure at least one board.
As a final test, start CCS to verify that it runs. For Embedded Coder to operate with
CCS, the CCS IDE must be able to run on its own.
Concepts to know about the objects in this toolbox are covered in these sections:
Refer to MATLAB Classes and Objects in your MATLAB documentation for more details
on object-oriented programming in MATLAB software.
Many of the objects use COM server features to create handles for working with the
objects. Refer to your MATLAB documentation for more information about COM as used
by MATLAB software.
39-8
IDE Automation Interface
To use an interactive example that shows how to automate interaction between IDE
Link component and Texas Instruments Code Composer Studio V3.3 using MATLAB®
commands, see “Automation Interface Tutorial”.
Before using the functions available with the objects, you must select a processor because
objects you create are specific to a designated processor and a designated instance of
CCS IDE. For multiprocessor boards or multiple board configurations of CCS, select the
specific processor.
39-9
39 Working with Texas Instruments Code Composer Studio 3.3 IDE
When you have one board with a single processor, the object defaults to the existing
processor. For the objects, the simulator counts as a board; if you have both a board and a
simulator that CCS recognizes, you must specify the processor explicitly.
To get you started using objects for CCS software, Embedded Coder includes a tutorial
that introduces you to working with data and files. As you work through this tutorial,
you perform the following tasks that step you through creating and using objects for CCS
IDE:
The tutorial provides a working process (a workflow) for using Embedded Coder and
your signal processing programs to develop programs for a range of Texas Instruments
processors.
During this tutorial, you load and run a digital signal processing application on a
processor you select. The tutorial shows both writing to memory and reading from
memory in the ““Working with Projects and Data” on page 39-18” portion of the
tutorial.
You can use the read and write methods, as described in this tutorial, to read and write
data to and from your processor.
The tutorial covers the object methods and functions for Embedded Coder. The functions
listed in the first table apply to CCS IDE independent of the objects — you do not
need an object to use these functions. The methods listed in the second and third table
requires a ticcs object that you use in the method syntax:
Functions for Working With Embedded Coder
Function Description
ccsboardinfo Return information about the boards that CCS IDE
recognizes as installed on your PC.
39-10
IDE Automation Interface
Function Description
ticcs Construct an object to communicate with CCS
IDE. When you construct the object you specify the
processor board and processor.
The methods in the following table require a ticcs object as an input argument:
Method Description
add Add files to active project in IDE.
address Memory address and page value of symbol
in IDE.
build Build or rebuild current project.
“display (IDE Object)” Display the properties of an object to CCS
IDE and RTDX.
“halt” Terminate execution of a process running
on the processor.
“info” Return information about the processor or
information about open RTDX channels.
insert Insert debug point in file.
isrtdxcapable Test whether your processor supports
RTDX communications.
isvisible Determine whether IDE appears on
desktop.
“isrunning” Test whether the processor is executing a
process.
“list” Return various information listings from
Code Composer Studio software.
load Load program file onto processor.
“read” Retrieve data from memory on the
processor.
regread Read values from processor registers.
regwrite Write data values to registers on processor.
39-11
39 Working with Texas Instruments Code Composer Studio 3.3 IDE
Method Description
remove Remove file, project, or breakpoint.
“restart” Restore the program counter (PC) to the
entry point for the current program.
“run” Execute the program loaded on the
processor.
“visible” Set whether CCS IDE window is visible on
the desktop while CCS IDE is running.
“write” Write data to memory on the processor.
When you create a ticcs object , Embedded Coder starts CCS in the background.
When CCS IDE is running in the background, it does not appear on your desktop, in your
task bar, or on the Applications page in the Task Manager. It does appear as a process,
cc_app.exe, on the Processes tab in Microsoft Windows Task Manager.
You can make the CCS IDE visible with the function visible. The function isvisible
returns the status of the IDE—whether it is visible on your desktop. To close the IDE
when it is not visible and MATLAB software is not running, use the Processes tab in
Microsoft Windows Task Manager and look for cc_app.exe.
If a link to CCS IDE exists when you close CCS, the application does not close. Microsoft
Windows software moves it to the background (it becomes invisible). Only after you
clear links to CCS IDE, or close MATLAB software, does closing CCS IDE unload the
application. You can see if CCS IDE is running in the background by checking in the
Microsoft Windows Task Manager. When CCS IDE is running, the entry cc_app.exe
appears in the Image Name list on the Processes tab.
When you close MATLAB software while CCS IDE is not visible, MATLAB software
closes CCS if it started the IDE. This happens because the operating system treats
CCS as a subprocess in MATLAB software when CCS is not visible. Having MATLAB
software close the invisible IDE when you close MATLAB software prevents CCS from
remaining open. You do not need to close it using Microsoft Windows Task Manager.
If CCS IDE is not visible when you open MATLAB software, closing MATLAB software
leaves CCS IDE running in an invisible state. MATLAB software leaves CCS IDE in the
visibility and operating state in which it finds it.
39-12
IDE Automation Interface
Interactive Learning
You have the option of running this tutorial from the MATLAB Command Window or
entering the functions as described in the following tutorial sections.
To run the tutorial in MATLAB software, click run ccstutorial. This command
opens the tutorial in an interactive mode where the tutorial program provides prompts
and text descriptions to which you respond to move to the next portion of the lesson.
The interactive tutorial covers the same information provided by the following tutorial
sections. You can view the tutorial file by clicking ccstutorial.m.
Links for CCS IDE provides two tools for selecting a board and processor in
multiprocessor configurations. One is a command line tool called “ccsboardinfo” which
prints a list of the available boards and processors. So that you can use this function in a
script, ccsboardinfo can return a MATLAB software structure that you use when you
want your script to select a board without your help.
Note The board and processor you select is used throughout the tutorial.
1 To see a list of the boards and processors installed on your PC, enter the following
command at the MATLAB software prompt:
ccsboardinfo
MATLAB software returns a list that shows you the boards and processors that CCS
IDE recognizes as installed on your system.
2 To use the Selection Utility, boardprocsel, to select a board, enter
[boardnum,procnum] = boardprocsel
When you use boardprocsel, you see a dialog similar to the following. Note that
some entries vary depending on your board set.
39-13
39 Working with Texas Instruments Code Composer Studio 3.3 IDE
You are selecting a board and processor number that identifies your particular
processor. When you create the object for CCS IDE in the next section of this
tutorial, the selected board and processor become the processor of the object.
4 Click Done to accept your board and processor selection and close the dialog.
boardnum and procnum now represent the Board name and Processor name you
selected — boardnum = 1 and procnum = 0
In this tutorial section, you create the connection between MATLAB software and CCS
IDE. This connection, or object, is a MATLAB software object that you save as variable
IDE_Obj.
You use function ticcs to create objects. When you create objects, ticcs input
arguments let you define other object property values, such as the global timeout. Refer
to the ticcs reference documentation for more information on these input arguments.
Use the generated object IDE_Obj to direct actions to your processor. In the following
tasks, IDE_Obj appears in function syntax that interacts with CCS IDE and the
processor:
1 Create an object that refers to your selected board and processor. Enter the following
command at the prompt.
IDE_Obj=ticcs('boardnum',boardnum,'procnum',procnum)
39-14
IDE Automation Interface
If you were to watch closely, and your machine is not too fast, you see Code
Composer Studio software appear briefly when you call “ticcs”. If CCS IDE was not
running before you created the new object, CCS starts and runs in the background.
2 Enter visible(IDE_Obj,1) to force CCS IDE to be visible on your desktop.
Usually, you need to interact with Code Composer Studio software while you
develop your application. The first function in this tutorial, “visible”, controls the
state of CCS on your desktop. visible accepts Boolean inputs that make CCS
either visible on your desktop (input to visible = 1) or invisible on your desktop
(input to visible = 0). For this tutorial, use visible to set the CCS IDE visibility
to 1.
3 Next, enter display(IDE_Obj) at the prompt to see the status information.
TICCS Object:
Processor type : Cxx
Processor name : CPU
Running? : No
Board number : 0
Processor number : 0
Default timeout : 10.00 secs
RTDX channels : 0
Embedded Coder provides methods to read the status of a board and processor:
The IDE_Obj link status information provides information about the hardware as
follows:
linkinfo =
procname: 'CPU_1'
isbigendian: 0
isrtdxcapable: 0
family: 320
39-15
39 Working with Texas Instruments Code Composer Studio 3.3 IDE
subfamily: 103
revfamily: 11
targettype: 'simulator'
siliconrev: 0
timeout: 10
boardname: 'Cxxxx Device Simulator'
5 Check whether the processor is running by entering
runstatus = isrunning(IDE_Obj)
0
6 At last, verify that the processor supports RTDX communications by entering
usesrtdx = isrtdxcapable(IDE_Obj)
usesrtdx =
You have established the connection to a processor and board and have created and
queried objects. Next, the processor needs something to do.
In this part of the tutorial, you load the executable code for the processor CPU in CCS
IDE. Embedded Coder includes a CCS project file. Through the next tasks in the tutorial,
you locate the tutorial project file and load it into CCS IDE. The open method directs
CCS to load a project file or workspace file.
Note CCS has workspace and workspace files that are different from the MATLAB
workspace files and workspace. Remember to monitor both workspaces.
After you have executable code running on your processor, you can exchange data blocks
with it. Exchanging data is the purpose of the objects provided by Embedded Coder
software.
1 To load the project file to your processor, enter the following command at the
MATLAB software prompt. getdemoproject is a specialized function for loading
39-16
IDE Automation Interface
demopjt.ProjectFile
ans =
C:\Temp\EmbIDELinkCCDemos_v4.1\ccstutorial\cxx\cxxx\ccstut.pjt
demoPjt.DemoDir
ans =
C:\Temp\EmbIDELinkCCDemos_v4.1\ccstutorial\cxx\cxxx
Your paths may be different if you use a different processor. Note where the software
stored the example files on your machine. In general, Embedded Coder software
stores the example project files in
EmbIDELinkCCDemos_v#.#
Embedded Coder creates this folder in a location where you have write permission.
There are two locations where Embedded Coder software tries to create the example
folder, in the following order:
build(IDE_Obj,'all',20)
You may get an error related to one or more missing .lib files. If you installed CCS
IDE in a folder other than the default installation folder, browse in your installation
folder to find the missing file or files. Refer to the path in the error message as an
indicator of where to find the missing files.
3 Change your working folder to the example folder and enter
load(IDE_Obj,'projectname.out') to load the processor execution file, where
projectname is the tutorial you chose, such as ccstut_67x.
You have a loaded program file and associated symbol table to the IDE and
processor.
4 To determine the memory address of the global symbol ddat, enter the following
command at the prompt:
39-17
39 Working with Texas Instruments Code Composer Studio 3.3 IDE
ddata = address(IDE_Obj,'ddat')
ddata =
1.0e+009 *
2.1475 0
Note The symbol table is available after you load the program file into the processor,
not after you build a program file.
5 To convert ddata to a hexadecimal string that contains the memory address and
memory page, enter the following command at the prompt:
dec2hex(ddata)
MATLAB software displays the following response, where the memory page is
0x00000000 and the address is 0x80000010.
ans =
80000010
00000000
After you load the processor code, you can use Embedded Coder functions to examine and
modify data values in the processor.
When you look at the source file listing in the CCS IDE Project view window, there
should be a file named ccstut.c. Embedded Coder ships this file with the tutorial and
includes it in the project.
ccstut.c has two global data arrays — ddat and idat — that you declare and
initialize in the source code. You use the functions read and write to access these
processor memory arrays from MATLAB software.
Embedded Coder provides three functions to control processor execution — run, halt,
and restart.
39-18
IDE Automation Interface
1 To see these commands, use the following function to add a breakpoint to line 68 of
ccstut.c.
insert(IDE_Obj,'ccstut.c',68)
Line 68 is
printf("Embedded Coder: Tutorial - Memory Modified by Matlab!\n");
For information about adding breakpoints to a file, refer to insert in the online
Help system. Then proceed with the tutorial.
2 To see the new functions, try the following functions.
halt(IDE_Obj) % Halt the processor.
restart(IDE_Obj) % Reset the PC to start of program.
run(IDE_Obj,'runtohalt',30); % Wait for program execution to stop at
% breakpoint (timeout = 30 seconds).
When you switch to viewing CCS IDE, you see that your program stopped at the
breakpoint you inserted, and the program printed the following messages in the CCS
IDE Stdout tab. Nothing prints in the MATLAB command window:
C5xxx processor family — Enter the following functions to see the read and
write functions.
ddatv =
idatv =
39-19
39 Working with Texas Instruments Code Composer Studio 3.3 IDE
If you used 8-bit integers (int8), the returned values would be incorrect.
idatv=read(IDE_Obj,address(IDE_Obj,'idat'),'int8',4)
idatv =
1 0 -4 1
c You can change the values stored in ddat by entering
write(IDE_Obj,address(IDE_Obj,'ddat'),double([pi 12.3
exp(-1)...
sin(pi/4)]))
The double argument directs MATLAB software to write the values to the
processor as double-precision data.
d To change idat, enter
write(IDE_Obj,address(IDE_Obj,'idat'),int32([1:4]))
Here you write the data to the processor as 32-bit integers (convenient for
representing phone numbers, for example).
e Start the program running again by entering the following command:
run(IDE_Obj,'runtohalt',30);
The Stdout tab in CCS IDE reveals that ddat and idat contain new values.
Next, read those new values back into MATLAB software.
f Enter ddatv = read(IDE_Obj,address(IDE_Obj,'ddat'),'double',4).
ddatv =
idatv = read(IDE_Obj,address(IDE_Obj,'idat'),'int16',4)
39-20
IDE Automation Interface
idatv =
1 2 3 4
h Use restart to reset the program counter for your program to the beginning.
Enter the following command at the prompt:
restart(IDE_Obj);
C6xxx processor family — Enter the following commands to see the read and
write functions.
ddatv =
idatv =
If you used 8-bit integers (int8), the returned values would be incorrect.
idatv=read(IDE_Obj,address(IDE_Obj,'idat'),'int8',4)
idatv =
1 0 -4 1
c Change the values stored in ddat by entering
write(IDE_Obj,address(IDE_Obj,'ddat'),double([pi 12.3
exp(-1)...
sin(pi/4)]))
39-21
39 Working with Texas Instruments Code Composer Studio 3.3 IDE
The double argument directs MATLAB software to write the values to the
processor as double-precision data.
d To change idat, enter the following command:
write(IDE_Obj,address(IDE_Obj,'idat'),int32([1:4]))
In this command, you write the data to the processor as 32-bit integers
(convenient for representing phone numbers, for example).
e Next, start the program running again by entering the following command:
run(IDE_Obj,'runtohalt',30);
The Stdout tab in CCS IDE reveals that ddat and idat contain new values.
Read those new values back into MATLAB software.
f Enter ddatv = read(IDE_Obj,address(IDE_Obj,'ddat'),'double',4).
ddatv =
idatv = read(IDE_Obj,address(IDE_Obj,'idat'),'int32',4)
idatv =
1 2 3 4
h Use restart to reset the program counter for your program to the beginning.
Enter the following command at the prompt:
restart(IDE_Obj);
4 Embedded Coder offers more functions for reading and writing data to your
processor. These functions let you read and write data to the processor registers:
regread and regwrite. They let you change variable values on the processor in
real time. The functions behave slightly differently depending on your processor.
39-22
IDE Automation Interface
Select one of the following procedures to see regread and regwrite used with your
processor.
a To read the value stored in register PC, enter the following command at the
prompt to indicate to MATLAB software the data type to read. The input string
binary indicates that the PC register contains a value stored as an unsigned
binary integer.
IDE_Obj.regread('PC','binary')
ans =
33824
b To write a new value to the PC register, enter the following command. This
time, the binary input argument tells MATLAB software to write the value to
the processor as an unsigned binary integer. Notice that you used hex2dec to
convert the hexadecimal string to decimal.
IDE_Obj.regwrite('PC',hex2dec('100'),'binary')
c Verify that the PC register contains the value you wrote.
IDE_Obj.regread('PC','binary')
C6xxx processor family — regread and regwrite let you access the processor
registers directly. Enter the following commands to get data into and out of the A0
and B2 registers on your processor.
treg = IDE_Obj.regread('A0','2scomp');
39-23
39 Working with Texas Instruments Code Composer Studio 3.3 IDE
IDE_Obj.regread('B2','binary');
c Next, enter the following command to use regwrite to put the value in treg
into register A2.
IDE_Obj.regwrite('A2',treg,'2scomp');
CCS IDE reports that A0, B2, and A2 have the values you expect. Select View
> CPU Registers > Core Registers from the CCS IDE menu bar to list the
processor registers.
Objects that you create in Embedded Coder software have COM handles to CCS. Until
you delete these handles, the CCS process (cc_app.exe in the Microsoft Windows
Task Manager) remains in memory. Closing MATLAB software removes these COM
handles, but there may be times when you want to delete the handles without closing the
application.
Use clear to remove objects from your MATLAB workspace and to delete handles they
contain. clear all deletes everything in your workspace. To retain your MATLAB
software data while deleting objects and handles, use clear objname. This applies to
IDE link handle objects you created with ticcs. To remove the objects created during
the tutorial, the tutorial program executes the following command at the prompt:
clear cvar cfield uintcvar
This tutorial also closes the project in CCS with the following command:
close(IDE_Obj,projfile,'project')
39-24
IDE Automation Interface
3 Used MATLAB software to load files into CCS IDE, and used MATLAB software to
run that file.
4 Worked with your CCS IDE project from MATLAB software by reading and writing
data to your processor, and changing the data from MATLAB software.
5 Created and used the embedded objects to manipulate data in a C-like way.
6 Closed the links you opened to CCS IDE.
You can use RTDX with Embedded Coder software and Code Composer Studio to
accelerate development and deployment to Texas Instruments C2000 processors. RTDX
helps you test and analyze your processing algorithms in your MATLAB workspace.
RTDX lets you interact with your process in real time while it's running on the processor.
For example, you can:
Enabling real-time interaction lets you more easily see your process or algorithm in
action, the results as they develop, and the way the process runs.
This tutorial assumes you have Texas Instruments Code Composer Studio software and
at least one target development board. You can use the hardware simulator in CCS IDE
to run this tutorial.
39-25
39 Working with Texas Instruments Code Composer Studio 3.3 IDE
After you complete the tutorial, you can start using RTDX with your applications and
hardware.
Note: To use RTDX with the XDS100 USB JTAG Emulator and the C28027 chip, add the
following line to the linker command file:
_RTDX_interrupt_mask = ~0x000000008;
Using RTDX
Digital signal processing development efforts begin with an idea for processing data; an
application area, such as audio or wireless communications or multimedia computing;
and a platform or hardware to host the signal processing. Usually these processing
efforts involve applying strategies like signal filtering, compression, and transformation
to change data content; or isolate features in data; or transfer data from one form to
another or one place to another.
Developers create algorithms they need to accomplish the desired result. After they have
the algorithms, they use models and target hardware development tools to test their
algorithms, to determine whether the processing achieves the goal, and whether the
processing works on the proposed platform.
Embedded Coder and the links for RTDX and CCS IDE ease the job of taking algorithms
from the model realm to the real world of the processor on which the algorithm runs.
RTDX and links for CCS IDE provide a communications pathway to manipulate data
and processing programs on your processor. RTDX offers real-time data exchange in
two directions between MATLAB software and your processor process. Data you send
to the processor do little to alter running processes. Plotting data you retrieve from the
processor lets you see how your algorithms are performing in real time.
To introduce the techniques and tools available in Embedded Coder for using RTDX,
the following procedures use many of the methods in the link software to configure the
processor, open and enable channels, send data to the processor, and clean up after you
finish your testing. Among the functions covered are:
Functions From Objects for CCS IDE
Function Description
ticcs Create connections to CCS IDE and RTDX.
39-26
IDE Automation Interface
Function Description
cd Change the CCS IDE working folder from
MATLAB software.
open Load program files in CCS IDE.
run Run processes on the processor.
Function Description
close Close the RTDX links between MATLAB
software and your processor.
configure Determine how many channel buffers to
use and set the size of each buffer.
disable Disable the RTDX links before you close
them.
display Return the properties of an object in
formatted layout. When you omit the
closing semicolon on a function, disp (a
built-in function) provides the default
display for the results of the operation.
enable Enable open channels so you can use
them to send and retrieve data from your
processor.
isenabled Determine whether channels are enabled
for RTDX communications.
isreadable Determine whether MATLAB software can
read the specified memory location.
iswritable Determine whether MATLAB software can
write to the processor.
msgcount Determine how many messages are waiting
in a channel queue.
open Open channels in RTDX.
readmat Read data matrices from the processor into
MATLAB software as an array.
39-27
39 Working with Texas Instruments Code Composer Studio 3.3 IDE
Function Description
readmsg Read one or more messages from a channel.
writemsg Write messages to the processor over a
channel.
This tutorial provides the following workflow to show you how to use many of the
functions in the links. By performing the steps provided, you work through many of
the operations yourself. The tutorial follows the general task flow for developing digital
signal processing programs through testing with the links for RTDX.
Within this set of tasks, numbers 1, 2, and 4 are fundamental to function syntax that
interacts development projects. Whenever you work with MATLAB software and objects
for RTDX, you perform the functions and tasks outlined and presented in this tutorial.
The differences lie in Task 3. Task 3 is the most important for using Embedded Coder to
develop your processing system.
1 Create an RTDX link to your desired processor and load the program to the
processor.
The projects begin this way. Without the links you cannot load your executable to the
processor.
2 Configure channels to communicate with the processor.
Creating the links in Task 1 did not open communications to the processor. With the
links in place, you open as many channels as you need to support the data transfer
for your development work. This task includes configuring channel buffers to hold
data when the data rate from the processor exceeds the rate at which MATLAB
software can capture the data.
3 Run your application on the processor. You use MATLAB software to investigate the
results of your running process.
4 Close the links to the processor and clean up the links and associated debris left over
from your work.
Closing channels and cleaning up the memory and links you created prepares CCS
IDE, RTDX, and Embedded Coder for the next time you start development on a
project.
39-28
IDE Automation Interface
You can view the tutorial file used here by clicking rtdxtutorial. To run this tutorial in
MATLAB software, click run rtdxtutorial.
Note To be able to open and enable channels over a link to RTDX, the program loaded on
your processor must include functions or code that define the channels.
Your C source code might look something like this to create two channels, one to write
and one to read.
rtdx_CreateInputChannel(ichan); % processor reads from this.
rtdx_CreateOutputChannel(ochan); % processor writes to this.
These are the entries we use in int16.c (the source code that generates
rtdxtutorial_6xevm.out) to create the read and write channels.
If you are working with a model in Simulink software and using code generation, use the
To Rtdx and From Rtdx blocks in your model to add the RTDX communications channels
to your model and to the executable code on your processor.
One more note about this tutorial. Throughout the code we use both the dot notation
(direct property referencing) to access functions and link properties and the function
form.
For example, use the following command to open and configure ichan for write mode.
IDE_Obj.rtdx.open('ichan','w');
You could use an equivalent syntax, the function form, that does not use direct property
referencing.
open(IDE_Obj.rtdx,'ichan','w');
Or, use
open(rx,'ichan','w');
if you created an alias rx to the RTDX portion of IDE_Obj, as shown by the following
command:
rx = IDE_Obj.rtdx;
39-29
39 Working with Texas Instruments Code Composer Studio 3.3 IDE
With your processing model converted to an executable for your desired processor, you
are ready to use the objects to test and run your model on your processor. Embedded
Coder and the objects do not distinguish the source of the executable — whether you used
Embedded Coder, CCS IDE, or some other development tool to program and compile your
model to an executable does not alter the object connections. So long as your .out file is
acceptable to the processor you select, Embedded Coder provides the connection to the
processor.
Before continuing with this tutorial, you must load a valid GEL file to configure the
EMIF registers of your processor and perform required processor initialization steps.
Default GEL files provided by CCS are stored in ..\IDE_Obj\gel in the folder where
you installed CCS software. Select File > Load_GEL in CCS IDE to load the default
GEL file that matches your processor family, such as init6x0x.gel for the Cxxxx
processor family, and your configuration.
Note: If you are performing the steps in this tutorial, create demoPjt as described in
“Loading Files into CCS” on page 39-16 before continuing.
Begin the process of getting your model onto the processor by creating a an object that
refers to CCS IDE. Start by clearing function syntax that interacts existing handles and
setting echo on so you see functions execute as the program runs:
clear all removes debugging breakpoints and resets persistent variables because
function breakpoints and persistent variables are cleared whenever the MATLAB
file changes or is cleared. Breakpoints within your executable remain after clear.
Clearing the MATLAB workspace does not alter your executable.
2 Now construct the link to your board and processor by entering
IDE_Obj=ticcs('boardnum',0);
boardnum defines which board the new link accesses. In this example, boardnum is
0. Embedded Coder connects the link to the first, and in this case only, processor on
the board. To find the boardnum and procnum values for the boards and simulators
on your system, use “ccsboardinfo”. When you enter the following command at the
prompt
39-30
IDE Automation Interface
ccsboardinfo
3 To open and load the processor file, change the path for MATLAB software to be able
to find the file.
projname = C:\Temp\EmbIDELinkCCDemos_v4.1\rtdxtutorial\cxx\cxxxp\rtdxtut_sim.pjt
outFile = C:\Temp\EmbIDELinkCCDemos_v4.1\rtdxtutorial\cxx\cxxxp\rtdxtut_sim.out
processor_dir = demoPjt.DemoDir
processor_dir = C:\Temp\EmbIDELinkCCDemos_v4.1\rtdxtutorial\cxx\cxxxp
To load the project file to your processor, enter the following commands at the
MATLAB software prompt. getDemoProject is a specialized function for loading
Embedded Coder example files. It is not supported as a standard Embedded Coder
function.
demoPjt = getDemoProject(IDE_Obj,'ccstutorial');
demoPjt.ProjectFile
ans = C:\Temp\EmbIDELinkCCDemos_v4.1\ccstutorial\cxx\cxxxp\ccstut.pjt
demoPjt.DemoDir
ans = C:\Temp\EmbIDELinkCCDemos_v4.1\ccstutorial\cxx\cxxxp
Notice where the example files are stored on your machine. In general, Embedded
Coder software stores the example project files in
EmbIDELinkCCDemos_v#.#
For example, if you are using version 4.1 of Embedded Coder software, the project
examples are stored in EmbIDELinkCCDemos_v4.1\. Embedded Coder software
creates this folder in a location on your machine where you have write permission.
Usually, there are two locations where Embedded Coder software tries to create the
example folder, in the order shown.
39-31
39 Working with Texas Instruments Code Composer Studio 3.3 IDE
Because open is overloaded for the CCS IDE and RTDX links, this may seem a bit
strange. In this syntax, open loads your executable file onto the processor identified
by IDE_Obj. Later in this tutorial, you use open with a different syntax to open
channels in RTDX.
In the next section, you use the new link to open and enable communications
between MATLAB software and your processor.
In the open function, you provide the channel names as strings for the channel name
property. The channel name you use is not random. The channel name string must match
a channel defined in the executable file. If you specify a string that does not identify an
existing channel in the executable, the open operation fails.
In this tutorial, two channels exist on the processor — ichan and ochan. Although the
channels are named ichan for input channel and ochan for output channel, neither
channel is configured for input or output until you configure them from MATLAB
software or CCS IDE. You could configure ichan as the output channel and ochan as the
input channel. The links would work just the same. For simplicity, the tutorial configures
ichan for input and ochan for output. One more note—reading and writing are defined
as seen by the processor. When you write data from MATLAB software, you write to the
channel that the processor reads, ichan in this case. Conversely, when you read from the
processor, you read from ochan, the channel that the processor writes to:
1 Configure buffers in RTDX to store the data until MATLAB software can read it
into your workspace. Often, MATLAB software cannot read data as quickly as the
processor can write it to the channel.
IDE_Obj.rtdx.configure(1024,4); % define 4 channels of 1024 bytes each
Channel buffers are optional. Adding them provides a measure of insurance that
data gets from your processor to MATLAB software without getting lost.
2 Define one of the channels as a write channel. Use 'ichan' for the channel name and
'w' for the mode. Either 'w' or 'r' fits here, for write or read.
IDE_Obj.rtdx.open('ichan','w');
39-32
IDE Automation Interface
IDE_Obj.rtdx.enable('ichan');
IDE_Obj.rtdx.open('ochan','r');
IDE_Obj.rtdx.enable('ochan');
5 To use the new channels, enable RTDX by entering
IDE_Obj.rtdx.enable;
You could do this step before you configure the channels — the order does not
matter.
6 Reset the global time-out to 20s to provide a little room for error. ticcs applies a
default timeout value of 10 s. In some cases this may not be enough.
IDE_Obj.rtdx.get('timeout')
ans =
10
IDE_Obj.rtdx.set('timeout', 20); % Reset timeout = 20 seconds
7 Check that the timeout property value is now 20s and that your object has a valid
configuration for the rest of the tutorial.
IDE_Obj.rtdx
RTDX Object:
API version: 1.0
Default timeout: 20.00 secs
Open channels: 2
To this point you have been doing common housekeeping functions. You load the
processor, configure the communications, and set up other properties you need.
This tutorial shows you some of the Embedded Coder functions you can use to prototype
and experiment with your application. To see the RTDX “readmat”, readmsg, and
writemsg functions, you write data to your processor. Then, after the data has been
processed, you read data from the processor.
1 Restart the program you loaded on the processor. restart sets the program counter
(PC) to the beginning of the executable code on the processor.
IDE_Obj.restart
39-33
39 Working with Texas Instruments Code Composer Studio 3.3 IDE
Restarting the processor does not start the program executing. You use run to start
program execution.
2 Type IDE_Obj.run('run');
Using 'run' for the run mode tells the processor to continue to execute the loaded
program continuously until it receives a halt directive. In this mode, control returns
to MATLAB software so you can work in MATLAB software while the program runs.
Other options for the mode are
IDE_Obj.rtdx.enable('ichan');
IDE_Obj.rtdx.isenabled('ichan')
If MATLAB software responds ans = 0 your channel is not enabled and you cannot
proceed with the tutorial. Try to enable the channel again and verify the status.
4 Write some data to the processor. Check that you can write to the processor, then use
writemsg to send the data. You do not need to enter the if-test code shown.
if IDE_Obj.rtdx.iswritable('ichan'), % Used in a script application.
disp('writing to processor...') % Optional to display progress.
indata=1:10
IDE_Obj.rtdx.writemsg('ichan', int16(indata))
end % Used in scripts for channel testing.
The if statement simulates writing the data from within a MATLAB software
script. The script uses iswritable to check that the input channel is functioning.
If iswritable returns 0 the script would skip the write and exit the program, or
respond in some way. When you are writing or reading data to your processor in a
script or MATLAB file, checking the status of the channels can help you avoid errors
during execution.
As your application runs you may find it helpful to display progress messages. In
this case, the program directed MATLAB software to print a message as it reads the
data from the processor by adding the function
39-34
IDE Automation Interface
disp('writing to processor...')
When you write indata to the processor, the following code running on the processor
takes your input data from ichan, adds one to the values and copies the data to
memory:
while ( !RTDX_isInputEnabled(&ichan) )
Program int16_rtdx.c contains this source code. You can find the file in a folder in
the ..\tidemos\rtdxtutorial folder.
5 Type the following to check the number of available messages to read from the
processor.
num_of_msgs = IDE_Obj.rtdx.msgcount('ochan');
num_of_msgs should be zero. Using this process to check the amount of data lets
you or your program know how much data to expect.
6 Type the following to verify that your read channel ochan is enabled for
communications.
IDE_Obj.rtdx.isenabled('ochan')
You should get back ans = 0 — you have not enabled the channel yet.
7 Now enable and verify 'ochan'.
39-35
39 Working with Texas Instruments Code Composer Studio 3.3 IDE
IDE_Obj.rtdx.enable('ochan');
IDE_Obj.rtdx.isenabled('ochan')
To show that ochan is ready, MATLAB software responds ans = 1. If not, try
enabling ochan again.
8 Type
pause(5);
The pause function gives the processor extra time to process the data in indata and
transfer the data to the buffer you configured for ochan.
9 Repeat the check for the number of messages in the queue. There should be 20
messages available in the buffer.
num_of_msgs = IDE_Obj.rtdx.msgcount('ochan')
With num_of_msgs = 20, you could use a looping structure to read the messages
from the queue in to MATLAB software. In the next few steps of this tutorial you
read data from the ochan queue to different data formats within MATLAB software.
10 Read one message from the queue into variable outdata.
outdata = IDE_Obj.rtdx.readmsg('ochan','int16')
outdata =
2 3 4 5 6 7 8 9 10 11
Notice the 'int16' represent option. When you read data from your processor you
need to tell MATLAB software the data type you are reading. You wrote the data in
step 4 as 16-bit integers so you use the same data type here.
While performing reads and writes, your process continues to run. You did not need
to stop the processor to get the data or send the data, unlike using most debuggers
and breakpoints in your code. You placed your data in memory across an RTDX
channel, the processor used the data, and you read the data from memory across an
RTDX channel, without stopping the processor.
11 You can read data into cell arrays, rather than into simple double-precision
variables. Use the following function to read three messages to cell array outdata,
an array of three, 1-by-10 vectors. Each message is a 1-by-10 vector stored on the
processor.
outdata = IDE_Obj.rtdx.readmsg('ochan','int16',3)
39-36
IDE Automation Interface
outdata =
[1x10 int16] [1x10 int16] [1x10 int16]
12 Cell array outdata contains three messages. Look at the second message, or matrix,
in outdata by using dereferencing with the array.
outdata{1,2}
outdata =
4 5 6 7 8 9 10 11 12 13
13 Read two messages from the processor into two 2-by-5 matrices in your MATLAB
workspace.
outdata = IDE_Obj.rtdx.readmsg('ochan','int16',[2 5],2)
outdata =
[2x5 int16] [2x5 int16]
To specify the number of messages to read and the data format in your workspace,
you used the siz and nummsgs options set to [2 5] and 2.
14 You can look at both matrices in outdata by dereferencing the cell array again.
outdata{1,:}
ans =
6 8 10 12 14
7 9 11 13 15
ans =
7 9 11 13 15
8 10 12 14 16
15 For a change, read a message from the queue into a column vector.
outdata = IDE_Obj.rtdx.readmsg('ochan','int16',[10 1])
outdata =
8
9
10
11
12
13
14
15
16
17
outdata =
39-37
39 Working with Texas Instruments Code Composer Studio 3.3 IDE
9 14
10 15
11 16
12 17
13 18
Because a 5-by-2 matrix requires ten elements, MATLAB software reads one
message into outdata to fill the matrix.
17 To check your progress, see how many messages remain in the queue. You have read
eight messages from the queue so 12 should remain.
num_of_msgs = IDE_Obj.rtdx.msgcount('ochan')
num_of_msgs =
12
18 To see the connection between messages and a matrix in MATLAB software, read
data from 'ochan' to fill a 4-by-5 matrix in your workspace.
outdata = IDE_Obj.rtdx.readmat('ochan','int16',[4 5])
outdata =
10 14 18 13 17
11 15 19 14 18
12 16 11 15 19
13 17 12 16 20
outdata =
12 13 14 15 16
13 14 15 16 17
14 15 16 17 18
15 16 14 18 19
16 17 18 19 20
17 18 19 20 21
18 19 20 21 22
19 20 21 22 23
20 21 22 23 24
21 22 23 24 25
21 Recheck the number of messages in the queue to see that five remain.
39-38
IDE Automation Interface
22 “flush” lets you remove messages from the queue without reading them. Data in the
message you remove is lost. Use flush to remove the next message in the read queue.
Then check the waiting message count.
IDE_Obj.rtdx.flush('ochan',1)
num_of_msgs = IDE_Obj.rtdx.msgcount('ochan')
num_of_msgs =
4
23 Empty the remaining messages from the queue and verify that the queue is empty.
IDE_Obj.rtdx.flush('ochan','all')
With the all option, flush discards the messages in the ochan queue.
One of the most important programmatic processes you should do in every RTDX
session is to clean up at the end. Cleaning up includes stopping your processor, disabling
the RTDX channels you enabled, disabling RTDX and closing your open channels.
Performing this series of tasks prevents trouble caused by unexpected interactions with
remaining handles, channels, and links from earlier development work.
Best practices suggest that you include the following tasks (or an subset that meets your
development needs) in your development scripts and programs.
We use several functions in this section; each has a purpose — the operational details in
the following list explain how and why we use each one. They are
• close — close the specified RTDX channel. To use the channel again, you must open
and enable the channel. Compare close to disable. close('rtdx') closes the
communications provided by RTDX. After you close RTDX, you cannot communicate
with your processor.
• disable — remove RTDX communications from the specified channel, but does not
remove the channel, or link. Disabling channels may be useful when you do not want
to see the data that is being fed to the channel, but you may want to read the channel
later. By enabling the channel later, you have access to the data entering the channel
buffer. Note that data that entered the channel while it was disabled is lost.
• halt — stop a running processor. You may still have one or more messages in the
host buffer.
39-39
39 Working with Texas Instruments Code Composer Studio 3.3 IDE
Use the following procedure to shut down communications between MATLAB software
and the processor, and end your session:
1 Begin the process of shutting down the processor and RTDX by stopping the
processor. Type the following functions at the prompt.
if (isrunning(IDE_Obj)) % Use this test in scripts.
IDE_Obj.halt; % Halt the processor.
end % Done.
Your processor may already be stopped at this point. In a script, you might put
the function in an if-statement as we have done here. When you direct a stopped
processor to halt, the function returns immediately.
2 You have stopped the processor. Now disable the RTDX channels you opened to
communicate with the processor.
IDE_Obj.rtdx.disable('all');
If required, using disable with channel name and processor identifier input
arguments lets you disable only the channel you choose. When you have more than
one board or processor, you may find disabling selected channels meets your needs.
When you finish your RTDX communications session, disable RTDX so that
Embedded Coder releases your open channels before you close them.
IDE_Obj.rtdx.disable;
3 Use the following function syntaxes to close your open channels. Either close selected
channels by using the channel name in the function, or use the all option to close
the open channels.
Consider using the all option with the close function when you finish your RTDX
work. Closing channels reduces unforeseen problems caused by channel objects that
exist but do not get closed when you end your session.
4 When you created your RTDX object (IDE_Obj = ticcs('boardnum',1) at the
beginning of this tutorial, the ticcs function opened CCS IDE and set the visibility
to 0. To avoid problems that occur when you close the interface to RTDX with
39-40
IDE Automation Interface
CCS visibility set to 0, make CCS IDE visible on your desktop. The following if
statement checks the CCS IDE visibility and changes it if required.
if IDE_Obj.isvisible,
IDE_Obj.visible(1);
end
Visibility can cause problems. When CCS IDE is running invisibly on your desktop,
do not use clear all to remove your links for CCS IDE and RTDX. Without a
ticcs object that references the CCS IDE you cannot access CCS IDE to change the
visibility setting, or close the application. To close CCS IDE when you do not have
an existing object, either create a new object to access the CCS IDE, or use Microsoft
Windows Task Manager to end the process cc_app.exe, or close the MATLAB
software.
5 You have finished the work in this tutorial. Enter the following commands to close
your remaining references to CCS IDE and release the associated resources.
clear ('all'); % Calls the link destructors to remove all links.
echo off
clear all without the parentheses removes the variables from your MATLAB
workspace.
You have completed the tutorial using RTDX. During the tutorial you
1 Opened connections to CCS IDE and RTDX and used those connections to load an
executable program to your processor.
2 Configured a pair of channels so you could transfer data to and from your processor.
3 Ran the executable on the processor, sending data to the processor for processing and
retrieving the results.
4 Stopped the executing program and closed the links to CCS IDE and RTDX.
This tutorial provides a working process for using Embedded Coder and your signal
processing programs to develop programs for a range of Texas Instruments processors.
While the processor may change, the essentials of the process remain the same.
Listing Functions
To review a complete list of functions and methods that operate with ticcs objects,
either CCS IDE or RTDX, enter either of the following commands at the prompt.
help ticcs
help rtdx
39-41
39 Working with Texas Instruments Code Composer Studio 3.3 IDE
If you already have a ticcs object IDE_Obj, you can use dot notation to return the
methods for CCS IDE or RTDX by entering one of the following commands at the prompt:
• IDE_Obj.methods
• IDE_Obj.rtdx.methods
In either instance MATLAB software returns a list of the available functions for the
specified link type, including both public and private functions. For example, to see the
functions (methods) for links to CCS IDE, enter:
help ticcs
The discussions in this section apply to the ticcs objects in Embedded Coder.
Like other MATLAB software structures, objects in Embedded Coder have predefined
fields called object properties.
• Setting the property values when you create the ticcs object
• Creating an object with default property values, and changing these property values
later
The easiest way to create an object is to use the function ticcs to create an object with
the default properties. Create an object named IDE_Obj to refer to CCS IDE by entering
IDE_Obj = ticcs
MATLAB software responds with a list of the properties of the object IDE_Obj you
created along with the associated default property values.
ticcs object:
39-42
IDE Automation Interface
RTDX channels : 0
Inspecting the output reveals two objects listed—a CCS IDE object and an RTDX object.
CCS IDE and RTDX objects cannot be created separately. By design they maintain a
member class relationship; the RTDX object is a class, a member of the CCS object class.
In this example, IDE_Obj is an instance of the class CCS. If you enter
rx = IDE_Obj.rtdx
RTDX channels : 0
The object properties are described in the function reference, and in more detail in ticcs
Object Properties. These properties are set to default values when you construct objects.
39-43
39 Working with Texas Instruments Code Composer Studio 3.3 IDE
functions with the same name operate on different types of objects (or on data) is called
overloading of functions.
For example, the set command is overloaded for ticcs objects. After you specify your
link by assigning values to its properties, you can apply the functions in this toolbox
(such as “readmat” for using RTDX to read an array of data from the processor) directly
to the variable name you assign to your object, without specifying your object parameters
again.
This section details the properties for the ticcs objects for CCS IDE and RTDX. First
the section provides tables of the properties, for quick reference. Following the tables, the
section offers in-depth descriptions of each property, its name and use, and whether you
can set and get the property value associated with the property. Descriptions include a
few examples of the property in use.
MATLAB software users may find much of this handling of objects familiar. Objects in
Embedded Coder, behave like objects in MATLAB software and the other object-oriented
toolboxes. For C++ programmers, discussion of object-oriented programming is likely to
be a review.
The following table lists the properties for the ticcs objects in Embedded Coder. The
second column tells you which object the property belongs to. Knowing which property
belongs to each object in a ticcs object tells you how to access the property.
39-44
IDE Automation Interface
Some properties are read only — you cannot set the property value. Other properties,
you can change. If the entry in the User Settable column is “Yes/initially”, you can set the
property value only when you create the link. Thereafter it is read only.
To use the links for CCS IDE and RTDX interface you set values for:
Details of the properties associated with connections to CCS IDE and RTDX interface
appear in the following sections, listed in alphabetical order by property name.
39-45
39 Working with Texas Instruments Code Composer Studio 3.3 IDE
Many of these properties are object linking and embedding (OLE) handles. The MATLAB
software COM server creates the handles when you create objects for CCS IDE and
RTDX. You can manipulate the OLE handles using get, set, and invoke to work
directly with the COM interface with which the handles interact.
apiversion
Property appversion contains a string that reports the version of the application
program interface (API) for CCS IDE that you are using when you create a link. You
cannot change this string. When you upgrade the API, or CCS IDE, the string changes
to match. Use display to see the apiversion property value for a link. This example
shows the appversion value for link IDE_Obj.
display(IDE_Obj)
TICCS Object:
API version : 1.0
Processor type : Cxx
Processor name : CPU
Running? : No
Board number : 0
Processor number : 0
Default timeout : 10.00 secs
RTDX channels : 0
Note that the API version is not the same as the CCS IDE version.
boardnum
Property boardnum identifies the board referenced by the IDE link handle object for
CCS. When you create a link, you use boardnum to specify the board you are using.
To get the value for boardnum, use “ccsboardinfo” or the CCS Setup utility from Texas
Instruments software. The CCS Setup utility assigns the number for each board installed
on your system.
ccsappexe
Property ccsappexe contains the path to the CCS IDE executable file cc_app.exe.
When you use ticcs to create a link, MATLAB software determines the path to the CCS
IDE executable and stores the path in this property. This is a read-only property. You
cannot set it.
numchannels
39-46
IDE Automation Interface
Property numchannels reports the number of open RTDX communications channels for
an RTDX link. Each time you open a channel for a link, numchannels increments by
one. For new links numchannels is zero until you open a channel for the link.
To see the value for numchannels create a link to CCS IDE. Then open a channel to
RTDX. Use display to see the RTDX link properties.
IDE_Obj=ticcs
TICCS Object:
API version : 1.0
Processor type : Cxx
Processor name : CPU
Running? : No
Board number : 0
Processor number : 0
Default timeout : 10.00 secs
RTDX channels : 0
rx=IDE_Obj.rtdx
RTDX channels : 0
open(rx,'ichan','r','ochan','w');
get(IDE_Obj.rtdx)
ans =
numChannels: 2
Rtdx: [1x1 COM ]
RtdxChannel: {'' '' ''}
procType: 103
timeout: 10
page
Property page contains the default value CCS IDE uses when the user does not specify
the page input argument in the syntax for a function that access memory.
procnum
Property procnum identifies the processor referenced by the IDE link handle object for
CCS. When you create an object, you use procnum to specify the processor you are using .
39-47
39 Working with Texas Instruments Code Composer Studio 3.3 IDE
The CCS Setup Utility assigns a number to each processor installed on each board. To
determine the value of procnum for a processor, use “ccsboardinfo” or the CCS Setup
utility from Texas Instruments software.
To identify a processor, you need both the boardnum and procnum values. For
boards with one processor, procnum equals zero. CCS IDE numbers the processors on
multiprocessor boards sequentially from 0 to the number of processors. For example, on a
board with four processors, the processors are numbered 0, 1, 2, and 3.
rtdx
Property rtdx is a subclass of the ticcs link and represents the RTDX portion of the
IDE link handle object for CCS. As shown in the example, rtdx has properties of its own
that you can set, such as timeout, and that report various states of the link.
get(IDE_Obj.rtdx)
ans =
version: 1
numChannels: 0
Rtdx: [1x1 COM ]
RtdxChannel: {'' [] ''}
procType: 103
timeout: 10
In addition, you can create an alias to the rtdx portion of a link, as shown in this code
example.
rx=IDE_Obj.rtdx
RTDX channels : 0
Now you can use rx with the functions in Embedded Coder, such as get or set. If you
have two open channels, the display looks like the following example:
get(rx)
ans =
numChannels: 2
Rtdx: [1x1 COM ]
RtdxChannel: {2x3 cell}
procType: 98
39-48
IDE Automation Interface
timeout: 10
rtdxchannel
rtdxchannel is a cell array that contains the channel name, handle, and mode for each
open channel for the link. For each open channel, rtdxchannel contains three fields, as
follows:
With four open channels, rtdxchannel contains four channel elements and three fields
for each channel element.
timeout
Property timeout specifies how long CCS IDE waits for a process to finish. Two
timeout periods can exist — one global, one local. You set the global timeout when
you create the IDE link handle object for CCS. The default global timeout value 10 s.
However, when you use functions to read or write data to CCS IDE or your processor,
you can set a local timeout that overrides the global value. If you do not set a specific
timeout value in a read or write process syntax, the global timeout value applies to the
operation. Refer to the help for the read and write functions for the syntax to set the local
timeout value for an operation.
version
Property version reports the version number of your RTDX software. When you
create a ticcs object, version contains a string that reports the version of the RTDX
application that you are using. You cannot change this string. When you upgrade
the API, or CCS IDE, the string changes to match. Use display to see the version
property value for a link. This example shows the apiversion value for object rx.
39-49
39 Working with Texas Instruments Code Composer Studio 3.3 IDE
ans =
version: 1
numChannels: 0
Rtdx: [1x1 COM ]
RtdxChannel: {'' [] ''}
procType: 103
timeout: 10
Function List
The following is a complete list of functions for working with CCS v.3.3. It includes
Automation Interface and other types of functions.
• activate
• add
• address
• animate
• build
• ccsboardinfo
• cd
• checkEnvSetup
• close
• configure
• dir
• disable
• display (IDE Object)
• enable
• flush
• getbuildopt
• halt
• info
• insert
• xmakefilesetup
39-50
IDE Automation Interface
• isenabled
• isreadable
• isrtdxcapable
• isrunning
• isvisible
• iswritable
• list
• load
• msgcount
• new
• open
• profile
• read
• readmat
• readmsg
• regread
• regwrite
• reload
• remove
• reset
• restart
• run
• save
• setbuildopt
• symbol
• ticcs
• visible
• write
• writemsg
39-51
39 Working with Texas Instruments Code Composer Studio 3.3 IDE
• Support automated project building for Texas Instruments Code Composer Studio
software that lets you create projects from code generated by Embedded Coder
products. The project automatically populates CCS projects in the CCS development
environment.
• Configure code generation using model Configuration Parameters and processor
preferences block options
• Select from two system target files to generate code specific to your processor
• Configure project build process
• Automatically download and run your generated projects on your processor
Note: You cannot generate code for C6000 processors in big-endian mode. Code
generation supports only little-endian processor data byte order.
39-52
IDE Project Generator
The result of the ticcs method changes, depending on the boards you configured in
CCS. The following table describes how the software selects the board to connect to in
your board configuration.
39-53
39 Working with Texas Instruments Code Composer Studio 3.3 IDE
(*)
You may encounter the situation where you do not have the valid board configured in
CCS because of one of the following conditions:
• You changed your board configuration and saved the model. When you reopen the
model, the board specified in Board name in the block is not in your configuration.
• You are working with a model from a source whose board configuration is not the
same as yours.
Use “ccsboardinfo” at the MATLAB prompt to verify or review your configured boards.
In this tutorial you will use the Embedded Coder software to:
• Build a model.
• Generate a project from the model.
• Build the project and run the binary on a processor.
Note The model shows project generation. You cannot not build and run the model on
your processor without additional blocks.
39-54
IDE Project Generator
The following sections describe how to configure the build and run parameters for your
model. Generating a project, or building and running a model on the processor, starts
with configuring model options in the Configuration Parameters dialog in Simulink
software.
Setting Solver Parameters
After you have designed and implemented your digital signal processing model in
Simulink software, complete the following steps to set the Configuration Parameters for
the model:
1 Configure your model for your IDE, tool chain, and target hardware, as described in
“Configure Target Hardware Resources” on page 36-3.
2 Select the Solver pane in the Configuration Parameters dialog.
3 Set Start time to 0.0 and Stop time to inf (model runs without stopping). If you
set a stop time, your generated code does not honor the setting. Set this to inf for
completeness.
4 Under Solver options, set Type to fixed-step and set Solver to discrete (no
continuous states). For PIL, set Type and Solver to any setting.
5 For Fixed step size (fundamental sample time), enter Auto, and set Tasking
mode for periodic sample times to SingleTasking.
Note Generated code does not honor Simulink software stop time from the simulation.
Stop time is interpreted as inf. To implement a stop in generated code, add a Stop
Simulation block in your model.
When you use PIL, you can set the Solver options to any selection from the Type and
Solver lists.
39-55
39 Working with Texas Instruments Code Composer Studio 3.3 IDE
To configure your software to use the right processor files and to compile and run your
model executable file, configure the Code Generation pane in the Configuration
Parameters dialog.
To configure code generation options and to compile and run your model executable file,
configure the Coder Target pane in the Configuration Parameters dialog.
1 In the Configuration Parameters dialog, expand the node for the Code Generation
pane and select the Coder Target pane.
2 Set the following options in the pane under Vendor Tool Chain:
You have configured the your software options that let you generate a project for you
processor. You may have noticed that you did not configure a few of the Configuration
Parameters panes, such as Comments, Symbols, and Optimization.
For your new model, the default values for the options in these panes are right. For
other models you develop, you may want to set the options in these panes to provide
information during the build and to run TLC debugging when you generate code. Refer
to your product documentation for more information about setting the Configuration
Parameters.
39-56
IDE Project Generator
After you set the Configuration Parameters and configure the coder product to create the
files you need, you direct the build process to create your project:
When you click Build with Create_project selected for Build action, the
automatic build process starts CCS IDE, populates a new project in the development
environment, builds the project, loads the binary on the processor, and runs it.
3 To stop processor execution, use the Halt option in CCS or enter IDE_Obj.halt at
the MATLAB command prompt. (Where “IDE_Obj” is the IDE link handle name you
specified previously in Configuration Parameters.)
Model Reference
Model reference lets your model include other models as modular components. This
technique provides useful features because it:
• Simplifies working with large models by letting you build large models from smaller
ones, or even large ones.
• Lets you generate code for the modules in the model, and later, regenerate code for
modules that change.
• Lets you develop the modules independently.
• Lets you reuse modules and models by reference, rather than including the model
or module multiple times in your model. Also, multiple models can refer to the same
model or module.
Your product documentation provides much more information about model reference.
Model reference behaves differently in simulation and in code generation. For this
discussion, you need to know the following terms:
• Top-model — The root model block or model. It refers to other blocks or models. In the
model hierarchy, this is the topmost model.
• Referenced models — Blocks or models that other models reference, such as models
the top-model refers to. The models or blocks below the top-model in the hierarchy are
reference models.
39-57
39 Working with Texas Instruments Code Composer Studio 3.3 IDE
The following sections describe briefly how model reference works. More details are
available in your product documentation in the online Help system.
Model Reference in Simulation
When you simulate the top-model, the coder product detects that your model contains
referenced models. Simulink software generates code for the referenced models and uses
the generated code to build shared library files for updating the model diagram and
simulation. It also creates an executable (a MEX file, .mex) for each reference model that
is used to simulate the top-model.
When you rebuild reference models for simulations or when you run or update a
simulation, Simulink software rebuilds the model reference files. Whether reference files
or models are rebuilt depends on:
Embedded Coder software requires executables to generate code from models. If you
have not simulated your model at least once, the coder product creates a .mex file for
simulation.
Next, for each referenced model, the code generation process calls make_rtw and builds
each referenced model. This build process creates a library file for each of the referenced
models in your model.
After building the referenced models, the coder product calls make_rtw on the top-model,
linking to the library files it created for the associated referenced models.
With few limitations or restrictions, Embedded Coder provides full support for
generating code from models that use model reference.
Build Action Setting
The most important requirement for using model reference with the TI's processors is to
set the Build action for the Model blocks in the simulation to Archive_library.
39-58
IDE Project Generator
If your top-model uses a reference model that does not have the build action set to
Archive_library, the build process automatically changes the build action to
Archive_library and issues a warning about the change.
• DSP/BIOS is disabled for the referenced models. Only the top-model supports DSP/
BIOS operation.
• Interrupt overrun notification method, Export IDE link handle to base
workspace, and System stack size are disabled for the referenced models.
Other Block Limitations
Model reference with Embedded Coder does not allow you to use the following blocks or
S-functions in reference models:
• Blocks from the C62x DSP Library (in c6000lib) (because these are noninlined S-
functions)
• Blocks from the C64x DSP Library (in c6000lib) (because these are noninlined S-
functions)
• Noninlined S-functions
• Driver blocks, such as the ADC or DAC blocks from a Embedded Coder block library
Processors that you plan to use in Model Referencing must meet some general
requirements.
• The System target file on the Code Generation pane of the Configuration
Parameters dialog must match the target hardware.
• When you generate code from a model that references another model, you need to
configure both the top-level model and the referenced models for the same code
generation processor.
39-59
39 Working with Texas Instruments Code Composer Studio 3.3 IDE
• The External mode option is not supported in model reference processor builds.
Embedded Coder product does not support External mode. If you select this option, it
is ignored during code generation.
• To support model reference builds, your TMF must support use of the shared utilities
folder, as described in “Supporting Shared Utility Directories in the Build Process” in
the Simulink Coder documentation.
To use an existing processor, or a new processor, with Model Reference, you set the
ModelReferenceCompliant flag for the processor. For information on how to set this
option, refer to ModelReferenceCompliant in the online Help system.
If you start with a model that was created prior to version 2.4 (R14SP3), to make your
model compatible with the model reference processor, use the following command to set
the ModelReferenceCompliant flag to On:
set_param(bdroot,'ModelReferenceCompliant','on')
Models that you develop with versions 2.4 and later of Embedded Coder automatically
include the model reference capability. You do not need to set the flag.
39-60
Exporting Filter Coefficients from FDATool
About FDATool
Signal Processing Toolbox™ software provides the Filter Design and Analysis tool
(FDATool) that lets you design a filter and then export the filter coefficients to a
matching filter implemented in a CCS project.
For instructions on using FDATool, refer to the section “Filter Design and Analysis Tool”
in the Signal Processing Toolbox documentation.
Procedures in this chapter show how to use the FDATool export options to export filter
coefficients to CCS. Using these procedures, you can perform the following tasks:
Caution For the best results, export coefficients in a header file. Exporting coefficients
directly to processor memory can generate unexpected results or corrupt memory.
39-61
39 Working with Texas Instruments Code Composer Studio 3.3 IDE
Also see the reference pages for the following functions. These primary functions allow
you use to access variables and write them to processor memory from the MATLAB
Command window.
• address — Return the address of a symbol so you can read or write to it.
• ticcs — Create a connection between MATLAB software and CCS IDE so you can
work with the project in CCS from the MATLAB Command window.
• write — Write data to memory on the processor.
Features of a Filter
When you create a filter in FDATool, the filter includes defining features identified in the
following table.
When you export your filter, FDATool exports only the number of and value of the filter
coefficients and the data type used to define the coefficients.
39-62
Exporting Filter Coefficients from FDATool
You can export a filter by generating an ANSI C header file, or by writing the filter
coefficients directly to processor memory. The following table summarizes when and how
to use the export modes.
The export process provides two ways you can specify the data type to use to represent
the filter coefficients. Select one of the options shown in the following table when you
export your filter.
39-63
39 Working with Texas Instruments Code Composer Studio 3.3 IDE
FDATool exports filter coefficients that use the following data types directly without
modifications:
If you have installed DSP System Toolbox software, you can use the filter quantization
options in FDATool to set the word and fraction lengths that represent your filter
coefficients. For information about using the quantization options, refer to Filter Design
and Analysis Tool in the Filter Design Toolbox documentation in the Online help system.
If your filter uses one of the supported data types, Export suggested specifies that data
type.
If your filter does not use one of the supported data types, FDATool converts the
unsupported data type to one of the supported types and then suggests that data type.
For more information about how FDATool determines the data type to suggest, refer to
“How FDATool Determines the Export Suggested Data Type” on page 39-65.
Follow these best-practice guidelines when you implement your filter algorithm in source
code and design your filter in FDATool:
• Implement your filter using one of the data types FDATool exports without
modifications.
• Design your filter in FDATool using the data type you used to implement your filter.
39-64
Exporting Filter Coefficients from FDATool
When you export your filter, follow this procedure to select the export data type so that
the exported filter coefficients closely match the coefficients of your filter in FDATool.
1 In FDATool, select Targets > Code Composer Studio IDE to open the Export to
Code Composer Studio IDE dialog.
2 Perform one of the following actions:
• Select Export suggested to export the coefficients in the suggested data type.
• Select Export as and choose the data type your filter requires from the list.
Caution If you select Export as, the exported filter coefficients can be very
different from the filter coefficients in FDATool. As a result, your filter cutoff
frequencies and performance may not match your design in FDATool.
If you set custom word and fraction lengths to represent your filter coefficients, the
export process suggests a data type to maintain the best fidelity for the filter.
The export process converts your custom word and fraction lengths to a suggested export
data type, using the following rules:
• Round the word length up to the nearest larger supported data type. For example,
round an 18-bit word length up to 32 bits.
• Set the fraction length to the maintain the same difference between the word and
fraction length in the new data type as applies in the custom data type.
For example, if you specify a fixed-point data type with word length of 14 bits and
fraction length of 11 bits, the export process suggests an integer data type with word
length of 16 bits and fraction length of 13 bits, retaining the 3 bit difference.
39-65
39 Working with Texas Instruments Code Composer Studio 3.3 IDE
In this section, you export filter coefficients to a project by generating an ANSI C header
file that contains the coefficients. The header file defines global arrays for the filter
coefficients. When you compile and link the project to which you added the header file,
the linker allocates the global arrays in static memory locations in processor memory.
Loading the executable file into your processor allocates enough memory to store
the exported filter coefficients in processor memory and writes the coefficients to the
allocated memory.
Use the following steps to export filter coefficients from FDATool to the CCS IDE text
editor.
The following figure shows a Direct-form II IIR filter example that uses second-order
sections.
3 Click Store Filter to store your filter design. Storing the filter allows you to recall
the design to modify it.
4 To export the filter coefficients, select Targets > Code Composer Studio IDE from
the FDATool menu bar.
The Export to Code Composer Studio IDE dialog opens, as shown in the following
figure.
39-66
Exporting Filter Coefficients from FDATool
6 In Variable names in C header file, enter variable names for the Numerator,
Denominator, Numerator length, and Denominator length parameters where
the coefficients will be stored.
The dialog shows only the variables you need to export to define your filter.
Note: You cannot use reserved ANSI C programming keywords, such as if or int as
variable names, or include invalid characters such as spaces or semicolons (;).
7 In Data type to use in export, select Export suggested to accept the
recommended export data type. FDATool suggests a data type that retains filter
coefficient fidelity.
39-67
39 Working with Texas Instruments Code Composer Studio 3.3 IDE
You may find it useful to select the Export as option and select an export data type
other than the one suggested.
Caution If you deviate from the suggested data type, the exported filter coefficients
can be very different from the filter coefficients in FDATool. As a result, your filter
cutoff frequencies and performance may not match your design in FDATool.
For more information about how FDATool decides which data type to suggest, refer
to “How FDATool Determines the Export Suggested Data Type” on page 39-65.
8 If you know the board number and processor number of your target, enter
DSP Board # and DSP Processor # values to identify your board.
When you have only one board or simulator, Embedded Coder software sets
DSP Board # and DSP Processor # values for your board automatically.
The default location to save the file is your MATLAB working folder. The default file
name is fdacoefs.h.
10 Click OK to export the header file to the CCS editor.
The export process does not add the file to your active project in the IDE.
11 Drag your generated header file into the project that implements the filter.
12 Add a #include statement to your project source code to include the new header file
when you build your project.
39-68
Exporting Filter Coefficients from FDATool
13 Generate a .out file and load the file into your processor. Loading the file allocates
locations in static memory on the processor and writes the filter coefficients to those
locations.
To see an example header file, refer to “Reviewing ANSI C Header File Contents” on page
39-69.
The following program listing shows the exported header (.h) file that FDATool
generates. This example shows a direct-form II filter that uses five second-order sections.
The filter is stable and has linear phase.
Comments in the file describe the filter structure, number of sections, stability, and the
phase of the filter. Source code shows the filter coefficients and variables associated with
the filter design, such as the numerator length and the data type used to represent the
coefficients.
/*
* Filter Coefficients (C Source) generated by the Filter Design and Analysis Tool
*
* Generated by MATLAB(R) 7.8 and the Signal Processing Toolbox 6.11.
*
* Generated on: xx-xxx-xxxx 14:24:45
*
*/
/*
* Discrete-Time IIR Filter (real)
* -------------------------------
* Filter Structure : Direct-Form II, Second-Order Sections
* Number of Sections : 5
* Stable : Yes
* Linear Phase : No
*/
39-69
39 Working with Texas Instruments Code Composer Studio 3.3 IDE
{
0.2436793028081, 0.4873586056161, 0.2436793028081
},
{
1, 0, 0
},
{
0.3768793219093, 0.7537586438185, 0.3768793219093
},
{
1, 0, 0
}
};
const int DL[MWSPT_NSEC] = { 1,3,1,3,1,3,1,3,1,3,1 };
const real64_T DEN[MWSPT_NSEC][3] = {
{
1, 0, 0
},
{
1, -0.1842138030775, 0.1775781189277
},
{
1, 0, 0
},
# {
1, -0.2160098642842, 0.3808329528195
},
{
1, 0, 0
}
};
You can allocate extra memory by editing the generated ANSI C header file. You can
then load the associated program file into your processor as described in “Using the
Exported Header File to Allocate Extra Processor Memory” on page 39-71. Extra
39-70
Exporting Filter Coefficients from FDATool
memory lets you change filter coefficients and overwrite existing coefficients stored in
processor memory more easily.
To prevent problems when you update filter coefficients in a project, , such as writing
coefficients to unintended memory locations, use the C header file export mode
option in FDATool to update filter coefficients in your program.
Exporting the header file to CCS IDE does not add the filter to your project. To
incorporate the filter coefficients from the header file, add a #include statement:
#include "headerfilename.h"
Refer to “Exporting Filter Coefficients to Your Code Composer Studio Project” on page
39-65 for information about generating a header file to export filter coefficients.
When you export filter coefficients directly to processor memory, the export process
writes coefficients to as many memory locations as they need. The write process does not
perform bounds checking. Plan memory allocation carefully, so that the software writes
to the right locations and has enough memory for filter coefficients.
• Your redesign did not increase the memory required to store the coefficients beyond
the allocated memory.
Changes that increase the memory required to store the filter coefficients include the
following redesigns:
39-71
39 Working with Texas Instruments Code Composer Studio 3.3 IDE
Caution Identify changes that require additional memory to store the coefficients
before you begin your export. Otherwise, exporting the new filter coefficients may
overwrite data in memory locations you did not allocate for storing coefficients. Also,
exporting filter coefficients to memory after you change the filter order, structure, design
algorithm, or data type can yield unexpected results and corrupt memory.
Changing the filter design algorithm in FDATool, such as changing from Butterworth
to Maximally Flat, often changes the number of filter coefficients (the filter order), the
number of sections, or both. Also, the coefficients from the new design algorithm may not
work with your source code filter implementation.
If you change the design algorithm, verify that your filter structure and length are the
same after you redesign your filter, and that the coefficients will work with the filter you
implemented.
If you change the number of sections or the filter order, your filter will not work well
unless your filter algorithm implementation accommodates the changes.
This example writes filter coefficients to processor memory to replace the existing
coefficients. To perform this process, you need the names of the variables in which your
project stores the filter data.
Before you export coefficients directly to memory, verify that your project allocated
enough memory for the new filter coefficients. If your project allocated enough memory,
you can modify your filter in FDATool and then follow the steps in this example to export
the updated filter coefficients to the allocated memory.
If your new filter requires additional memory space, use a C header file to allocate
memory on the processor and export the new coefficients as described in “Exporting
Filter Coefficients to Your Code Composer Studio Project” on page 39-65.
39-72
Exporting Filter Coefficients from FDATool
Follow these steps to export filter coefficients from FDATool directly to memory on your
processor.
1 Load the program file that contains your filter into CCS IDE to activate the program
symbol table. The symbol must contain the global variables you use to store the filter
coefficients and length parameters.
2 Start FDATool.
3 Click Filter Manager to open the Filter Manager dialog, shown in the following
figure.
4 Highlight the filter to modify on the list of filters, and select Edit current filter.
The highlighted filter appears in FDATool for you to change.
If you did not store your filter from a previous session, design the filter in FDATool
and continue.
39-73
39 Working with Texas Instruments Code Composer Studio 3.3 IDE
Keep the export dialog open while you work. When you do so, the contents update as
you change the filter in FDATool.
Tip Click Generate to export coefficients to the same processor memory location
multiple times without reentering variable names.
8 In the Export to Code Composer Studio dialog:
For more information about how FDATool determines the data type to suggest, refer
to “How FDATool Determines the Export Suggested Data Type” on page 39-65.
11 If you know the board number and processor number of your target, enter
DSP Board # and DSP Processor # values to identify your board.
39-74
Exporting Filter Coefficients from FDATool
Note: When you have only one board or simulator, Embedded Coder sets
DSP Board # and DSP Processor # to your board automatically.
You can continue to export the filter, or cancel the export process. To prevent this
warning dialog from appearing, select Disable memory transfer warnings in the
Export to Code Composer Studio IDE dialog.
13 (Optional) Continue to optimize filter performance by modifying your filter in
FDATool and then export the updated filter coefficients directly to processor
memory.
14 When you finish testing your filter, return to FDATool, and click Store filter to save
your changes.
39-75
39 Working with Texas Instruments Code Composer Studio 3.3 IDE
Introduction
This tutorial shows you how to use the XMakefile feature in your MathWorks software
to build and run embedded software with Code Composer Studio 3.3 (CCSv3). For more
information about XMakefile, see “Makefiles for Software Build Tool Chains” on page
36-15
Note: The Embedded Coder IDE Project Generator feature is not available for CCSv3
in the current release. For more information about IDE Project Generator, see “IDE
Projects” on page 36-13
To build the target software, complete the process covered in this chapter:
Select and complete a configuration for Code Composer Studio 3.3 (CCSv3):
39-76
Using Makefiles with Code Composer Studio 3.x
1 Enter xmakefilesetup at the MATLAB command prompt. This action opens the
XMakefile User Configuration dialog.
2 Clear Display operational configurations only. This displays the configuration
files, including ones that need updated path information.
3 For Configurations, select a configuration that matches your target and ends with
ccsv3. Then click Apply.
4 If the configuration is incomplete, the software displays a series of Browse For
Folder dialoges that include instructions to provide missing information.
5 Examine the Tool Directories tab to see if the paths are right.
6 When you have supplied the missing information, and the configuration is complete,
click OK to close the XMakefile User Configuration dialog.
For example, to generate code for CCSv3 and a C6000 processor with DSP/BIOS:
39-77
39 Working with Texas Instruments Code Composer Studio 3.3 IDE
1 In the CCSv3, select File > New > Target Configuration File to display a New
Target Configuration dialog:
• For File name, update the file name that ends with .ccxml to describe your
project and hardware.
• Click Finish. This action displays a utility in the CCS editor pane for
customizing the target configuration file.
2 Use the utility to select the Connection and Device type. Typing a partial string
next to Device filters the list of devices.
3 Click Save.
Note: For more information about target configuration files, consult the Texas
Instruments documentation for CCSv3.
39-78
Using Makefiles with Code Composer Studio 3.x
Note: The path cannot contain spaces. Customize the installation directory when you
install CCSv3 so it does not contain spaces.
MathWorks provides an example JavaScript file, runProgram.js, for you to use with DSS.
This script loads and runs the specified program on the target specified in the target
configuration file. You can create a copy of this script and modify it to suit your needs.
The location of runProgram.js is:
[MATLABROOT]\toolbox\idelink\extensions\ticcs\ccsdemos
Replace targetConfigurationFile and programFile with paths and file names. For
example, if you are using a working directory called the CCSv3 workspace, and the model
name is myProgram, enter:
> dss runProgram.js c:\workspace\myC6416dsk.ccxml myProgram.out
This command builds and loads your software on the target or simulator.
You have completed the process of loading and running embedded software using
XMakefile and CCSv3.
39-79
39 Working with Texas Instruments Code Composer Studio 3.3 IDE
In this section...
“Example Programs Do Not Run Well with Incorrect GEL Files” on page 39-80
“Changing Values of Local Variables Does Not Work” on page 39-81
“Code Composer Studio Cannot Find a File After You Halt a Program” on page 39-81
“C54x XPC Register Can Be Modified Only Through the PC Register” on page 39-83
“Working with More Than One Installed Version of Code Composer Studio” on page
39-83
“Changing CCS Versions During a MATLAB Session” on page 39-84
“MATLAB Hangs When Code Composer Studio Cannot Find a Board” on page 39-84
“Using Mapped Drives” on page 39-85
“Uninstalling Code Composer Studio 3.3 Prevents Embedded Coder From Connecting”
on page 39-85
“PostCodeGenCommand Commands Do Not Apply to IDE Projects” on page 39-86
Some long-standing issues apply to the Embedded Coder product. When you are using
ticcs objects and the software methods to work with Code Composer Studio and
supported hardware or simulators, recall the information in this section.
The latest issues in the list appear at the bottom. HIL refers to “hardware in the loop,”
also called processor in the loop (PIL) here and in other applications, and sometimes
referred to as function calls.
Here are examples and boards which require specific GEL files.
39-80
Reported Limitations and Tips
Emulator: XDS-510
In general, if a example does not run with the default GEL file, try using a device-specific
GEL file by defining the file in the CCS Setup Utility.
This problem happens only with local variables. When you write to the local variable via
the Code Composer Studio Watch Window or via a MATLAB object, you are writing into
the variable's absolute location (register or address in memory).
However, within the processor function, the compiler sometimes saves the local variable's
values in an intermediate location, such as in another register or to the stack. That
intermediate location cannot be determined or changed/updated with a new value
during execution. Thus the compiler uses the old, unchanged variable value from the
intermediate location.
Code Composer Studio Cannot Find a File After You Halt a Program
When you halt a running program on your processor, Code Composer Studio may display
a dialog that says it cannot find a source code file or a library file.
When you halt a program, CCS tries to display the source code associated with the
current program counter. If the program stops in a system library like the runtime
library, DSP/BIOS, or the board support library, it cannot find the source code for debug.
You can either find the source code to debug it or select the Don't show this message
again check box to ignore messages like this in the future.
For more information about how CCS responds to the halt, refer the online Help for
CCS. In the online help system, use the search engine to search for the keywords
“Troubleshooting” and “Support.” The following information comes from the online help
for CCS, starting with the error message:
39-81
39 Working with Texas Instruments Code Composer Studio 3.3 IDE
The debugger is unable to locate the source file required to enable source-level debugging
for this program.
The Directories dialog enables you to specify the search path the debugger uses to find
the source files included in a project.
• Directories. The Directories list displays the defined search path. The
debugger searches the listed folders in order from top to bottom.
If two files have the same name and are located in different folders, the file
located in the folder that appears highest in the Directories list takes
precedence.
• New. To add a new folder to the Directories list, click New. Enter the full path
or click browse [...] to navigate to a folder. By default, the new folder is added to
the bottom of the list.
• Delete. Select a folder in the Directories list, then click Delete to remove
that folder from the list.
• Up. Select a folder in the Directories list, then click Up to move that folder
higher in the list.
• Down. Select a folder in the Directories list, then click Down to move that
folder lower in the list.
39-82
Reported Limitations and Tips
You can then read the XPC register value using regread.
Working with More Than One Installed Version of Code Composer Studio
When you have more than one version of Code Composer Studio installed on your
machine, you cannot select which CCS version MATLAB Embedded Coder attaches to
when you create a ticcs object. If, for example, you have both CCS for C5000 and CCS
for C6000 versions installed, you cannot choose to connect to the C6000 version rather
than the C5000 version.
IDE_obj = ticcs
Embedded Coder starts the CCS version you last used. If you last used your C5000
version, the IDE_obj object accesses the C5000 version.
Workaround
1 Start and close the CCS version you plan to use before you create the ticcs object in
MATLAB.
2 Create the ticcs object using the boardnum and procnum properties to select your
processor, if required.
Recall that ccsboardinfo returns the boardnum and procnum values for the
processors that CCS recognizes.
39-83
39 Working with Texas Instruments Code Composer Studio 3.3 IDE
• Abort — Closes CCS and suspends control for about 30 seconds. If you used MATLAB
software functions to open CCS, such as when you create a ticcs object, the system
returns control to MATLAB command window after a considerable delay, and issues
this warning:
39-84
Reported Limitations and Tips
One more option, Diagnostic, lets you enter diagnostic mode if it is enabled. Usually,
Diagnostic is not available for you to use.
Texas Instruments has documented this uninstall problem and the solution on their Web
site.
39-85
39 Working with Texas Instruments Code Composer Studio 3.3 IDE
Updated information on this issue may also be available from the Bug Reports section of
www.mathworks.com at http://www.mathworks.com/support/bugreports/379676
Use the 'Compiler options string' and 'Linker options string' parameters located in the
Configuration Parameters dialog (Ctrl+E) on the Code Generation > Coder Target pane
instead. You can also automate this process using a model callback to SET_PARAM the
'CompilerOptionsStr' and 'LinkerOptionsStr' parameters.
39-86
Setting Up Code Composer Studio (ert.tlc System Target File)
Otherwise, you have to create your own .ccxml file that matches the target hardware
and the connection. See “Create Target Configuration File in CCSv4/5” on page
39-87 to create your own .ccxml file (Target Configuration File) in CCSv4/5.
3 Build your embedded software by pressing CTRL+B.
Before loading and running your target software, use the CCSv4/5 IDE to create a “target
configuration file”. The TI Debug Server uses this file while it works with CCSv4/5 to
load and run your target software.
1 In the CCSv4/5, select File > New > Target Configuration File to display a New
Target Configuration dialog:
39-87
39 Working with Texas Instruments Code Composer Studio 3.3 IDE
• For File name, update the file name that ends with .ccxml to describe your
project and hardware.
• Click Finish. This action displays a utility in the CCSv4/5 editor pane for
customizing the target configuration file.
2 Use the utility to select the Connection and Device type. Typing a partial string
next to Device filters the list of devices.
3 Click Save.
39-88
IDE Link Frequently Asked Question: Why do I get an error when I invoke TICCS?
Example 1:
cc = ticcs
Example 2:
cc = ticcs
The following instructions show you how to register the components required by IDE
Link.
39-89
39 Working with Texas Instruments Code Composer Studio 3.3 IDE
Note: Before you register the components, you must have write permission to modify
the registry. If you do not have this permission, look for someone who has (e.g., system
administrator) and have this person perform the registration.
regsvr32 [MATLABROOT]\bin\win32\LinkCCS.dll
5 Verify that the preceding command displays the following message in a dialog box:
regsvr32 [MATLABROOT]\toolbox\idelink\extensions\ticcs\bin\win32\MWCCSStu.ocx
7 Verify that the preceding command displays the following message in a dialog box:
DllRegisterServer in [MATLABROOT]\toolbox\idelink\extensions\ticcs\bin\win32\MWCCSS
succeeded
After you register the components, enable the CCS component before using IDE Link.
1 Open MATLAB
2 Enter cc = ticcs at the MATLAB prompt. CCS starts and prompts that "New
components were detected".
3 Click Yes to enable components for compatible CCS releases. The first time CCS is
invoked (either through TICCS or directly), it detects new components and asks if
you want enable them. You see the following dialog:
Note: Click OK to enable the new component. For more information on ticcs or to see
this FAQ again, enter help ticcs at the MATLAB prompt. For your convenience these
instructions are available here.
39-90
IDE Link Frequently Asked Question: Why do I get an error when I invoke TICCS?
What happens if I click Deselect All when CCS prompts that 'New
components were detected'?
You will not be able to use IDE Link. The New Components dialog box appears only once.
To enable the components after you click 'Deselect All', use the CCS Component
Manager.
39-91
39-92
40
Set Up
Before you use Embedded Coder with Code Composer Studio (CCS IDE) for the
first time, use the checkEnvSetup function to check for third-party tools and set
environment variables. Run checkEnvSetup again whenever you configure CCS IDE to
interact with a new board or processor, or upgrade the related third-party tools.
To verify that CCSv3 is installed on your machine and has at least one board configured,
enter
ccsboardinfo
in the MATLAB Command Window. With CCS installed and configured, MATLAB
software returns information about the boards that CCS recognizes on your machine, in a
form similar to the following listing.
Board Board Proc Processor Processor
Num Name Num Name Type
--- -------------------------------- --- -------------
1 C6xxx Simulator (Texas Instrum .0 6701 TMS320C6701
0 C6x13 DSK (Texas Instruments) 0 CPU TMS320C6x1x
If MATLAB software does not return information about the boards, open your CCS
installation and use the Setup Utility in CCS to configure at least one board.
As a final test, start CCS to verify that it runs. For Embedded Coder to operate with
CCS, the CCS IDE must be able to run on its own.
40-2
Code Composer Studio
Feature Support
When you use Code Composer Studio 4 or Code Composer Studio 5 with Embedded Coder
software, you can use:
• Makefiles to automate building and deploying software to target hardware. For more
information, see “Makefiles for Software Build Tool Chains” and “Using Makefiles
with Code Composer Studio 4/5” on page 40-5.
• Processor-in-the-loop (PIL) simulations to verify your software running on target
hardware. For more information, see “PIL Simulation for IDE and Toolchain Targets”.
• Execution profiling with PIL to measure the performance of synchronous tasks
running on target hardware. For more information, see “Execution Profiling During
PIL Simulation”.
Features that require IDE projects (Build format = Project), such as IDE Project
Generator and IDE Automation Interface, are not available for use with Code Composer
Studio 4 & 5.
You can use CCSv4/5 with the Simulink Block Libraries for the following Texas
Instruments processors:
• TI’s C2000
• TI’s C5000
• TI’s C6000
40-3
40 Working with Texas Instruments Code Composer Studio 4 & 5 IDE
Getting Started
In this section...
“Verifying Your Code Composer Studio Installation” on page 40-4
“Learning About Makefiles” on page 40-4
For an example of using CCSv4/5 with makefiles, model-block PIL, and the Serial
Communications Interface (SCI), see “Performing a Model Block PIL Simulation via SCI
Using Makefiles”.
40-4
Using Makefiles with Code Composer Studio 4/5
Introduction
This tutorial shows you how to use the XMakefile feature in your MathWorks software
to build and run embedded software with Code Composer Studio 4 or 5 (CCSv4/5). For
more information about XMakefile, see “Makefiles for Software Build Tool Chains” on
page 36-15
Note: The Embedded Coder IDE Project Generator feature is not available for CCSv4/5
in the current release. For more information about IDE Project Generator, see “IDE
Projects” on page 36-13
To build the target software, complete the process covered in this chapter:
Select and complete a configuration for Code Composer Studio 4 & 5 (CCSv4/5):
40-5
40 Working with Texas Instruments Code Composer Studio 4 & 5 IDE
1 Enter xmakefilesetup at the MATLAB command prompt. This action opens the
XMakefile User Configuration dialog.
2 Clear Display operational configurations only. This displays the configuration
files, including ones that need updated path information.
3 For Configurations, select a configuration that matches your target and ends with
ccsv4 or ccsv5. Then click Apply.
4 If the configuration is incomplete, the software displays a series of Browse For
Folder dialoges that include instructions to provide missing information.
5 Examine the Tool Directories tab to see if the paths are right.
6 When you have supplied the missing information, and the configuration is complete,
click OK to close the XMakefile User Configuration dialog.
For example, to generate code for CCSv4/5 and a C6000 processor with DSP/BIOS:
40-6
Using Makefiles with Code Composer Studio 4/5
1 In the CCSv4/5, select File > New > Target Configuration File to display a New
Target Configuration dialog:
• For File name, update the file name that ends with .ccxml to describe your
project and hardware.
• Click Finish. This action displays a utility in the CCSv4/5 editor pane for
customizing the target configuration file.
2 Use the utility to select the Connection and Device type. Typing a partial string
next to Device filters the list of devices.
3 Click Save.
Note: For more information about target configuration files, consult the Texas
Instruments documentation for CCSv4/5.
40-7
40 Working with Texas Instruments Code Composer Studio 4 & 5 IDE
Note: The path cannot contain spaces. Customize the installation directory when you
install CCSv4/5 so it does not contain spaces.
[MATLABROOT]\toolbox\idelink\extensions\ticcs\ccsdemos
The syntax for running dss.bat with runProgram.js using XMakefile Configuration is:
For example, to automate, load, and run an embedded software on C2000 processor with
CCSv4/5 using xmakefile configuration, the steps are as follows:
1 Enter
xmakefilesetup
on the [MATLAB] command prompt.
2 In the XMakefile User Configuration dialog box, clear Display operational
configurations only check box.
3 Select ticcs_c2000_ccsv4 or ticcs_c2000_ccsv5 in Configuration parameter.
4 Click Apply.
5 Create a new Configuration as explained in the section, “Creating a New XMakefile
Configuration”.
6 Select Execute tab. In this tab, enter values for the syntax
40-8
Using Makefiles with Code Composer Studio 4/5
When you enter the filepath, use double quotes or double back-slashes.
For example:
[MATLABROOT]\\toolbox\\idelink\\extensions\\ticcs\\ccsdemos\
\runProgram.js
C:\\ccsv4\\CCSTargetConfigurations\\ezdsp28335.ccxml
[|||MW_XMK_GENERATED_TARGET_REF[E]|||]
or
“[MATLABROOT]\toolbox\idelink\extensions\ticcs\ccsdemos\runProgram.js"
"C:\ccsv4\CCSTargetConfigurations\ezdsp28335.ccxml"
[|||MW_XMK_GENERATED_TARGET_REF[E]|||]
You have completed the process of loading and running the embedded software using
XMakefile on the target or simulator.
The syntax for running dss.bat with runProgram.js using Windows command prompt is:
> dss runProgramFile targetConfigurationFile programFile
This command loads and runs the embedded software on the target or simulator.
40-9
40 Working with Texas Instruments Code Composer Studio 4 & 5 IDE
Troubleshooting DSS
With Code Composer Studio 4 & 5, using runProgram.js to download and run the
generated program file can produce an error message similar to:
SEVERE: Could not open session. Found 2 devices matching: .*
Spectrum Digital DSK-EVM-eZdsp onboard USB Emulator_0/C64XP_0
Spectrum Digital DSK-EVM-eZdsp onboard USB Emulator_0/IcePick_C_0
If this happens, specify one of the devices in line 65 in runProgram.js. For example:
debugSession = debugServer.openSession(".*C64XP.*");
Alternatively, to connect to the first board & CPU detected, use ("*","*") in line 65.
For example:
debugSession = debugServer.openSession("*","*");
To use advanced DSS features, you can also use the CCSv4/5 example batch file,
loadti.bat, as follows:
Replace programFile with the name of the .out created using the XMakefile feature.
For example:
> loadti -a -c=c:\workspace\myC6416dsk.ccxml myProgram.out
For more information about loadti and its options, type the following on your system
command prompt
> loadti -help
40-10
Reported Limitations and Tips
Here are examples and boards which require specific GEL files.
Emulator: XDS-510
In general, if a example does not run with the default GEL file, try using a device-specific
GEL file by defining the file in the CCSv4/5 Setup Utility.
Use the 'Compiler options string' and 'Linker options string' parameters located in the
Configuration Parameters dialog (Ctrl+E) on the Code Generation > Coder Target
pane instead. You can also automate this process using a model callback to SET_PARAM
the 'CompilerOptionsStr' and 'LinkerOptionsStr' parameters.
40-11
40-12
41
Go to the vendor Web sites to find 64-bit compatible drivers for installing CCSv3 on
64-bits machine with drivers such as, Spectrum Digital Emulators or BlackHawk
Emulators. Most vendors have 64-bit drivers that are compatible with CCSv3.
For more information about Embedded Coder support with idelink_ert.tlc, see
“Code Composer Studio” on page 39-3.
For more information about Embedded Coder support for CCSv3 and CCSv4/5 with
ert.tlc, see “Setting Up Code Composer Studio (ert.tlc System Target File)”.
41-2
Install Support for C2000 Processors
1 Install TI CCS.
2 Install TI Service Release for CCS.
3 Install the TI Code Generation Tools for Windows.
4 If you are using a Spectrum Digital board, download and install the matching
Spectrum Digital Driver.
5 If you are using RTDX for C28x host/target communications, download and install TI
DSP/BIOS.
6 If you program flash memory with standalone code, download the TI Flash API for
your target hardware.
1 In CCSv3, open Help > About > Component manager > Build tools >
TMS320C28XX and select (check) C2000 Code Generation Tools .
2 With the Component manager open, open Target Content (DSP/BIOS) >
TMS320C28XX and select Texas Instruments DSP/BIOS.
3 Save, exit, and restart CCSv3.
Before you install the software, if you install the Texas Instruments (TI) Code Composer
Studio CCSv3 on Windows 7, then, make sure that:
Using this installation process, you download and install the following items on your host
computer:
41-3
41 Working with Texas Instruments C2000 Processors
• Related examples.
Note Before you generate code for Texas Instruments processors, you must
configure your environment by creating the system environment variables used
by code generation software. To configure your environment type, execute the
function checkEnvSetup in MATLAB Command Window. To know more on
checkEnvSetup, see “checkEnvSetup”.
Note You can also use targetupdater function in the MATLAB command window to
install/update the latest third party software for the support package.
41-4
Install Support for C2000 Processors
If you do not see the listed libraries, or MATLAB does not recognize the command, install
the Embedded Coder software. Without the software, you cannot use Simulink and
Simulink Coder software to develop applications targeted to the TI boards.
To verify that Code Composer Studio 3.3 (CCSv3) is present on your machine, enter this
command at the MATLAB prompt:
ccsboardinfo
With CCSv3 installed and configured, MATLAB returns a list of the boards that CCSv3
recognizes on your machine like the following example:
Board Board Proc Processor Processor
Num Name Num Name Type
--- ---------------------------------- ---
1 F2812 Simulator 0 CPU TMS320C28xx
0 F2812 PP Emulator 0 CPU_1 TMS320C28xx
If MATLAB does not return information about boards, revisit the installation and setup
instructions in your CCSv3 documentation. If you have not done so already, install the
third-party “Board Support Packages” for your boards.
As a final test, launch CCSv3 to verify that it runs. For Embedded Coder software to
operate with CCSv3, the CCSv3 IDE must be able to run on its own.
Note: For a model to work in the targeting environment, select the discrete-time solver
in the Solver pane of the Simulink Configuration Parameters dialog. Targeting does not
work with continuous-time solvers.
41-5
41 Working with Texas Instruments C2000 Processors
If you select int8 or uint8 in your model, your simulation runs with 8-bit data, but in
the generated code, that data will be represented as 16-bit. This may cause instances
where data overflow and wraparound occurs in the simulation, but not in the generated
code.
For example, to make the overflow behavior of the simulation and generated code match
for a Simulink Add block in your model, select Saturate on integer overflow in that
block.
41-6
Scheduling and Timing
Overview
Normally the code generated by Embedded Coder software runs in the context of a timer
interrupt. Model blocks run in a periodical fashion clocked by the periodical interrupt
whose period is tied to the base sample time of the model.
This execution scheduling model, however, is not flexible enough for many systems,
especially control and communication systems, which must respond to external events in
real time. Such systems require the ability to handle various hardware interrupts in an
asynchronous fashion.
Embedded Coder software lets you model and generate code for such systems by creating
tasks driven by Hardware Interrupt blocks in addition to the tasks that are left to be
handled in the context of the timer interrupt.
The timer is configured so that the model's base rate sample time corresponds to the
interrupt rate. The timer period and prescaler are calculated and set up to produce the
desired rate as follows:
TimerPeriod
BaseRateSampleTime =
TimerClockSpeed
The minimum achievable base rate sample time depends on the model complexity.
The maximum value depends on the maximum timer period value (232-1 for the F2812,
41-7
41 Working with Texas Instruments C2000 Processors
F2808, and F28x35) and the CPU clock speed. The CPU clock speed is 100 MHz for the
F2808, and 150 MHz for the F2812 and F28335.
If the blocks in the model inherit their sample time value, and a sample time is not
explicitly defined, the default value is 0.2 s.
The Event Managers and their general-purpose timers, which drive PWM waveform
generation use the high-speed peripheral clock (HISCLK). By default, this clock is
selected in Embedded Coder software. This clock is derived from the system clock
(SYSCLKOUT):
HISCLK = [SYSCLKOUT / (high-speed peripheral prescaler)]
The high-speed peripheral prescaler is determined by the HSPCLK bits set in SysCtrl.
The default value of HSPCLK is 1, which corresponds to a high-speed peripheral
prescaler value of 2.
Asynchronous Scheduling
This example shows how to use the c28x peripherals and Hardware Interrupt blocks to
control the execution of function-call subsystems in an asynchronous fashion.
Required Hardware:
41-8
Scheduling and Timing
Model
Description
The EV Timer blocks are used to configure timer interrupts to be raised on period
match. Hardware Interrupt block installs the ISRs for the timer interrupts as well as
for an eCAN message receive interrupt. The ISRs in turn call function-call subsystems
connected to the Hardware Interrupt block output ports.
The outputs of first two subsystems are running counters. Their sum is used to control
the duty cycle of the PWMB for F2812 or ePWM2 for F2808/F28335. The PWM waveform
duty cycle increases linearly from 0 to 100 %.
The third subsystem contains an eCAN Rcv block whose message output drives a PWM
block (PWMA for F2812 or ePWM1 for F2808/F28335) to control its duty cycle. The duty
cycle varies from 0 to 100 % as the eCAN messages are received from an eCAN Xmt
block.
NOTE: The Self-Test mode of eCAN_A is enabled to connect eCAN_A tranmitter and
receiver internally to avoid external connection between transmitter and receiver.
Disabling the Self-Test mode for eCAN_A requires tranmitter and receiver to be
connected together externally.
41-9
41 Working with Texas Instruments C2000 Processors
The following sections explain how to configure, build, and deploy the executable.
• Open the model corresponding to the family of processor you are using.
• Go to Peripherals > eCAN_A and check Self-Test Mode.
• Click Incremental build to generate, build, load and run the program.
• Observe the PWM waveform on the oscilloscope.
CCSv4 support is provided via a makefile based approach. This requires running
xmakefilesetup to set the environment. You can ignore the following if you have
already gone through these steps. For more information, please refer to the Xmakefile
Documentation
• Open the model corresponding to the family of processor you are using.
• Open the Coder Target pane. Under the Target Hardware Resources tab, set the IDE/
Tool chain parameter to
41-10
Scheduling and Timing
CCSv5 support is provided via a makefile based approach. This requires running
xmakefilesetup to set the environment. You can ignore the following if you have
already gone through these steps. For more information, please refer to the Xmakefile
Documentation
• Open the model corresponding to the family of processor you are using.
• Open the Coder Target pane. Under the Target Hardware Resources tab, set the
IDE/Tool chain parameter to Texas Instruments Code Composer Studio v5
(makefile generation only).
41-11
41 Working with Texas Instruments C2000 Processors
41-12
Sharing General Purpose Timers between C281x Peripherals
In this section...
“Sharing General Purpose Timers between CAP and eCAN” on page 41-14
“Sharing General Purpose Timers between CAP and SPI” on page 41-17
TMS320x281x DSP devices have four General Purpose (GP) timers. Each Event Manager
(EV) module includes two GP timers:
You can use the GP Timers independently or to operate peripherals associated with the
EV Manager, such as PWM, QEP, and CAP.
The following table describes the timer-peripheral mapping of the c281xlib block library.
Each PWM and QEP peripheral has access to only one timer, while each CAP peripheral
has access to two timers. In the PWM and QEP blocks, you can set the Module option
to A or B to determine which unique timer-peripheral combination the block configures.
By comparison, in the CAP block, you can use the Time base option to select one of two
timers for each CAP peripheral.
41-13
41 Working with Texas Instruments C2000 Processors
The PWM, QEP, CAP, and Timer blocks each provide independent access to key timer
registers. If the blocks in your model share a specific GP timer, check that the timer-
related settings are compatible. If the peripheral settings for a shared timer are not
compatible, the software generates an error when you update the model or generate code.
The model contains Timer and CAP blocks that both use Timer 1 (GP Timer 1).
41-14
Sharing General Purpose Timers between C281x Peripherals
41-15
41 Working with Texas Instruments C2000 Processors
Both blocks have the same values for Timer prescaler and Counting mode. However,
each block has different values for Timer period. The value of Timer period for Timer
1 is 65535 in the CAP block and 10000 in the Timer block.
41-16
Sharing General Purpose Timers between C281x Peripherals
Since both blocks configure the same timer, and settings conflict, the software generates
an error when you update the model.
41-17
41 Working with Texas Instruments C2000 Processors
The model contains QEP and CAP blocks that both use Timer 2. In the CAP block, the
Time base option shows which timer the block uses. In the QEP block, setting Module
to A configures the block to use QEP1–QEP2. GP Timer Use for C281x Peripheral Blocks
shows that QEP1–QEP2 use Timer 2.
41-18
Sharing General Purpose Timers between C281x Peripherals
41-19
41 Working with Texas Instruments C2000 Processors
Currently, both blocks define different clock sources for Timer 2. The CAP block uses
Internal as a Clock source. The QEP block, which does not have a configurable
Clock source setting, uses the QEP circuit as a clock source. If you build the model, the
software generates the following error message.
To avoid generating errors when you build the model, change Clock source in the CAP
block to QEP device.
41-20
Overview of Creating Models for C2000 Processors
In this section...
“Accessing the Embedded Coder Block Library” on page 41-21
“Building Your Model” on page 41-21
You can open the c2000lib blockset in the Simulink library browser, or by typing the
following command at the MATLAB command prompt:
c2000lib
Create your real-time model for your application the same way you create other Simulink
models. Select blocks to build your model from the following sources or products:
• The libraries in the c2000lib block library (for handling input and output functions
for on your target hardware)
• Simulink Coder software
• Discrete time blocks from Simulink
• Another blockset that meets your needs and operates in the discrete time domain
During the same build operation, block parameter dialog entries are combined into a
project file for CCS for your TI C2000 board. If you selected the Build and execute
build action in the configuration settings, the TI cross-compiler builds an executable file.
After automatically downloading the executable file to the target, the build process runs
the file on the board's DSP.
41-21
41 Working with Texas Instruments C2000 Processors
Note: After using the run-time Build option to generate and build code for your
application, you must perform the following reset sequence before you can run that
code on your board. If you want to rerun your application manually once it has been
generated, you must also use this procedure.
41-22
Using the c2000lib Blockset
Introduction
This section uses an example to show how to create a Simulink model that uses
Embedded Coder blocks to target your board. The example creates a model that performs
PWM duty cycle control via pulse width change. It uses the C2812 ADC block to sample
an analog voltage and the C2812 PWM block to generate a pulse waveform. The analog
voltage controls the duty cycle of the PWM and you can observe the duty cycle change on
the oscilloscope. This model is also provided in the Examples library. The model in the
Examples library also includes a model simulation.
Hardware Setup
The following hardware is required for this example:
1 Connect the function generator output to the ADC input ADCINA0 on the eZdsp
F2812.
2 Connect the output of PWM1 on the eZdsp F2812 to the analog input of the
oscilloscope.
3 Connect VREFLO to AGND on the eZdsp F2812. See the section on the Analog
Interface in Chapter 2 of the eZdsp™ F2812 Technical Reference, available from the
Spectrum Digital Web site at http://c2000.spectrumdigital.com/ezf2812/
41-23
41 Working with Texas Instruments C2000 Processors
This command open the c2000lib library blockset, which contains libraries of blocks
designed for targeting your board.
Note: Generated code does not honor Simulink stop time from the simulation. Stop
time is interpreted as inf. To implement a stop in generated code, you must put a
Stop Simulation block in your model.
3 From your model's main menu, select Simulation > Model Configuration
Parameters to verify and set the simulation parameters for this model. Parameters
you set in this dialog belong to the model you are building. They are saved with
41-24
Using the c2000lib Blockset
the model and stored in the model file. Refer to your Simulink documentation for
information on the Configuration Parameters dialog.
4 Use the Code Generation pane to set options for the real-time model.
5 Use the Browse button to locate and select a target configuration
file, idelink_grt.tlc, idelink_ert.tlc, or ert.tlc. When you
selectidelink_grt.tlc or idelink_ert.tlc, your coder product chooses the
system target file, and make command.
When you select ert.tlc, the Target hardware parameter and the Toolchain
parameter are displayed. Select TI 281x as Target hardware and Texas
Instruments Code Composer Studio v5 (c2000) for Toolchain.
41-25
41 Working with Texas Instruments C2000 Processors
There are three ways to start the automatic code generation process:
41-26
Using the c2000lib Blockset
Note: For idelink_ert.tlc with CCSv3, you see your project with the files in place in
the folder structure.
41-27
41 Working with Texas Instruments C2000 Processors
In this section...
“The CAN Blocks” on page 41-28
“Setting Timing Parameters” on page 41-28
“Parameter Tuning and Signal Logging” on page 41-33
To set the Bitrate for a block whose bitrate cannot be set directly:
For example, the Target Hardware Resources tab for the F2812 eZdsp, this dialog is
shown in the following figure.
41-28
Configuring Timing Parameters for CAN Blocks
41-29
41 Working with Texas Instruments C2000 Processors
The following sections describe the series of steps and rules that govern the process of
setting these timing parameters.
41-30
Configuring Timing Parameters for CAN Blocks
To determine the values for the timing parameters, complete the following steps:
• CAN module clock = 100 MHz for the F2808 (Same as SYSCLKOUT)
• CAN module clock = 150 MHz for the F2812 (Same as SYSCLKOUT)
• CAN module clock = 75 MHz for the F28x3x (150 SYSCLKOUT/2)
3 Estimate the value of the BaudRatePrescaler (BRP).
4 Solve this equation for BitTime:
The following illustration shows the relationship between the eCAN bit timing
parameters.
41-31
41 Working with Texas Instruments C2000 Processors
Assume that CAN Module Clock Frequency = 75 MHz, and a Bitrate of 1 Mbits/s is
required.
1 Set the BRP to 5. Then substitute the values of CAN Module Clock Frequency, BRP,
and Bitrate into the following equation, solving for BitTime:
41-32
Configuring Timing Parameters for CAN Blocks
4 When the chosen values satisfy the criteria, so further iteration is not required.
The following table provides example values for several bit rates when CAN Module
Clock Frequency = 75 MHz, as it is with the F28335. Other combinations of the register
values are possible.
The following table provides example values for several bit rates when CAN Module
Clock Frequency = 100 MHz, as it is with the F2808. Other combinations of the register
values are possible.
The following table provides example values for several bit rates when CAN Module
Clock Frequency = 150 MHz, as it is with the F2812. Other combinations of the register
values are possible.
41-33
41 Working with Texas Instruments C2000 Processors
Overview
Embedded Coder software supports parameter tuning and signal logging either using
Simulink External mode or with a third party calibration tool. In both cases the model
must include a CAN Calibration Protocol block.
The Simulink External mode feature enables you to log signals and tune parameters
without requiring a calibration tool. This section describes the steps for converting a
model to use External mode.
External mode is supported using the CAN Calibration Protocol block and ASAP2
interface. The CAN Calibration Protocol block is used to communicate with the target,
download parameter updates, and upload signal information. The ASAP2 interface is
used to get information about where in the target memory a parameter or signal lives.
Note: You must configure the host-side CAN application channel. See “Configuring the
Host Vector CAN Application Channel” on page 41-35.
For information about visualizing logged signal data, see “Viewing and Storing
Signal Data” on page 41-37.
4 Load the Simulink.Parameter or canlib.Parameter and canlib.Signal data
objects into the base workspace.
5 Configure the model for building, as described in “Manual Configuration For
External Mode” on page 41-40.
6 Build the model, and download the executable to the target
41-34
Configuring Timing Parameters for CAN Blocks
7 After downloading the executable to the target, you can switch the model to External
mode, as described in “Manual Configuration For External Mode” on page 41-40.
8 You can now connect to the target using External mode by clicking the Connect
button.
9 If you have set up tunable parameters, you can now tune them. See “Tuning
Parameters” on page 41-37.
External mode expects that the host-side CAN connection is using the 'MATLAB 1'
application channel. To configure the application channel used by the Vector CAN
drivers, enter the following in the MATLAB Command Window:
TargetsComms_VectorApplicationChannel.configureApplicationChannels
The Vector CAN Configuration tool appears. Use this tool to configure your host-side
CAN channel settings.
If you try to connect using an application channel other than 'MATLAB 1', then you see
the following warning in the command window:
Warning:
It was not possible to connect to the target using CCP.
An error occurred when issuing the CONNECT command.
If you have not already installed the Vector CAN drivers, you will get the following error
message:
??? Error using ==>
TargetsComms_VectorApplicationChannel.TargetsComms_VectorApplicationChannel>
TargetsComms_VectorApplicationChannel.configureApplicationChannels at 40
Unable to launch the application channel configuration utility.
The "vcanconf" utility was not found on the Windows System Path.
To fix this error, make sure the required CAN drivers are installed on this computer;
refer to the product documentation for details.
41-35
41 Working with Texas Instruments C2000 Processors
If you want to use CAN to transmit or receive CAN messages between your host PC
and your target, you require Vector-Informatik CAN hardware supported by the Vector
CAN Driver Library. Choose the driver libraries to support profiling, downloading, and
External mode.
Note: For CANcaseXL, install both the Vector XL-driver library and Vector CAN Driver
Library vcand32.dll.
For older CAN hardware, you must install the Vector CAN Driver Library vcand32.dll.
Make sure that the library, vcand32.dll, is placed in the Windows system32 folder.
Using Supported Objects and Data Types
Supported objects:
• uint8, int8
• uint16, int16
• uint32, int32
• single
You need to define data objects for the signals and parameters of interest for ASAP 2 file
generation. For ease of use, create a MATLAB file to define the data objects, so that you
only have to set up the objects once.
41-36
Configuring Timing Parameters for CAN Blocks
stepSize.Value = 1;
2 Associate the signals to be logged with canlib.Signal objects. It is important to set
the data type of the canlib.Signal. The following code example shows how to declare
such a canlib.Signal object for logging:
counter = canlib.Signal;
counter.DataType = 'uint8';
3 Associate the data objects you defined in the MATLAB file with parameters or
signals in the model. For the previous code examples, you could set the Constant
value in a Source block to stepSize, and set a Signal name to counter in the
Signal Properties dialog. Remember that stepSize and counter are data objects
defined in the code.
Tuning Parameters
Simulink.Parameter (handle)
CoderInfo: [1x1 Simulink.ParamCoderInfo]
Description: ''
DataType: 'uint8'
Min: []
Max: []
DocUnits: ''
Value: 2
Complexity: 'real'
Dimensions: [1 1]
2 Return to your model, and update the model (press Ctrl+D) to apply the changed
parameter.
To view the logged signals, attach a supported scope type to the signal (see “Limitations”
on page 41-41 for supported scope types).
41-37
41 Working with Texas Instruments C2000 Processors
1 In the Simulink Editor, select Code > External Mode Control Panel.
2 In External Mode Control Panel, click the Signal & Triggering button.
3 In External Signal & Triggering, clear the check boxes for scope data you do not
want to log.
Storing signal data for further analysis. It is possible to store the logged data for
further analysis in MATLAB.
1 To use the Data Archiving feature of External mode, click Data Archiving in the
External Mode Control Panel. The External Data Archiving dialog appears.
41-38
Configuring Timing Parameters for CAN Blocks
41-39
41 Working with Texas Instruments C2000 Processors
3 You may want to edit the Variable name in the edit box. The data that is displayed
on the scope at the end of the External mode session is available in the workspace
with this variable name.
The data that was previously displayed in the scope is stored in .mat files as
previously setup using Data Archiving.
For example, at the end of an External mode session, the following variable and files
could be available in the workspace and current folder:
ScopeData5
ScopeData5 =
ExternalMode_0.mat
ExternalMode_2.mat
ExternalMode_1.mat
You can configure models manually for build and execution with External mode.
41-40
Configuring Timing Parameters for CAN Blocks
6 In the Configuration Parameters dialog, open the Code Generation > Interface
pane.
7 Set the Interface parameter to ASAP2.
After you build the model, you can configure it for External mode execution:
2 In the Configuration Parameters dialog, open the Code Generation > Interface
pane.
3 Set the Interface parameter to External mode.
Limitations
Only the following kinds of scopes are supported with External mode Logging:
41-41
41 Working with Texas Instruments C2000 Processors
Before connecting to External mode, you also need to right-click the signal, and select
Signal Properties. In the dialog, select the Test point check box, and click OK.
Subsystem builds are not supported for External mode, only top-level builds are
supported.
Logging and tuning of nonscalars is not supported. It is possible to log nonscalar signals
by breaking the signal down into its scalar components. For an example of how to do
this signal deconstruction, see the CCP example models, which use a Demux and Signal
Conversion block with contiguous copy.
Logging and tuning of complex numbers is not supported. It is possible to work with
complex numbers by breaking the complex number down into its real and imaginary
components. This breakdown can be performed using the following blocks in the
Simulink Math Operations library: Complex to Real-Imag, Real-Imag to Complex,
Magnitude-Angle to Complex, Complex to Magnitude-Angle.
Embedded Coder allows an ASAP2 data definition file to be generated during the code
generation process. This file can be used by a third party tool to access data from the
real-time application while it is executing.
Before you begin generating ASAP2 files with Embedded Coder software, see
“Generating an ASAP2 File” in the product help for Simulink Coder. That section
describes how to define the signal and parameter information required by the ASAP2 file
generation process.
41-42
Configuring Timing Parameters for CAN Blocks
The build process creates an ASAM-compliant ASAP2 data definition file for the
generated C code.
• The standard ASAP2 file generation does not include the memory address attributes
in the generated file. Instead, it leaves a placeholder that must be replaced with the
actual address by postprocessing the generated file.
• The map file options in the template project need to be set up a certain way for this
procedure to work. If you have created your own template projects, and you do not
have the right settings, you see the following instructions:
Warning: It was not possible to do ASAP2 processing on your
.map file.This is because your IDE project template is not
configured to generate a .map file in the correct format.
To generate a .map file in the correct format you need to
setup the following options in your IDE project template:
Generate section map should be checked on
Generate register map should be checked off
Generate symbol table should be checked on
Format list file into pages should be checked off
Generate summary should be checked off
Page width should be equal to 132 characters
Symbol colums should be 1
You can change these options via Project -> Project Options
-> Linker/Locator -> Map File -> Map File Format.
Embedded Coder software performs this postprocessing for you. To do this, it first
extracts the memory address information from the map file generated during the
link process. Secondly, it replaces the placeholders in the ASAP2 file with the actual
memory addresses. This postprocessing is performed automatically and does not require
additional input from you.
41-43
41 Working with Texas Instruments C2000 Processors
Required Hardware:
To open the model, enter the model name in the MATLAB Command Window.
41-44
ADC-PWM Synchronization via ADC Interrupt
This model shows how to use the ADC block to sample an analog voltage and how to
use the PWM block to generate a pulse waveform. The analog voltage controls the duty
cycle of the PWM waveform. Duty cycle changes can be observed on the oscilloscope.
"Hardware Interrupt" installs an Interrupt Service Routine (ISR) for ADC interrupt and
schedules the execution of the connected subsystem (ADC-PWM Subsystem) when ADC
interrupt (ADCINT) is received.
"ADC-PWM Subsystem" consists of an ADC driving the duty cycle input port of the
PWM. PWM is configured to trigger ADC start of conversion (SOC).
Before using the model, connect the function generator output to the ADC input
ADCINA0 on the board. Connect the output of the PWM1 to the analog input of the
oscilloscope.
41-45
41 Working with Texas Instruments C2000 Processors
• Open the model that corresponds to the processor family you are using.
• Open the Target Hardware Resources tab, as described in “Configure Target
Hardware Resources”, and set the IDE/Tool chain parameter to Texas
Instruments Code Composer Studio v4 (makefile generation only).
41-46
ADC-PWM Synchronization via ADC Interrupt
41-47
41 Working with Texas Instruments C2000 Processors
• Click Incremental build or press Ctrl+b to generate and build an .out executable
file.
• Using CCSv5, connect to your board, load and run the .out file.
• Observe the PWM waveform on the oscilloscope.
41-48
Configuring Acquisition Window Width for ADC Blocks
In this section...
“What Is an Acquisition Window?” on page 41-49
“Configuring ADC Parameters for Acquisition Window Width” on page 41-51
41-49
41 Working with Texas Instruments C2000 Processors
Ideally, as soon as the measurement window is opened, the actual signal coming in
would be measured perfectly. In reality the signal does not reach its full magnitude
immediately. The measurement process can be modeled by a circuit similar to the one
shown in the following figure for the ADC found on the F2812 eZdsp
41-50
Configuring Acquisition Window Width for ADC Blocks
Acquisition
Actual Signal Window
Width
Because the signal acquisition is not instantaneous, it is very important to set a wide
enough acquisition window to allow the signal to ramp up to full strength before the
measurement is taken. If the window is too narrow, the measurement is taken before
the signal has reached its full magnitude, resulting in erroneous data. If the window is
too wide, the source signal itself may change, and the sampling may be too infrequent
to reflect the actual value, also resulting in erroneous data. You must calculate the
width of the acquisition window based on the circuit characteristics of resistance and
capacitance of your specific circuit. Then, using the ADC parameters described in the
following section, you can configure the acquisition window width.
The ADC parameters can be set from the Peripherals tab of the Target Hardware
Resources tab.
• You can set ACQ_PS — Acquisition Prescaler — to a value from 0 to 15. To obtain the
actual value, increment the setting by 1. This produces an actual range from 1 to 16.
• You can set ADCLKPS — AD Clock Prescaler — to a value from 0 to 15. To obtain
the actual value, increment the setting by 1. This produces an actual range from 1 to
16.
41-51
41 Working with Texas Instruments C2000 Processors
• You can set CPS — Clock Prescaler — to a value from 0 to 1. To obtain the actual
value, increment the setting by 1. This produces an actual range from 1 to 2.
These three prescalers serve to reduce the speed of the clock and to set the acquisition
window width. The following diagram shows how these prescalers are used.
41-52
Configuring Acquisition Window Width for ADC Blocks
ADCLKPS CPS
1 - 16
(4 bit clock ACQ_PS
divider) CPS
ADCCLK -
HISPCLK this is the
(high speed CPS - ADC clock
peripheral further reduces signal
clock) ADCLKPS - the clock
reduces the frequency by a
incoming clock factor of 1 or 2 ACQ_PS -
frequency by a Acquisition
factor of 1 to 16 Prescaler -
indicates Sample
how many Hold
ADCCLK clock
ticks will pulse
comprise
the window
In the preceding diagram, the high speed peripheral clock frequency is received and then
divided by the ADCLKPS. The reduced clock frequency is then further divided by CPS.
The resulting frequency is the ADCCLK signal. The value of ACQ_PS then determines
how many ADCCLK ticks comprise one S/H (sample and hold) period, or in other words,
the length of the acquisition window.
The following examples show how you can use ADC parameters to configure the
acquisition window width:
Example 1:
If the HISPCLK = 30 MHz, and ADCLKPS=1 (which is a value of 2), the result is 15
MHz.
If ACQ_PS = 0 (which is a value of 1), then the sample/hold period is 1 ADCCLK tick,
or .1333 microseconds.
Example 2:
41-53
41 Working with Texas Instruments C2000 Processors
If the HISPCLK = 30 MHz, and ADCLKPS=1 (which is a value of 2), the result is 15
MHz.
Note: HISPCLK is set automatically for the user, and it is not possible to change the
rate. For more information, see “High-Speed Peripheral Clock” on page 41-8
41-54
Real-Time Data Exchange via RTDX™
The Real-Time Data Exchange via RTDX supports only Code Composer Studio v3.3.
Required Hardware:
This example can be run on different boards by changing the processor selection on the
Target Hardware Resources tab of the model: c28x_rtdxtest
Model
41-55
41 Working with Texas Instruments C2000 Processors
Description
The first step to run this example is to generate code for the model and to build it to run
on the target. Once the model is running, we use a MATLAB script to read the sine wave
values from the channel specified by the "To RTDX" block and plot them. To change the
frequency and amplitude of the sine wave while it is running on the target, we use the
same MATLAB script to write data to the channels specified by the "From RTDX" blocks.
Note that the RTDX™ channel names specified in the RTDX blocks in the Simulink
model are the same channel names used in the MATLAB script. Open the example script
to see the specific MATLAB code used to establish RTDX communication.
41-56
SPI-Based Control of PWM Duty Cycle
Required Hardware:
Note: This model only runs with Code Composer Studio v3.3
Model
41-57
41 Working with Texas Instruments C2000 Processors
Description
Memory Copy block labeled "Read Duty Cycle" reads duty cycle value stored at the
memory location 0x8FF0. "C28xx SPI Transmit" block transmits this value, while "C28xx
SPI Receive" receives it. The duty cycle value is then sent to the PWM1. The duty cycle
of the generated pulse waveform is determined by the relative ratio of the received pulse
width value and the pulse period which is fixed at 64000 clock cycles. The duty cycle
toggles between 25%, 50%, and 75% based on user selection.
PWM Duty Cycle can be changed while the generated code is running using write
function. This method writes selected value to the memory location 0x8FF0. Select either
25%, 50%, or 75% value from the GUI that opens up when "Build/Reload & Run" is
pressed.
'Enable loopback' mode is checked for 'SPI_A' on the peripherals tab of the Target
Hardware Resources tab. This is required to get the transmitted data back to the
processor. If this mode is disabled, SPI_A tranmitter and receiver have to be connected.
Note that "Simulate Duty Cycle Change" and "Simulate PWM Waveform" are dedicated
to simulation only. Use these blocks to simulate and observe effects achieved with the
generated code.
41-58
SPI-Based Control of PWM Duty Cycle
Hardware Connections
Connect the output of PWM1 on the board to the analog input of the oscilloscope.
Note that SPI module is set to work in "loopback" mode. External SPI hardware is not
needed. As an alternative, the user may disable SPI loopback mode and bridge SPI
transmit and receive pins on each of the following:
• Open the model corresponding to the family of processor you are using.
• Each model is configured for a default processor, open the Target Hardware Resources
tab to select a different processor.
• Go to Peripherals > SPI_A. Check Enable loopback. If your processor is F2803x/
F2806x, select GPIO16 for SOMI pin assignment and GPIO17 for SIMO pin
assignment.
• Click Build/Reload & Run to generate, build, load and run the program.
• Select a new duty cycle value in the dialog that opens.
• Observe the PWM waveform on the oscilloscope.
41-59
41 Working with Texas Instruments C2000 Processors
Required hardware:
On the following boards the embedded xds100 JTAG can be used as a serial connection
over USB. Jumper and switch settings with corresponding FTDI drivers are required to
use this serial communication technique.
Host Model
41-60
HIL Verification of IIR Filter via SCI
Target Model
41-61
41 Working with Texas Instruments C2000 Processors
Description
This example shows HIL verification of an IIR filter using serial communication interface
between a host simulation and generated code on an c28x processor-based target board.
Based on the position of the manual switch, either a saw-tooth or sine waveform is
passed to the Host-side SCI Transmit block and sent to the target. The stream of data
is received from the target the via Host-side SCI Receive block and sent to the Simulink
scope block.
The same algorithm runs on the target and the host side at the same time. The scope
displays three signals showing the result of the simulation compared with the result
of the algorithm running on the target. Because the algorithm uses an IIR filter, its
output is therefore dependent on every sample time that occurs from the beginning of the
simulation. Using an IIR filter clearly shows the time consistency between the simulation
and the generated code.
You can add a delay in the simulation by using the "Show Delayed Output" switch. This
delay can be used to verify the time consistency between both models.
Hardware Connections
• Connect the RS232 connector of your computer to the RS232 connector of the F28xx
chip-based board.
41-62
HIL Verification of IIR Filter via SCI
• F2812 eZdsp is not equipped with RS232 transceivers. You must add RS232
transceivers to this board to run this example.
• ControlCARDs with Docking Stations, ControlSTICK boards can support serial over
the xds100 USB JTAG connection. Jumper and switch settings with corresponding
FTDI drivers are required to use this serial communication technique.
The following sections explain how to configure, build, and deploy the executable.
Note: The host model is set to use "COM1". Configure the SCI Setup, SCI Transmit, and
SCI Receive blocks to use a different COM port.
CCSv4 support is provided via a makefile based approach. This requires running
xmakefilesetup to set the environment. You can ignore the following if you have
already gone through these steps. For more information, please refer to the Xmakefile
Documentation
41-63
41 Working with Texas Instruments C2000 Processors
CCSv5 support is provided via a makefile based approach. This requires running
xmakefilesetup to set the environment. You can ignore the following if you have
already gone through these steps. For more information, please refer to the Xmakefile
Documentation
41-64
HIL Verification of IIR Filter via SCI
41-65
41 Working with Texas Instruments C2000 Processors
Required Hardware:
Note: These models only runs with Code Composer Studio v3.3
Model
41-66
CAN-Based Control of PWM Duty Cycle
Description
Memory Copy block labeled "Read Duty Cycle" reads duty cycle value stored at the
memory location 0x8FF0. "Transmit CAN Msg" block uses mailbox 5 to transmit this
value packed in a standard CAN message frame, while "Receive CAN Msg" uses mailbox
0 to receive it. When the CAN message is received, "Process CAN Msg" unpacks the duty
cycle value and sends it to the PWM1. The duty cycle of the generated pulse waveform is
determined by the relative ratio of the received pulse width value and the pulse period
which is fixed at 64000 clock cycles. The duty cycle toggles between 25%, 50%, and 75%
based on user selection.
PWM Duty Cycle can be changed while the generated code is running using the write
function. This method writes selected value to the memory location 0x8FF0. Select either
25%, 50%, or 75% value from the GUI that opens up when "Build/Reload & Run" is
pressed.
NOTE: 'Self-Test' mode is enabled for eCAN_A to receive the data transmitted back to
the processor in the example models. If 'Self-test' mode is disabled, the CAN transmitter
and receiver have to be physically connected for the example to work.
Note that "Simulate Duty Cycle Change" and "Simulate PWM Waveform" are dedicated
to simulation only. Use these blocks to simulate and observe effects achieved with the
generated code.
41-67
41 Working with Texas Instruments C2000 Processors
Hardware Connections
Connect the output of PWM1 on the board to the analog input of the oscilloscope.
Note that CAN module is set to work in "Self Test Mode". External CAN hardware is not
needed, as the CAN handshaking signals are emulated in software.
• Open the model corresponding to the family of processor you are using.
• Click Start simulation button
• Double-click on the "Duty Cycle Change" block and select a new duty cycle value
• Observe the PWM waveform change
• Open the model corresponding to the family of processor you are using.
• Each model is configured for a default processor, open the Target Hardware Resources
tab to select a different processor.
• Go to Peripherals > eCAN_A and check Self-Test Mode.
• Click the "Build/Reload & Run" button to generate, build, load and run the
program.
• Select a new duty cycle value in the dialog that opens.
• Observe the PWM waveform on the oscilloscope.
41-68
CAN Calibration Protocol and External Mode
Required hardware:
• Before running the model in external mode, install Vector-Informatik CAN hardware
and drivers on your host computer, and set the baud rate to 1M to match processor
CAN configurations.
• Spectrum Digital F2812/F2808/F28335 eZdsp board, F28069 controlSTICK or F2808/
F28035/F28044/F28069/F28335 ControlCARD with Docking Station
• The model runs in MATLAB Win32 as Vector-Informatik supports win32
• The example model c28x_ccp can be used for TI Piccolo F2803x/F2806x, F28x3x,
F280x, F281x series processors. Default F28335 processor is selected.
• The target hardware can be selected from Target Hardware Resources tab for the
model
Required hardware:
• Before running the model in external mode, install Vector-Informatik CAN hardware
and drivers on your host computer, and set the baud rate to 1M to match processor
CAN configurations.
• Spectrum Digital F2812/F2808/F28335 eZdsp board, F28069 controlSTICK or F2808/
F28035/F28044/F28069/F28335 ControlCARD with Docking Station
• The model runs in MATLAB Win32 as Vector-Informatik supports win32
• The example model c28x_ccp can be used for TI Piccolo F2803x/F2806x, F28x3x,
F280x, F281x series processors. Default F28335 processor is selected.
• The target hardware can be selected from Target Hardware Resources tab for the
model
41-69
41 Working with Texas Instruments C2000 Processors
Model
41-70
CAN Calibration Protocol and External Mode
Scope Snapshots
41-71
41 Working with Texas Instruments C2000 Processors
Description
This example shows how to use the c28x CCP block. During code generation, for this
model an ASAP2 file is generated. The ASAP2 file contains symbol and memory address
information that is used either by external mode or a third party calibration tool. You can
use either external mode or a calibration tool to log signals and update parameters on the
real-time application.
The following sections explain how to configure, build, and deploy the executable.
41-72
CAN Calibration Protocol and External Mode
• While opening the model c28x_ccp, a script will be processed as a Pre-Load Function
callback. This call can be viewed by selecting File > Model Properties > Callbacks >
PreLoadFcn.
• The c2000_ccp_data.m callback is setting Simulink signals and parameters to resolve
Simulink objects used for CCP DAQ lists and Simulink tunable parameters as
described in the CCP documentation. This step is required to interact with these
signals in real-time using CCP.
• The example model is configured for default processor F28335. Open the Target
Hardware Resources tab to select a different processor.
• Build the model. You can press Ctrl+B or click Incremental Build button on the
toolbar of your model.
• Follow the progress of the build in the MATLAB command window, and wait until the
project is created and built in Code Composer Studio™.
CCSv4 support is provided via a makefile based approach. This requires running
xmakefilesetup to set the environment. You can ignore the following if you have
already gone through these steps. For more information, please refer to the Xmakefile
Documentation
41-73
41 Working with Texas Instruments C2000 Processors
• While opening the model c28x_ccp, a script will be processed as a Pre-Load Function
callback. This call can be viewed by selecting File > Model Properties > Callbacks >
PreLoadFcn.
• The c2000_ccp_data.m callback is setting Simulink signals and parameters to resolve
Simulink objects used for CCP DAQ lists and Simulink tunable parameters as
described in the CCP documentation. This step is required to interact with these
signals in real-time using CCP.
• Open the Target Hardware Resources tab and set the IDE/Tool chain parameter
to Texas Instruments Code Composer Studio v4 (makefile generation
only).
• Change the selected board and processor to match your hardware.
• Click OK to save the changes on the Target Hardware Resources tab.
• Build the model. You can press Ctrl+B or click Incremental Build button on the
toolbar of your model.
• Open CCSv4 and Connect to the Hardware. Load the program on to the Hardware
using CCSv4 and run.
CCSv5 support is provided via a makefile based approach. This requires runnning
xmakefilesetup to set the environment. You can ignore the following if you have
already gone through these steps. For more information, please refer to the Xmakefile
Documentation
41-74
CAN Calibration Protocol and External Mode
• While opening the model c28x_ccp, a script will be processed as a Pre-Load Function
callback. This call can be viewed by selecting File > Model Properties > Callbacks >
PreLoadFcn.
• The c2000_ccp_data.m callback is setting Simulink signals and parameters to resolve
Simulink objects used for CCP DAQ lists and Simulink tunable parameters as
described in the CCP documentation. This step is required to interact with these
signals in real-time using CCP.
• Open the Target Hardware Resources tab and set the IDE/Tool chain parameter
to Texas Instruments Code Composer Studio v5 (makefile generation
only).
• Change the selected board and processor to match your hardware.
• Click OK to save the changes on the Target Hardware Resources tab.
• Build the model. You can press Ctrl+B or click Incremental Build button on the
toolbar of your model.
• Open CCSv5 and Connect to the Hardware. Load the program on to the Hardware
using CCSv5 and run.
The model, c28x_ccp, contains a variety of signals and parameters that can be logged
or changed while the application is executing in real-time. Parameter tuning and signal
logging is enabled by the CCP block included in the model. Additionally, when the
model is built, it must be configured to generate an ASAP2 file. The ASAP2 file contains
information about the signals and parameters that are available for logging or tuning in
the real-time application.
The model contains a simple counter with parameterized step size, STEP_PARAM.
You can update the parameter STEP_PARAM and log the output of the counter,
COUNTER_SIGNAL. Additional signals available for logging are SINE_SIGNAL,
PULSE_SIGNAL and the RANDOMx signals.
Before running the model in external mode you must have Vector-Informatik CAN
hardware installed on your host computer.
• Check that the model is already built and running on the target.
41-75
41 Working with Texas Instruments C2000 Processors
• Run the model in external mode by selecting Simulation > Connect To Target.
• You can change the parameter STEP_PARAM in the real-time application: first
change its value, "STEP_PARAM.Value", in the MATLAB workspace; then update the
model to apply this new value to the real-time application; to update the model select
Edit > Update Diagram or press Ctrl+D.
Signal Logging and Parameter Tuning with a Third Party Calibration Tool
As an alternative to using external mode, you can use a third party calibration tool for
signal logging and parameter tuning. The same signals and parameters may be logged or
updated as those that are available with external mode.
41-76
Using the I2C Bus to Access a Connected EEPROM
Required Hardware:
Note: C2000 (except c281x) controlSTICK or ControlCARD with Docking Station board
is not equipped with I2C EEPROM. You must add I2C EEPROM to this board to run the
example.
Model
Description
41-77
41 Working with Texas Instruments C2000 Processors
This example shows how to access the EEPROM connected to the I2C bus at I2C slave
address 0x50 on an F2808/F28335 eZdsp board.
This program writes 4 bytes to EEPROM and reads back the data from the corresponding
EEPROM address to show that communication has occurred.
The I2C Transmit block in the "EEPROM Write" subsystem writes the free-running
counter data from the "EEPROM Data" subsystem to the address specified by "EEPROM
Memory Addr" subsystem.
When an I2C interrupt is detected, "I2C SYS INTR" subsystem function is executed.
As a result, the I2C Receive block reads the EEPROM data in "I2C SYS INTR:ARDY
Subsystem:Subsystem". The global array "EEPROM_DATA" contains the received data.
You can monitor the value of this array in Code Composer Studio™ Watch Window.
The following sections explain how to configure, build, and deploy the executable.
CCSv4 support is provided via a makefile based approach. This requires running
xmakefilesetup to set the environment. You can ignore the following if you have
already gone through these steps. For more information, please refer to the Xmakefile
Documentation
41-78
Using the I2C Bus to Access a Connected EEPROM
CCSv5 support is provided via a makefile based approach. This requires running
xmakefilesetup to set the environment. You can ignore the following if you have
already gone through these steps. For more information, please refer to the Xmakefile
Documentation
41-79
41 Working with Texas Instruments C2000 Processors
41-80
Using the IQmath Library
Introduction
Note: The implementation of this library for the TI C28x processor produces the same
simulation and code-generation output as the TI version of this library, but it does not
use a global Q value, as does the TI version. The Q format is dynamically adjusted based
on the Q format of the input data.
The IQmath Library blocks generally input and output fixed-point data types and use
numbers in Q format. The C28x IQmath Library block reference pages discuss the data
types accepted and produced by each block in the library. For more information, consult
the “Fixed-Point Numbers” on page 41-82 and “Q Format Notation” on page 41-84
topics, as well as the Fixed-Point Designer product documentation, which includes more
information on fixed-point data types, scaling, and precision issues.
You can use IQmath Library blocks with some core Simulink blocks and Fixed-Point
Designer blocks to run simulations in Simulink models before generating code. Once
you develop your model, you can generate equivalent code that is optimized to run on
a TI C28x DSP. During code generation, a call is made to the IQmath Library for each
41-81
41 Working with Texas Instruments C2000 Processors
IQmath Library block in your model to create target-optimized code. To learn more about
creating models that include IQmath Library blocks and blocks from other blocksets,
consult “Building Models” on page 41-86.
Common Characteristics
To learn more about characteristics particular to each block in the library, see the
individual block reference pages.
References
For detailed information on the IQmath library, see the user's guide for the C28x IQmath
Library - A Virtual Floating Point Engine, Literature Number SPRC087, available at the
Texas Instruments Web site. The user's guide is included in the zip file download that
also contains the IQmath library (registration required).
Fixed-Point Numbers
• “Notation” on page 41-82
• “Signed Fixed-Point Numbers” on page 41-83
• “Q Format Notation” on page 41-84
Notation
In digital hardware, numbers are stored in binary words. A binary word is a fixed-length
sequence of binary digits (1s and 0s). How hardware components or software functions
interpret this sequence of 1s and 0s is defined by the data type.
Binary numbers are used to represent either fixed-point or floating-point data types.
A fixed-point data type is characterized by the word size in bits, the binary point, and
whether it is signed or unsigned. The position of the binary point is the means by which
fixed-point values are scaled and interpreted.
41-82
Using the IQmath Library
where
Note: For Embedded Coder, the results of fixed-point and integer operations in
MATLAB/Simulink match the results on the hardware target down to the least
significant bit (bit-trueness). The results of floating-point operations in MATLAB/
Simulink do not match those on the hardware target, because the libraries used by
the third-party compiler may be different from those used by MATLAB/Simulink.
Signed binary fixed-point numbers are typically represented in one of three ways:
• Sign/magnitude
• One's complement
• Two's complement
Two's complement is the most common representation of signed fixed-point numbers and
is used by TI digital signal processors.
41-83
41 Working with Texas Instruments C2000 Processors
Q Format Notation
The position of the binary point in a fixed-point number determines how you interpret
the scaling of the number. When it performs basic arithmetic such as addition or
subtraction, hardware uses the same logic circuits regardless of the value of the scale
factor. In essence, the logic circuits do not have knowledge of a binary point. They
perform signed or unsigned integer arithmetic — as if the binary point is to the right of
b0. Therefore, you determine the binary point.
In the IQmath Library, the position of the binary point in the signed, fixed-point data
types is expressed in and designated by Q format notation. This fixed-point notation
takes the form
Qm.n
where
In Q format, the most significant bit is designated as the sign bit. Representing a signed
fixed-point data type in Q format requires m+n+1 bits to account for the sign.
Note: The range and resolution varies for different Q formats. For specific details, see
Section 3.2 in the Texas Instruments C28x Foundation Software, IQmath Library Module
User's Guide.
When converting from Q format to floating-point format, the accuracy of the conversion
depends on the values and formats of the numbers. For example, for single-precision
floating-point numbers that use 24 bits, the resolution of the corresponding 32-bit
number cannot be achieved. The 24-bit number approximates its value by truncating the
lower end. For example:
32-bit integer 11110000 11001100 10101010 00001111
Single-precision float +1.1110000 11001100 10101010 x 231
Corresponding value 11110000 11001100 10101010 00000000
41-84
Using the IQmath Library
For example, a signed 16-bit number with n = 15 bits to the right of the binary point is
expressed as
Q0.15
in this notation. This is (1 sign bit) + (m = 0 integer bits) + (n = 15 fractional bits) = 16
bits total in the data type. In Q format notation, the m = 0 is often implied, as in
Q.15
sfrac16
or
sfix16_En15
[16 15]
Multiplying two Q0.15 numbers yields a product that is a signed 32-bit data type with
n = 30 bits to the right of the binary point. One bit is the designated sign bit, thereby
forcing m to be 1:
m+n+1 = 1+30+1 = 32 bits total
Q1.30
sfix32_En30
[32 30]
Consider a signed 16-bit number with a scaling of 2(-17). This requires n = 17 bits to the
right of the binary point, meaning that the most significant bit is a sign-extended bit.
41-85
41 Working with Texas Instruments C2000 Processors
Sign extension fills additional bits with the value of the MSB. For example, consider a
4-bit two's complement number 1011. When this number is extended to 7 bits with sign
extension, the number becomes 1111101 and the value of the number remains the same.
Q-2.17
sfix16_En17
[16 17]
Consider a signed 16-bit number with a scaling of 2^(2) or 4. This means that the binary
point is implied to be 2 bits to the right of the 16 bits, or that there are n = -2 bits to the
right of the binary point. One bit must be the sign bit, thereby forcing m to be 17:
m+n+1 = 17+(-2)+1 = 16
Q17.-2
sfix16_E2
[16 -2]
Building Models
• “Overview” on page 41-87
• “Converting Data Types” on page 41-87
• “Using Sources and Sinks” on page 41-87
41-86
Using the IQmath Library
Overview
You can use IQmath Library blocks in models along with certain core Simulink, Fixed-
Point Designer, and other blockset blocks. This section discusses issues you should
consider when building a model with blocks from these different libraries.
It is vital to make sure that blocks you connect in a model have compatible input and
output data types. In most cases, IQmath Library blocks handle only a limited number of
specific data types. You can refer to the block reference page for a discussion of the data
types that the block accepts and produces.
When you connect IQmath Library blocks and Fixed-Point Designer blocks, you often
need to set the data type and scaling in the block parameters of the Fixed-Point Designer
block to match the data type of the IQmath Library block. Many Fixed-Point Designer
blocks allow you to set their data type and scaling through inheritance from the driving
block, or through backpropagation from the next block. This can be a good way to set the
data type of a Fixed-Point Designer block to match a connected IQmath Library block.
Some DSP System Toolbox blocks and core Simulink blocks also accept fixed-point data
types. Choose the right settings in these blocks' parameters when you connect them to an
IQmath Library block.
The IQmath Library does not include source or sink blocks. Use source or sink
blocks from the core Simulink library or Fixed-Point Designer in your models with
IQmath Library blocks.
In some cases, blocks that perform similar functions appear in more than one blockset.
For example, the IQmath Library and Fixed-Point Designer software have a Multiply
block. When you are building a model to run on C2000 DSP, choosing the block from the
IQmath Library yields better optimized code. You can use a similar block from another
library if it gives you functionality that the IQmath Library block does not support, but
you will generate code that is less optimized.
41-87
41 Working with Texas Instruments C2000 Processors
When you enter double-precision floating-point values for parameters in the IQ Math
blocks, the software converts them to single-precision values that are compatible with the
behavior on c28x processor. For example, with the Ramp Generator block, the software
converts the value of the Maximum step angle parameter to a single-precision value.
41-88
Programming Flash Memory
Introduction
The Embedded Coder software includes a feature for programming Flash memory on
the target hardware. You can configure this feature to automatically program Flash
memory when you build and execute models for DSP boards. You can also use the Flash
programming feature to selectively erase, program, or verify specific sectors of Flash
memory.
Note: Reprogramming Flash memory thousands of times may deplete its ability to hold
data. Consult the manufacturer's documentation for specifications.
Requirements:
• F281x: http://focus.ti.com/docs/toolsw/folders/print/sprc125.html
• F280x: http://focus.ti.com/docs/toolsw/folders/print/sprc193.html
• F2802x: http://focus.ti.com/docs/toolsw/folders/print/sprc848.html
41-89
41 Working with Texas Instruments C2000 Processors
• F2804x: http://focus.ti.com/docs/toolsw/folders/print/sprc325.html
• F2823x: http://focus.ti.com/docs/toolsw/folders/print/sprc665.html
• F2833x: http://focus.ti.com/docs/toolsw/folders/print/sprc539.html
2 Start the TI Flash API installation software (.exe) contained in the ZIP file.
3 During installation, use the default folder location for Location to Save Files.
Otherwise, each time you create a model, you must configure Specify API
Location, located under the Peripherals tab of the Target Hardware Resources
tab.
4 Complete the installation process.
Typically, you can enable the bootloader switch or jumper by moving it from the factory
default position (Flash disabled) to the opposite position (enabled). For example:
• On the F2812 eZdsp, change jumper JP7 from the factory default setting.
• On the F2808 eZdsp, change switches 1 and 3 on bank SW1 from the factory default
settings.
• On F28335 eZdsp, change switch 3 on bank SW1 from the factory default setting.
1 On your keyboard, press Ctrl+E to open the Configuration Parameters dialog, select
the Code Generation > Coder Target pane.
2 On the Tool Chain Automation tab, set Build Action to Build_and_execute.
3 On the Target Hardware Resources tab, set Board to a board whose name includes
(boot from flash).
4 Select the Peripherals tab, and then select Flash_loader
5 Set Enable flash programmer to Erase, Program, Verify.
41-90
Programming Flash Memory
When you build the model, the software automatically erases, programs, and verifies
Flash memory. When the DSP board restarts, it loads and executes the program from
Flash memory.
1 Open the Target Hardware Resources tab for your model, and select the
Peripherals tab.
2 Select Flash_loader from the Peripherals list.
3 Set Enable flash programmer to erase, program, or verify flash.
4 (Optional) To protect specific Flash sectors:
1 Determine the address and length of the individual Flash sectors. You may need to
refer to the manufacturer's specifications.
2 Determine the size of the primary C code program and the number of Flash sectors it
occupies.
3 Determine the size of the additional code or data and the number of Flash sectors it
will occupy.
4 Under the Target Hardware Resources tab, on the Memory tab, click Add to
create two or more new memory banks; one for the primary C code program (e.g.,
FLASH_AB) and one or more for the additional code or data (e.g., FLASH_CD). The
address and length of each memory bank must align with those of the flash sectors.
41-91
41 Working with Texas Instruments C2000 Processors
41-92
Programming Flash Memory
5 Under the Sections tab, under Default sections, select .text. Then, under
Placement, select the new memory bank (e.g., FLASH_AB) you created for the
primary C code program. The next time you program the Flash memory, the
software places the .text C code file in the new memory bank.
6 Similarly, select items from the Default sections or Custom sections list,
and place them in the new memory banks (e.g., FLASH_CD) for the previously
unoccupied Flash sectors.
41-93
41 Working with Texas Instruments C2000 Processors
Overview
The LIN communications architecture supports a single master node and up to 16 slave
nodes on a LIN network.
LIN nodes use message frames to exchange data. The message has two parts:
• Add a LIN Transmit block to the model. This block enables the Master to generate
message headers.
• To send data, set the ID input and Tx ID Mask input to make Tx ID Match happen
on this node.
41-94
Configuring LIN Communications
• To receive data, place LIN Receive block in the model. Set the Rx ID Mask input to
make Rx ID Match happen on this node.
For example, to configure a model with a master node that receives data from a slave
node:
• Add a LIN Transmit block and a LIN Receive block to the model.
• In the Target Hardware Resources tab, configure the ID Slave Task Byte.
• For the LIN Transmit block, set the ID input.
• For the LIN Receive block, set the Rx ID Mask input so that: Rx ID Mask = ID XOR
Slave Task ID Byte.
• To send data, place LIN Transmit block in the model. Set the ID input to match the
LIN frame header issued by the remote Master. Set Tx ID Mask to make a Tx ID
Match happen on this node.
• To receive data, place LIN Receive block in the model. Set the Rx ID Mask input to
make an Rx ID Match happen on this node.
For example, to configure a model with a slave node that transmits data to a master
node:
Set the Data type and Data length values in your LIN Receive blocks to match the type
and length of the transmitted data. These values enable the receive block reconstruct the
data from the message frames.
Note: The LIN Transmit block inherits the data type and length from its input.
41-95
41 Working with Texas Instruments C2000 Processors
41-96
Open Examples for Embedded Coder Texas Instruments C2000
Note Make sure you first download and install Embedded Coder Texas Instruments
C2000 support package before trying to open the examples.
41-97
41 Working with Texas Instruments C2000 Processors
41-98
RTDX Simulation Blocks
41-99
41 Working with Texas Instruments C2000 Processors
samples are processed one at a time. Frame-based processing can increase the speed of
your application running on your target. Note that throughput in samples per second
processed remains the same. Frame-based operation is the default. Data type Sets the
type for the data output from the block. Select one of the following types: Double - double-
precision floating-point numbers. Values range from -1 to 1. This is the default setting.
Single - single-precision floating-point numbers. Values range from -1 to 1. Int16 - 16-
bit signed integers. Values range from -32768 to 32767. Int32 - 32-bit signed integers.
Values range from -2147483648 to -2147483647. Uint8 - 8-bit unsigned integers. Values
range from 0 to 255. RTDX™ Write Block Description In simulation, this block writes
the block input data to the specified RTDX channel. When your simulation uses RTDX to
communicate with a target, the RTDX Write block writes messages to the RTDX channel
that your target application reads. If your target model is running code you generated
from a Simulink model that used RTDX blocks from the Target Support Package
component software, the From RTDX block you included in your target model configures
and reads messages from the RTDX channel to which the RTDX Write block in your
simulation is sending messages. Block Dialog Channel name Name of a write RTDX
channel. The RTDX Write block in the host model writes data to the target through this
channel. The name specified here must match an input channel defined in the target
code. Relationship Between RTDX™ Blocks in Simulation and Target Application To
make the correspondence between the RTDX simulation blocks and the RTDX code
generation blocks clear: Using the RTDX Read block in simulation provides one end of
a RTDX channel. Using the To RTDX block in a model generates code to implement the
other end. Together they form one complete RTDX communications path from the target
application to the host simulation. Using the RTDX Write block in simulation provides
one end of a RTDX channel. Using the From RTDX block in a model generates code
to implement the other end. Together they form one complete RTDX communications
path from the host simulation to the target application. close_system('rtdxsimlib', 0);
Copyright 2006-2011 The MathWorks, Inc. Published with MATLAB® R2013b
41-100
Code Generation from MATLAB Code
42
In this section...
“Specify Comment Style Using the Project Interface” on page 42-2
“Specify Comment Style at the Command-Line Interface” on page 42-2
If you have an Embedded Coder license, you can specify the comment style for C and
C++ code generated from MATLAB code. Specify single-line style to generate single-
line comments preceded by //. Specify multi-line style to generate single-line or multi-
line comments delimited by /* and */. Single-line style is the default for C++ code
generation. Multi-line style is the default for C code generation. For C code generation,
select single-line comment style only if your compiler supports it.
Value Description
Auto(Use standard comment style For C, generate multi-line comments.
of the target language) For C++, generate single-line comments.
(default)
Single-line (Use C++-style Generate single-line comments preceded
comments) by //.
Multi-line (Use C-style Generate single or multi-line comments
comments) delimited by /* and */.
cfg = coder.config('lib','ecoder',true);
2 Set the CommentStyle property to one of the following values:
42-2
Specify Comment Style
Value Description
'Auto' For C, generate multi-line comments. For C++, generate single-
line comments. (default)
'Single-line' Generate single-line comments preceded by //.
'Multi-line' Generate single or multi-line comments delimited by /* and */.
For example, this code sets the comment style to single-line style:
cfg.CommentStyle='Single-line';
42-3
42 Build Configuration for Code Generation from MATLAB Code
Generate Custom File and Function Banners for C and C++ Code
When you generate C and C++ code from MATLAB code, you can use a code generation
template (CGT) file to specify custom:
• File banners
• Function Banners
• File trailers
• Comments before code sections
This example shows how you can create your own CGT file and customize it to generate
your own file and function banners.
1 Create a local copy of the default CGT file for MATLAB Coder and rename it. The
default CGT file is matlabcoder_default_template.cgt in the matlabroot/toolbox/
coder/matlabcoder/templates/ folder.
2 Store the copy in a folder that is outside of the MATLAB folder structure, but on the
MATLAB path. If required, add the folder to the MATLAB path. If you intend to use
the CGT file with a custom target, locate the CGT file in a folder under your target
root folder. If the file is not on the MATLAB path, specify a full path to the file when
adding the file to your configuration.
3 View the default template and generated output. For example, here is the default
File Banner section:
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%% Custom File Banner section (optional)
%% Customize File banners by using either custom tokens or the following
%% predefined tokens:
%% %<FileName>, %<MATLABCoderVersion>, %<EmbeddedCoderVersion>
%% %<SourceGeneratedOn>, %<HardwareSelection>, %<OutputType>
%%
%% You can also use "custom tokens" in all of the sections below. See the
%% documentation center for more details.
%%
<FileBanner style="classic">
File: %<FileName>
42-4
Generate Custom File and Function Banners for C and C++ Code
* File: coderand.c
*
* MATLAB Coder version : 2.7
* C/C++ source code generated on : 06-Apr-2014 14:34:15
*/
4 Edit your local copy of the CGT file. You can change the default values and add
your own custom tokens. For example, here is the File Banner section with the style
changed to box and a custom token myCustomToken :
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%% Custom File Banner section (optional)
%% Customize File banners by using either custom tokens or the following
%% predefined tokens:
%% %<FileName>, %<MATLABCoderVersion>, %<EmbeddedCoderVersion>
%% %<SourceGeneratedOn>, %<HardwareSelection>, %<OutputType>
%%
%% You can also use "custom tokens" in all of the sections below. See the
%% documentation center for more details.
%%
<FileBanner style="box">
File: %<FileName>
For more information, see “Code Generation Template (CGT) Files for MATLAB”.
5 Create a configuration object for generation of a C static library for an embedded
target.
% Create configuration object for an embedded target
cfgObj = coder.config('lib','ecoder',true);
6 Create a MATLABCodeTemplate object from your CGT file and add it to the
configuration object.
% Specify the custom CGT file
CGTFile = 'myCGTFile.cgt';
% Use custom template
cfgObj.CodeTemplate = coder.MATLABCodeTemplate(CGTFile);
7 Assign values for custom tokens that you added to the template. For example, assign
the value 'myValue' to the myCustomToken token that you added in a previous
step.
cfgObj.CodeTemplate.setTokenValue('myCustomToken','myValue');
8 Generate code using the configuration object that you just created.
42-5
42 Build Configuration for Code Generation from MATLAB Code
Changes to a CGT file do not affect the generated code unless you create a
MATLABCodeTemplate object from the modified CGT file, and then add it to the
configuration object. If you modify the CGT File, myCGTFile.cgt, used in the previous
example, you must repeat these steps:
cfgObj.CodeTemplate.setTokenValue('myCustomToken','myValue');
3 Generate code.
codegen -config cfgObj coderand
42-6
Code Generation Template (CGT) Files for MATLAB
A code generation template (CGT) file defines the sections in generated code that you can
customize using comments and tokens. Using a code generation template (CGT) file for
the generation of C and C++ code from MATLAB, you can specify custom file banners and
function banners for generated code. File banners are comment sections in the header
and trailer sections of a generated file. Function banners are comment sections for each
function in the generated code. You can also customize comments before code sections.
Use these banners to:
For information on creating, customizing, and using a CGT file, see “Generate Custom
File and Function Banners for C and C++ Code” on page 42-4.
Note: If you choose not to customize banners for your generated code, the default
template is used for code generation.
42-7
42 Build Configuration for Code Generation from MATLAB Code
Contains comments and tokens for use in generating a custom file banner.
Contains comments and tokens for use in generating a custom function banner.
Contains comments and tokens for use in generating custom banners for shared utility
functions.
Contains comments for use in generating a custom banner for the include files section.
Type Definitions
Contains comments for use in generating a custom banner for the type definitions
section.
Named Constants
Contains comments for use in generating a custom banner for the named constants
section.
Variable Declarations
Contains comments for use in generating a custom banner for the variable declarations
section.
Variable Definitions
Contains comments for use in generating a custom banner for the variable definitions
section.
Function Declarations
Contains comments for use in generating a custom banner for the function declarations
section.
42-8
Code Generation Template (CGT) Files for MATLAB
Function Definitions
Contains comments for use in generating a custom banner for the function definitions
section.
Contains comments for use in generating a custom banner for the custom source code
section.
Contains comments for use in generating a custom banner for the custom header code
section.
42-9
42 Build Configuration for Code Generation from MATLAB Code
You can customize your banners by including tokens and comments between the open
and close tags for each section. Tokens are replaced with values in the generated code.
The following rules apply to tokens in your CGT file:
Note: In the contents of your banner, C comment indicators, '/*' or '*/', can introduce an
error in the generated code.
An open tag includes tag attributes. Enclose the value of the attribute in double quotes.
The attributes available for an open tag are:
• width: specifies the width of the file or function banner comments in the generated
code. The default value is 80.
• style: specifies the boundary for the file or function banner comments in the
generated code.
There are five options for the banner style. The CommentStyle and TargetLang
configuration object properties determine the use of C or C++ comment style. The built-in
style options for the style attribute are:
42-10
Code Generation Template (CGT) Files for MATLAB
• classic
/*
* multiple line comments
* second line
*/
//
// multiple line comments
// second line
//
• box
/**********************************************************/
/* banner contents */
/**********************************************************/
////////////////////////////////////////////////////////////
// banner contents //
////////////////////////////////////////////////////////////
• open_box
/**********************************************************
* banner contents
**********************************************************/
////////////////////////////////////////////////////////////
// banner contents
42-11
42 Build Configuration for Code Generation from MATLAB Code
////////////////////////////////////////////////////////////
• doxygen
/**
* multiple line comments
* second line
*/
///
/// multiple line comments
///second line
///
• doxygen_qt
/*!
* multiple line comments
* second line
*/
//!
//! multiple line comments
//!second line
//!
File Banner
This section contains comments and tokens for use in generating a custom file banner
that precedes the generated C and C++ code. If you omit the file banner section from the
42-12
Code Generation Template (CGT) Files for MATLAB
CGT file, the code generation software does not generate a file banner in the generated
code. The file banner section provided in the default CGT file is:
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%% Custom File Banner section (optional)
%% Customize File banners by using either custom tokens or the following
%% predefined tokens:
%% %<FileName>, %<MATLABCoderVersion>, %<EmbeddedCoderVersion>
%% %<SourceGeneratedOn>, %<HardwareSelection>, %<OutputType>
%%
%% You can also use "custom tokens" in all of the sections below. See the
%% documentation center for more details.
%%
<FileBanner style="classic">
File: %<FileName>
Function Banner
This section contains comments and tokens for use in generating a custom function
banner that precedes a generated C or C++ function. If you omit the function banner
section from the CGT file, the code generation software does not generate function
banners. The function banner section provided in the default CGT file is:
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%% Custom function banner section (optional)
%% Customize function banners by using the following predefined tokens:
%% %<FunctionName>, %<FunctionDescription>
%% %<Arguments>, %<ReturnType>
%%
<FunctionBanner style="classic">
%<FunctionDescription>
Arguments : %<Arguments>
Return Type : %<ReturnType>
%</FunctionBanner>
42-13
42 Build Configuration for Code Generation from MATLAB Code
This section contains comments and tokens for use in generating a custom shared utility
function banner that precedes a generated C or C++ shared utility function. If you
omit the shared utility function banner section from the CGT file, the code generation
software does not generate shared utility function banners. The shared utility function
banner section provided in the default CGT file is:
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%% Custom Shared Utility Function Banner section (optional)
%% Customize shared utility function banners by using the following
%% predefined tokens:
%% %<FunctionName>, %<FunctionDescription>
%% %<Arguments>, %<ReturnType>
%%
<SharedUtilityBanner style="classic">
Arguments : %<Arguments>
Return Type : %<ReturnType>
</SharedUtilityBanner>
File Trailer
The file trailer section contains comments for generating a custom file trailer that follows
the generated C or C++ code. If you omit the file trailer section from the CGT file, the
code generation software does not generate a file trailer. The file trailer section provided
in the default CGT file is:
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%% Custom file trailer section (optional)
%% You can use any of the predefined tokens used for File Banner
42-14
Code Generation Template (CGT) Files for MATLAB
%%
<FileTrailer style="classic">
File trailer for %<FileName>
[EOF]
</FileTrailer>
Tokens for the file banner are available for the file trailer. See Summary of Tokens for
File Banner Generation.
The include files banner section contains comments for generating a custom banner
that precedes the include files section in the generated code. If you omit the include
files banner section from the CGT file, the code generation software does not generate a
banner for this section. The include files banner section provided in the default CGT file
is:
<IncludeFilesBanner style="classic">
Include Files
</IncludeFilesBanner>
The type definitions banner section contains comments for generating a custom banner
that precedes the type definitions section in the generated code. If you omit the type
definitions banner section from the CGT file, the code generation software does not
generate a banner for this section. The type definitions banner section provided in the
default CGT file is:
<TypeDefinitionsBanner style="classic">
Type Definitions
</TypeDefinitionsBanner>
The named constants banner section contains comments for generating a custom banner
that precedes the named constants section in the generated code. If you omit the named
constants banner section from the CGT file, the code generation software does not
generate a banner for this section. The named constants banner section provided in the
default CGT file is:
<NamedConstantsBanner style="classic">
Named Constants
</NamedConstantsBanner>
42-15
42 Build Configuration for Code Generation from MATLAB Code
Variable Declarations
The variable declarations banner section contains comments for generating a custom
banner that precedes the variable declarations section in the generated code. If you omit
the variable declarations banner section from the CGT file, the code generation software
does not generate a banner for this section. The variable declarations banner section
provided in the default CGT file is:
<VariableDeclarationsBanner style="classic">
Variable Declarations
</VariableDeclarationsBanner>
Variable Definitions
The variable definitions banner section contains comments for generating a custom
banner that precedes the variable definitions section in the generated code. If you omit
the variable definitions banner section from the CGT file, the code generation software
does not generate a banner for this section. The variable definitions banner section
provided in the default CGT file is:
<VariableDefinitionsBanner style="classic">
Variable Definitions
</VariableDefinitionsBanner>
Function Declarations
The function declarations banner section contains comments for generating a custom
banner that precedes the function declarations section in the generated code. If you omit
the function declarations banner section from the CGT file, the code generation software
does not generate a banner for this section. The function declarations banner section
provided in the default CGT file is:
<functionDeclarationsBanner style="classic">
Function Declarations
</FunctionDeclarationsBanner>
Function Definitions
The function definitions banner section contains comments for generating a custom
banner that precedes the function definitions section in the generated code. If you omit
the function definitions banner section from the CGT file, the code generation software
does not generate a banner for this section. The function definitions banner section
provided in the default CGT file is:
42-16
Code Generation Template (CGT) Files for MATLAB
<FunctionDefinitionsBanner style="classic">
Function Definitions
</FunctionDefinitionsBanner>
The custom source code banner section contains comments for generating a custom
banner that precedes the custom source code section in the generated code. If you omit
the custom source code banner section from the CGT file, the code generation software
does not generate a banner for this section. The custom source code banner section
provided in the default CGT file is:
<CustomSourceCodeBanner style="classic">
Custom Source Code
</CustomSourceCodeBanner>
The custom header code banner section contains comments for generating a custom
banner that precedes the custom header code section in the generated code. If you omit
the custom header code banner section from the CGT file, the code generation software
does not generate a banner for this section. The custom header code banner section
provided in the default CGT file is:
<CustomHeaderCodeBanner style="classic">
Custom Header Code
</CustomHeaderCodeBanner>
42-17
42 Build Configuration for Code Generation from MATLAB Code
If you have an Embedded Coder license, you can customize the identifiers that the
MATLAB Coder software generates in the C/C++ code. To customize generated
identifiers, specify the identifier format parameters in the project or the embedded code
configuration object. For each parameter, enter a macro string. The code generation
software expands the macro string and includes it in the generated identifiers.
Token Description
$M Insert name mangling string to avoid naming collisions.
Required.
$N Insert name of the object (global variable, global type, local
function, local temporary variable, or constant macro) for which
the identifier is generated.
42-18
Customize Generated Identifiers
For example, suppose Global variables has the value glob_$M$N. For a global variable
named g, when name mangling is not required, the generated identifier is glob_g. If
name mangling is required, the generated identifier includes the name mangling string.
For example:
cfg = coder.config('lib','ecoder',true);
cfg.CustomSymbolStrGlobalVar = 'glob_$M$N';
42-19
42 Build Configuration for Code Generation from MATLAB Code
For a global variable named g, when name mangling is not required, the generated
identifier is glob_g. If name mangling is required, the generated identifier includes the
name mangling string.
42-20
43
• Optimization for a specific run-time environment, including, but not limited to,
specific target hardware.
• Integration with existing application code.
• Compliance with a standard, such as AUTOSAR.
• Modification of code behavior, such as enabling or disabling nonfinite or inline
support.
• Application- or project-specific code requirements, such as:
• Elimination of math.h.
• Elimination of system header files.
• Elimination of calls to memcpy or memset.
• Use of BLAS.
• Use of a specific BLAS.
To apply this technique, configure the code generator to apply a code replacement
library (CRL) during code generation. By default, the code generator does not apply a
code replacement library. You can choose from the following libraries that MathWorks
provides:
• GNU C99 extensions—GNU6 gcc math library, which provides C99 extensions as
defined by compiler option -std=gnu99.
• Intel IPP for x86-64 (Windows)—Generates calls to the Intel Performance Primitives
(IPP) library for the x86-64 Windows platform.
• Intel IPP/SSE with GNU99 extensions for x86-64 (Windows)—GNU libraries for Intel
Performance Primitives (IPP) and Streaming SIMD Extensions (SSE), with GNU C99
extensions.
• Intel IPP for x86/Pentium (Windows)—Generates calls to the Intel Performance
Primitives (IPP) library for the x86/Pentium Windows platform.
6. GNU is a registered trademark of the Free Software Foundation.
43-2
What Is Code Replacement?
Libraries that include GNU99 extensions are intended for use with the GCC compiler. If
use one of those libraries with another compiler, generated code might not compile.
Depending on the product licenses that you have, other libraries might be available . If
you have an Embedded Coder license, you can view and choose from other libraries and
you can create custom code replacement libraries.
Code replacement is a technique to change the code that the code generator produces for
functions and operators to meet application code requirements. For example, you can
replace generated code to meet requirements such as:
• Optimization for a specific run-time environment, including, but not limited to,
specific target hardware.
• Integration with existing application code.
• Compliance with a standard, such as AUTOSAR.
• Modification of code behavior, such as enabling or disabling nonfinite or inline
support.
• Application- or project-specific code requirements, such as:
• Elimination of math.h.
• Elimination of system header files.
• Elimination of calls to memcpy or memset.
• Use of BLAS.
• Use of a specific BLAS.
To apply this technique, configure the code generator to apply a code replacement
library (CRL) during code generation. By default, the code generator does not apply a
code replacement library. You can choose from the following libraries that MathWorks
provides:
43-3
43 Code Replacement for MATLAB Code
• GNU C99 extensions—GNU7 gcc math library, which provides C99 extensions as
defined by compiler option -std=gnu99.
• Intel IPP for x86-64 (Windows)—Generates calls to the Intel Performance Primitives
(IPP) library for the x86-64 Windows platform.
• Intel IPP/SSE with GNU99 extensions for x86-64 (Windows)—GNU libraries for Intel
Performance Primitives (IPP) and Streaming SIMD Extensions (SSE), with GNU C99
extensions.
• Intel IPP for x86/Pentium (Windows)—Generates calls to the Intel Performance
Primitives (IPP) library for the x86/Pentium Windows platform.
• Intel IPP/SSE with GNU99 extensions for x86/Pentium (Windows)—Generates calls
to the GNU libraries for Intel Performance Primitives (IPP) and Streaming SIMD
Extensions (SSE), with GNU C99 extensions, for the x86/Pentium Windows platform.
• Intel IPP for x86-64 (Linux)—Generates calls to the Intel Performance Primitives
(IPP) library for the x86-64 Linux platform.
• Intel IPP/SSE with GNU99 extensions for x86-64 (Linux)—Generates calls to
the GNU libraries for Intel Performance Primitives (IPP) and Streaming SIMD
Extensions (SSE), with GNU C99 extensions, for the x86-64 Linux platform.
Libraries that include GNU99 extensions are intended for use with the GCC compiler. If
use one of those libraries with another compiler, generated code might not compile.
Depending on the product licenses that you have, other libraries might be available . If
you have an Embedded Coder license, you can view and choose from other libraries and
you can create custom code replacement libraries.
Related Examples
• “Replace Code Generated from MATLAB Code”
• “Choose a Code Replacement Library”
More About
• “Code You Can Replace from MATLAB Code”
• “Code Replacement Libraries”
• “Code Replacement Terminology”
• “Code Replacement Limitations”
43-4
Code You Can Replace from MATLAB Code
For information on how to explore functions and operators that a code replacement
library supports, see “Choose a Code Replacement Library”. If you have an Embedded
Coder license and want to develop a custom code replacement library, see Code
Replacement Customization.
Math Functions
When generating C/C++ code from MATLAB code, depending on code replacement
libraries available in your development environment, you can configure the code
generator to replace instances of the following math functions with application-specific
implementations.
Function Data Type Support Scalar, Vector, Matrix Real, Complex Support
Support
abs1 Floating point Scalar Real
acos Floating point Scalar Real
Vector Complex
Matrix Complex input/complex output
Real input/complex output
acosd Floating point Scalar Real
Vector Complex
Matrix
43-5
43 Code Replacement for MATLAB Code
Function Data Type Support Scalar, Vector, Matrix Real, Complex Support
Support
acot Floating point Scalar Real
Vector Complex
Matrix
acotd Floating point Scalar Real
Vector Complex
Matrix
acoth Floating point Scalar Real
Vector Complex
Matrix
acsc Floating point Scalar Real
Vector Complex
Matrix
acscd Floating point Scalar Real
Vector Complex
Matrix
acsch Floating point Scalar Real
Vector Complex
Matrix
asec Floating point Scalar Real
Vector Complex
Matrix
asecd Floating point Scalar Real
Vector Complex
Matrix
asech Floating point Scalar Real
Vector Complex
Matrix
asin Floating point Scalar Real
Vector Complex
Matrix Complex input/complex output
Real input/complex output
43-6
Code You Can Replace from MATLAB Code
Function Data Type Support Scalar, Vector, Matrix Real, Complex Support
Support
asind Floating point Scalar Real
Vector Complex
Matrix
atan Floating point Scalar Real
Vector Complex
Matrix Complex input/complex output
Real input/complex output
atan2 Floating point Scalar Real
Vector
Matrix
atan2d Floating point Scalar Real
Vector
Matrix
atand Floating point Scalar Real
Vector Complex
Matrix
cos Floating point Scalar Real
Vector Complex
Matrix Complex input/complex output
Real input/complex output
ceil • Floating-point • Floating-point • Floating-point
• Scalar • Scalar • Scalar
cosd Floating point Scalar Real
Vector Complex
Matrix
cosh Floating point Scalar Real
Vector Complex
Matrix Complex input/complex output
Real input/complex output
cot Floating point Scalar Real
Vector Complex
Matrix
43-7
43 Code Replacement for MATLAB Code
Function Data Type Support Scalar, Vector, Matrix Real, Complex Support
Support
cotd Floating point Scalar Real
Vector Complex
Matrix
coth Floating point Scalar Real
Vector Complex
Matrix
csc Floating point Scalar Real
Vector Complex
Matrix
cscd Floating point Scalar Real
Vector Complex
Matrix
csch Floating point Scalar Real
Vector Complex
Matrix
exp Floating point Scalar Real
fix Floating point Scalar Real
floor • Floating-point • Floating-point • Floating-point
• Scalar • Scalar • Scalar
hypot Floating point Scalar Real
Vector
Matrix
ldexp Floating point Scalar Real
log Floating point Scalar Real
Vector Complex
Matrix
log10 Floating point Scalar Real
Vector Complex
Matrix
log2 Floating point Scalar Real
Vector Complex
Matrix
43-8
Code You Can Replace from MATLAB Code
Function Data Type Support Scalar, Vector, Matrix Real, Complex Support
Support
max Integer Scalar Real
Floating point
min Integer Scalar Real
Floating point
pow Floating point Scalar Real
rem Floating point Scalar Real
round Floating point Scalar Real
sec Floating point Scalar Real
Vector Complex
Matrix
secd Floating point Scalar Real
Vector Complex
Matrix
sech Floating point Scalar Real
Vector Complex
Matrix
sign Floating point Scalar Real
sin Floating point Scalar Real
Vector Complex
Matrix Complex input/complex output
Real input/complex output
sind Floating point Scalar Real
Vector Complex
Matrix
sinh Floating point Scalar Real
Vector Complex
Matrix Complex input/complex output
Real input/complex output
sqrt Floating point Scalar Real
43-9
43 Code Replacement for MATLAB Code
Function Data Type Support Scalar, Vector, Matrix Real, Complex Support
Support
tan Floating point Scalar Real
Vector Complex
Matrix Complex input/complex output
Real input/complex output
tand Floating point Scalar Real
Vector Complex
Matrix
tanh Floating point Scalar Real
Vector Complex
Matrix Complex input/complex output
Real input/complex output
1
Wrap on integer overflow only
Memory Functions
Depending on code replacement libraries available in your development environment,
you can configure the code generator to replace instances of the following memory
functions with application-specific implementations.
Function Data Type Support Scalar, Vector, Matrix Real, Complex Support
Support
memcmp Void pointer (void*) Scalar Real
Vector Complex
Matrix
memcpy Void pointer (void*) Scalar Real
Vector Complex
Matrix
memset Void pointer (void*) Scalar Real
Vector Complex
Matrix
memset2zero Void pointer (void*) Scalar Real
Vector Complex
Matrix
43-10
Code You Can Replace from MATLAB Code
Some target processors provide optimized functions to set memory to zero. Use the code
replacement library programming interface to replace the memset2zero function with
more efficient target-specific functions.
Operators
When generating C/C++ code from MATLAB code, depending on code replacement
libraries available in your development environment, you can configure the code
generator to replace instances of the following operators with application-specific
implementations.
Mixed data type support indicates you can specify different data types of different inputs.
43-11
43 Code Replacement for MATLAB Code
43-12
Code You Can Replace from MATLAB Code
43-13
43 Code Replacement for MATLAB Code
Related Examples
• “Choose a Code Replacement Library”
More About
• “Code Replacement Libraries”
• “Code Replacement Terminology”
• “Code Replacement Limitations”
43-14
Code Replacement Libraries
A code replacement table contains one or more code replacement entries, with each entry
representing a potential replacement for a function or operator. Each entry maps a
conceptual representation of a function or operator to an implementation representation
and priority.
43-15
43 Code Replacement for MATLAB Code
When the code generator looks for a match in a code replacement library, it creates and
populates a call site object with the function or operator conceptual representation. If
a match exists, the code generator uses the matched code replacement entry populated
with the implementation representation and uses it to generate code.
The code generator searches the tables in a code replacement library for a match in the
order that the tables appear in the library. If the code generator finds multiple matches
within a table, the priority determines the match. The code generator uses a higher-
priority entry over a similar entry with a lower priority.
Related Examples
• “What Is Code Replacement?”
• “Replace Code Generated from MATLAB Code”
• “Choose a Code Replacement Library”
More About
• “Code You Can Replace from MATLAB Code”
• “Code Replacement Terminology”
43-16
Code Replacement Terminology
43-17
43 Code Replacement for MATLAB Code
Term Definition
'u1', 'u2', ...) and data types familiar to the code
generator.
Conceptual representation Represents match criteria that the code generator
uses to qualify functions and operators for
replacement. Consists of:
43-18
Code Replacement Terminology
Term Definition
Priority Defines the match priority for a code replacement
entry relative to other entries, which have the
same name and conceptual argument list, within
a code replacement library. The priority can
range from 0 to 100, with 0 being the highest
priority. The default is 100. If a library provides
two implementations for a function or operator, the
implementation with the higher priority shadows
the one with the lower priority.
More About
• “What Is Code Replacement?”
• “Code Replacement Libraries”
43-19
43 Code Replacement for MATLAB Code
Related Examples
• “Replace Code Generated from MATLAB Code”
More About
• “Code You Can Replace from MATLAB Code”
• “Code Replacement Libraries”
43-20
Replace Code Generated from MATLAB Code
1 Make sure required software is installed. You need MATLAB, MATLAB Coder,
and a C compiler. Some code replacement libraries available in your development
environment might also require Embedded Coder.
If you are not sure which library to use, explore available libraries.
1 Configure the code generator to apply a code replacement library during code
generation for the MATLAB function.
• In a project, on the Build tab, set the Generate code only parameter.
• In a code configuration object, set the GenCodeOnly parameter.
If you have an Embedded Coder license, you can configure the code generator to include
a code replacement section in the code generation report. The additional information can
help you verify code replacements.
43-21
43 Code Replacement for MATLAB Code
• In a project, on the Debugging tab, set the Always create a code generation
report parameter.
• In a code configuration object, set the GenerateReport parameter.
2 Include the code replacement section in the report.
Generate C/C++ code from the MATLAB code and, if you configured the code generator
accordingly, a code generation report. For example, on the Build tab, click Build. Or, at
the command prompt, enter:
codegen -report myFunction -args {5} -config cfg
The code generator produces the code and displays the report.
Verify code replacements by examining the generated code. Code replacement might
behave differently than you expect, for example, data types that you observe in the code
generator input might not match what the code generator uses as intermediate data
types during an operation.
Related Examples
• “Choose a Code Replacement Library”
• “Build Setting Configuration”
• “Review and Test Code Replacements”
More About
• “What Is Code Replacement?”
• “Code You Can Replace from MATLAB Code”
• “Code Replacement Libraries”
• “Code Replacement Terminology”
43-22
Replace Code Generated from MATLAB Code
43-23
43 Code Replacement for MATLAB Code
1 Explore available libraries. Identify one that best meets your application needs.
• Consider the lists of application code replacement requirements and libraries that
MathWorks provides in “What Is Code Replacement?”.
• See “Explore Available Code Replacement Libraries”.
2 Explore the contents of the library. See “Explore Code Replacement Library
Contents”.
If you do not find a suitable library and you have an Embedded Coder license, you can
create a custom code replacement library.
43-24
Choose a Code Replacement Library
The viewer opens. To view the content of a specific library, specify the name of the
library as an argument in single quotes. For example:
>> RTW.viewTfl('GNU C99 extensions')
2 In the left pane, select the name of a library. The viewer displays information about
the library in the right pane.
3 In the left pane, expand the library, explore the list of tables it contains, and select a
table from the list. In the middle pane, the viewer displays the function and operator
entries that are in that table, along with abbreviated information for each entry.
4 In the middle pane, select a function or operator. The viewer displays information
from the table entry in the right pane.
If you select an operator entry that specifies net slope fixed-point parameters
(instantiated from entry class RTW.TflCOperationEntryGenerator or
RTW.TflCOperationEntryGenerator_NetSlope), the viewer displays an
additional tab that shows fixed-point settings.
See Code Replacement Viewer for details on what the viewer displays.
Related Examples
• “Replace Code Generated from MATLAB Code”
More About
• “What Is Code Replacement?”
• “Code You Can Replace from MATLAB Code”
• “Code Replacement Libraries”
• “Code Replacement Terminology”
• “Code Replacement Limitations”
43-25
43-26
44
In this section...
“Enable Highlight Option Using a Project” on page 44-3
“Enable Highlight Option Using the Command Line Interface” on page 44-4
If you have an Embedded Coder license, you have the option to highlight potential data
types issues in the code generation report for standalone code generated from MATLAB
code. If you enable this option, the Highlight section on the MATLAB Code tab lists
the number of single-precision and double-precision operations in the generated C/C+
+ code. If you have a Fixed-Point Designer license, it also lists the number of expensive
fixed-point operations.
To highlight the MATLAB code that corresponds to the potential data type issues:
1 Select the check box for the type of operation that you want to highlight.
2 Select the function that you want to highlight.
The report highlights the operations in the selected function. The following example
report highlights MATLAB code that results in double-precision operations in the
generated code.
44-2
Highlight Potential Data Type Issues in a Report
44-3
44 Verification of Code Generated from MATLAB Code
3 On the Debugging tab, select the Always create a code generation report and
Highlight potential data type issues check boxes.
cfg.GenerateReport = true;
cfg.HighlightPotentialDataTypeIssues = true;
Related Examples
• “Find Potential Data Type Issues in Generated Code”
44-4
Find Potential Data Type Issues in Generated Code
1 On the Build tab, set the Output Type to one of the following:
44-5
44 Verification of Code Generated from MATLAB Code
3 On the Debugging tab, select the Always create a code generation report and
Highlight potential data type issues check boxes.
Procedure 44.2. Enable the highlight option using the command line interface
cfg.GenerateReport = true;
cfg.HighlightPotentialDataTypeIssues = true;
This example requires Embedded Coder and Fixed-Point Designer licenses to run.
cfg = coder.config('lib');
cfg.GenerateReport = true;
cfg.HighlightPotentialDataTypeIssues = true;
codegen -config cfg myMul -args {fi(1, 1, 33, 4), fi(1, 1, 32, 4)}
3 Click View report.
4 In the Code Generation Report, on the left pane, click the MATLAB code tab.
5 Expand the Highlight section and select the Expensive fixed-point operations
check box.
44-6
Find Potential Data Type Issues in Generated Code
The in1 * in2 operation is highlighted in the HTML report. On the bottom pane,
click the Variables tab. The word length of in1 is 33, and the word length of in2
is 32. Hovering over the highlighted expression reveals that the product has a
word length of 65, which is larger than the target word length of 64. Therefore, the
software detects a cumbersome operation.
To resolve this issue, modify the data types of in1 and in2 so the word length of the
product does not exceed the target word length.
44-7
44 Verification of Code Generated from MATLAB Code
This example requires Embedded Coder and Fixed-Point Designer licenses to run.
cfg = coder.config('lib');
cfg.GenerateReport = true;
cfg.HighlightPotentialDataTypeIssues = true;
codegen -config cfg myRounding -args {fi(1, 1, 32, 2), fi(1, 1, 32, 4)}
3 Click View report.
4 In the Code Generation Report, on the left pane, click the MATLAB code tab.
5 Expand the Highlight section and select the Expensive fixed-point operations
check box.
44-8
Find Potential Data Type Issues in Generated Code
This division operation uses the default rounding method, nearest. Changing the
rounding method to Floor provides a more efficient implementation.
This example requires Embedded Coder and Fixed-Point Designer licenses to run.
44-9
44 Verification of Code Generated from MATLAB Code
cfg = coder.config('lib');
cfg.GenerateReport = true;
cfg.HighlightPotentialDataTypeIssues = true;
codegen -config cfg myRelop -args {fi(1, 1, 32, 1.5, 9, 17), fi(1, 0, 32, 16)}
3 Click View report.
4 In the Code Generation Report, on the left pane, click the MATLAB code tab.
5 Expand the Highlight section and select the Expensive fixed-point operations
check box.
44-10
Find Potential Data Type Issues in Generated Code
The first input argument, in1, is signed with slope bias scaling, while in2 is
unsigned with binary point scaling. Extra code is generated because a cast must
occur before the two inputs can be compared.
Change the signedness and scaling of one of the inputs to generate more efficient
code.
44-11
44-12