Real-Time Workshop® Embedded Coder™

Introduction to Target Function Libraries

Overview of Target Function Libraries

The Real-Time Workshop Embedded Coder software provides the target function library (TFL) API, which allows you to create and register function replacement tables. When selected for a model, these TFL tables provide the basis for replacing default math functions and operators in your model code with target-specific code. The ability to control function and operator replacements potentially allows you to optimize target performance (speed and memory) and better integrate model code with external and legacy code.

A target function library (TFL) is a set of one or more function replacement tables that define the target-specific implementations of math functions and operators to be used in generating code for your Simulink model. The Real-Time Workshop software provides three default TFLs, described in the following table. You select these TFLs from the Target function library drop-down list on the Interface pane of the Configuration Parameters dialog box.

When a TFL contains multiple tables, the order in which they are listed reflects the order in which they are searched. The TFL API allows you to create your own TFLs, made up of your own function tables in combination with one of the three default TFLs. For example, you could create a TFL for an embedded processor that combines some special-purpose function customizations with a processor-specific library of function and operator implementations:

Each TFL function replacement table contains one or more table entries, with each table entry representing a potential replacement for a single math function or an operator. Each table entry provides a mapping between a conceptual view of the function or operator (similar to the Simulink block view of the function or operator) and a target-specific implementation of that function or operator.

The conceptual view of a function or operator is represented in a TFL table entry by the following elements, which identify the function or operator entry to the code generation process:

• A function or operator key (a function name such as 'cos' or an operator ID string such as 'RTW_OP_ADD')

• A set of conceptual arguments that observe a Simulink naming scheme ('y1', 'u1', 'u2', ...), along with their I/O types (output or input) and data types

• Other attributes, such as fixed-point saturation and rounding characteristics for operators, as needed to identify the function or operator to the code generation process as exactly as you require for matching purposes

The target-specific implementation of a function or operator is represented in a TFL table entry by the following elements:

• The name of your implementation function (such as 'cos_dbl' or 'u8_add_u8_u8')

• A set of implementation arguments that you define (the order of which must correspond to the conceptual arguments), along with their I/O types (output or input) and data types

• Parameters providing the build information for your implementation function, including header file and source file names and paths

Additionally, a TFL table entry includes a priority value (0–100, with 0 as the highest priority), which defines the entry's priority relative to other entries in the table.

During code generation for your model, when the code generation process encounters a call site for a math function or operator, it creates and partially populates a TFL entry object, for the purpose of querying the TFL database for a replacement function. The information provided for the TFL query includes the function or operator key and the conceptual argument list. The TFL entry object is then passed to the TFL. If there is a matching table entry in the TFL, a fully-populated TFL entry, including the implementation function name, argument list, and build information, is returned to the call site and used to generate code.

Within the TFL that is selected for your model, the tables that comprise the TFL are searched in the order in which they are listed (by RTW.viewTFL or by the TFL's Target function library tool tip). Within each table, if multiple matches are found for a TFL entry object, priority level determines the match that is returned. A higher-priority (lower-numbered) entry is used over a similar entry with a lower priority (higher number).

The TFL API supports the following functions for replacement with custom library functions using TFL tables:

The TFL API also supports the following scalar operators for replacement with custom library functions using TFL tables:

Back to Top

Target Function Libraries General Workflow

The general steps for creating and using a target function library are as follows:

1. Create one or more TFL tables containing replacement entries for math operators (+, –, *, /) and functions using an API based on the MATLAB API. (The demo rtwdemo_tfl_script provides example tables that can be used as a starting point for customization.)

   

2. Register a target function library, consisting of one or more replacement tables, for use with Simulink or Embedded MATLAB Coder software. The M APIs sl_customization and rtwTargetInfo are provided for this purpose.

3. Open your Simulink model and select the desired target function library from the Target function library drop-down list located on the Interface pane of the Configuration Parameters dialog box. For Embedded MATLAB Coder applications, select the desired target function library from the Target function library drop-down list located on the Interface pane of the Real-Time Workshop dialog box.

   

4. Build your Simulink model or Embedded MATLAB Coder application.

See the demo rtwdemo_tfl_script, which illustrates how to use TFLs to replace operators and functions in generated code. With each example model included in this demo, a separate TFL is provided to illustrate the creation of operator and function replacements and how to register the replacements with Simulink software.

Back to Top

Target Function Libraries Quick-Start Example

This section steps you through a simple example of the complete TFL workflow. (The materials for this example can easily be created based on the file and model displays in this section.)

1. Create and save a TFL table definition file that instantiates and populates a TFL table entry, such as the file tfl_table_sinfcn.m shown below. This file creates function table entries for the sin function. For detailed information on creating table definition files for math functions and operators, see Creating Function Replacement Tables.

   function hTable = tfl_table_sinfcn()
   %TFL_TABLE_SINFCN - Describe function entries for a Target Function Library table.
   
   hTable = RTW.TflTable;
   
   % Create entry for double data type sine function replacement
   hTable.registerCFunctionEntry(100, 1, 'sin', 'double', 'sin_dbl', ...
                                                'double', '<sin_dbl.h>','','');
   
   % Create entry for single data type sine function replacement
   hTable.registerCFunctionEntry(100, 1, 'sin', 'single', 'sin_sgl', ...
                                                'double', '<sin_sgl.h>','','');

   Note   See Example: Mapping Floating-Point Math Functions to Target-Specific Implementations for another example of sin function replacement, in which function arguments are created individually.

2. As a first check of the validity of your table entries, invoke the TFL table definition file as follows:

   >> tbl = tfl_table_sinfcn
    
   tbl =
    
   RTW.TflTable
               Version: '1.0'
            AllEntries: [2x1 RTW.TflCFunctionEntry]
       ReservedSymbols: []
   
   >> 

   Any errors found during the invocation are displayed.

3. As a further check of your table entries, invoke the TFL Viewer using the following MATLAB command:

   >> RTW.viewTfl(tfl_table_sinfcn)

   

   Select entries in your table and verify that the graphical display of the contents of your table meets your expectations. (The TFL Viewer can also help you debug issues with the order of entries in a table, the order of tables in a TFL, and function signature mismatches. For more information, see Examining and Validating Function Replacement Tables.)

4. Create and save a TFL registration file that includes the tfl_table_sinfcn table, such as the sl_customization.m file shown below. The file specifies that the TFL to be registered is named 'Sine Function Example' and consists of tfl_table_sinfcn, with the default ANSI^[2] math library as the base TFL table.

   function sl_customization(cm)
   % sl_customization function to register a target function library (TFL)
   
     % Register the TFL defined in local function locTflRegFcn
     cm.registerTargetInfo(@locTflRegFcn);
   
   end % End of SL_CUSTOMIZATION
   
   
   % Local function to define a TFL containing tfl_table_sinfcn
   function thisTfl = locTflRegFcn
   
     % Instantiate a TFL registry entry
     thisTfl = RTW.TflRegistry;
   
     % Define the TFL properties
     thisTfl.Name = 'Sine Function Example'; 
     thisTfl.Description = 'Demonstration of sine function replacement';
     thisTfl.TableList = {'tfl_table_sinfcn'};
     thisTfl.BaseTfl = 'C89/C90 (ANSI)';
     thisTfl.TargetHWDeviceType = {'*'};
   
   end % End of LOCTFLREGFCN

   If you place this sl_customization.m file in the MATLAB search path or in the current working directory, the TFL is registered at each Simulink startup.

   Tip   To refresh Simulink customizations within the current MATLAB session, use the command sl_refresh_customizations. (To refresh Embedded MATLAB Coder TFL registration information within a MATLAB session, use the command RTW.TargetRegistry.getInstance('reset');.)

   For more information about registering TFLs with Simulink or Embedded MATLAB Coder software, see Registering Target Function Libraries.

5. With your sl_customization.m file in the MATLAB search path or in the current working directory, open an ERT-based Simulink model and navigate to the Interface pane of the Configuration Parameters dialog box. Verify that the Target function library option lists the TFL name you specified and select it.

   Note   If you hover over the selected library with the cursor, a tool tip appears. This tip contains information derived from your TFL registration file, such as the TFL description and the list of tables it contains.

   

   Optionally, you can relaunch the TFL Viewer, using the command RTW.viewTFL with no argument, to examine all registered TFLs, including Sine Function Example.

6. Create an ERT-based model with a Trigonometric Function block set to the sine function, such as the following:

   

   Make sure that the TFL you registered, Sine Function Example, is selected for this model.

7. Go to the Real-Time Workshop > Report pane of the Configuration Parameters dialog box and select the options Create code generation report and Model-to-code. Then go to the Real-Time Workshop pane, select the Generate code only option, and generate code for the model.

8. Go to the model window and use model-to-code highlighting to trace the code generated using your TFL entry. For example, right-click the Trigonometric Function block and select Real-Time Workshop > Navigate to Code. This selection highlights the sin function code within the model step function in sinefcn.c. In this case, sin has been replaced with sin_dbl in the generated code.

   

9. If functions were not replaced as you intended, you can use the techniques described in Examining and Validating Function Replacement Tables to help you determine why the code generation process was unable to match a function signature with the TFL table entry you created for it.

   For example, you can view the TFL cache hits and misses logged during the most recent build. For the code generation step in this example, there was one cache hit and zero cache misses, as shown in the following HitCache and MissCache entries:

   >> a=get_param('sinefcn','TargetFcnLibHandle')
    
   a =
    
   RTW.TflControl
           Version: '1.0'
          HitCache: [1x1 RTW.TflCFunctionEntry]
         MissCache: [0x1 handle]
       TLCCallList: [0x1 handle]
         TflTables: [2x1 RTW.TflTable]
   
   >> a.HitCache(1)
    
   ans =
    
   RTW.TflCFunctionEntry
                           Key: 'sin'
                      Priority: 100
                ConceptualArgs: [2x1 RTW.TflArgNumeric]
                Implementation: [1x1 RTW.CImplementation]
   .
   .
   .
   >> 

^[a] GNU is a registered trademark of the Free Software Foundation.

^[2] ANSI is a registered trademark of the American National Standards Institute, Inc.

Back to Top

Target Function Libraries

Creating Function Replacement Tables