| 1 | |
|---|
| 2 | ARB compiles with vectorization (enabled by -O3 in NDEBUG or RELEASE mode). |
|---|
| 3 | The vectorization check is automatically activated for gcc versions >= 4.9.0 |
|---|
| 4 | Compiler output of earlier versions is not suitable for automated checks. |
|---|
| 5 | |
|---|
| 6 | To ensure that code does not degrade (i.e. does not fail to vectorize), the |
|---|
| 7 | compiler output is searched for successful vectorizations and the result is |
|---|
| 8 | checked against special comments in code. |
|---|
| 9 | |
|---|
| 10 | Currently there are 2 types of comments for vectorization-checks: |
|---|
| 11 | |
|---|
| 12 | IRRELEVANT_LOOP |
|---|
| 13 | LOOP_VECTORIZED[<count>][<exclusions>] |
|---|
| 14 | |
|---|
| 15 | Use IRRELEVANT_LOOP to mark a loop where vectorization occurs (maybe only |
|---|
| 16 | sometimes) and where it isn't mandatory. No error or warning will show if |
|---|
| 17 | vectorization fails. |
|---|
| 18 | |
|---|
| 19 | Note: You have to use IRRELEVANT_LOOP for conditional code (e.g. unittest code) |
|---|
| 20 | |
|---|
| 21 | |
|---|
| 22 | Use LOOP_VECTORIZED for loops that SHALL get vectorized (i.e. loops with |
|---|
| 23 | relevant impact on performance). If vectorization fails for a loop commented |
|---|
| 24 | with LOOP_VECTORIZED, compilation will fail with an error. |
|---|
| 25 | |
|---|
| 26 | The optional argument <count> allows to specify the amount of performed |
|---|
| 27 | vectorizations. This is relevant if the loop is part of a template, gets |
|---|
| 28 | vectorized multiple times and it shall be ensured that the vectorizations |
|---|
| 29 | happens for each instanciation of that template. |
|---|
| 30 | |
|---|
| 31 | The syntax of the <count> argument is "=<num>" or "=*". The first form |
|---|
| 32 | expects that <num> vectorizations occur. The second form allows any number |
|---|
| 33 | of vectorizations (1 to many). The default for <count> is "=1". |
|---|
| 34 | |
|---|
| 35 | The 2nd optional argument <exclusions> allows to exclude compiler versions |
|---|
| 36 | that fail to vectorize that loop. |
|---|
| 37 | |
|---|
| 38 | The syntax is "["<excl>[","<excl>]*"]". |
|---|
| 39 | <excl> may have any of the following forms: |
|---|
| 40 | |
|---|
| 41 | "!" <version> exclude specified version |
|---|
| 42 | "!<" <version> exclude all versions BEFORE specified version |
|---|
| 43 | "!>" <version> exclude all versions AFTER specified version |
|---|
| 44 | "!<="<version> exclude all versions UNTIL specified version |
|---|
| 45 | "!>="<version> exclude all versions SINCE specified version |
|---|
| 46 | |
|---|
| 47 | <version> is a specific compiler version (e.g. "4.9.3" or "493" or "5"). |
|---|
| 48 | |
|---|
| 49 | Multiple conditions can be specified in one <excl>, e.g. "!>=5<7" excludes |
|---|
| 50 | all compilers of 5.x and 6.x series. |
|---|
| 51 | |
|---|
| 52 | Example: // LOOP_VECTORIZED[!493,!531] |
|---|
| 53 | => expects vectorization occurs for all compiler versions but 4.9.3 and 5.3.1 |
|---|
| 54 | |
|---|
| 55 | Included code: |
|---|
| 56 | |
|---|
| 57 | Vectorization checks do not work very well with included code (e.g. inline |
|---|
| 58 | code from headers): IRRELEVANT_LOOP behaves normal, but LOOP_VECTORIZED may |
|---|
| 59 | differ for different includers. 'LOOP_VECTORIZED=*' might work, but is not |
|---|
| 60 | recommended, because if code starts to fail vectorization, no warning will |
|---|
| 61 | show up! If possible better move code from header into source. |
|---|
| 62 | |
|---|
| 63 | Recompilation needed for complete check: |
|---|
| 64 | |
|---|
| 65 | To force a complete check of expected vectorizations call target |
|---|
| 66 | 'clean_checked_vect' before build! Previous failures (only) in |
|---|
| 67 | vectorization-check will not delete the generated object file, i.e. w/o |
|---|
| 68 | change of the affected source file no re-compilation will happen. |
|---|
| 69 | |
|---|
| 70 | Alternative ways to use vectorization checker: |
|---|
| 71 | |
|---|
| 72 | Set ../Makefile@TRACE_MISSED_VECTORIZATIONS |
|---|
| 73 | to 1 to dump details about performed and failed vectorizations. |
|---|
| 74 | |
|---|
| 75 | Set ../Makefile@VECTORIZATION_CHECK_CANDIDATES |
|---|
| 76 | to 1 to dump candidates from unchecked files. |
|---|
| 77 | |
|---|
| 78 | Related stuff: |
|---|
| 79 | |
|---|
| 80 | If you encounter problems caused by vectorization, you may use |
|---|
| 81 | ../TEMPLATES/attributes.h@__ATTR__DONT_VECTORIZE |
|---|
| 82 | |
|---|
| 83 | Some pointers (if you need to adapt vectorization checking): |
|---|
| 84 | |
|---|
| 85 | - global vectorization toggles: |
|---|
| 86 | ../Makefile@DISABLE_VECTORIZE_CHECK |
|---|
| 87 | (automatically disabled if sanitizer enabled) |
|---|
| 88 | ../Makefile@TRACE_MISSED_VECTORIZATIONS |
|---|
| 89 | ../Makefile@VECTORIZATION_CHECK_CANDIDATES |
|---|
| 90 | |
|---|
| 91 | - the build maintains a list of source-files to be checked using |
|---|
| 92 | target 'vectorize_checks' (called via target 'depends'). |
|---|
| 93 | The list is stored in ./vectorized.source |
|---|
| 94 | and is generated by ./Makefile@vectorize_checks |
|---|
| 95 | |
|---|
| 96 | - the actual check is performed by ./postcompile.pl |
|---|
