MATLAB: How to call custom MATLAB functions in code generation templates (.cgt) files

Embedded Coder

I have a function called "getMatlabVersion.m" in my current folder. I'd like to use it in my custom code generation template file to display the MATLAB version in the banner of each source file.

I have written a .cgt file that has a line with the following:

*       MATLAB Version: %<!getMatlabVersion()>

However, when I build the above, I get the following error:

Code Generation 1

Elapsed: 3 sec

Error: File: myCustomTemplate_cgt.tlc

Attempt to call a non-function value: GetMatlabVersion

Error: File: myCustomTemplate_cgt.tlc

Values of NULL type cannot be expanded

How do I call my function within my .cgt file?

Best Answer

Code generation templates are eventually generated into .tlc files if you try to call functions within them. This means you can leverage functions from TLC programming.

In TLC programming, you would use the FEVAL function to call any MATLAB functions. Similarly, you can use the same function n your .cgt file, like so:

*       MATLAB Version: %<!getMatlabVersion()>

would become

*       MATLAB Version: %<!FEVAL("getMatlabVersion")>

The above will allow you to call custom MATLAB functions from within your .cgt file.

Another way would be to use the same syntax original syntax

* MATLAB Version: %<!getMatlabVersion()>

but also write a custom file processing template that defines the above function. You would attach this file to the model using "Configuration parameters -> Code generation -> templates -> custom file processing" and put your .tlc file there.

The contents of your custom TLC would look like this:

%function getMatlabVersion() void
%assign outBuffer = ""
%openfile outBuffer
%assign result = FEVAL("getMatlabVersion")
%<result>
%closefile outBuffer
%return outBuffer
%endfunction

This requires knowledge of TLC programming. Refer to the following links for more information on the above:

Custom File Processing

TLC Programming

Related Solutions

MATLAB: How to use the Code Generation Template (CGT) File

1.) The simplest use for the CGT is to be used for code markup, in fact much of the surface level functionality is geared towards this. For example we provide four built in definitions for code mark up:

File Banner Section

(Optional) This section contains comments and tokens you use in generating a custom file banner.

Function Banner Section

(Optional) This section contains comments and tokens for use in generating a custom function banner.

Shared Utility Function Banner Section

(Optional) This section contains comments and tokens for use in generating a custom shared utility function banner.

File Trailer Section

(Optional) This section contains comments for use in generating a custom trailer banner.

An example syntax would be something like this:

 <FunctionBanner style = "open_box" width = "80">
 Model Name        : %<ModelName>
 FunctionName      : %<FunctionName>
 Return Type       : %<ReturnType>
 Arguments         : %<Arguments>
 Block             : %<GeneratedFor>
 Abstract          : %<FunctionDescription>
 Block Description : %<BlockDescription style = "content_only">
 </FunctionBanner>

Which would subsequently generate this in the code:

More in-depth syntax for these sections is described on this page here:

https://www.mathworks.com/help/releases/R2018a/ecoder/ug/generate-custom-file-and-function-banners.html

And the example that this was drawn from can be opened using

>> rtwdemo_codetemplate

2.) You can also use the CGT file to simply drop text you would like to have placed in the generated code before or after a desired section. For example if I modify this section of the CGT from this:

 %<Includes>

 %<Defines>

 %<Types>

 %<Enums>

 %<Definitions>

 %<Declarations>

 %<Functions>

To this:

 #include topinclude.h
 %<Includes>
 #include bottominclude.h
 %<Defines>
 %<Types>
 %<Enums>
 %<Definitions>
 %<Declarations>
 %<Functions>

then the subsequent code generation will produce the following:

This covers the basic functionality of the CGT file.

3.) Now, for more advanced use and specification of custom tokens, sections and subsections we need to bring in the Custom File Processing (CFP) template file described here:

https://www.mathworks.com/help/releases/R2018a/ecoder/ug/generate-source-and-header-files-with-a-custom-file-processing-cfp-template.html#f25568

The CFP file can be used for a few purposes, the most important of which are, generating your own additional source and header files, and modifying the predefined source and header files that normally get generated. The following code in a CFP file can be used to modify the standard generated header file, and serves as a good template for how to modify the predefined sections in the CGT file:

 %%Add a #define to the model's public header file model.h
 %assign pubName = LibGetMdlPubHdrBaseName()
 %assign modelH = LibCreateSourceFile("Header", "Simulink", pubName)
 %openfile tmpBuf
 #define ACCELERATION 9.81
 %closefile tmpBuf
 %<LibSetSourceFileSection(modelH,"Defines",tmpBuf)>

The %assign statements are getting the name of the generated header file and grabbing the file itself

The text inside the %openfile %closefile pair is what we want to append to the header file

And the final statement is pushing the text from the buffer tmpBuf and appending it to modelH (the header file we specifed earlier) at the "Defines" section.

The entirety of the CFP doc page is a very good start if you want to dive deeper into TLC code generation and manipulating the Code Generation Output and I would suggest following through the example if you want to understand more about the creation of custom sections to use in the CGT file, or other customization of the code generation process. I would also just like to mention that if you do make custom modifications to the code generation process, we cannot guarantee the functionality of the newly modified code, so always make sure to check the effects of modifying these files.

MATLAB: How to customize the “main” function generated by Real-Time Workshop Embedded Coder 5.2 (R2008b)

Among other ways, Real-Time Workshop Embedded Coder 5.2 (R2008b) provides two types of customization files to change the appearance of the generated code:

1. Code Generation Template or CGT files which control the overall structure of the generated code. These customizations are applied to most of the code and data files generated by Real-Time Workshop Embedded Coder. These template files are specified in the “Code Template” and “Data Template” panels under 'Configuration Parameters -> Real-Time Workshop -> Templates'.

2. Custom File Processing or CFP Templates which control the control the content of individual files in the generated code. This file is specified in the “Custom Template” panel of 'Configuration Parameters -> Real-Time Workshop -> Templates'.

In order to customize the auto-generated "main" function, a custom CFP Template file needs to be specified.

Refer to the steps below in order to customize the "main" function:

1. For any model, by default, "example_file_process.tlc" CFP Template file is specified to generate the "main" function. However, in this file, line 23 declaring the flag "ERTCustomFileTest" is commented out. Hence the contents of this file are not being used. Uncommenting this line will cause Real-Time Workshop Embedded Coder to use the contents of this CFP template file.

2. Lines 104-112 of this file call the template for a "main" function stored in the files "bareboard_srmain.tlc" OR "bareboard_mrmain.tlc". The structure of the main program depends on the content of these TLC files.

Now if you try to generate code for a model by using this file (after uncommenting line 23), the following lines of code will be executed and the warning message will no longer appear in the generated "main" function since it is not defined in the TLC files that are being called in the code below.

%%Create a simple main. Files are located in $MATLABROOT/rtw/c/tlc/mw.
    %if LibIsSingleRateModel() || LibIsSingleTasking()
      %include "bareboard_srmain.tlc"
      %<FcnSingleTaskingMain()>
    %else
      %include "bareboard_mrmain.tlc"
      %<FcnMultiTaskingMain()>
    %endif

In fact, these are the only lines of TLC code required in a custom "File customization template" file to create a custom "main" function and for picking up the template for the "main" function from "bareboard_srmain.tlc" or "bareboard_mrmain.tlc" file. Hence, the rest of the lines in the TLC file can be deleted while testing.

To create a custom look for the "main" function, modify the contents of the following files to suit the requirements:

a. $MATLABROOT\rtw\c\tlc\mw\bareboard_mrmain.tlc

b. $MATLABROOT\rtw\c\tlc\mw\bareboard_srmain.tlc

c. $MATLABROOT\toolbox\rtw\targets\ecoder\example_file_process.tlc

For details on how to use these advanced customization techniques please refer to the link below:

https://www.mathworks.com/help/releases/R2008b/toolbox/ecoder/index.html?/help/releases/R2008b/toolbox/ecoder/ug/f22219.html

In MATLAB 8.0 (R2012b) from MATLAB commad line:

>> web([docroot '/ecoder/ug/configure-templates-for-customizing-code-organization-and-format.html'])

Best Answer

Related Solutions

MATLAB: How to use the Code Generation Template (CGT) File

MATLAB: How to customize the “main” function generated by Real-Time Workshop Embedded Coder 5.2 (R2008b)

Related Question