Data Alignment for Code Replacement - MATLAB & Simulink (original) (raw)

Main Content

Code replacement libraries can align data objects passed into a replacement function to a specified boundary.

Code Replacement Data Alignment

You can take advantage of function implementations that require aligned data to optimize application performance when using MATLAB® Coder™. To configure data alignment for a function implementation:

1. Specify the data alignment requirements in a code replacement entry. Specify alignment separately for each implementation function argument or collectively for all function arguments. See Specify Data Alignment Requirements for Function Arguments.
2. Specify the data alignment capabilities and syntax for one or more compilers. Include the alignment specifications in a library registration entry in the rtwTargetInfo.m file. See Provide Data Alignment Specifications for Compilers.
3. Register the library containing the table entry and alignment specification object.
4. Configure the code generator to use the code replacement library and generate code. Observe the results.

For examples, see Programmatically Develop a Code Replacement Library Using Data Alignment and the “Data Alignment for Function Implementations” section of the Optimize Generated Code by Developing and Using Code Replacement Libraries - Simulink example page.

Specify Data Alignment Requirements for Function Arguments

To specify the data alignment requirement for an argument in a code replacement entry:

• If you are defining a replacement function in a code replacement table registration file, create an argument descriptor object (RTW.ArgumentDescriptor). Use its AlignmentBoundary property to specify the required alignment boundary and assign the object to the argument Descriptor property.
• If you are defining a replacement function using the Code Replacement Tool, on the Mapping Information tab, in the Argument properties section for the replacement function, enter a value for the Alignment value parameter.
  

The AlignmentBoundary property (or Alignment value parameter) specifies the alignment boundary for data passed to a function argument, in number of bytes. The AlignmentBoundary property is valid only for addressable objects, including matrix and pointer arguments. It is not applicable for value arguments. Valid values are:

• -1 (default) — If the data is a Simulink.Bus, Simulink.Signal, or Simulink.Parameter object, specifies that the code generator determines an optimal alignment based on usage. Otherwise, specifies that there is not an alignment requirement for this argument.
• Positive integer that is a power of 2 — Specifies number of bytes in the boundary. The starting memory address for the data allocated for the function argument is a multiple of the specified value. If you specify an alignment boundary that is less than the natural alignment of the argument data type, the alignment directive is emitted in the generated code. However, the target compiler ignores the directive.

The following code specifies the AlignmentBoundary for an argument as 16 bytes.

hLib = RTW.TflTable; entry = RTW.TflCOperationEntry; arg = getTflArgFromString(hLib, 'u1','single*'); desc = RTW.ArgumentDescriptor; desc.AlignmentBoundary = 16; arg.Descriptor = desc; entry.Implementation.addArgument(arg);

The equivalent alignment boundary specification in the Code Replacement Tool dialog box is in this figure.

Note

If your model imports Simulink.Bus, Simulink.Parameter, or Simulink.Signal objects, specify an alignment boundary in the object properties, using the Alignment property. For more information, see Simulink.Bus, Simulink.Parameter, and Simulink.Signal.

Provide Data Alignment Specifications for Compilers

To support data alignment in generated code, describe the data alignment capabilities and syntax for your compilers in the code replacement library registration. Provide one or more alignment specifications for each compiler in a library registry entry.

• If you are defining a code replacement library registration entry in a rtwTargetInfo.m customization file, add one or more AlignmentSpecification objects to an RTW.DataAlignment object. Attach the RTW.DataAlignment object to the TargetCharacteristics object of the registry entry.
  The RTW.DataAlignment object also has the property DefaultMallocAlignment, which specifies the default alignment boundary, in bytes, that the compiler uses for dynamically allocated memory. If the code generator uses dynamic memory allocation for a data object involved in a code replacement, this value determines if the memory satisfies the alignment requirement of the replacement. If not, the code generator does not use the replacement. The default value for DefaultMallocAlignment is -1, indicating that the default alignment boundary used for dynamically allocated memory is unknown. In this case, the code generator uses the natural alignment of the data type to determine whether to allow a replacement.
  Additionally, you can specify the alignment boundary for complex types by using the addComplexTypeAlignment function.
• If you are generating a customization file function using the Code Replacement Tool, fill out the following fields for each compiler.
  
  Click the plus (+) symbol to add additional compiler specifications.

For each data alignment specification, provide the following information.

An example of a data alignment specification for the GCC compiler follows.

da = RTW.DataAlignment;

as = RTW.AlignmentSpecification; as.AlignmentType = {'DATA_ALIGNMENT_LOCAL_VAR', ... 'DATA_ALIGNMENT_STRUCT_FIELD', ... 'DATA_ALIGNMENT_GLOBAL_VAR'}; as.AlignmentSyntaxTemplate = 'attribute((aligned(%n)))'; as.AlignmentPosition = 'DATA_ALIGNMENT_PREDIRECTIVE'; as.SupportedLanguages = {'c', 'c++'}; da.addAlignmentSpecification(as);

tc = RTW.TargetCharacteristics; tc.DataAlignment = da;

Here is the corresponding specification in the Generate registration file dialog box of the Code Replacement Tool.

Specify Data Alignment in MATLAB Code for Imported Data

If MATLAB Coder code replacements that require data alignment use imported data, such as an entry-point or exported function I/O, specify data alignment to external code with coder.dataAlignment statements in the MATLAB code.

If MATLAB Coder code replacements occur that require data alignment (uses imported data), such as an entry-point or exported function with I/O, specify code replacement data alignment with coder.DataAlignment statements in the MATLAB code.

To specify the data alignment requirements for imported data in a MATLAB code:

• For each instance of imported data that requires data alignment, specify the alignment in the function with a coder.dataAlignment statement of the form:
  coder.dataAlignment('_`varName`_', _`alignvalue`_)
• The varName is a character array of the variable name that requires alignment information specification. The_alignvalue_ is an integer number which should be a power of 2. This number specifies the power-of-2 byte alignment boundary.
• An example function that specifies data alignment is:
  function y = testFunction(x1,x2)
  coder.dataAlignment('x1',16); % Specifies information
  coder.dataAlignment('x2',16); % Specifies information
  coder.dataAlignment('y',16); % Specifies information
  y = x1 + x2;
  end

If testFunction is an entry-point or exported function, imported data x1, x2, and y are not aligned automatically by the code generator. The coder.DataAlignment statements for these variables are only meant as information for the code generator. The call sites allocating memory for the data need to ensure that the data is aligned as specified.

You also can specify code replacement data alignment for exported data, such as aglobal variable or an ExportedGlobal storage class. For more information, see Choose Storage Class for Controlling Data Representation in Generated Code.

See Also

Topics

• Code You Can Replace From Simulink Models
• Define Code Replacement Library Optimizations
• Develop a Code Replacement Library