Add a new altera kernel name restriction check to clang-tidy.

The altera kernel name restriction check finds kernel files and include
directives whose filename is "kernel.cl", "Verilog.cl", or "VHDL.cl".
Such kernel file names cause the Altera Offline Compiler to generate
intermediate design files that have the same names as certain internal
files, which leads to a compilation error.

As per the "Guidelines for Naming the Kernel" section in the "Intel FPGA
SDK for OpenCL Pro Edition: Programming Guide."

Author: ffrankies

clang-tools-extra/clang-tidy/altera/AlteraTidyModule.cpp

@@ -9,6 +9,7 @@
 #include "../ClangTidy.h"
 #include "../ClangTidyModule.h"
 #include "../ClangTidyModuleRegistry.h"
+#include "KernelNameRestrictionCheck.h"
 #include "StructPackAlignCheck.h"
 
 using namespace clang::ast_matchers;
@@ -20,6 +21,8 @@ namespace altera {
 class AlteraModule : public ClangTidyModule {
 public:
   void addCheckFactories(ClangTidyCheckFactories &CheckFactories) override {
+    CheckFactories.registerCheck<KernelNameRestrictionCheck>(
+        "altera-kernel-name-restriction");
     CheckFactories.registerCheck<StructPackAlignCheck>(
         "altera-struct-pack-align");
   }

clang-tools-extra/clang-tidy/altera/CMakeLists.txt

@@ -5,6 +5,7 @@ set(LLVM_LINK_COMPONENTS
 
 add_clang_library(clangTidyAlteraModule
   AlteraTidyModule.cpp
+  KernelNameRestrictionCheck.cpp
   StructPackAlignCheck.cpp
 
   LINK_LIBS

clang-tools-extra/clang-tidy/altera/KernelNameRestrictionCheck.cpp

@@ -0,0 +1,107 @@
+//===--- KernelNameRestrictionCheck.cpp - clang-tidy ----------------------===//
+//
+// 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
+//
+//===----------------------------------------------------------------------===//
+
+#include "KernelNameRestrictionCheck.h"
+#include "clang/Frontend/CompilerInstance.h"
+#include "clang/Lex/PPCallbacks.h"
+#include "clang/Lex/Preprocessor.h"
+#include <string>
+#include <vector>
+
+using namespace clang::ast_matchers;
+
+namespace clang {
+namespace tidy {
+namespace altera {
+
+namespace {
+
+class KernelNameRestrictionPPCallbacks : public PPCallbacks {
+public:
+  explicit KernelNameRestrictionPPCallbacks(ClangTidyCheck &Check,
+                                            const SourceManager &SM)
+      : Check(Check), SM(SM) {}
+
+  void InclusionDirective(SourceLocation HashLoc, const Token &IncludeTok,
+                          StringRef FileName, bool IsAngled,
+                          CharSourceRange FileNameRange, const FileEntry *File,
+                          StringRef SearchPath, StringRef RelativePath,
+                          const Module *Imported,
+                          SrcMgr::CharacteristicKind FileType) override;
+
+  void EndOfMainFile() override;
+
+private:
+  /// Returns true if the name of the file with path FilePath is 'kernel.cl',
+  /// 'verilog.cl', or 'vhdl.cl'. The file name check is case insensitive.
+  bool FileNameIsRestricted(StringRef FilePath);
+
+  struct IncludeDirective {
+    SourceLocation Loc; // Location in the include directive.
+    StringRef FileName; // Filename as a string.
+  };
+
+  std::vector<IncludeDirective> IncludeDirectives;
+  ClangTidyCheck &Check;
+  const SourceManager &SM;
+};
+
+} // namespace
+
+void KernelNameRestrictionCheck::registerPPCallbacks(const SourceManager &SM,
+                                                     Preprocessor *PP,
+                                                     Preprocessor *) {
+  PP->addPPCallbacks(
+      std::make_unique<KernelNameRestrictionPPCallbacks>(*this, SM));
+}
+
+void KernelNameRestrictionPPCallbacks::InclusionDirective(
+    SourceLocation HashLoc, const Token &, StringRef FileName, bool,
+    CharSourceRange, const FileEntry *, StringRef, StringRef, const Module *,
+    SrcMgr::CharacteristicKind) {
+  IncludeDirective ID = {HashLoc, FileName};
+  IncludeDirectives.push_back(std::move(ID));
+}
+
+bool KernelNameRestrictionPPCallbacks::FileNameIsRestricted(
+    StringRef FileName) {
+  return FileName.equals_lower("kernel.cl") ||
+         FileName.equals_lower("verilog.cl") ||
+         FileName.equals_lower("vhdl.cl");
+}
+
+void KernelNameRestrictionPPCallbacks::EndOfMainFile() {
+
+  // Check main file for restricted names.
+  const FileEntry *Entry = SM.getFileEntryForID(SM.getMainFileID());
+  StringRef FileName = llvm::sys::path::filename(Entry->getName());
+  if (FileNameIsRestricted(FileName))
+    Check.diag(SM.getLocForStartOfFile(SM.getMainFileID()),
+               "compiling '%0' may cause additional compilation errors due "
+               "to the name of the kernel source file; consider renaming the "
+               "included kernel source file")
+        << FileName;
+
+  if (IncludeDirectives.empty())
+    return;
+
+  // Check included files for restricted names.
+  for (const IncludeDirective &ID : IncludeDirectives) {
+    StringRef FileName = llvm::sys::path::filename(ID.FileName);
+    if (FileNameIsRestricted(FileName))
+      Check.diag(ID.Loc,
+                 "including '%0' may cause additional compilation errors due "
+                 "to the name of the kernel source file; consider renaming the "
+                 "included kernel source file")
+          << FileName;
+  }
+}
+
+} // namespace altera
+} // namespace tidy
+} // namespace clang

clang-tools-extra/clang-tidy/altera/KernelNameRestrictionCheck.h

@@ -0,0 +1,35 @@
+//===--- KernelNameRestrictionCheck.h - clang-tidy --------------*- 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 LLVM_CLANG_TOOLS_EXTRA_CLANG_TIDY_ALTERA_KERNEL_NAME_RESTRICTION_CHECK_H
+#define LLVM_CLANG_TOOLS_EXTRA_CLANG_TIDY_ALTERA_KERNEL_NAME_RESTRICTION_CHECK_H
+
+#include "../ClangTidyCheck.h"
+
+namespace clang {
+namespace tidy {
+namespace altera {
+
+/// Finds kernel files and include directives whose filename is `kernel.cl`,
+/// `Verilog.cl`, or `VHDL.cl`.
+///
+/// For the user-facing documentation see:
+/// http://clang.llvm.org/extra/clang-tidy/checks/altera-kernel-name-restriction.html
+class KernelNameRestrictionCheck : public ClangTidyCheck {
+public:
+  KernelNameRestrictionCheck(StringRef Name, ClangTidyContext *Context)
+      : ClangTidyCheck(Name, Context) {}
+  void registerPPCallbacks(const SourceManager &SM, Preprocessor *PP,
+                           Preprocessor *) override;
+};
+
+} // namespace altera
+} // namespace tidy
+} // namespace clang
+
+#endif // LLVM_CLANG_TOOLS_EXTRA_CLANG_TIDY_ALTERA_KERNEL_NAME_RESTRICTION_CHECK_H

clang-tools-extra/docs/ReleaseNotes.rst

@@ -85,6 +85,12 @@ New modules
 New checks
 ^^^^^^^^^^
 
+- New :doc:`altera-kernel-name-restriction
+  <clang-tidy/checks/kernel-name-restriction>` check.
+
+  Finds kernel files and include directives whose filename is `kernel.cl`,
+  `Verilog.cl`, or `VHDL.cl`.
+
 - New :doc:`altera-struct-pack-align
   <clang-tidy/checks/altera-struct-pack-align>` check.
 

clang-tools-extra/docs/clang-tidy/checks/altera-kernel-name-restriction.rst

@@ -0,0 +1,15 @@
+.. title:: clang-tidy - altera-kernel-name-restriction
+
+altera-kernel-name-restriction
+==============================
+
+Finds kernel files and include directives whose filename is `kernel.cl`,
+`Verilog.cl`, or `VHDL.cl`. The check is case insensitive.
+
+Such kernel file names cause the offline compiler to generate intermediate
+design files that have the same names as certain internal files, which
+leads to a compilation error.
+
+Based on the `Guidelines for Naming the Kernel` section in the
+`Intel FPGA SDK for OpenCL Pro Edition: Programming Guide
+<https://www.intel.com/content/www/us/en/programmable/documentation/mwh1391807965224.html#ewa1412973930963>`_.

clang-tools-extra/docs/clang-tidy/checks/list.rst

@@ -30,6 +30,7 @@ Clang-Tidy Checks
    `abseil-time-comparison <abseil-time-comparison.html>`_, "Yes"
    `abseil-time-subtraction <abseil-time-subtraction.html>`_, "Yes"
    `abseil-upgrade-duration-conversions <abseil-upgrade-duration-conversions.html>`_, "Yes"
+   `altera-kernel-name-restriction <altera-kernel-name-restriction.html>`_,
    `altera-struct-pack-align <altera-struct-pack-align.html>`_,
    `android-cloexec-accept <android-cloexec-accept.html>`_, "Yes"
    `android-cloexec-accept4 <android-cloexec-accept4.html>`_,

clang-tools-extra/test/clang-tidy/checkers/Inputs/altera-kernel-name-restriction/kernel.cl

@@ -0,0 +1 @@
+const int KERNELINT = 1;

clang-tools-extra/test/clang-tidy/checkers/Inputs/altera-kernel-name-restriction/kernel.h

@@ -0,0 +1 @@
+const int KERNELINT3 = 1;

clang-tools-extra/test/clang-tidy/checkers/Inputs/altera-kernel-name-restriction/other_Verilog.cl

@@ -0,0 +1 @@
+const int OTHERVERILOGINT = 2;

clang-tools-extra/test/clang-tidy/checkers/Inputs/altera-kernel-name-restriction/otherdir/vhdl.cl

@@ -0,0 +1 @@
+const int OTHERDIRVHDLINT = 3;

clang-tools-extra/test/clang-tidy/checkers/Inputs/altera-kernel-name-restriction/otherthing.cl

@@ -0,0 +1 @@
+const int OTHERTHINGINT = 1;

clang-tools-extra/test/clang-tidy/checkers/Inputs/altera-kernel-name-restriction/some/dir/kernel.cl

@@ -0,0 +1 @@
+const int SOMEDIRKERNELINT = 1;

clang-tools-extra/test/clang-tidy/checkers/Inputs/altera-kernel-name-restriction/some/kernel.cl/foo.h

@@ -0,0 +1 @@
+int SOME_KERNEL_FOO_INT = 0;

clang-tools-extra/test/clang-tidy/checkers/Inputs/altera-kernel-name-restriction/some/verilog.cl/foo.h

@@ -0,0 +1 @@
+int SOME_VERILOG_FOO_INT = 0;

clang-tools-extra/test/clang-tidy/checkers/Inputs/altera-kernel-name-restriction/some/vhdl.cl/foo.h

@@ -0,0 +1 @@
+int SOME_VHDL_FOO_INT = 0;

clang-tools-extra/test/clang-tidy/checkers/Inputs/altera-kernel-name-restriction/some_kernel.cl

@@ -0,0 +1 @@
+const int SOMEKERNELINT = 1;

clang-tools-extra/test/clang-tidy/checkers/Inputs/altera-kernel-name-restriction/somedir/verilog.cl

@@ -0,0 +1 @@
+const int SOMEDIRVERILOGINT = 2;

clang-tools-extra/test/clang-tidy/checkers/Inputs/altera-kernel-name-restriction/thing.h

@@ -0,0 +1 @@
+const int THINGINT = 1;

clang-tools-extra/test/clang-tidy/checkers/Inputs/altera-kernel-name-restriction/vERILOG.cl

@@ -0,0 +1 @@
+const int VERILOGINT2 = 2;

clang-tools-extra/test/clang-tidy/checkers/Inputs/altera-kernel-name-restriction/verilog.h

@@ -0,0 +1 @@
+const int VERILOGINT3 = 2;

clang-tools-extra/test/clang-tidy/checkers/Inputs/altera-kernel-name-restriction/vhdl.CL

@@ -0,0 +1 @@
+const int VHDLINT2 = 3;

clang-tools-extra/test/clang-tidy/checkers/Inputs/altera-kernel-name-restriction/vhdl.h

@@ -0,0 +1 @@
+const int VHDLINT3 = 3;

clang-tools-extra/test/clang-tidy/checkers/Inputs/altera-kernel-name-restriction/vhdl_number_two.cl

@@ -0,0 +1 @@
+const int VHDLNUMBERTWOINT = 3;

clang-tools-extra/test/clang-tidy/checkers/altera-kernel-name-restriction.cpp

@@ -0,0 +1,50 @@
+// RUN: %check_clang_tidy %s altera-kernel-name-restriction %t -- -- -I%S/Inputs/altera-kernel-name-restriction
+
+// These are the banned kernel filenames, and should trigger warnings
+#include "kernel.cl"
+// CHECK-MESSAGES: :[[@LINE-1]]:1: warning: including 'kernel.cl' may cause additional compilation errors due to the name of the kernel source file; consider renaming the included kernel source file [altera-kernel-name-restriction]
+#include "Verilog.cl"
+// CHECK-MESSAGES: :[[@LINE-1]]:1: warning: including 'Verilog.cl' may cause additional compilation errors due to the name of the kernel source file; consider renaming the included kernel source file [altera-kernel-name-restriction]
+#include "VHDL.cl"
+// CHECK-MESSAGES: :[[@LINE-1]]:1: warning: including 'VHDL.cl' may cause additional compilation errors due to the name of the kernel source file; consider renaming the included kernel source file [altera-kernel-name-restriction]
+
+// The warning should be triggered regardless of capitalization
+#include "KERNEL.cl"
+// CHECK-MESSAGES: :[[@LINE-1]]:1: warning: including 'KERNEL.cl' may cause additional compilation errors due to the name of the kernel source file; consider renaming the included kernel source file [altera-kernel-name-restriction]
+#include "vERILOG.cl"
+// CHECK-MESSAGES: :[[@LINE-1]]:1: warning: including 'vERILOG.cl' may cause additional compilation errors due to the name of the kernel source file; consider renaming the included kernel source file [altera-kernel-name-restriction]
+#include "vhdl.CL"
+// CHECK-MESSAGES: :[[@LINE-1]]:1: warning: including 'vhdl.CL' may cause additional compilation errors due to the name of the kernel source file; consider renaming the included kernel source file [altera-kernel-name-restriction]
+
+// The warning should be triggered if the names are within a directory
+#include "some/dir/kernel.cl"
+// CHECK-MESSAGES: :[[@LINE-1]]:1: warning: including 'kernel.cl' may cause additional compilation errors due to the name of the kernel source file; consider renaming the included kernel source file [altera-kernel-name-restriction]
+#include "somedir/verilog.cl"
+// CHECK-MESSAGES: :[[@LINE-1]]:1: warning: including 'verilog.cl' may cause additional compilation errors due to the name of the kernel source file; consider renaming the included kernel source file [altera-kernel-name-restriction]
+#include "otherdir/vhdl.cl"
+// CHECK-MESSAGES: :[[@LINE-1]]:1: warning: including 'vhdl.cl' may cause additional compilation errors due to the name of the kernel source file; consider renaming the included kernel source file [altera-kernel-name-restriction]
+
+// There are no FIX-ITs for the altera-kernel-name-restriction lint check
+
+// The following include directives shouldn't trigger the warning
+#include "otherthing.cl"
+#include "thing.h"
+
+// It doesn't make sense to have kernel.h, verilog.h, or vhdl.h as filenames
+// without the corresponding .cl files, but the Altera Programming Guide doesn't
+// explicitly forbid it.
+#include "kernel.h"
+#include "verilog.h"
+#include "vhdl.h"
+
+// The files can still have the forbidden names in them, so long as they're not
+// the entire file name, and are not the kernel source file name.
+#include "some_kernel.cl"
+#include "other_Verilog.cl"
+#include "vhdl_number_two.cl"
+
+// Naming a directory kernel.cl, verilog.cl, or vhdl.cl is not explicitly
+// forbidden in the Altera Programming Guide either.
+#include "some/kernel.cl/foo.h"
+#include "some/verilog.cl/foo.h"
+#include "some/vhdl.cl/foo.h"