Author:

Nitin S
Senior Engineer
www.Tataelxsi.co.in

About this document

One most powerful, versatile and widely used MATLAB feature is code generation from
model using RTW. The use of RTW significantly reduces the development time for
embedded systems. Lot of companies is exploring the possibility of using MATLAB in
their product development cycle. Its being talked that Very high level language based on
models will soon replace middle level language C like the way C replaced assembly
language programming long time back. So lets be ready for the change that is coming.
TLC or Target language compiler is one of the most advanced features of RTW. This
feature is to be studied only by those who want to test your guts in MATLAB
environment. TLC is a very powerful feature. It seems like very few people outside
MATHWORKS has tried to play with it. The fact is that it is not so complicated. But the
lack of proper documents and tutorials and other resources make life hell. You can’t get
good tutorials except those 1000 page ones provided my MATHWORKS. Who is going
to read them all? I got a chance to work with TLC. So I thought of writing this document,
which complies all that, I know about TLC. I have not invented anything. I have just
studies something and presenting it in the way I know. Please bear with my mistakes.
And do help me with your suggestions:
Contact me: nitins@tataelxsi.co.in

What’s TLC?
Is an advanced feature of MATLAB which lets you customize the way code is generated
by MATLAB. TLC files are asci files which control way code is generated with real time
workshop. TLC files are written in a language which beard similarity to html, m-scripts
etc. So you must study this scripting to play with TLC’s.
There are 2 types of TLC files
1. modelwide TLC
2. Block TLC’s
Block TLC – is concerned with code generation for a specific block. For all the blocks
supplied by SIMULINK, MATLAB provides set of block TLC’s also. For user made
blocks (S-functions) separate TLC files has to be written by user for efficient code
generation.
Modelwide TLC- dictates the general structure of code generation for a model. This TLC
calls Block TLC’s for this. For each Target environment of RTW there is exists a set of
modelwide TLC’s which controls the code generation.

TLC process-How code is generated?

The SIMULINK model ie:*.mdl file is first converted to a *.rtw file. See the folder
nit_exp1, an example model is given and also its rtw file. The rtw file is obtained using
the following command. >> rtwgen exp1
You can see exp1.rtw now.
After reading rtw file the target language compiler generates the ISO –ANSI C code.
If you want to build the C – code generated for a particular processor using some cross
compiler that is also possible. A temple make file (*.tmf) is provided from which a make
file (*.mk) is created. This is possible only is the cross compiler permits compiling and
linking with scripts.

TLC functions
There are two types of TLC’s block TLC and system wide TLC. Block TLC takes care of
code generation from a particular block. System wide TLC decides the overall structure
of code generation.
Block TLC’s are used for inlining S-functions. Lets see what is this. When writing S
functions we follow a general C – API. When generating code the same API is called.
This method is least efficient and leads to more function calls, memory usage. Inlining of
S function is done to avoid this. A Block TLC file has to be written for S function to
inline it. This C S function will look after simulation and TLC will look after code
generation. Inlining is necessary for IO blocks like A/D converters.
System wide TLC’s are used to change format of code generation. They are responsible
for translating *.rtw file to C code using Block TLC’s.
You can use Target language compiler to generate any type of code from rtw file by
replaced all the TLC files, or, you can customize the code generated by modifying the
existing file.
Playing with system wide TLC’s is not recommended, as MATLAB will keep on
changing the code generation architecture, system TLC for a version might not work in
another one. But Block TLC is backward compatible.

RTW file
The mdl file of the model is converted to rtw file which is an asci file representing the
specifics of the model. TLC compiler reads the rtw file and then interprets the TLC file
starting from grt.tlc or some other based target platform.
Structure of rtw file mirrors the block diagram structure. It is organized into nested
records and name – value pairs. All rtw files will have a global record of name Compiled
model. For each block in the model there will be a corresponding record in the rtw file.

To access values in record you must go inside that scope. Records are like structures. To
access values inside a record you have use ‘.’ Operator. For ex:
CompiledModel.Block[1].Name – gets the name of block 1.
Direct access of values this way must never be encouraged. Values of records must
only be accessed through library functions provided to ensure portability of TLC
program across various releases.(EXCEPTION: IN CASE OF PARAMS WRITTEN
WITH mdlRTW( ) – comes to use when inlining S functions)

When you are making custom blocks then you can generate block specific details in rtw
file using mdlRTW ( ) function in the S function. For ex: if block has 2 parameters the
value of the parameters at time of simulation must come in the rtw file. This can be
accomplished by using functions written inside mdlRTW ( ) function.
Lets start…
Basic idea of TLC
 All executable line of code must start with %
 All non executable lines (comments) start with %%
 All other line which does not start with either % or %% will go to default output
stream selected which can be MATLAB workspace, some file, NULL (no stream)
etc.

First example:
With this small idea you are having about TLC Lets make model and write a TLC. See
folder exp1.
The model is made. In simulation parameters use fixed step solver with discrete states.
Create rtw file using rtwgen command.
Edit a TLC file exp2.tlc. This TLC file will print the details of model on workspace.
To run the TLC file use the command below in command window.
>> tlc –r exp2.rtw –v exp2.tlc
This means that, compile exp2.rtw using exp2.tlc residing in same directory as exp2.rtw.
Lets try to understand the TLC file now: -
There are lot of records in the rtw file Complied model is the root record. There are
several nested records. Each record will have its own name and other name - value pairs
associated. %with command define the scope for all the executable statements. Whatever
executable statements are there between %with and %endwith will have the same scope
here it is root.
%<expression> This is used for specifying a TLC expression.
By default the output stream in workspace so all results are displayed in workspace now.
If you want to debug think about taking a look at TLC debugger. I will be posting an
article on this.

Output streams
Output streams of TLC deals with where should the output of running TLC file must
come. When you are working with RTW the output stream is C files. So the result of
running TLC will be put in C files.
Second example:
See the folder exp3. There is a TLC file demonstrating the various output streams. The tlc
file when run will direct output to various output stream. To run:
>> tlc exp3.tlc
Lets try to understand:
Openfile command will open a buffer or a file. File1 and file 2 are like file pointers.
Selectfile selects an output stream. Closefile will close the output streams created.
NULL_FILE if selected deselects all output streams. STDOUT will select standard
output stream that is workspace. Please verify the output of program and see what all line
is coming where.

Playing with Blocks

Let us now come to a more complicated example. Now on you must refer to the contents
of mdl.rtw in the MATLAB documentation to understand the variables used in the
program. For example number of blocks in a sub system is given under the variable
NumBlocks in the record of the subsystem. Or number of subsystems in a model will
come in NumNonvirtSubSystems
*Note: If you want to access name – value pairs in rtw file you have got 2 ways to do it.
Either access it directly in TLC or use some library function supplied by MATLAB. It is
advisable never to play directly with rtw file contents as content and structure of rtw file
is evolving in each release.

Third example:
Exp4.tlc: prints the name of all blocks used in the model exp4.mdl.
Lets try to understand:
Some new keywords have been introduced. Foreach – is an important keyword
equivalent to for loops. The mdl have got many subsystems and each subsystem has got
many blocks. So the operation must be like this:
Identify the number of subsystems – take each subsystem – identify the number of blocks
in it – take each block – print its name.
Selection is done with %with and looping is done with %foreach.
%foreach identifier = constant expression
is equivalent to for ( identifier = 0; identifier < number; identifier++)
%break and %continue can be use in the for the same way as in C.

*Note: command line options can be given. Like if you use a switch –atestvar = 1 in TLC
command line it is equivalent to %assign testvar = 1 in TLC code.
Ex: tlc –r exp4.rtw –v exp4.tlc –atestvar=1
This will come to use when conditions line
%if !EXISTS(testvar)
%assign testvar = 0
%endif

Fourth example:
See folder exp5. The TLC file examines the model. In the model there is one subsystem
that is shaded. The TLC program skims through the model and prints the name of shaded
subsystem. This example demonstrates the use of FEVAL tlc function. This function is
used to run matlab commands from TLC file and is of great use.
‘\’ and ‘…’ are used to indicate the continuation of TLC command line.
Before running the TLC program, make sure that the model is already open.

%roll directive
This is very important and difficult to understand TLC directive that results in the
formation of for – loops based on loop rolling threshold value. Let us examine this in
detail.
Syntax is:

%roll ident1 = roll-vector-exp, ident2 = threshold-exp, ...

block-exp [, type-string [,exp-list] ]
%break
%continue
%endroll
If a range is provided in roll-vector-exp and that range is greater than threshold
expression loop will roll. As loop rolls the body of loop is expanded and ident2 is set to
name of loop control variable. If no range is larger than threshold value then this
statement is similar to %foreach.
For example,
%roll Idx = [ 1 2 3:5, 6, 7:10 ], lcv = 10, ablock
%endroll
In this case, the body of the %roll statement expands 10 times as in the %foreach
statement since there are no regions greater than or equal to 10. Idx counts from 1 to 10,
and lcv is set to the null string, "".
This equivalent to
%foreach Idx = 10
%endroll
Once the compiler determines that the loop will roll then it will perform a
GENERATE_TYPE function call to generate the relevant pieces of loop.

Example of loop rolling:

%assign rollVars = ["U", "Y"]
%roll sigIdx=RollRegions, lcv=RollThreshold, block, ...
"Roller", rollVars
%assign u = LibBlockInputSignal(0, "", lcv, sigIdx)
%assign y = LibBlockOutputSignal(0, "", lcv, sigIdx)
%<y> = 2.0 * %<u>;
%endroll

%roll sigIdx=RollRegions, lcv=RollThreshold, block, "Roller", rollVars

This line performs the loop rolling. RollThreshold is the threshold value obtained from
loop rolling threshold value in simulation parameters dialog box. SigIdx is used to
specify the index of the vector. Rollvars will tell which all things are to be rolled here
they are input and output only. Vector size of input signal is greater than rollthreshold
value then the body of loop is rolled otherwise it is inlined.
These things can be understood only if you work with Block TLC’s considerably.

Forward
Now with this basic idea and acquaintance from the example you can now start writing
Block TLC and system wide TLC’s. Lot of TLC library functions are there. Please take a
look into documentation for further reference. I have also posted documents on writing
Block and system TLC’s which can be studied after reading this.
Any comments contact me: