Target Language Compiler

More on TLC Loop Rolling

The following TLC %roll code is the Outputs function of timestwo.tlc:

• %function Outputs(block, system) Output
    /* %<Type> Block: %<Name> */
    %%
    /* Multiply input by two */
    %assign rollVars = ["U", "Y"]
    %roll idx = RollRegions, lcv = RollThreshold, block,...
    "Roller", rollVars
      %<LibBlockOutputSignal(0, "", lcv, idx)> = \
      %<LibBlockInputSignal(0, "", lcv, idx)> * 2.0;
    %endroll
  
  %endfunction %% Outputs
  

Arguments for %roll

The lines between %roll and %endroll may be either repeated or looped. The key to understanding the %roll directive is in its arguments:

• %roll sigIdx = RollRegions, lcv = RollThreshold, block, ...
   "Roller", rollVars
  

1. TLC uses the first argument, sigIdx, to specify the appropriate index into a (signal) vector that is used in the generated code. If the signal is scalar, when analyzing that block of the model.rtw file, the TLC determines that only a single line of code is required. In this case, it sets sigIdx to 0 so as to access only the first element of a vector, and no loop is constructed.
2. The second argument of %roll, lcv, is generally specified in the %roll directive as lcv = RollThreshold. RollThreshold is global (model-wide) threshold with the default value of 5. Therefore, whenever a block contains more than five contiguous and rollable variables, TLC collapses the lines nested between %roll and %endroll into a loop. If fewer than five contiguous rollable variables exist, %roll does not create a loop and instead produces individual lines of code.
3. The third argument should just be block. This tells TLC that it is operating on block objects. TLC code for S-functions simply use this argument as shown.
4. The fourth argument of %roll is a string, "Roller". This, specified in rtw/c/tlc/roller.tlc, formats the loop. Normally you pass this as is, but other loop control constructs are possible for advanced uses (see LibBlockInputSignal in the Target Language Compiler Functions.
5. The fifth argument, rollVars, tells TLC what types of items should be rolled: input signals, output signals, and/or parameters. It is not necessary to use all of them. In a previous line, rollVars is defined using %assign.

• %assign rollVars = ["U", "Y"]
  

1. This list tells TLC that it is rolling through input signals (Us) and output signals (Ys). In cases where blocks specify an array of parameters instead of a scalar parameter, rollvars is specified as:

   • %assign rollVars = ["U", "Y", "P"]
     

Input Signals, Output Signals, and Parameters

Look at the lines that appear between %roll and %endroll:

• %<LibBlockOutputSignal(0, "", lcv, idx)> = \
  %<LibBlockInputSignal (0, "", lcv, idx)> * 2.0;
  

The TLC library functions LibBlockInputSignal and LibBlockOutputSignal expand to produce scalar or vector identifiers that are appropriately named and indexed. They and a number of related TLC functions are passed four canonical arguments:

1. The first argument corresponds to the input port index for a given block. The first input port has index 0. The second input port has index 1, and so on.
2. The second argument is an index variable reserved for advanced use. For now, specify the second argument as an empty string. In advanced applications, you may define your own variable name to be used as an index with %roll. In such a case, TLC declares this variable as an integer in an appropriate location in the generated code.
3. The third argument to the functions is lcv (loop control variable). As described previously, lcv = RollThreshold was set in %roll to indicate that a loop be constructed whenever RollThreshold (default value of 5) is exceeded. For example, if there are six contiguous inputs into the block, they are rolled into a loop.
4. The fourth argument, sigIdx, enables the TLC to handle special cases. In the event that the RollThreshold is not exceeded (for example, if the block is only connected to a scalar input signal) the TLC does not roll it into a loop. Instead, the TLC provides an integer value for the appropriate index variable in a corresponding line of "inline" code. Whenever the RollThreshold is exceeded, the TLC creates a for-loop and uses an index variable to access inputs, outputs and parameters within the loop.

For further details, see Target Language Compiler Functions.

Change the Loop Rolling Threshold

Debugging Your TLC Code