Basic S-Functions and TLC Coding
Basic S-Functions and TLC
Creating Custom Blocks for Simulink
Simulink has the notion of S-functions to create user defined
blocks
S-functions can be written in M, C, or FORTRAN
We will focus on C
Embedded Coder cannot code generate an S-Function without
the help of a TLC (Target Language Compiler)
All MotoHawk Blocks are created using S-Functions, Masks, and
TLC using interfaces defined by Mathworks
No sneaky “special” functions or APIs are used
MotoHawk maintains a very thin interface to Simulink to simplify
issues that can be caused during Matlab version changes
Confidential
Help Material
S-Functions are Described in the Simulink Help
Confidential
S-Function Primer
Add a S-Function from the
Simulink Browser
Set the Name and add any
parameters
Recommend using
company_sfun_xxx
Confidential
S-Function Primer (con’t)
Copy <MatlabInstall>\simulink\src\sfuntmpl_basic.c to
your local project directory
Rename to the same name you chose in the s-function
block, in this case mototron_sfun_timesX.c
Edit c file: > edit mototron_sfun_timesX.c
This must be
changed to
match filename
Confidential
Editing the S-Function C File
Set the number of Parameters in the function
ssSetNumSFcnParams(S, 1);
One Parameter
Confidential
Input Port Definition
Set Input Port Attributes
Confidential
Input Port Direct FeedThrough
What does Input Port Direct Feed Through mean?
This tells the block sorter that this input port is used as part of
the calculation of the output ports
Setting it to Zero means that the ports are independent and the
sorter does not need to make sure that blocks upstream are
calculated first…This is NOT usually the case.
Setting it to One means that this input must be calculated prior to
the execution of the block. This is USUALLY the case.
Confidential
Output Port Definition
Set Output Port Attributes
Confidential
Set Options
Set Code Generation Options
Confidential
How Do I Know What Options to Set?
<MATLABDIR>\simulink\include\simstruc.h has the
documentation
Confidential
Setting the Sample Time
Set to Inherited Sample Time
Confidential
Creating the Simulation Behavior
mdlOutputs contains code for simulation
Example to multiply Input by Parameter Value
Confidential
Build DLL
Use Matlab’s mex command to compile file
Choose LCC if asked
Note resultant file
(may be mex32 on
newer versions)
Confidential
Check Simulation Behavior
Run in simulation to verify operation
Confidential
Port Data Types
We didn’t specify data types for the ports so they
defaulted to double.
To accommodate different datatypes requires deeper sfunction knowledge
Confidential
S-Function Wrapup
S-function describes the block with respect to the
Simulation Engine (and the Diagram Checker)
S-Function describes port data types, sizes, number of
parameters, sample times, and memory allocations
S-Functions contain code that runs in the simulation but
that code is not generated into a MotoHawk build, TLC
will help us with that
S-Function Syntax and Help are contained in Matlab’s
Help and simstruc.h
Confidential
Masks
Interacting with the User is defined by a Mask
Select S-function block, right click->Mask Subsystem
See Matlab Help
regarding Mask
Details
Confidential
Add a Parameter
Parameters are design time choices needed from the
Application Builder
Evaluate as a
MatLab expression
Confidential
Tunable means
adjustable at run time
(not available in
MotoHawk)
Document on Mask Icon
Show the designer’s choice on the block icon for
documentation
Confidential
Add some Help Text
Add Mask Help, Copyright Recommended
Confidential
Mask Wrapup
Masks present the custom block to the user
Masks can pre-compute via scripts in the Initialization
pane
Heavy lifting of sorting, querying the model for information,
rationalizing the designers choices, etc should be done here.
Masks should show as much of the Parameter choices
as possible on the icon.
Don’t make readers look for data in dialogue boxes
Help text should not be overlooked.
Too much help documentation is almost enough
Good block design should also make the functions and
parameters obvious
Masks don’t do any code generation but can precompute information used by the code generator
Confidential
TLC Telling the Code Generator What to Do
TLC (Target Language Compiler) is the language that
drives the Real Time Workshop code generator
TLC can be thought of a as a Macro Expansion
Language
TLC has many computer language constructs like
variables, loops, and functions
TLC directives use the % sign to indicate that this is a
TLC statement
Anything without a % sign is either dumped to the
current source file or ignored if no file is being created
The code generator makes essentially 4 passes over the
model to collect code generation directives
Confidential
TLC Documentation
TLC is descibed in Matlab’s Help under Real Time
Workshop
Confidential
TLC File Contents
TLC Files Must have an Implements directive and certain
“Callback” functions
Must match the sfunction name and
TLC file name
Run once if at least one instance of
the block is in the model.
Typically we add header files here.
Note “VOID” means no active
output file during this pass
Run once for each instance of the
block in the model. Note no output
active. Usually we add blocks to
lists here
Confidential
TLC File Contents
TLC Files Must have an Implements directive and certain
“Callback” functions
Generate code destined for Startup
function
Generate code destined for
triggered susbsystems.
Confidential
TLC File Contents
Anything without a % directive is dumped to the output
Confidential
Asking The Code Generator for Names
LibBlockInputSignal() and LibBlockOutputSignal ask the
code generator for signal names, Parameter[] gets
parameter value
%<var> expands the TLC variable var into the output
Note Constant value is expanded
as the literal value.
Output is actually a global variable.
Confidential
Custom Blocks So Far
First, we built the S-function DLL from a c file (language
#1)
Next, we masked the S-Function block to make it look
good (language #2)
Finally, we wrote a TLC file (language #3) to generated
embedded C (language #4).
Looking at the generated code, we see some issues
A global variable was created when obviously the expression
could have been inlined costing no RAM
The S-Function C file is terribly complex (and we used
the simple template)
We can address these two issues by using a better
template
Confidential
A better Approach
The MotoHawk
Template s-function file
contains all of the
“Correct” settings for
good code generation
Simply fill out details at
the top, add the
simulation behavior
and most everything
else is taken care of
(see
motohawk_mex_templ
ate.c for the details)
Confidential
Reuse Outputs and Use Expressions
Fix S-Function Options to Re-use outputs (save
memory) and Use Expressions if possible
Original required two global
variables and a run time operation
Better version uses stack variable
and no run time operation.
Confidential
Custom Block Wrapup
Custom Blocks are Powerful
Often times complex Simulink subsystems can be aggregated
into a simple block
Lower Block count = faster update and compile times
Building them requires mastery of 4 languages
TLC drives the code generator
TLC documentation is readily available in Simulink
Look at both MotoHawk and Simulink TLC files for lots of
examples
Warning, using MotoHawk provided TLC functions may
break in the future. We don’t publish that as a public API
so we reserve the right to change without notice.
Confidential
Thanks for your attention!
MotoTron Corporation
734-822-7700
sales@mototron.com
www.mototron.com
www.motohawk.info
www.smartcraftnetworked.com