4.4. Pragmas

Pragma directives tell the compiler how to treat a certain function, object, or section of code. This section covers pragmas that are relevant to improving performance of executed code. For the complete set of pragmas supported by the compiler, refer to Section 6.10, Pragma Directives in the TMS320C28x Optimizing C/C++ Compiler User’s Guide.

4.4.1. MUST_ITERATE

#pragma MUST_ITERATE ( min, max, multiple )

The MUST_ITERATE pragma specifies to the compiler certain properties of a loop. The arguments min and max are programmer-guaranteed minimum and maximum trip counts. The trip count is the number of times a loop iterates. The trip count of the loop must be evenly divisible by multiple.

Listing 4.10 Using MUST_ITERATE pragma to avoid generating loop bounds checks and enable unrolling by 4.
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
int16_t sum(int16_t* input, int16_t count)
{
    int16_t sum = 0;
    int16_t i   = 0;

    #pragma MUST_ITERATE(4, , 4)
    for (i = 0; i < count; i++)
        sum += input[i];

    return sum;
}

The assembly code generated for Listing 4.10 when compiled with --opt_level=3 is shown in Listing 4.11.

Listing 4.11 Assembly generated with MUST_ITERATE pragma
||sum||:
        MOV       AH,AL
        MOVB      AL,#0
        ASR       AH,2
        ADDB      AH,#-1
        MOVZ      AR6,AH
||$C$L1||:
        ADD       AL,*XAR4++
        ADD       AL,*XAR4++
        ADD       AL,*XAR4++
        ADD       AL,*XAR4++
        BANZ      ||$C$L1||,AR6--
        LRETR

Refer to the Assertions section for another approach to specifying loop information to the compiler.

Warning

When specifying a multiple via the MUST_ITERATE pragma, results of the program are undefined if the trip count is not evenly divisible by multiple. Also, results of the program are undefined if the trip count is less than the minimum or greater than the maximum specified.

4.4.2. UNROLL

#pragma UNROLL(n)

If possible, the compiler unrolls the loop so there are n copies of the original loop. The compiler only unrolls if it can determine that unrolling by a factor of n is safe. In order to increase the chances the loop is unrolled, the compiler needs to know certain properties:

  • The loop iterates a multiple of n times. This information can be specified to the compiler via the multiple argument in the MUST_ITERATE pragma.

  • The smallest possible number of iterations of the loop

  • The largest possible number of iterations of the loop

In cases where the compiler is not able to analyze and determine these properties, the MUST_ITERATE pragma can be used.

Specifying #pragma UNROLL(1) asks that the loop not be unrolled. Automatic loop unrolling also is not performed in this case.

4.4.3. FUNC_ALWAYS_INLINE

#pragma FUNC_ALWAYS_INLINE ( func )

The pragma FUNC_ALWAYS_INLINE and the equivalent always_inline attribute force a function to be inlined (where it is legal to do so) unless --opt_level=off. That is, the pragma FUNC_ALWAYS_INLINE forces function inlining even if the function is not declared as inline and the --opt_level=0 or --opt_level=1.

For a discussion on the benefits of inlining, refer to section Inlining.