Real-Time Workshop Embedded Coder

Customizing an ASAP2 File

The Real-Time Workshop Embedded Coder provides a number of TLC files to enable you to customize the ASAP2 file generated from a Simulink model. The following figure illustrates the hierarchy of ASAP2 related directories and files within the MATLAB directory.

ASAP2 File Structure on the MATLAB Path

The ASAP2 related files are located within the directories shown above. The files are organized as follows:

• TLC files for generating ASAP2 files

• The matlabroot/rtw/c/tlc directory contains TLC files that generate ASAP2 files. These files are included by the Real-Time Workshop Embedded Coder and ASAP2 system target files (ert.tlc and asap2.tlc).

• ASAP2 target files

• The matlabroot/toolbox/rtw/targets/asap2/asap2 directory contains the ASAP2 system target file and other control files.

• ASAP2 class creation files

• The matlabroot/toolbox/rtw/targets/asap2/asap2/@ASAP2 directory contains the M-files that define the ASAP2.Parameter and ASAP2.Signal classes.

• Customizable TLC files

• The matlabroot/toolbox/rtw/targets/asap2/asap2/user directory contains files that you can modify to customize the content of your ASAP2 files.

• ASAP2 templates

• The matlabroot/toolbox/rtw/targets/asap2/asap2/user/templates directory contains templates that define each type of CHARACTERISTIC in the ASAP2 file.

Customizing the Contents of the ASAP2 File

The ASAP2 related TLC files enable you to customize the appearance of the ASAP2 file generated from a Simulink model. Most customization is done by modifying or adding to the files contained in the matlabroot/toolbox/rtw/targets/asap2/asap2/user directory.This section refers to this directory as the asap2/user directory.

The user-customizable files provided are divided into two groups:

• The static files define the parts of the ASAP2 file that are related to the environment in which the generated code is used. They describe information specific to the user and/or project. The static files are not model-dependant.
• The dynamic files define the parts of the ASAP2 file that are generated based on the structure of the source model.

The procedure for customizing the ASAP2 file is as follows:

1. Make a copy of the asap2/user directory before making any modifications.
2. Remove the old asap2/user directory from the MATLAB path, or add the new asap2/user directory to the MATLAB path above the old directory. This will ensure that MATLAB uses the new ASAP2 setup file, asap2setup.tlc.

1. asap2setup.tlc specifies which directories and files to include in the TLC path during the ASAP2 file generation process. Modify asap2setup.tlc to control the directories and folders included in the TLC path.

3. Modify the static parts of the ASAP2 file. These include
• Project and header symbols, which are specified in asap2setup.tlc
• Static sections of the file, such as file header and tail, A2ML, MOD_COMMON, etc. These are specified in asap2userlib.tlc.
• Specify the appearance of the dynamic contents of the ASAP2 file by modifying the existing ASAP2 templates, or by defining new ASAP2 templates. Sections of the ASAP2 file affected include
•     RECORD_LAYOUTS: modify appropriate parts of the ASAP2 template files.
•     CHARACTERISTICS: modify appropriate parts of the ASAP2 template files.

• For more information on modifying the appearance of CHARACTERISTICS, see ASAP2 Templates.

• MEASUREMENTS: These are specified in asap2userlib.tlc.
• COMPU_METHODS: These are specified in asap2userlib.tlc.

ASAP2 Templates

The appearance of CHARACTERISTICS in the ASAP2 file is controlled using a different template for each type of CHARACTERISTIC. The asap2/user directory contains template definition files for scalars, 1-D Lookup Table blocks and 2-D Lookup Table blocks. You can modify these template definition files, or you can create additional templates as required.

The procedure for creating a new ASAP2 template is as follows:

1. Define a parameter group. See Defining Parameter Groups.
2. Create a template definition file. See Creating Template Definition Files.
3. Include the template definition file in the TLC path. The path is specified in the ASAP2 setup file, asap2setup.tlc.

Defining Parameter Groups.   In some cases you must group multiple parameters together in the ASAP2 file (for example, the x and y data in a 1-D Lookup Table block). Parameter groups enable Simulink blocks to define an associative relationship between some or all of their parameters. The following example shows the Lookup1D parameter group and describes how to create and use parameter groups in conjunction with the ASAP2 file generation process.

The BlockInstanceSetup function, within a block's TLC file, creates parameter groups. There are two built-in TLC functions that facilitate this process: SLibCreateParameterGroup and SLibAddMember. The following code fragment creates the Lookup1D parameter group in look_up.tlc. Similar syntax is used to create parameter groups for the Look-Up Table (2D) block, the Fixed-Point Blockset Look-Up Table block, and the Look-Up Table (2-D) block:

• %if GenerateInterfaceAPI
    %% Create a parameter group for ASAP2 data definition
    %assign group  = SLibCreateParameterGroup(block,"Lookup1D")
    %assign tmpVar = SLibAddMember(block,group,InputValues)
    %assign tmpVar = SLibAddMember(block,group,OutputValues)
  %endif
  

ParameterGroup records are not written to the model.rtw file, but are included as part of the relevant Block records in the CompiledModel. The following code fragment shows the Lookup1D parameter group. The Lookup1D parameter group has two Member records. The Reference fields of these records refer to the relevant x and y data records in the GlobalMemoryMap:

• Block {
    Type        Lookup
    Name        "<Root>/Look-Up Table"
    ...
    NumParameterGroups    1
    ParameterGroup {
      Name         Lookup1D
      NumMembers   2
      Member {
        NumMembers   0
        Reference    ...
      }
      Member {
        NumMembers   0
        Reference    ...
      }
    }
  }
  

The Lookup1D parameter group is used by the function ASAP2UserFcnWriteCharacteristic_Lookup1D, which is defined in the template definition file, asap2lookup1d.tlc. This function uses the parameter group to obtain the references to the associated x and y data records in the GlobalMemoryMap, as shown in the following code fragment.

• %function ASAP2UserFcnWriteCharacteristic_Lookup1D(paramGroup) Output
    %assign xParam = paramGroup.Member[0].Reference
    %assign yParam = paramGroup.Member[1].Reference
    ...
  %endfunction
  

Creating Template Definition Files.   This section describes the components that make up an ASAP2 template definition file. This description is in the form of code examples from asap2lookup1d.tlc, the template definition file for the Lookup1D template. This template corresponds to the Lookup1D parameter group.

Note    When creating a new template, use the corresponding parameter group name in place of Lookup1D in the code fragments shown.

The following sections describe the components of an ASAP2 template definition file.

Template Registration Function.   The input argument is the name of the parameter group associated with this template:

• %<LibASAP2RegisterTemplate("Lookup1D")>
  

RECORD_LAYOUT Name Definition Function.   Record layout names (aliases) can be arbitrarily specified for each data type. This function is used by the other components of this file.

• %function ASAP2UserFcnRecordLayoutAlias_Lookup1D(dtId) void
    %switch dtId
    %case tSS_UINT8
      %return "Lookup1D_UBYTE"
    ...
    %endswitch
  %endfunction
  

Function to Write RECORD_LAYOUT Definitions.   This function writes out RECORD_LAYOUT definitions associated with this template. The function is called by the built-in functions involved in the ASAP2 file generation process. The function name must be defined as shown, with the appropriate template name after the underscore:

• %function ASAP2UserFcnWriteRecordLayout_Lookup1D() Output
    /begin RECORD_LAYOUT 
  %<ASAP2UserFcnRecordLayoutAlias_Lookup1D(tSS_UINT8)>
      ...
    /end   RECORD_LAYOUT
  %endfunction
  

Function to Write the CHARACTERISTIC.   This function writes out the CHARACTERISTIC associated with this template. The function is called by the built-in functions involved in the ASAP2 file generation process. The function name must be defined as shown, with the appropriate template name after the underscore.

The input argument to this function is a pointer to a parameter group record. The example shown is for a Lookup1D parameter group that has two members. The references to the associated x and y data records are obtained from the parameter group record as shown.

This function calls a number of built-in functions to obtain the required information. For example, LibASAP2GetSymbol returns the symbol (name) for the specified data record.

• %function ASAP2UserFcnWriteCharacteristic_Lookup1D(paramGroup) 
  Output
    %assign xParam = paramGroup.Member[0].Reference
    %assign yParam = paramGroup.Member[1].Reference
    %assign dtId = LibASAP2GetDataTypeId(xParam)
      /begin CHARACTERISTIC
       /* Name */              %<LibASAP2GetSymbol(xParam)>
       /* Long identifier */   "%<LibASAP2GetLongID(xParam)>"
       ...
      /end CHARACTERISTIC
  %endfunction
  

Generating an ASAP2 File

Structure of the ASAP2 File