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.

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.

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.

Note

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

Optimize Loops in MATLAB Function Blocks

To optimize loops for MATLAB code that is inside a MATLAB Function block, use the LoopOptimization HDL block property. Your options for the LoopOptimization HDL block property depend on whether the Architecture HDL block property is set to MATLAB Function or MATLAB Datapath.

Choose from these settings for the LoopOptimization HDL block property when you set Architecture to MATLAB Function:

LoopOptimization SettingDescription
none (default)Do not optimize loops.
UnrollingUnroll loops.
'Streaming'Stream loops and then stream vector data paths to scalar data paths.

Choose from these settings for LoopOptimization when you set Architecture to MATLAB Datapath:

LoopOptimization SettingDescription
Unrolling (default)Unroll loops.

Streaming (since R2026a)

Unroll loops and then stream vector data paths to scalar data paths.

To partially stream vector data paths, set LoopOptimization to Unrolling, and use the StreamingFactor HDL block property.

How to Optimize MATLAB Function Block For Loops

To select a loop optimization using the HDL Block Properties dialog box:

  1. Right-click the block. To add the HDL Coder app options to the context menu, point to Select Apps and click HDL Coder. Then, in the HDL Coder app section, select HDL Block Properties.

  2. The HDL Block Properties dialog box opens. In the General tab, set the LoopOptimization property to none, Unrolling, or Streaming.

To select a loop optimization from the command line, use hdlset_param. For example, to turn on loop streaming for a MATLAB Function block, my_mlfn:

hdlset_param('my_mlfn', 'LoopOptimization', 'Streaming')
See also hdlset_param.

Limitations for Loop Optimization

HDL Coder cannot stream a loop in MATLAB or in a MATLAB Function block if:

  • If there are 2 or more nested loops at the same level of hierarchy within another loop, the code generator streams one of them and the remaining loop is not streamed.

  • Any particular persistent variable is updated both inside and outside a 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