[SYCL][FPGA] Add support for new attribute for loop pipelining (#6254)

This patch adds support for new FPGA attribute called [[intel::fpga_pipeline(N)]] that takes a Boolean parameter.
N can be a template parameter or constexpr. If the user didn't provide a parameter, the default value of N would
be 1, which implies enable pipelining.

This attribute can be applied to loops.

Example syntax:

// will disable loop pipelining
[[intel::fpga_pipeline(0)]]
for (int i = 0; i<N; ++i) {...}

LLVM IR:
When applied on a loop, the LLVM IR should be attached to llvm.loop metadata:

!{!"llvm.loop.intel.pipelining.enable", i32 N}

The value of the !"llvm.loop.intel.pipelining.enable" metadata is an i32 value that corresponds to the boolean parameter N.
A value of 0 is used for not pipelining the loop.
A value of 1 is used for pipelining the loop.

If the parameter is not given, value of N will be the default value 1,  which implies we will pipeline the loop, and the IR will look like

!{!"llvm.loop.intel.pipelining.enable", i32 1}

Error Message:

We should emit an error when [[intel::initiation_interval(k)]] and [[intel::fpga_pipeline(0)]] are used together:

"error: initiation_interval and fpga_pipeline(0) attributes are not compatible"

We should emit an error when [[intel::max_concurrency(k)]] and [[intel::fpga_pipeline(0)]] are used together:

"error: max_concurrency and fpga_pipeline(0) attributes are not compatible"

Note: this basically performs very similar functionalities as [[intel::disable_loop_pipelining]], the plan is to deprecate disable_loop_pipelining in future releases and use [[intel::fpga_pipeline(n)]] instead.

Signed-off-by: Soumi Manna <soumi.manna@intel.com>

Author: smanna12

clang/include/clang/Basic/Attr.td

@@ -2308,6 +2308,23 @@ def : MutualExclusions<[SYCLIntelFPGAIVDep,
 def : MutualExclusions<[SYCLIntelFPGAMaxConcurrency,
                         SYCLIntelFPGADisableLoopPipelining]>;
 
+def SYCLIntelFPGAPipeline : InheritableAttr {
+  let Spellings = [CXX11<"intel","fpga_pipeline">];
+  let Args = [ExprArgument<"Value", /*optional*/1>];
+  let LangOpts = [SYCLIsDevice, SilentlyIgnoreSYCLIsHost];
+  let Subjects = SubjectList<[ForStmt, CXXForRangeStmt, WhileStmt, DoStmt],
+                              ErrorDiag, "'for', 'while', and 'do' statements">;
+  let Documentation = [SYCLIntelFPGAPipelineAttrDocs];
+  let IsStmtDependent = 1;
+}
+
+def : MutualExclusions<[SYCLIntelFPGAInitiationInterval,
+                        SYCLIntelFPGAPipeline]>;
+def : MutualExclusions<[SYCLIntelFPGAIVDep,
+                        SYCLIntelFPGAPipeline]>;
+def : MutualExclusions<[SYCLIntelFPGAMaxConcurrency,
+                        SYCLIntelFPGAPipeline]>;
+
 def SYCLIntelFPGALoopCount : StmtAttr {
   let Spellings = [CXX11<"intel", "loop_count_min">,
                    CXX11<"intel", "loop_count_max">,
@@ -2340,6 +2357,9 @@ def SYCLIntelFPGAMaxInterleaving : StmtAttr {
 def : MutualExclusions<[SYCLIntelFPGADisableLoopPipelining,
                         SYCLIntelFPGAMaxInterleaving]>;
 
+def : MutualExclusions<[SYCLIntelFPGAPipeline,
+                        SYCLIntelFPGAMaxInterleaving]>;
+
 def SYCLIntelFPGASpeculatedIterations : StmtAttr {
   let Spellings = [CXX11<"intel", "speculated_iterations">];
   let Subjects = SubjectList<[ForStmt, CXXForRangeStmt, WhileStmt, DoStmt],
@@ -2352,6 +2372,9 @@ def SYCLIntelFPGASpeculatedIterations : StmtAttr {
 def : MutualExclusions<[SYCLIntelFPGADisableLoopPipelining,
                         SYCLIntelFPGASpeculatedIterations]>;
 
+def : MutualExclusions<[SYCLIntelFPGAPipeline,
+                        SYCLIntelFPGASpeculatedIterations]>;
+
 def SYCLIntelFPGANofusion : StmtAttr {
   let Spellings = [CXX11<"intel","nofusion">];
   let Subjects = SubjectList<[ForStmt, CXXForRangeStmt, WhileStmt, DoStmt],

clang/include/clang/Basic/AttrDocs.td

@@ -3291,6 +3291,9 @@ function, or in conjunction with ``max_interleaving``,
 ``speculated_iterations``, ``max_concurrency``, ``initiation_interval``,
 or ``ivdep``.
 
+The ``[[intel::disable_loop_pipelining]]`` attribute spelling is a deprecated
+synonym for ``[[[intel::fpga_pipeline]]`` and will be removed in the future.
+
 .. code-block:: c++
 
   void foo() {
@@ -3303,6 +3306,58 @@ or ``ivdep``.
   }];
 }
 
+def SYCLIntelFPGAPipelineAttrDocs : Documentation {
+  let Category = DocCatVariable;
+  let Heading = "intel::fpga_pipeline";
+  let Content = [{
+The ``intel::fpga_pipeline(N)`` attribute applies to a loop and it allows users
+to disable or enable pipelining iterations of a loop. The attribute optionally
+accepts an integer constant expression that is converted to `bool`. A `true`
+value enables pipelining while a `false` value disables pipelining. The
+optional argument defaults to `true`. This attribute cannot be applied to a
+loop in conjunction with the  ``max_interleaving``, ``speculated_iterations``,
+``max_concurrency``, ``initiation_interval``, or ``ivdep`` attributes.
+
+.. code-block:: c++
+
+  // Disable loop pipelining
+  void bar() {
+    int a[10];
+    [[[intel::fpga_pipeline(0)]] for (int i = 0; i != 10; ++i) a[i] = 0;
+  }
+
+  // Enable loop pipelining
+  void foo() {
+    int var = 0;
+    [[intel::fpga_pipeline(1)]] for (int i = 0; i < 10; ++i) var++;
+  }
+
+  void Array(int *array, size_t n) {
+    // identical to [[intel::fpga_pipeline(1)]]
+    [[intel::fpga_pipeline]] for (int i = 0; i < n; ++i) array[i] = 0;
+  }
+
+  void count () {
+  int a1[10], int i = 0;
+  [[intel::fpga_pipeline(1)]] while (i < 10) {
+    a1[i] += 3;
+  }
+
+  void check() {
+    int a = 10;
+    [[intel::fpga_pipeline(1)]] do {
+      a = a + 1;
+    } while (a < 20);
+  }
+
+  template<int A>
+  void func() {
+    [[intel::fpga_pipeline(A)]] for(;;) { }
+  }
+
+  }];
+}
+
 def SYCLIntelFPGALoopCountAttrDocs : Documentation {
   let Category = DocCatVariable;
   let Heading = "intel::loop_count_min, intel::loop_count_max, intel::loop_count_avg, intel::loop_count";

clang/include/clang/Sema/Sema.h

@@ -2277,6 +2277,9 @@ class Sema final {
   SYCLIntelFPGALoopCoalesceAttr *
   BuildSYCLIntelFPGALoopCoalesceAttr(const AttributeCommonInfo &CI, Expr *E);
 
+  SYCLIntelFPGAPipelineAttr *
+  BuildSYCLIntelFPGAPipelineAttr(const AttributeCommonInfo &CI, Expr *E);
+
   bool CheckQualifiedFunctionForTypeId(QualType T, SourceLocation Loc);
 
   bool CheckFunctionReturnType(QualType T, SourceLocation Loc);

clang/lib/CodeGen/CGLoopInfo.cpp

@@ -611,6 +611,14 @@ MDNode *LoopInfo::createMetadata(
                             llvm::Type::getInt32Ty(Ctx), VC.second))};
     LoopProperties.push_back(MDNode::get(Ctx, Vals));
   }
+
+  for (auto &FP : Attrs.SYCLIntelFPGAPipeline) {
+    Metadata *Vals[] = {MDString::get(Ctx, FP.first),
+                        ConstantAsMetadata::get(ConstantInt::get(
+                            llvm::Type::getInt32Ty(Ctx), FP.second))};
+    LoopProperties.push_back(MDNode::get(Ctx, Vals));
+  }
+
   LoopProperties.insert(LoopProperties.end(), AdditionalLoopProperties.begin(),
                         AdditionalLoopProperties.end());
   return createFullUnrollMetadata(Attrs, LoopProperties, HasUserTransforms);
@@ -654,6 +662,7 @@ void LoopAttributes::clear() {
   PipelineDisabled = false;
   PipelineInitiationInterval = 0;
   SYCLNofusionEnable = false;
+  SYCLIntelFPGAPipeline.clear();
   MustProgress = false;
 }
 
@@ -687,7 +696,8 @@ LoopInfo::LoopInfo(BasicBlock *Header, const LoopAttributes &Attrs,
       Attrs.UnrollEnable == LoopAttributes::Unspecified &&
       Attrs.UnrollAndJamEnable == LoopAttributes::Unspecified &&
       Attrs.DistributeEnable == LoopAttributes::Unspecified && !StartLoc &&
-      Attrs.SYCLNofusionEnable == false && !EndLoc && !Attrs.MustProgress)
+      Attrs.SYCLNofusionEnable == false &&
+      Attrs.SYCLIntelFPGAPipeline.empty() && !EndLoc && !Attrs.MustProgress)
     return;
 
   TempLoopID = MDNode::getTemporary(Header->getContext(), None);
@@ -1011,6 +1021,8 @@ void LoopInfoStack::push(BasicBlock *Header, clang::ASTContext &Ctx,
   // emitted
   // For attribute nofusion:
   // 'llvm.loop.fusion.disable' metadata will be emitted
+  // For attribute fpga_pipeline:
+  // n - 'llvm.loop.intel.pipelining.enable, i32 n' metadata will be emitted
   for (const auto *A : Attrs) {
     if (const auto *IntelFPGAIVDep = dyn_cast<SYCLIntelFPGAIVDepAttr>(A))
       addSYCLIVDepInfo(Header->getContext(), IntelFPGAIVDep->getSafelenValue(),
@@ -1075,6 +1087,15 @@ void LoopInfoStack::push(BasicBlock *Header, clang::ASTContext &Ctx,
 
     if (isa<SYCLIntelFPGANofusionAttr>(A))
       setSYCLNofusionEnable();
+
+    if (const auto *IntelFPGAPipeline =
+            dyn_cast<SYCLIntelFPGAPipelineAttr>(A)) {
+      const auto *CE = cast<ConstantExpr>(IntelFPGAPipeline->getValue());
+      Optional<llvm::APSInt> ArgVal = CE->getResultAsAPSInt();
+      unsigned int Value = ArgVal->getBoolValue() ? 1 : 0;
+      const char *Var = "llvm.loop.intel.pipelining.enable";
+      setSYCLIntelFPGAPipeline(Var, Value);
+    }
   }
 
   setMustProgress(MustProgress);

clang/lib/CodeGen/CGLoopInfo.h

@@ -152,6 +152,10 @@ struct LoopAttributes {
   /// Flag for llvm.loop.fusion.disable metatdata.
   bool SYCLNofusionEnable;
 
+  /// Value for fpga_pipeline variant and metadata.
+  llvm::SmallVector<std::pair<const char *, unsigned int>, 2>
+      SYCLIntelFPGAPipeline;
+
   /// Value for whether the loop is required to make progress.
   bool MustProgress;
 };
@@ -407,6 +411,11 @@ class LoopInfoStack {
   /// Set flag of nofusion for the next loop pushed.
   void setSYCLNofusionEnable() { StagedAttrs.SYCLNofusionEnable = true; }
 
+  /// Set variant and value of fpga_pipeline for the next loop pushed.
+  void setSYCLIntelFPGAPipeline(const char *Var, unsigned int Value) {
+    StagedAttrs.SYCLIntelFPGAPipeline.push_back({Var, Value});
+  }
+
   /// Set no progress for the next loop pushed.
   void setMustProgress(bool P) { StagedAttrs.MustProgress = P; }
 

clang/lib/Sema/SemaDeclAttr.cpp

@@ -364,6 +364,14 @@ void Sema::CheckDeprecatedSYCLAttributeSpelling(const ParsedAttr &A,
     Diag(A.getLoc(), diag::ext_sycl_2020_attr_spelling) << A;
     return;
   }
+
+  // Deprecate [[intel::disable_loop_pipelining]] attribute spelling in favor
+  // of the SYCL FPGA attribute spelling [[intel::fpga_pipeline]].
+  if (A.hasScope() && A.getScopeName()->isStr("intel") &&
+      A.getAttrName()->isStr("disable_loop_pipelining")) {
+    DiagnoseDeprecatedAttribute(A, "intel", "fpga_pipeline");
+    return;
+  }
 }
 
 /// Check if IdxExpr is a valid parameter index for a function or

clang/lib/Sema/SemaStmtAttr.cpp

@@ -219,6 +219,33 @@ static Attr *handleSYCLIntelFPGADisableLoopPipeliningAttr(Sema &S, Stmt *,
   return new (S.Context) SYCLIntelFPGADisableLoopPipeliningAttr(S.Context, A);
 }
 
+// Handle [[intel:fpga_pipeline]] attribute.
+static Attr *handleSYCLIntelFPGAPipelineAttr(Sema &S, Stmt *,
+                                             const ParsedAttr &A) {
+  // If no attribute argument is specified, set to default value '1'.
+  Expr *E = A.isArgExpr(0)
+                ? A.getArgAsExpr(0)
+                : IntegerLiteral::Create(S.Context, llvm::APInt(32, 1),
+                                         S.Context.IntTy, A.getLoc());
+
+  return S.BuildSYCLIntelFPGAPipelineAttr(A, E);
+}
+
+SYCLIntelFPGAPipelineAttr *
+Sema::BuildSYCLIntelFPGAPipelineAttr(const AttributeCommonInfo &A, Expr *E) {
+
+  if (!E->isValueDependent()) {
+    // Check if the expression is not value dependent.
+    llvm::APSInt ArgVal;
+    ExprResult Res = VerifyIntegerConstantExpression(E, &ArgVal);
+    if (Res.isInvalid())
+      return nullptr;
+    E = Res.get();
+  }
+
+  return new (Context) SYCLIntelFPGAPipelineAttr(Context, A, E);
+}
+
 static bool checkSYCLIntelFPGAIVDepSafeLen(Sema &S, llvm::APSInt &Value,
                                            Expr *E) {
   if (!Value.isStrictlyPositive())
@@ -821,6 +848,7 @@ static void CheckForIncompatibleSYCLLoopAttributes(
   CheckForDuplicationSYCLLoopAttribute<LoopUnrollHintAttr>(S, Attrs, false);
   CheckRedundantSYCLIntelFPGAIVDepAttrs(S, Attrs);
   CheckForDuplicationSYCLLoopAttribute<SYCLIntelFPGANofusionAttr>(S, Attrs);
+  CheckForDuplicationSYCLLoopAttribute<SYCLIntelFPGAPipelineAttr>(S, Attrs);
 }
 
 void CheckForIncompatibleUnrollHintAttributes(
@@ -966,6 +994,8 @@ static Attr *ProcessStmtAttribute(Sema &S, Stmt *St, const ParsedAttr &A,
     return handleUnlikely(S, St, A, Range);
   case ParsedAttr::AT_SYCLIntelFPGANofusion:
     return handleIntelFPGANofusionAttr(S, St, A);
+  case ParsedAttr::AT_SYCLIntelFPGAPipeline:
+    return handleSYCLIntelFPGAPipelineAttr(S, St, A);
   default:
     // N.B., ClangAttrEmitter.cpp emits a diagnostic helper that ensures a
     // declaration attribute is not written on a statement, but this code is

clang/lib/Sema/SemaTemplateInstantiate.cpp

@@ -1110,6 +1110,8 @@ namespace {
         const SYCLIntelFPGASpeculatedIterationsAttr *SI);
     const SYCLIntelFPGALoopCountAttr *
     TransformSYCLIntelFPGALoopCountAttr(const SYCLIntelFPGALoopCountAttr *SI);
+    const SYCLIntelFPGAPipelineAttr *
+    TransformSYCLIntelFPGAPipelineAttr(const SYCLIntelFPGAPipelineAttr *SI);
 
     ExprResult TransformPredefinedExpr(PredefinedExpr *E);
     ExprResult TransformDeclRefExpr(DeclRefExpr *E);
@@ -1601,6 +1603,13 @@ const LoopUnrollHintAttr *TemplateInstantiator::TransformLoopUnrollHintAttr(
   return getSema().BuildLoopUnrollHintAttr(*LU, TransformedExpr);
 }
 
+const SYCLIntelFPGAPipelineAttr *
+TemplateInstantiator::TransformSYCLIntelFPGAPipelineAttr(
+    const SYCLIntelFPGAPipelineAttr *PA) {
+  Expr *TransformedExpr = getDerived().TransformExpr(PA->getValue()).get();
+  return getSema().BuildSYCLIntelFPGAPipelineAttr(*PA, TransformedExpr);
+}
+
 ExprResult TemplateInstantiator::transformNonTypeTemplateParmRef(
                                                  NonTypeTemplateParmDecl *parm,
                                                  SourceLocation loc,

clang/test/CodeGenSYCL/intel-fpga-loops.cpp

@@ -20,6 +20,14 @@
 // CHECK: br label %for.cond2, !llvm.loop ![[MD_LCA_1:[0-9]+]]
 // CHECK: br label %for.cond13, !llvm.loop ![[MD_LCA_2:[0-9]+]]
 // CHECK: br label %for.cond24, !llvm.loop ![[MD_LCA_3:[0-9]+]]
+// CHECK: br label %for.cond, !llvm.loop ![[MD_FP:[0-9]+]]
+// CHECK: br label %for.cond2, !llvm.loop ![[MD_FP_1:[0-9]+]]
+// CHECK: br label %for.cond13, !llvm.loop ![[MD_FP_2:[0-9]+]]
+// CHECK: br label %for.cond24, !llvm.loop ![[MD_FP_3:[0-9]+]]
+// CHECK: br label %while.cond, !llvm.loop ![[MD_FP_4:[0-9]+]]
+// CHECK: br i1 %cmp38, label %do.body, label %do.end, !llvm.loop ![[MD_FP_5:[0-9]+]]
+// CHECK: br label %for.cond40, !llvm.loop ![[MD_FP_6:[0-9]+]]
+// CHECK: br label %while.cond47, !llvm.loop ![[MD_FP_7:[0-9]+]]
 
 void disable_loop_pipelining() {
   int a[10];
@@ -126,6 +134,7 @@ void speculated_iterations() {
       a[i] = 0;
 }
 
+// Add CodeGen tests for FPGA loop attribute: [[intel::fpga_pipeline()]].
 template <int A>
 void loop_count_control() {
   int a[10];
@@ -150,6 +159,48 @@ void loop_count_control() {
       a[i] = 0;
 }
 
+// Add CodeGen tests for Loop attribute: [[intel::fpga_pipeline()]].
+template <int A>
+void fpga_pipeline() {
+  int a[10];
+  // CHECK: ![[MD_FP]] = distinct !{![[MD_FP]], ![[MP]], ![[MD_fpga_pipeline:[0-9]+]]}
+  // CHECK-NEXT: ![[MD_fpga_pipeline]] = !{!"llvm.loop.intel.pipelining.enable", i32 1}
+  [[intel::fpga_pipeline(A)]] for (int i = 0; i != 10; ++i)
+    a[i] = 0;
+
+  // CHECK: ![[MD_FP_1]] = distinct !{![[MD_FP_1]], ![[MP]], ![[MD_fpga_pipeline]]}
+  [[intel::fpga_pipeline(1)]] for (int i = 0; i != 10; ++i)
+    a[i] = 0;
+
+  // CHECK: ![[MD_FP_2]] = distinct !{![[MD_FP_2]], ![[MP]], ![[MD_fpga_pipeline]]}
+  [[intel::fpga_pipeline]] for (int i = 0; i != 10; ++i)
+    a[i] = 0;
+
+  // CHECK: ![[MD_FP_3]] = distinct !{![[MD_FP_3]], ![[MP]], ![[MD_dlp]]}
+  [[intel::fpga_pipeline(0)]] for (int i = 0; i != 10; ++i)
+    a[i] = 0;
+
+  // CHECK: ![[MD_FP_4]] = distinct !{![[MD_FP_4]], ![[MP]], ![[MD_fpga_pipeline]]}
+  int j = 0;
+  [[intel::fpga_pipeline]] while (j < 10) {
+    a[j] += 3;
+  }
+
+  // CHECK: ![[MD_FP_5]] = distinct !{![[MD_FP_5]], ![[MP]], ![[MD_fpga_pipeline]]}
+  int b = 10;
+  [[intel::fpga_pipeline(1)]] do {
+    b = b + 1;
+  } while (b < 20);
+
+  // CHECK: ![[MD_FP_6]] = distinct !{![[MD_FP_6]], ![[MD_fpga_pipeline]]}
+  int c[] = {0, 1, 2, 3, 4, 5};
+  [[intel::fpga_pipeline(A)]] for (int n : c) { n *= 2; }
+
+  // CHECK: ![[MD_FP_7]] = distinct !{![[MD_FP_7]], ![[MP]], ![[MD_fpga_pipeline]]}
+  int k = 0;
+  [[intel::fpga_pipeline(-1)]] while (k < 20) { a[k] += 2; }
+}
+
 template <typename name, typename Func>
 __attribute__((sycl_kernel)) void kernel_single_task(const Func &kernelFunc) {
   kernelFunc();
@@ -165,6 +216,7 @@ int main() {
     max_interleaving<3, 0>();
     speculated_iterations<4, 0>();
     loop_count_control<12>();
+    fpga_pipeline<1>();
   });
   return 0;
 }