eml.unroll - Package: eml

Copy body of for-loop in generated code for each iteration

Syntax

for i = eml.unroll(range) for i = eml.unroll(range,flag)

Description

for i = eml.unroll(range) copies the body of a for-loop (unrolls a for-loop) in generated code for each iteration specified by the bounds in range. i is the loop counter variable.

for i = eml.unroll(range,flag) unrolls a for-loop as specified in range if flag is true.

You must use eml.unroll in a for-loop header. eml.unroll modifies the generated code, but does not affect the computed results.

eml.unroll must be able to evaluate the bounds of the for-loop at compile time. The number of iterations cannot exceed 1024; unrolling large loops can increase compile time significantly and generate inefficient code

This function has no effect in MATLAB code; it applies to the Embedded MATLAB subset only.

Inputs

flag

Boolean expression that indicates whether to unroll the for-loop:

`true`	Unroll the `for-`loop
`false`	Do not unroll the `for-`loop

range

Specifies the bounds of the for-loop iteration:

init_val : end_val Iterate from init_val to end_val, using an increment of 1

init_val : step_val : end_val Iterate from init_val to end_val, using step_val as an increment if positive or as a decrement if negative

Matrix variable Iterate for a number of times equal to the number of columns in the matrix

Examples

Limit the number of times to copy the body of a for-loop in generated code:

Write an Embedded MATLAB compliant function getrand(n) that uses a for-loop to generate a vector of length n and assign random numbers to specific elements. Also, add a test function test_unroll. This function calls getrand(n) with n equal to values both less than and greater than the threshold for copying the for-loop in generated code.

function [y1, y2] = test_unroll() %#eml
% The directive %#eml declares the function
%  to be Embedded MATLAB compliant
  % Trigger flag variable = true
  y1 = getrand(8);
  % Trigger flag variable = false
  y2 = getrand(50);
 
function y = getrand(n)
  % Turn off inlining to make 
  % generated code easier to read
  eml.inline('never');

  % Set flag variable dounroll to repeat loop body
  % only for fewer than 10 iterations
  dounroll = n < 10;
  % Declare size, class, and complexity
  % of variable y by assignment
  y = zeros(n, 1);
  % Loop body begins
  for i = eml.unroll(1:2:n, dounroll)
      if (i > 2) && (i < n-2) 
          y(i) = rand();
      end;
  end;
  % Loop body ends

Generate C library code for test_unroll in the default output directory emcprj/rtwlib/test_unroll:

emlc -T rtw:lib test_unroll

In test_unroll.c, the generated C code for getrand(8) repeats the body of the for-loop (unrolls the loop) because the number of iterations is less than 10:

static void m_getrand(real_T eml_y[8])
{
  int32_T eml_i0;
  for(eml_i0 = 0; eml_i0 < 8; eml_i0++) {
    eml_y[eml_i0] = 0.0;
  }
  /*  Loop body begins */
  eml_y[2] = m_rand();
  eml_y[4] = m_rand();
  /*  Loop body ends */
}

The generated C code for getrand(50) does not unroll the for-loop because the number of iterations is greater than 10:

static void m_b_getrand(real_T eml_y[50])
{
  int32_T eml_i;
  for(eml_i = 0; eml_i < 50; eml_i++) {
    eml_y[eml_i] = 0.0;
  }
  /*  Loop body begins */
  for(eml_i = 0; eml_i < 50; eml_i += 2) {
    if((eml_i + 1 > 2) && (eml_i + 1 < 48)) {
      eml_y[eml_i] = m_rand();
    }
  }
  /*  Loop body ends */
}