flang/docs/Directives.md

   1 <!--===- docs/Directives.md
   2
   3    Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
   4    See https://llvm.org/LICENSE.txt for license information.
   5    SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
   6
   7 -->
   8
   9 # Compiler directives supported by Flang
  10
  11 A list of non-standard directives supported by Flang
  12
  13 * `!dir$ fixed` and `!dir$ free` select Fortran source forms.  Their effect
  14   persists to the end of the current source file.
  15 * `!dir$ ignore_tkr [[(TKRDMAC)] dummy-arg-name]...` in an interface definition
  16   disables some semantic checks at call sites for the actual arguments that
  17   correspond to some named dummy arguments (or all of them, by default).
  18   The directive allow actual arguments that would otherwise be diagnosed
  19   as incompatible in type (T), kind (K), rank (R), CUDA device (D), or
  20   managed (M) status.  The letter (A) is a shorthand for all of these,
  21   and is the default when no letters appear.  The letter (C) checks for
  22   contiguity for example allowing an element of an assumed-shape array to be
  23   passed as a dummy argument. For example, if one wanted to call a "set all
  24   bytes to zero" utility that could be applied to arrays of any type or rank:
  25 ```
  26   interface
  27     subroutine clear(arr,bytes)
  28 !dir$ ignore_tkr arr
  29       integer(1), intent(out) :: arr(bytes)
  30     end
  31   end interface
  32 ```
  33 * `!dir$ assume_aligned desginator:alignment`, where designator is a variable,
  34   maybe with array indices, and alignment is what the compiler should assume the
  35   alignment to be. E.g A:64 or B(1,1,1):128. The alignment should be a power of 2,
  36   and is limited to 256.
  37   [This directive is currently recognised by the parser, but not
  38   handled by the other parts of the compiler].
  39 * `!dir$ vector always` forces vectorization on the following loop regardless
  40   of cost model decisions. The loop must still be vectorizable.
  41   [This directive currently only works on plain do loops without labels].
  42
  43 # Directive Details
  44
  45 ## Introduction
  46 Directives are commonly used in Fortran programs to specify additional actions
  47 to be performed by the compiler. The directives are always specified with the
  48 `!dir$` or `cdir$` prefix.
  49
  50 ## Loop Directives
  51 Some directives are associated with the following construct, for example loop
  52 directives. Directives on loops are used to specify additional transformation to
  53 be performed by the compiler like enabling vectorisation, unrolling, interchange
  54 etc.
  55
  56 Currently loop directives are not accepted in the presence of OpenMP or OpenACC
  57 constructs on the loop. This should be implemented as it is used in some
  58 applications.
  59
  60 ### Array Expressions
  61 It is to be decided whether loop directives should also be able to be associated
  62 with array expressions.
  63
  64 ## Semantics
  65 Directives that are associated with constructs must appear in the same section
  66 as the construct they are associated with, for example loop directives must
  67 appear in the executable section as the loops appear there. To facilitate this
  68 the parse tree is corrected to move such directives that appear in the
  69 specification part into the execution part.
  70
  71 When a directive that must be associated with a construct appears, a search
  72 forward from that directive to the next non-directive construct is performed to
  73 check that that construct matches the expected construct for the directive.
  74 Skipping other intermediate directives allows multiple directives to appear on
  75 the same construct.
  76
  77 ## Lowering
  78 Evaluation is extended with a new field called dirs for representing directives
  79 associated with that Evaluation. When lowering loop directives, the associated
  80 Do Loop's evaluation is found and the directive is added to it. This information
  81 is used only during the lowering of the loop.
  82
  83 ### Representation in LLVM
  84 The `llvm.loop` metadata is used in LLVM to provide information to the optimizer
  85 about the loop. For example, the `llvm.loop.vectorize.enable` metadata informs
  86 the optimizer that a loop can be vectorized without considering its cost-model.
  87 This attribute is added to the loop condition branch.
  88
  89 ### Representation in MLIR
  90 The MLIR LLVM dialect models this by an attribute called LoopAnnotation
  91 Attribute. The attribute can be added to the latch of the loop in the cf
  92 dialect and is then carried through lowering to the LLVM dialect.
  93
  94 ## Testing
  95 Since directives must maintain a flow from source to LLVM IR, an integration
  96 test is provided that tests the `vector always` directive, as well as individual
  97 lit tests for each of the parsing, semantics and lowering stages.