Main Content

Optimize MATLAB Loops

With loop optimization, you can stream or unroll loops in generated code. Loop streaming is an area optimization, and loop unrolling is a speed optimization. To optimize loops for MATLAB® code that is inside a MATLAB Function block, use the MATLAB Function architecture. When you use the MATLAB Datapath architecture, the code generator unrolls loops irrespective of the loop optimization setting.

Loop Streaming

HDL Coder™ streams a loop by instantiating the loop body once and using that instance for each loop iteration. The code generator oversamples the loop body instance to keep the generated loop functionally equivalent to the original loop.

If you stream a loop, the advantage is decreased hardware resource usage because the loop body is instantiated fewer times. The disadvantage is the hardware implementation runs at a lower speed.

You can partially stream a loop. A partially streamed loop instantiates the loop body more than once, so it uses more area than a fully streamed loop. However, a partially streamed loop also uses less oversampling than a fully streamed loop.

Loop Unrolling

HDL Coder unrolls a loop by instantiating multiple instances of the loop body in the generated code. You can also partially unroll a loop. The generated code uses a loop statement that contains multiple instances of the original loop body and fewer iterations than the original loop.

The distributed pipelining and resource sharing can optimize the unrolled code. Distributed pipelining can increase speed. Resource sharing can decrease area.

When loop unrolling creates multiple instances, these instances are likely to increase area. Loop unrolling also makes the code harder to read.

How to Optimize MATLAB Loops

You can specify a global loop optimization by using the HDL Workflow Advisor, or at the command line.

You can also specify a local loop optimization for a specific loop by using the coder.hdl.loopspec pragma in the MATLAB code. If you specify both a global and local loop optimization, the local loop optimization overrides the global setting.

Global Loop Optimization

To specify a loop optimization in the Workflow Advisor:

  1. In the HDL Workflow Advisor left pane, select HDL Workflow Advisor > HDL Code Generation.

  2. In the Optimizations tab, for Loop Optimizations, select None, Unroll Loops, or Stream Loops.

To specify a loop optimization at the command line in the MATLAB to HDL workflow, specify the LoopOptimization property of the coder.HdlConfig object. For example, for a coder.HdlConfig object, hdlcfg, enter one of the following commands:

hdlcfg.LoopOptimization = 'UnrollLoops'; % unroll loops
hdlcfg.LoopOptimization = 'StreamLoops'; % stream loops
hdlcfg.LoopOptimization = 'LoopNone'; % no loop optimization

Local Loop Optimization

To learn how to optimize a specific MATLAB loop, see coder.hdl.loopspec.


If you specify the coder.unroll pragma, this pragma takes precedence over coder.hdl.loopspec. coder.hdl.loopspec has no effect.

Limitations for MATLAB Loop Optimization

HDL Coder cannot stream a loop if:

  • The loop index counts down. The loop index must increase by 1 on each iteration.

  • There are two or more nested loops at the same level of hierarchy within another loop.

  • Any particular persistent variable is updated both inside and outside a loop.

  • A persistent variable that is initialized to a nonzero value is updated inside the loop.

HDL Coder can stream a loop when the persistent variable is:

  • Updated inside the loop and read outside the loop.

  • Read within the loop and updated outside the loop.

You cannot use the coder.hdl.loopspec('stream') pragma:

  • In a subfunction. You must specify it in the top-level MATLAB design function.

  • For a loop that is nested within another loop.

  • For a loop containing a nested loop, unless the streaming factor is equal to the number of iterations.

See Also