Debian Codegraph @

llvm-project/clang-tools-extra/docs/clang-tidy/checks/altera/unroll-loops.rst

raw
1 .. title:: clang-tidy - altera-unroll-loops
2
3 altera-unroll-loops
4 ===================
5
6 Finds inner loops that have not been unrolled, as well as fully unrolled loops
7 with unknown loop bounds or a large number of iterations.
8
9 Unrolling inner loops could improve the performance of OpenCL kernels. However,
10 if they have unknown loop bounds or a large number of iterations, they cannot
11 be fully unrolled, and should be partially unrolled.
12
13 Notes:
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
27 Based 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
96 Options
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.