source: trunk/SOURCE_TOOLS/vectorize.README

ARB compiles with vectorization (enabled by -O3 in NDEBUG or RELEASE mode).
The vectorization check is automatically activated for gcc versions >= 4.9.0
Compiler output of earlier versions is not suitable for automated checks.

To ensure that code does not degrade (i.e. does not fail to vectorize), the
compiler output is searched for successful vectorizations and the result is
checked against special comments in code.

Currently there are 2 types of comments for vectorization-checks:

        IRRELEVANT_LOOP
        LOOP_VECTORIZED[[<count>][<conditions>]]*

Use IRRELEVANT_LOOP to mark a loop where vectorization occurs (maybe only
sometimes) and where it isn't mandatory. No error or warning will show if
vectorization fails.

Note: You have to use IRRELEVANT_LOOP for conditional code (e.g. unittest code)


Use LOOP_VECTORIZED for loops that SHALL get vectorized (i.e. loops with
relevant impact on performance). If vectorization fails for a loop commented
with LOOP_VECTORIZED, compilation will fail with an error.

  The optional argument <count> allows to specify the amount of performed
  vectorizations. This is relevant if the loop is part of a template, gets
  vectorized multiple times and it shall be ensured that the vectorizations
  happens for each instanciation of that template.

    The standard syntax of the <count> argument is "=<num>".
    This requires that <num> vectorizations take place.
    The default for <count> is "=1" (if not specified; only directly after LOOP_VECTORIZED).

    Sometimes the count depends on optimization level (esp. whether a
    function gets inlined or not). You may specify '=<num>|<num>' to allow
    several different amounts of accepted vectorizations.
    (Hint: test with DEBUG=0 and UNIT_TEST=0 to check under RELEASE conditions)

  The 2nd optional argument <conditions> allows to include/exclude compiler
  versions that succeed/fail to vectorize that loop with the specified count.

    The syntax is "["<cond>[","<cond>]*"]".
    <cond> has the following syntax:
           ["!"]("<"|">")["="]<version>

    <version> is a specific compiler version (e.g. "4.9.3" or "493" or "5").

    Multiple conditions can be specified in one <cond>, e.g. "!>=5<7" excludes
    all compilers of 5.x and 6.x series.

    Examples for <cond>:

           493                  only version 4.9.3
           !493                 all but 4.9.3
           >493                 all versions after 4.9.3
           >=5<7                5.x and 6.x-series
           !>=8<9               all but 8.x series

    Example: // LOOP_VECTORIZED[!493,!531]
    => expects vectorization occurs for all compiler versions but 4.9.3 and 5.3.1

    Warning: <conditions> reports true only if ALL <cond> are true!
    => // LOOP_VECTORIZED[493,531]
       will NEVER be true!!!

    To chain conditions by OR operator, use
       // LOOP_VECTORIZED[493][531]

Included code:

  Vectorization checks do not work very well with included code (e.g. inline
  code from headers): IRRELEVANT_LOOP behaves normal, but LOOP_VECTORIZED may
  differ for different includers. 'LOOP_VECTORIZED=*' might work, but is not
  recommended, because if code starts to fail vectorization, no warning will
  show up! If possible better move code from header into source.

Recompilation needed for complete check:

  To force a complete check of expected vectorizations call target
  'clean_checked_vect' before build! Previous failures (only) in
  vectorization-check will not delete the generated object file, i.e. w/o
  change of the affected source file no re-compilation will happen.

Alternative ways to use vectorization checker:

  Set ../Makefile@TRACE_MISSED_VECTORIZATIONS
  to 1 to dump details about performed and failed vectorizations.

  Set ../Makefile@VECTORIZATION_CHECK_CANDIDATES
  to 1 to dump candidates from unchecked files.

Related stuff:

  If you encounter problems caused by vectorization, you may use
  ../TEMPLATES/attributes.h@__ATTR__DONT_VECTORIZE

Some pointers (if you need to adapt vectorization checking):

  - global vectorization toggles:
       ../Makefile@DISABLE_VECTORIZE_CHECK
                    (automatically disabled if sanitizer enabled)
       ../Makefile@TRACE_MISSED_VECTORIZATIONS
       ../Makefile@VECTORIZATION_CHECK_CANDIDATES

  - the build maintains a list of source-files to be checked using
    target 'vectorize_checks' (called via target 'depends').
    The list is stored in ./vectorized.source
    and is generated by ./Makefile@vectorize_checks

  - the actual check is performed by ./postcompile.pl@parse_expected_vectorizations