[LLVM][llvm-cov] Inclusive language: rename option -name-whitelist to -name-allowlist

[ZarkoCA]

Summary

Renamed the option for llvm-cov and changed variable names to use more
inclusive terms. Also changed the binary for the test.

[vsk]

Thanks for the patch. We usually go out of our way to not break llvm-cov workflows. I'd suggest:

• Leaving the old -name-whitelist around for a release, but marked cl::Hidden. Using it should print a deprecation warning.
• Adding a llvm-14 release note (llvm/docs/ReleaseNotes.txt) about the planned deprecation and removal of -name-whitelist. llvm-14 would ship both options.
• Posting on llvm-dev (or a forum) about the change.
• Removing -name-whitelist when llvm-15 branches.

[ZarkoCA]

In D112816#3103937, @vsk wrote:

Thanks for the patch. We usually go out of our way to not break llvm-cov workflows. I'd suggest:

• Leaving the old -name-whitelist around for a release, but marked cl::Hidden. Using it should print a deprecation warning.
• Adding a llvm-14 release note (llvm/docs/ReleaseNotes.txt) about the planned deprecation and removal of -name-whitelist. llvm-14 would ship both options.
• Posting on llvm-dev (or a forum) about the change.
• Removing -name-whitelist when llvm-15 branches.

Thanks for the review, I will follow up with all of your suggestions and update the patch.

[ZarkoCA]

• now accept both options
• bring back old tests

[ZarkoCA]

In D112816#3103937, @vsk wrote:

Thanks for the patch. We usually go out of our way to not break llvm-cov workflows. I'd suggest:

• Leaving the old -name-whitelist around for a release, but marked cl::Hidden. Using it should print a deprecation warning.
• Adding a llvm-14 release note (llvm/docs/ReleaseNotes.txt) about the planned deprecation and removal of -name-whitelist. llvm-14 would ship both options.
• Posting on llvm-dev (or a forum) about the change.
• Removing -name-whitelist when llvm-15 branches.

Again, thanks for the review and apologies if the patch was overzealous in removing the existing option.

I've posted an RFC for the option name change here: https://lists.llvm.org/pipermail/llvm-dev/2021-November/153632.html

[alanphipps]

Thanks for putting this up! The changes appear to be straightforward, and it makes sense to deprecate the older option and still accept it until next release. LGTM.

[ZarkoCA]

-Fix binary file in test

[ZarkoCA]

In D112816#3149483, @alanphipps wrote:

Thanks for putting this up! The changes appear to be straightforward, and it makes sense to deprecate the older option and still accept it until next release. LGTM.

Thanks for the review and approval. There was an issue with the binary file in my previous diff. I've fixed and once I see this is passing pre-commit CI, I will go ahead and commit the patch.

[ZarkoCA]

Pushed 715d2dc126ee4aaf0cb1df8826c3f1072c952e66 to fix the docs buildbot break.

llvm/docs/CommandGuide/llvm-cov.rst

  binary, this specifies the architecture to use. It is an error to specify an
  architecture that is not included in the universal binary or to use an
  architecture that does not match a non-universal binary.
 
 .. option:: -name=<NAME>
 
  Show code coverage only for functions with the given name.
 
+.. option:: -name-allowlist=<FILE>
+
+ Show code coverage only for functions listed in the given file. Each line in
+ the file should start with `allowlist_fun:`, immediately followed by the name
+ of the function to accept. This name can be a wildcard expression.
+
 .. option:: -name-whitelist=<FILE>
 
  Show code coverage only for functions listed in the given file. Each line in
  the file should start with `whitelist_fun:`, immediately followed by the name
- of the function to accept. This name can be a wildcard expression.
+ of the function to accept. This name can be a wildcard expression. This option
+ will be deprecated for `-name-allowlist=<FILE> in future releases.
 
 .. option:: -name-regex=<PATTERN>
 
  Show code coverage only for functions that match the given regular expression.
 
 .. option:: -ignore-filename-regex=<PATTERN>
 
  Skip source code files with file paths that match the given regular expression.

llvm/docs/ReleaseNotes.rst

 Changes to the Debug Info
 ---------------------------------
 
 During this release ...
 
 Changes to the LLVM tools
 ---------------------------------
 
-* ...
+* llvm-cov: `-name-allowlist` is now accepted in addition to `-name-whitelist`.
+  `-name-whitelist` is marked as deprecated and to be removed in future
+  releases.
 
 Changes to LLDB
 ---------------------------------
 
 * A change in Clang's type printing has changed the way LLDB names array types
   (from ``int [N]`` to ``int[N]``) - LLDB pretty printer type name matching
   code may need to be updated to handle this.
 

llvm/test/tools/llvm-cov/Inputs/allowlist1.txt

+# Comment
+
+allowlist_fun:*func1*
+allowlist_fun:*func2*

llvm/test/tools/llvm-cov/Inputs/allowlist2.txt

+allowlist_fun:*func3*
+allowlist_fun:*func4*

llvm/test/tools/llvm-cov/Inputs/name_allowlist.cpp

+int func1() {
+  return 1;
+}
+int func2() {
+  return 1;
+}
+int func3() {
+  return 1;
+}
+int func4() {
+  return 1;
+}
+int func5() {
+  return 1;
+}
+int func6() {
+  return 1;
+}

llvm/test/tools/llvm-cov/Inputs/name_allowlist.proftext

+_Z5func1v
+# Func Hash:
+0
+# Num Counters:
+1
+# Counter Values:
+0
+
+_Z5func2v
+# Func Hash:
+0
+# Num Counters:
+1
+# Counter Values:
+0
+
+_Z5func3v
+# Func Hash:
+0
+# Num Counters:
+1
+# Counter Values:
+0
+
+_Z5func4v
+# Func Hash:
+0
+# Num Counters:
+1
+# Counter Values:
+0
+
+main
+# Func Hash:
+0
+# Num Counters:
+1
+# Counter Values:
+1
+
+_Z5func5v
+# Func Hash:
+0
+# Num Counters:
+1
+# Counter Values:
+0
+
+_Z5func6v
+# Func Hash:
+0
+# Num Counters:
+1
+# Counter Values:
+0
+

llvm/test/tools/llvm-cov/name_allowlist.test

+RUN: llvm-profdata merge %S/Inputs/name_allowlist.proftext -o %t.profdata
+
+RUN: llvm-cov show %S/Inputs/name_allowlist.covmapping -instr-profile=%t.profdata -path-equivalence=/tmp,%S/Inputs -name-allowlist=%S/Inputs/allowlist1.txt %S/Inputs/name_allowlist.cpp > %t.one_list
+RUN: FileCheck -input-file=%t.one_list -check-prefix=ONE_ALLOWLIST %s
+RUN: FileCheck -input-file=%t.one_list -check-prefix=ONE_ALLOWLIST_NEG %s
+ONE_ALLOWLIST: _Z5func1v:
+ONE_ALLOWLIST: _Z5func2v:
+ONE_ALLOWLIST_NEG-NOT: _Z5func3v:
+ONE_ALLOWLIST_NEG-NOT: _Z5func4v:
+ONE_ALLOWLIST_NEG-NOT: _Z5func5v:
+ONE_ALLOWLIST_NEG-NOT: _Z5func6v:
+
+RUN: llvm-cov show %S/Inputs/name_allowlist.covmapping -instr-profile=%t.profdata -path-equivalence=/tmp,%S/Inputs -name-allowlist=%S/Inputs/allowlist1.txt -name-allowlist=%S/Inputs/allowlist2.txt %S/Inputs/name_allowlist.cpp  > %t.two_list
+RUN: FileCheck -input-file=%t.two_list -check-prefix=TWO_ALLOWLIST %s
+RUN: FileCheck -input-file=%t.two_list -check-prefix=TWO_ALLOWLIST_NEG %s
+TWO_ALLOWLIST: _Z5func1v:
+TWO_ALLOWLIST: _Z5func2v:
+TWO_ALLOWLIST: _Z5func3v:
+TWO_ALLOWLIST: _Z5func4v:
+TWO_ALLOWLIST_NEG-NOT: _Z5func5v:
+TWO_ALLOWLIST_NEG-NOT: _Z5func6v:

llvm/tools/llvm-cov/CodeCoverage.cpp

private:
   /// A lock which guards printing to stderr.
   std::mutex ErrsLock;
 
   /// A container for input source file buffers.
   std::mutex LoadedSourceFilesLock;
   std::vector<std::pair<std::string, std::unique_ptr<MemoryBuffer>>>
       LoadedSourceFiles;
 
-  /// Whitelist from -name-whitelist to be used for filtering.
-  std::unique_ptr<SpecialCaseList> NameWhitelist;
+  /// Allowlist from -name-allowlist to be used for filtering.
+  std::unique_ptr<SpecialCaseList> NameAllowlist;
 };
 }
 
 static std::string getErrorString(const Twine &Message, StringRef Whence,
                                   bool Warning) {
   std::string Str = (Warning ? "warning" : "error");
   Str += ": ";
   if (!Whence.empty())
int CodeCoverageTool::run(Command Cmd, int argc, const char **argv) {
   cl::OptionCategory FilteringCategory("Function filtering options");
 
   cl::list<std::string> NameFilters(
       "name", cl::Optional,
       cl::desc("Show code coverage only for functions with the given name"),
       cl::ZeroOrMore, cl::cat(FilteringCategory));
 
   cl::list<std::string> NameFilterFiles(
-      "name-whitelist", cl::Optional,
+      "name-allowlist", cl::Optional,
       cl::desc("Show code coverage only for functions listed in the given "
                "file"),
       cl::ZeroOrMore, cl::cat(FilteringCategory));
 
+  // Allow for accepting previous option name.
+  cl::list<std::string> NameFilterFilesDeprecated(
+      "name-whitelist", cl::Optional, cl::Hidden,
+      cl::desc("Show code coverage only for functions listed in the given "
+               "file. Deprecated, use -name-allowlist instead"),
+      cl::ZeroOrMore, cl::cat(FilteringCategory));
+
   cl::list<std::string> NameRegexFilters(
       "name-regex", cl::Optional,
       cl::desc("Show code coverage only for functions that match the given "
                "regular expression"),
       cl::ZeroOrMore, cl::cat(FilteringCategory));
 
   cl::list<std::string> IgnoreFilenameRegexFilters(
       "ignore-filename-regex", cl::Optional,
if (!DemanglerOpts.empty()) {
         error("Could not find the demangler!",
               DemanglerPathOrErr.getError().message());
         return 1;
       }
       DemanglerOpts[0] = *DemanglerPathOrErr;
       ViewOpts.DemanglerOpts.swap(DemanglerOpts);
     }
 
-    // Read in -name-whitelist files.
-    if (!NameFilterFiles.empty()) {
+    // Read in -name-allowlist files.
+    if (!NameFilterFiles.empty() || !NameFilterFilesDeprecated.empty()) {
       std::string SpecialCaseListErr;
-      NameWhitelist = SpecialCaseList::create(
+      if (!NameFilterFiles.empty())
+        NameAllowlist = SpecialCaseList::create(
             NameFilterFiles, *vfs::getRealFileSystem(), SpecialCaseListErr);
-      if (!NameWhitelist)
+      if (!NameFilterFilesDeprecated.empty())
+        NameAllowlist = SpecialCaseList::create(NameFilterFilesDeprecated,
+                                                *vfs::getRealFileSystem(),
+                                                SpecialCaseListErr);
+
+      if (!NameAllowlist)
         error(SpecialCaseListErr);
     }
 
     // Create the function filters
-    if (!NameFilters.empty() || NameWhitelist || !NameRegexFilters.empty()) {
+    if (!NameFilters.empty() || NameAllowlist || !NameRegexFilters.empty()) {
       auto NameFilterer = std::make_unique<CoverageFilters>();
       for (const auto &Name : NameFilters)
         NameFilterer->push_back(std::make_unique<NameCoverageFilter>(Name));
-      if (NameWhitelist)
+      if (NameAllowlist) {
+        if (!NameFilterFiles.empty())
+          NameFilterer->push_back(
+              std::make_unique<NameAllowlistCoverageFilter>(*NameAllowlist));
+        if (!NameFilterFilesDeprecated.empty())
           NameFilterer->push_back(
-            std::make_unique<NameWhitelistCoverageFilter>(*NameWhitelist));
+              std::make_unique<NameWhitelistCoverageFilter>(*NameAllowlist));
+      }
       for (const auto &Regex : NameRegexFilters)
         NameFilterer->push_back(
             std::make_unique<NameRegexCoverageFilter>(Regex));
       Filters.push_back(std::move(NameFilterer));
     }
 
     if (RegionCoverageLtFilter.getNumOccurrences() ||
         RegionCoverageGtFilter.getNumOccurrences() ||

llvm/tools/llvm-cov/CoverageFilters.h

public:
 
   bool matches(const coverage::CoverageMapping &CM,
                const coverage::FunctionRecord &Function) const override;
 
   bool matchesFilename(StringRef Filename) const override;
 };
 
 /// Matches functions whose name appears in a SpecialCaseList in the
-/// whitelist_fun section.
+/// allowlist_fun section.
+class NameAllowlistCoverageFilter : public CoverageFilter {
+  const SpecialCaseList &Allowlist;
+
+public:
+  NameAllowlistCoverageFilter(const SpecialCaseList &Allowlist)
+      : Allowlist(Allowlist) {}
+
+  bool matches(const coverage::CoverageMapping &CM,
+               const coverage::FunctionRecord &Function) const override;
+};
+
+// TODO: Remove this class when -name-whitelist option is removed.
 class NameWhitelistCoverageFilter : public CoverageFilter {
   const SpecialCaseList &Whitelist;
 
 public:
   NameWhitelistCoverageFilter(const SpecialCaseList &Whitelist)
       : Whitelist(Whitelist) {}
 
   bool matches(const coverage::CoverageMapping &CM,

llvm/tools/llvm-cov/CoverageFilters.cpp

bool NameRegexCoverageFilter::matches(
     const coverage::FunctionRecord &Function) const {
   return llvm::Regex(Regex).match(Function.Name);
 }
 
 bool NameRegexCoverageFilter::matchesFilename(StringRef Filename) const {
   return llvm::Regex(Regex).match(Filename);
 }
 
+bool NameAllowlistCoverageFilter::matches(
+    const coverage::CoverageMapping &,
+    const coverage::FunctionRecord &Function) const {
+  return Allowlist.inSection("llvmcov", "allowlist_fun", Function.Name);
+}
+
+// TODO: remove this when -name-whitelist option is removed.
 bool NameWhitelistCoverageFilter::matches(
     const coverage::CoverageMapping &,
     const coverage::FunctionRecord &Function) const {
   return Whitelist.inSection("llvmcov", "whitelist_fun", Function.Name);
 }
 
 bool RegionCoverageFilter::matches(
     const coverage::CoverageMapping &CM,