Add documentation for change in Directives.md

Other misc fixes for review

Author: DavidTruby

flang/docs/Directives.md

@@ -36,6 +36,46 @@ A list of non-standard directives supported by Flang
   and is limited to 256.
   [This directive is currently recognised by the parser, but not
   handled by the other parts of the compiler].
-* `!dir$ vector always` forces vectorization on the following loop regardless 
+* `!dir$ vector always` forces vectorization on the following loop regardless
   of cost model decisions. The loop must still be vectorizable.
   [This directive currently only works on plain do loops without labels].
+
+# Directive Details
+
+## Introduction
+Directives are commonly used in Fortran programs to specify additional actions 
+to be performed by the compiler. The directives are always specified with the 
+`!dir$` or `cdir$` prefix. 
+
+## Loop Directives
+Some directives are associated with the following construct, for example loop
+directives. Directives on loops are used to specify additional transformation to
+be performed by the compiler like enabling vectorisation, unrolling, interchange
+etc.
+
+### Array Expressions
+It is to be decided whether loop directives should also be able to be associated
+with array expressions.
+
+## Semantics
+Dirctives that are associated with constructs must appear in the same section as
+the construct they are associated with, for example loop directives must appear
+in the executable section as the loops appear there. To facilitate this the
+parse tree is corrected to move such directives that appear in the specification
+part into the execution part.
+When a directive that must be associated with a construct appears, a search 
+forward from that directive to the next non-directive construct is performed to
+check that that construct matches the expected construct for the directive.
+Skipping other intermediate directives allows multiple directives to appear on
+the same construct.
+
+## Lowering 
+Evaluation is extended with a new field called dirs for representing directives
+associated with that Evaluation. When lowering loop directives, the associated
+Do Loop's evaluation is found and the directive is added to it. This information
+is used only during the lowering of the loop.
+
+## Testing
+Since directives must maintain a flow from source to LLVM IR, an integration
+test is provided that tests the `vector always` directive, as well as individual
+lit tests for each of the parsing, semantics and lowering stages.

flang/include/flang/Optimizer/Dialect/FIROps.td

@@ -2161,7 +2161,7 @@ def fir_DoLoopOp : region_Op<"do_loop", [AttrSizedOperandSegments,
     OptionalAttr<UnitAttr>:$unordered,
     OptionalAttr<UnitAttr>:$finalValue,
     OptionalAttr<ArrayAttr>:$reduceAttrs,
-    OptionalAttr<LoopAnnotationAttr>:$loop_annotation
+    OptionalAttr<LoopAnnotationAttr>:$loopAnnotation
   );
   let results = (outs Variadic<AnyType>:$results);
   let regions = (region SizedRegion<1>:$region);

flang/lib/Lower/Bridge.cpp

@@ -2598,7 +2598,7 @@ class FirConverter : public Fortran::lower::AbstractConverter {
   }
 
   void attachDirectiveToLoop(const Fortran::parser::CompilerDirective &dir,
-                           Fortran::lower::pft::Evaluation *e) {
+                             Fortran::lower::pft::Evaluation *e) {
     while (e->isDirective())
       e = e->lexicalSuccessor;
 

flang/lib/Optimizer/Transforms/ControlFlowConverter.cpp

@@ -136,9 +136,9 @@ class CfgLoopConv : public mlir::OpRewritePattern<fir::DoLoopOp> {
         loc, comparison, firstBlock, llvm::ArrayRef<mlir::Value>(), endBlock,
         llvm::ArrayRef<mlir::Value>());
 
-    if (auto ann = loop.getLoopAnnotation()) {
+    // Copy loop annotations from the do loop to the loop entry condition.
+    if (auto ann = loop.getLoopAnnotation())
       cond->setAttr("loop_annotation", *ann);
-    }
 
     // The result of the loop operation is the values of the condition block
     // arguments except the induction variable on the last iteration.

flang/lib/Semantics/canonicalize-directives.cpp

@@ -1,4 +1,5 @@
-//===-- lib/Semantics/check-directives.cpp --------------------------------===//
+//===-- lib/Semantics/canonicalize-directives.cpp
+//--------------------------===//
 //
 // Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
 // See https://llvm.org/LICENSE.txt for license information.
@@ -13,7 +14,9 @@ namespace Fortran::semantics {
 
 using namespace parser::literals;
 
-// Check that directives are associated with the correct constructs
+// Check that directives are associated with the correct constructs.
+// Directives that need to be associated with other constructs in the execution
+// part are moved to the execution part so they can be checked there.
 class CanonicalizationOfDirectives {
 public:
   CanonicalizationOfDirectives(parser::Messages &messages)
@@ -107,7 +110,7 @@ void CanonicalizationOfDirectives::CheckLoopDirective(
 }
 
 void CanonicalizationOfDirectives::Post(parser::Block &block) {
-  for (auto it = block.begin(); it != block.end(); ++it) {
+  for (auto it{block.begin()}; it != block.end(); ++it) {
     if (auto *dir{GetConstructIf<parser::CompilerDirective>(*it)}) {
       std::visit(
           common::visitors{[&](parser::CompilerDirective::VectorAlways &) {

flang/lib/Semantics/canonicalize-directives.h

@@ -1,13 +1,14 @@
-//===-- lib/Semantics/check-directives.h ------------------------*- C++ -*-===//
+//===-- lib/Semantics/canonicalize-directives.h ------------------*- C++
+//-*-===//
 //
 // Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
 // See https://llvm.org/LICENSE.txt for license information.
 // SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
 //
 //===----------------------------------------------------------------------===//
 
-#ifndef FORTRAN_SEMANTICS_CHECK_DIRECTIVES_H_
-#define FORTRAN_SEMANTICS_CHECK_DIRECTIVES_H_
+#ifndef FORTRAN_SEMANTICS_CANONICALIZE_DIRECTIVES_H_
+#define FORTRAN_SEMANTICS_CANONICALIZE_DIRECTIVES_H_
 
 namespace Fortran::parser {
 struct Program;
@@ -19,4 +20,4 @@ bool CanonicalizeDirectives(
     parser::Messages &messages, parser::Program &program);
 }
 
-#endif // FORTRAN_SEMANTICS_CHECK_DIRECTIVES_H_
+#endif // FORTRAN_SEMANTICS_CANONICALIZE_DIRECTIVES_H_

flang/test/Fir/vector-always.fir

@@ -18,4 +18,4 @@ func.func @_QPvector_always() -> i32 {
       fir.result %c1, %c1_i32 : index, i32
     }
     return %8#1 : i32
-  }
+  }

flang/test/Lower/vector-always.f90

@@ -1,4 +1,4 @@
-! RUN: %flang_fc1 -emit-fir -o - %s | FileCheck %s
+! RUN: %flang_fc1 -emit-hlfir -o - %s | FileCheck %s
 
 ! CHECK: #access_group = #llvm.access_group<id = distinct[0]<>>
 ! CHECK: #access_group1 = #llvm.access_group<id = distinct[1]<>>

flang/test/Semantics/loop-directives.f90

@@ -1,13 +1,19 @@
 ! RUN: %python %S/test_errors.py %s %flang
 
-program empty
+subroutine empty
   ! ERROR: A DO loop must follow the VECTOR ALWAYS directive
   !dir$ vector always
-end program empty
+end subroutine empty
 
-program non_do
+subroutine non_do
   ! ERROR: A DO loop must follow the VECTOR ALWAYS directive
   !dir$ vector always
   a = 1
-end program non_do
+end subroutine non_do
 
+subroutine execution_part
+  do i=1,10
+  ! ERROR: A DO loop must follow the VECTOR ALWAYS directive
+  !dir$ vector always
+  end do
+end subroutine execution_part