Embedded MATLAB™

eml.unroll - Unroll a for-loop

Syntax

eml.unroll(range) eml.unroll(range, flag)

Arguments

range

Specification of for-loop parameters in one of the following forms:

initval : endval
initval : stepval : endval
Matrix variable

flag

Boolean variable that indicates whether or not to unroll the loop

Description

Loop unrolling eliminates the loop logic by creating a separate copy of the for-loop body in the generated code for each iteration. Within each iteration, the loop index variable becomes a constant.

eml.unroll(range) unrolls the for-loop in generated code for each iteration specified in range. If range is a matrix variable, the loop iterates as described in Using Arrays as Indices in the MATLAB Programming Fundamentals documentation.

eml.unroll(range, flag) evaluates flag as a boolean expression at compile time and performs the following actions:

If flag:	Action:
Is `true`	Unrolls the for-loop
Is `false`	Does not unroll the for-loop
Is not boolean or cannot be evaluated at compile time	Generates an error

Best Practices for Loop Unrolling

Loop bounds must be known at compile time

eml.unroll must be able to evaluate the bounds of the for-loop at compile time.

Consider the following example:

%#eml
function y = fcn(u, v, w, x)
y = subfcn(u, v, w, x);

function y = subfcn(u, varargin)
y = 0;
for i = eml.unroll(1:u)
    y = y + varargin{i};
end

In this code, the Embedded MATLAB function cannot determine the upper bound of the loop because it depends on the value of input u, a value not known at compile time. As a result, the function does not unroll the loop and generates a compilation error:

Could not unroll the loop because the number 
of iterations is not known at compile time. 
This loop must be unrolled because its counter
variable is used as an index into the cell array.

Do not exceed 1024 iterations

Example

The following example shows how to use eml.unroll with a flag variable called dounroll:

function y = one(x)
  y = x + testfun(x, 8) + testfun(x, 50);
 
function y = testfun(x, n)
  dounroll = n < 10;
  y = 0;
  for i = eml.unroll(1:2:n, dounroll)
      if (i > 2) && (i < n-2) 
          y = y + i;
      end;
  end;

In this example, the for-loop is unrolled in testfun(x, 8) because dounroll is true. The for-loop is not unrolled in testfun(x, 50) because dounroll is false.

eml.target

eml.wref