1.. title:: clang-tidy - altera-unroll-loops 2 3altera-unroll-loops 4=================== 5 6Finds inner loops that have not been unrolled, as well as fully unrolled loops 7with unknown loop bounds or a large number of iterations. 8 9Unrolling inner loops could improve the performance of OpenCL kernels. However, 10if they have unknown loop bounds or a large number of iterations, they cannot 11be fully unrolled, and should be partially unrolled. 12 13Notes: 14 15- This check is unable to determine the number of iterations in a ``while`` or 16 ``do..while`` loop; hence if such a loop is fully unrolled, a note is emitted 17 advising the user to partially unroll instead. 18 19- In ``for`` loops, our check only works with simple arithmetic increments ( 20 ``+``, ``-``, ``*``, ``/``). For all other increments, partial unrolling is 21 advised. 22 23- Depending on the exit condition, the calculations for determining if the 24 number of iterations is large may be off by 1. This should not be an issue 25 since the cut-off is generally arbitrary. 26 27Based on the `Altera SDK for OpenCL: Best Practices Guide 28<https://www.altera.com/en_US/pdfs/literature/hb/opencl-sdk/aocl_optimization_guide.pdf>`_. 29 30.. code-block:: c++ 31 32 for (int i = 0; i < 10; i++) { // ok: outer loops should not be unrolled 33 int j = 0; 34 do { // warning: this inner do..while loop should be unrolled 35 j++; 36 } while (j < 15); 37 38 int k = 0; 39 #pragma unroll 40 while (k < 20) { // ok: this inner loop is already unrolled 41 k++; 42 } 43 } 44 45 int A[1000]; 46 #pragma unroll 47 // warning: this loop is large and should be partially unrolled 48 for (int a : A) { 49 printf("%d", a); 50 } 51 52 #pragma unroll 5 53 // ok: this loop is large, but is partially unrolled 54 for (int a : A) { 55 printf("%d", a); 56 } 57 58 #pragma unroll 59 // warning: this loop is large and should be partially unrolled 60 for (int i = 0; i < 1000; ++i) { 61 printf("%d", i); 62 } 63 64 #pragma unroll 5 65 // ok: this loop is large, but is partially unrolled 66 for (int i = 0; i < 1000; ++i) { 67 printf("%d", i); 68 } 69 70 #pragma unroll 71 // warning: << operator not supported, recommend partial unrolling 72 for (int i = 0; i < 1000; i<<1) { 73 printf("%d", i); 74 } 75 76 std::vector<int> someVector (100, 0); 77 int i = 0; 78 #pragma unroll 79 // note: loop may be large, recommend partial unrolling 80 while (i < someVector.size()) { 81 someVector[i]++; 82 } 83 84 #pragma unroll 85 // note: loop may be large, recommend partial unrolling 86 while (true) { 87 printf("In loop"); 88 } 89 90 #pragma unroll 5 91 // ok: loop may be large, but is partially unrolled 92 while (i < someVector.size()) { 93 someVector[i]++; 94 } 95 96Options 97------- 98 99.. option:: MaxLoopIterations 100 101 Defines the maximum number of loop iterations that a fully unrolled loop 102 can have. By default, it is set to `100`. 103 104 In practice, this refers to the integer value of the upper bound 105 within the loop statement's condition expression. 106