[llvm-exegesis] Add options to SnippetGenerator.

[courbet]

Summary

This adds a -max-configs-per-opcode option to limit the number of
configs per opcode.

llvm/docs/CommandGuide/llvm-exegesis.rst

.. option:: -snippets-file=<filename>
   Either `opcode-index`, `opcode-name` or `snippets-file` must be set.
 
 .. option:: -mode=[latency|uops|inverse_throughput|analysis]
 
  Specify the run mode. Note that if you pick `analysis` mode, you also need
  to specify at least one of the `-analysis-clusters-output-file=` and
  `-analysis-inconsistencies-output-file=`.
 
-.. option:: -num-repetitions=<Number of repetition>
+.. option:: -num-repetitions=<Number of repetitions>
 
  Specify the number of repetitions of the asm snippet.
  Higher values lead to more accurate measurements but lengthen the benchmark.
 
+.. option:: -max-configs-per-opcode=<value>
+
+ Specify the maximum configurations that can be generated for each opcode.
+ By default this is `1`, meaning that we assume that a single measurement is
+ enough to characterize an opcode. This might not be true of all instructions:
+ for example, the performance characteristics of the LEA instruction on X86
+ depends on the value of assigned registers and immediates. Setting a value of
+ `-max-configs-per-opcode` larger than `1` allows `llvm-exegesis` to explore
+ more configurations to discover if some register or immediate assignments
+ lead to different performance characteristics.
+
+
 .. option:: -benchmarks-file=</path/to/file>
 
  File to read (`analysis` mode) or write (`latency`/`uops`/`inverse_throughput`
  modes) benchmark results. "-" uses stdin/stdout.
 
 .. option:: -analysis-clusters-output-file=</path/to/file>
 
  If provided, write the analysis clusters as CSV to this file. "-" prints to

llvm/test/tools/llvm-exegesis/X86/max-configs.test

+# RUN: llvm-exegesis -mode=latency -opcode-name=SBB8rr -max-configs-per-opcode=1 | FileCheck -check-prefixes=CHECK,CHECK1 %s
+# RUN: llvm-exegesis -mode=latency -opcode-name=SBB8rr -max-configs-per-opcode=2 | FileCheck -check-prefixes=CHECK,CHECK2 %s
+
+CHECK:      ---
+CHECK-NEXT: mode: latency
+CHECK-NEXT: key:
+CHECK-NEXT:   instructions:
+CHECK-NEXT:     SBB8rr
+CHECK-NEXT: config: ''
+CHECK-NEXT: register_initial_values:
+CHECK-DAG: - '[[REG1:[A-Z0-9]+]]=0x0'
+CHECK-LAST: ...
+
+CHECK1-NOT: SBB8rr
+
+CHECK2:      ---
+CHECK2-NEXT: mode: latency
+CHECK2-NEXT: key:
+CHECK2-NEXT:   instructions:
+CHECK2-NEXT:     SBB8rr
+CHECK2-NEXT: config: ''
+CHECK2-NEXT: register_initial_values:
+CHECK2-DAG: - '[[REG1:[A-Z0-9]+]]=0x0'
+CHECK2-LAST: ...

llvm/tools/llvm-exegesis/lib/Latency.h

 #include "MCInstrDescView.h"
 #include "SnippetGenerator.h"
 
 namespace llvm {
 namespace exegesis {
 
 class LatencySnippetGenerator : public SnippetGenerator {
 public:
-  LatencySnippetGenerator(const LLVMState &State) : SnippetGenerator(State) {}
+  using SnippetGenerator::SnippetGenerator;
   ~LatencySnippetGenerator() override;
 
   llvm::Expected<std::vector<CodeTemplate>>
   generateCodeTemplates(const Instruction &Instr,
                         const BitVector &ForbiddenRegisters) const override;
 };
 
 class LatencyBenchmarkRunner : public BenchmarkRunner {

llvm/tools/llvm-exegesis/lib/SnippetGenerator.h

 class SnippetGeneratorFailure : public llvm::StringError {
 public:
   SnippetGeneratorFailure(const llvm::Twine &S);
 };
 
 // Common code for all benchmark modes.
 class SnippetGenerator {
 public:
-  explicit SnippetGenerator(const LLVMState &State);
+  struct Options {
+    unsigned MaxConfigsPerOpcode = 1;
+  };
+
+  explicit SnippetGenerator(const LLVMState &State, const Options &Opts);
 
   virtual ~SnippetGenerator();
 
   // Calls generateCodeTemplate and expands it into one or more BenchmarkCode.
   llvm::Expected<std::vector<BenchmarkCode>>
   generateConfigurations(const Instruction &Instr,
                          const llvm::BitVector &ExtraForbiddenRegs) const;
 
   // Given a snippet, computes which registers the setup code needs to define.
   std::vector<RegisterValue> computeRegisterInitialValues(
       const std::vector<InstructionTemplate> &Snippet) const;
 
 protected:
   const LLVMState &State;
+  const Options Opts;
 
 private:
   // API to be implemented by subclasses.
   virtual llvm::Expected<std::vector<CodeTemplate>>
   generateCodeTemplates(const Instruction &Instr,
                         const BitVector &ForbiddenRegisters) const = 0;
 };
 

llvm/tools/llvm-exegesis/lib/SnippetGenerator.cpp

std::vector<CodeTemplate> getSingleton(CodeTemplate &&CT) {
   std::vector<CodeTemplate> Result;
   Result.push_back(std::move(CT));
   return Result;
 }
 
 SnippetGeneratorFailure::SnippetGeneratorFailure(const llvm::Twine &S)
     : llvm::StringError(S, llvm::inconvertibleErrorCode()) {}
 
-SnippetGenerator::SnippetGenerator(const LLVMState &State) : State(State) {}
+SnippetGenerator::SnippetGenerator(const LLVMState &State, const Options &Opts)
+    : State(State), Opts(Opts) {}
 
 SnippetGenerator::~SnippetGenerator() = default;
 
 llvm::Expected<std::vector<BenchmarkCode>>
 SnippetGenerator::generateConfigurations(
     const Instruction &Instr, const llvm::BitVector &ExtraForbiddenRegs) const {
   llvm::BitVector ForbiddenRegs = State.getRATC().reservedRegisters();
   ForbiddenRegs |= ExtraForbiddenRegs;
for (CodeTemplate &CT : E.get()) {
           BC.Key.Instructions.push_back(IT.build());
         }
         if (CT.ScratchSpacePointerInReg)
           BC.LiveIns.push_back(CT.ScratchSpacePointerInReg);
         BC.Key.RegisterInitialValues =
             computeRegisterInitialValues(CT.Instructions);
         BC.Key.Config = CT.Config;
         Output.push_back(std::move(BC));
+        if (Output.size() >= Opts.MaxConfigsPerOpcode)
+          return Output; // Early exit if we exceeded the number of allowed
+                         // configs.
       }
     }
     return Output;
   } else
     return E.takeError();
 }
 
 std::vector<RegisterValue> SnippetGenerator::computeRegisterInitialValues(

llvm/tools/llvm-exegesis/lib/Target.h

public:
   // starting from OPERAND_FIRST_TARGET.
   virtual void randomizeMCOperand(const Instruction &Instr, const Variable &Var,
                                   llvm::MCOperand &AssignedValue,
                                   const llvm::BitVector &ForbiddenRegs) const;
 
   // Creates a snippet generator for the given mode.
   std::unique_ptr<SnippetGenerator>
   createSnippetGenerator(InstructionBenchmark::ModeE Mode,
-                         const LLVMState &State) const;
+                         const LLVMState &State,
+                         const SnippetGenerator::Options &Opts) const;
   // Creates a benchmark runner for the given mode.
   std::unique_ptr<BenchmarkRunner>
   createBenchmarkRunner(InstructionBenchmark::ModeE Mode,
                         const LLVMState &State) const;
 
   // Returns the ExegesisTarget for the given triple or nullptr if the target
   // does not exist.
   static const ExegesisTarget *lookup(llvm::Triple TT);
public:
   const PfmCountersInfo &getPfmCounters(llvm::StringRef CpuName) const;
 
 private:
   virtual bool matchesArch(llvm::Triple::ArchType Arch) const = 0;
 
   // Targets can implement their own snippet generators/benchmarks runners by
   // implementing these.
   std::unique_ptr<SnippetGenerator> virtual createLatencySnippetGenerator(
-      const LLVMState &State) const;
+      const LLVMState &State, const SnippetGenerator::Options &Opts) const;
   std::unique_ptr<SnippetGenerator> virtual createUopsSnippetGenerator(
-      const LLVMState &State) const;
+      const LLVMState &State, const SnippetGenerator::Options &Opts) const;
   std::unique_ptr<BenchmarkRunner> virtual createLatencyBenchmarkRunner(
       const LLVMState &State, InstructionBenchmark::ModeE Mode) const;
   std::unique_ptr<BenchmarkRunner> virtual createUopsBenchmarkRunner(
       const LLVMState &State) const;
 
   const ExegesisTarget *Next = nullptr;
   const llvm::ArrayRef<CpuAndPfmCounters> CpuPfmCounters;
 };
 
 } // namespace exegesis
 } // namespace llvm
 
 #endif // LLVM_TOOLS_LLVM_EXEGESIS_TARGET_H

llvm/tools/llvm-exegesis/lib/Target.cpp

if (FirstTarget == nullptr) {
     return;
   }
   if (Target->Next != nullptr)
     return; // Already registered.
   Target->Next = FirstTarget;
   FirstTarget = Target;
 }
 
-std::unique_ptr<SnippetGenerator>
-ExegesisTarget::createSnippetGenerator(InstructionBenchmark::ModeE Mode,
-                                       const LLVMState &State) const {
+std::unique_ptr<SnippetGenerator> ExegesisTarget::createSnippetGenerator(
+    InstructionBenchmark::ModeE Mode, const LLVMState &State,
+    const SnippetGenerator::Options &Opts) const {
   switch (Mode) {
   case InstructionBenchmark::Unknown:
     return nullptr;
   case InstructionBenchmark::Latency:
-    return createLatencySnippetGenerator(State);
+    return createLatencySnippetGenerator(State, Opts);
   case InstructionBenchmark::Uops:
   case InstructionBenchmark::InverseThroughput:
-    return createUopsSnippetGenerator(State);
+    return createUopsSnippetGenerator(State, Opts);
   }
   return nullptr;
 }
 
 std::unique_ptr<BenchmarkRunner>
 ExegesisTarget::createBenchmarkRunner(InstructionBenchmark::ModeE Mode,
                                       const LLVMState &State) const {
   switch (Mode) {
   case InstructionBenchmark::Unknown:
     return nullptr;
   case InstructionBenchmark::Latency:
   case InstructionBenchmark::InverseThroughput:
     return createLatencyBenchmarkRunner(State, Mode);
   case InstructionBenchmark::Uops:
     return createUopsBenchmarkRunner(State);
   }
   return nullptr;
 }
 
-std::unique_ptr<SnippetGenerator>
-ExegesisTarget::createLatencySnippetGenerator(const LLVMState &State) const {
-  return std::make_unique<LatencySnippetGenerator>(State);
+std::unique_ptr<SnippetGenerator> ExegesisTarget::createLatencySnippetGenerator(
+    const LLVMState &State, const SnippetGenerator::Options &Opts) const {
+  return std::make_unique<LatencySnippetGenerator>(State, Opts);
 }
 
-std::unique_ptr<SnippetGenerator>
-ExegesisTarget::createUopsSnippetGenerator(const LLVMState &State) const {
-  return std::make_unique<UopsSnippetGenerator>(State);
+std::unique_ptr<SnippetGenerator> ExegesisTarget::createUopsSnippetGenerator(
+    const LLVMState &State, const SnippetGenerator::Options &Opts) const {
+  return std::make_unique<UopsSnippetGenerator>(State, Opts);
 }
 
 std::unique_ptr<BenchmarkRunner> ExegesisTarget::createLatencyBenchmarkRunner(
     const LLVMState &State, InstructionBenchmark::ModeE Mode) const {
   return std::make_unique<LatencyBenchmarkRunner>(State, Mode);
 }
 
 std::unique_ptr<BenchmarkRunner>

llvm/tools/llvm-exegesis/lib/Uops.h

 #include "BenchmarkRunner.h"
 #include "SnippetGenerator.h"
 
 namespace llvm {
 namespace exegesis {
 
 class UopsSnippetGenerator : public SnippetGenerator {
 public:
-  UopsSnippetGenerator(const LLVMState &State) : SnippetGenerator(State) {}
+  using SnippetGenerator::SnippetGenerator;
   ~UopsSnippetGenerator() override;
 
   llvm::Expected<std::vector<CodeTemplate>>
   generateCodeTemplates(const Instruction &Instr,
                         const BitVector &ForbiddenRegisters) const override;
 
   static constexpr const size_t kMinNumDifferentAddresses = 6;
 

llvm/tools/llvm-exegesis/lib/X86/Target.cpp

std::vector<llvm::MCInst> setRegTo(const llvm::MCSubtargetInfo &STI,
                                      const llvm::APInt &Value) const override;
 
   ArrayRef<unsigned> getUnavailableRegisters() const override {
     return makeArrayRef(kUnavailableRegisters,
                         sizeof(kUnavailableRegisters) /
                             sizeof(kUnavailableRegisters[0]));
   }
 
-  std::unique_ptr<SnippetGenerator>
-  createLatencySnippetGenerator(const LLVMState &State) const override {
-    return std::make_unique<X86LatencySnippetGenerator>(State);
+  std::unique_ptr<SnippetGenerator> createLatencySnippetGenerator(
+      const LLVMState &State,
+      const SnippetGenerator::Options &Opts) const override {
+    return std::make_unique<X86LatencySnippetGenerator>(State, Opts);
   }
 
-  std::unique_ptr<SnippetGenerator>
-  createUopsSnippetGenerator(const LLVMState &State) const override {
-    return std::make_unique<X86UopsSnippetGenerator>(State);
+  std::unique_ptr<SnippetGenerator> createUopsSnippetGenerator(
+      const LLVMState &State,
+      const SnippetGenerator::Options &Opts) const override {
+    return std::make_unique<X86UopsSnippetGenerator>(State, Opts);
   }
 
   bool matchesArch(llvm::Triple::ArchType Arch) const override {
     return Arch == llvm::Triple::x86_64 || Arch == llvm::Triple::x86;
   }
 
   static const unsigned kUnavailableRegisters[4];
 };

llvm/tools/llvm-exegesis/llvm-exegesis.cpp

cl::values(clEnumValN(exegesis::InstructionBenchmark::Duplicate,
                clEnumValN(exegesis::InstructionBenchmark::Loop, "loop",
                           "Loop over the snippet")));
 
 static cl::opt<unsigned>
     NumRepetitions("num-repetitions",
                    cl::desc("number of time to repeat the asm snippet"),
                    cl::cat(BenchmarkOptions), cl::init(10000));
 
+static cl::opt<unsigned> MaxConfigsPerOpcode(
+    "max-configs-per-opcode",
+    cl::desc(
+        "allow to snippet generator to generate at most that many configs"),
+    cl::cat(BenchmarkOptions), cl::init(1));
+
 static cl::opt<bool> IgnoreInvalidSchedClass(
     "ignore-invalid-sched-class",
     cl::desc("ignore instructions that do not define a sched class"),
     cl::cat(BenchmarkOptions), cl::init(false));
 
 static cl::opt<exegesis::InstructionBenchmarkClustering::ModeE>
     AnalysisClusteringAlgorithm(
         "analysis-clustering", cl::desc("the clustering algorithm to use"),
generateSnippets(const LLVMState &State, unsigned Opcode,
   // Ignore instructions that we cannot run.
   if (InstrDesc.isPseudo())
     return make_error<Failure>("Unsupported opcode: isPseudo");
   if (InstrDesc.isBranch() || InstrDesc.isIndirectBranch())
     return make_error<Failure>("Unsupported opcode: isBranch/isIndirectBranch");
   if (InstrDesc.isCall() || InstrDesc.isReturn())
     return make_error<Failure>("Unsupported opcode: isCall/isReturn");
 
+  SnippetGenerator::Options Options;
+  Options.MaxConfigsPerOpcode = MaxConfigsPerOpcode;
   const std::unique_ptr<SnippetGenerator> Generator =
-      State.getExegesisTarget().createSnippetGenerator(BenchmarkMode, State);
+      State.getExegesisTarget().createSnippetGenerator(BenchmarkMode, State,
+                                                       Options);
   if (!Generator)
     llvm::report_fatal_error("cannot create snippet generator");
   return Generator->generateConfigurations(Instr, ForbiddenRegs);
 }
 
 void benchmarkMain() {
 #ifndef HAVE_LIBPFM
   llvm::report_fatal_error(

llvm/unittests/tools/llvm-exegesis/X86/SnippetGeneratorTest.cpp

protected:
   X86SnippetGeneratorTest() : InstrInfo(State.getInstrInfo()) {}
 
   const llvm::MCInstrInfo &InstrInfo;
 };
 
 template <typename SnippetGeneratorT>
 class SnippetGeneratorTest : public X86SnippetGeneratorTest {
 protected:
-  SnippetGeneratorTest() : Generator(State) {}
+  SnippetGeneratorTest() : Generator(State, SnippetGenerator::Options()) {}
 
   std::vector<CodeTemplate> checkAndGetCodeTemplates(unsigned Opcode) {
     randomGenerator().seed(0); // Initialize seed.
     const Instruction &Instr = State.getIC().getInstr(Opcode);
     auto CodeTemplateOrError = Generator.generateCodeTemplates(
         Instr, State.getRATC().emptyRegisters());
     EXPECT_FALSE(CodeTemplateOrError.takeError()); // Valid configuration.
     return std::move(CodeTemplateOrError.get());
TEST_F(UopsSnippetGeneratorTest, MemoryUse) {
   EXPECT_EQ(IT.VariableValues[2].getImm(), 1);
   EXPECT_EQ(IT.VariableValues[3].getReg(), 0u);
   EXPECT_EQ(IT.VariableValues[4].getImm(), 0);
   EXPECT_EQ(IT.VariableValues[5].getReg(), 0u);
 }
 
 class FakeSnippetGenerator : public SnippetGenerator {
 public:
-  FakeSnippetGenerator(const LLVMState &State) : SnippetGenerator(State) {}
+  FakeSnippetGenerator(const LLVMState &State, const Options &Opts)
+      : SnippetGenerator(State, Opts) {}
 
   Instruction createInstruction(unsigned Opcode) {
     return State.getIC().getInstr(Opcode);
   }
 
 private:
   llvm::Expected<std::vector<CodeTemplate>>
   generateCodeTemplates(const Instruction &, const BitVector &) const override {