Customize Generated ASAP2 File

Note

The function coder.asap2.export (Embedded Coder) does not work with the customizations described in this page.

Note

TLC based customization will be deprecated in a future release. To customize the ASAP2 file, see Customize Generated ASAP2 File (Embedded Coder).

About ASAP2 File Customization

The Embedded Coder^® product provides a number of Target Language Compiler (TLC) files to enable you to customize the ASAP2 file generated from a Simulink^® model.

ASAP2 File Structure on the MATLAB Path

The ASAP2 related files are organized within the folders identified below:

TLC files for generating ASAP2 file
The matlabroot/rtw/c/tlc/mw (open) folder contains TLC files that generate ASAP2 files, asamlib.tlc, asap2lib.tlc, asap2main.tlc, and asap2grouplib.tlc. These files are included by the setting of model configuration parameter System target file.
ASAP2 target files
The matlabroot/toolbox/rtw/targets/asap2/asap2 (open) folder contains the ASAP2 system target file and other control files.
Customizable TLC files
The matlabroot/toolbox/rtw/targets/asap2/asap2/user (open) folder 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 (open) folder contains templates that define each type of CHARACTERISTIC in the ASAP2 file.

Customize 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 (open) folder. This section refers to this folder as the asap2/user folder.

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 or project. The static files are not model dependent.
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:

Make a copy of the asap2/user folder before making modifications.
Remove the old asap2/user folder from the MATLAB^® path, or add the new asap2/user folder to the MATLAB path above the old folder. The MATLAB session uses the ASAP2 setup file, asap2setup.tlc, in the new folder.
asap2setup.tlc specifies the folders and files to include in the TLC path during the ASAP2 file generation process. Modify asap2setup.tlc to control the folders and folders included in the TLC path.
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, and so on 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_LAYOUT: modify parts of the ASAP2 template files.
  CHARACTERISTIC: modify parts of the ASAP2 template files. For more information on modifying the appearance of CHARACTERISTIC records, see ASAP2 Templates.
- MEASUREMENT: These are specified in asap2userlib.tlc.
- COMPU_METHOD: These are specified in asap2userlib.tlc.

ASAP2 Templates

The appearance of CHARACTERISTIC records in the ASAP2 file is controlled using a different template for each type of CHARACTERISTIC. The asap2/user folder 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:

Create a template definition file. See Create Template Definition Files.
Include the template definition file in the TLC path. The path is specified in the ASAP2 setup file, asap2setup.tlc.

Create 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 shown.

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 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 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 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 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

Customize Computation Method Names

In generated ASAP2 files, computation methods translate the electronic control unit (ECU) internal representation of measurement and calibration quantities into a physical model oriented representation. Simulink Coder™ software provides the ability to customize the names of computation methods. You can provide names that are more intuitive, enhancing ASAP2 file readability, or names that meet organizational requirements.

To customize computation method names, use the MATLAB function getCompuMethodName, which is defined in matlabroot/toolbox/rtw/targets/asap2/asap2/user/getCompuMethodName.m.

The getCompuMethodName function constructs a computation method name. The function prototype is

cmName = getCompuMethodName(dataTypeName, cmUnits)

where dataTypeName is the name of the data type associated with the computation method, cmUnits is the units as specified in the Unit property of a Simulink.Parameter or Simulink.Signal object (for example, rpm or m/s), and cmName returns the constructed computation method name.

The default constructed name returned by the function has the format

<localPrefix><datatype>_<cmUnits>

where

<local_Prefix> is a local prefix, CM_, defined in matlabroot/toolbox/rtw/targets/asap2/asap2/user/getCompuMethodName.m.
<datatype> and <cmUnits> are the arguments you specified to the getCompuMethodName function.

Additionally, in the generated ASAP2 file, the constructed name is prefixed with <ASAP2CompuMethodName_Prefix>, a model prefix defined in matlabroot/toolbox/rtw/targets/asap2/asap2/user/asap2setup.tlc.

For example, if you call the getCompuMethodName function with the dataTypeName argument 'int16' and the cmUnits argument 'm/s', and generate an ASAP2 file for a model named myModel, the computation method name would appear in the generated file as follows:

/begin COMPU_METHOD
   /* Name of CompuMethod */ myModel_CM_int16_m_s
   /* Units */ "m/s"
   ...
/end COMPU_METHOD

Suppress Computation Methods for FIX_AXIS

Versions 1.51 and later of the ASAP2 specification state that for certain cases of lookup table axis descriptions (integer data type and no doc units), a computation method is not required and the Conversion Method parameter must be set to the value NO_COMPU_METHOD. You can control whether or not computation methods are suppressed when not required using the Target Language Compiler (TLC) option ASAP2GenNoCompuMethod. This TLC option is disabled by default. If you enable the option, ASAP2 file generation does not generate computation methods for lookup table axis descriptions when not required, and instead generates the value NO_COMPU_METHOD. For example:

/begin CHARACTERISTIC
/* Name            */
lu1d_fix_axisTable_data
...
/begin AXIS_DESCR
    ...	
    /* Conversion Method    */
NO_COMPU_METHOD
    ...
/end CHARACTERISTIC

The ASAP2GenNoCompuMethod option is defined in matlabroot/toolbox/rtw/targets/asap2/asap2/user/asap2setup.tlc.