Basic S-Functions and TLC Coding

Confidential

Basic S-Functions and TLC

Creating Custom Blocks for SimulinkSimulink has the notion of S-functions to create user defined blocks

S-functions can be written in M, C, or FORTRANWe 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 ParameterOne 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 fileChoose 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 s-function 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

Tunable means adjustable at run time

(not available in MotoHawk)

Confidential

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 pre-compute 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 s-function 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 issuesA 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_template.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 operationOriginal 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 PowerfulOften 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.

Thanks for your attention!

MotoTron Corporation734-822-7700

sales@mototron.com

www.mototron.comwww.motohawk.info

www.smartcraftnetworked.com