[llvm-exegesis] Replace --num-repetitions with --min-instructions (#77153)

This patch replaces --num-repetitions with --min-instructions to make it
more clear that the value refers to the minimum number of instructions
in the final assembled snippet rather than the number of repetitions of
the snippet. This patch also refactors some llvm-exegesis internal
variable names to reflect the name change.

Fixes #76890.

10 files changed, 46 insertions, 35 deletions

diff --git a/llvm/docs/CommandGuide/llvm-exegesis.rst b/llvm/docs/CommandGuide/llvm-exegesis.rst
index 0d5b11255138..601082a78f1e 100644
--- a/llvm/docs/CommandGuide/llvm-exegesis.rst
+++ b/llvm/docs/CommandGuide/llvm-exegesis.rst
@@ -304,12 +304,12 @@ OPTIONS
 .. option:: --repetition-mode=[duplicate|loop|min|middle-half-duplicate|middle-half-loop]
 
  Specify the repetition mode. `duplicate` will create a large, straight line
- basic block with `num-repetitions` instructions (repeating the snippet
- `num-repetitions`/`snippet size` times). `loop` will, optionally, duplicate the
+ basic block with `min-instructions` instructions (repeating the snippet
+ `min-instructions`/`snippet size` times). `loop` will, optionally, duplicate the
  snippet until the loop body contains at least `loop-body-size` instructions,
- and then wrap the result in a loop which will execute `num-repetitions`
+ and then wrap the result in a loop which will execute `min-instructions`
  instructions (thus, again, repeating the snippet
- `num-repetitions`/`snippet size` times). The `loop` mode, especially with loop
+ `min-instructions`/`snippet size` times). The `loop` mode, especially with loop
  unrolling tends to better hide the effects of the CPU frontend on architectures
  that cache decoded instructions, but consumes a register for counting
  iterations. If performing an analysis over many opcodes, it may be best to
@@ -320,10 +320,10 @@ OPTIONS
  length of the first one, and then subtract the difference between them to get
  values without overhead.
 
-.. option:: --num-repetitions=<Number of repetitions>
+.. option:: --min-instructions=<Number of instructions>
 
  Specify the target number of executed instructions. Note that the actual
- repetition count of the snippet will be `num-repetitions`/`snippet size`.
+ repetition count of the snippet will be `min-instructions`/`snippet size`.
  Higher values lead to more accurate measurements but lengthen the benchmark.
 
 .. option:: --loop-body-size=<Preferred loop body size>
diff --git a/llvm/tools/llvm-exegesis/lib/BenchmarkResult.cpp b/llvm/tools/llvm-exegesis/lib/BenchmarkResult.cpp
index e985c323ff05..c193a8e50277 100644
--- a/llvm/tools/llvm-exegesis/lib/BenchmarkResult.cpp
+++ b/llvm/tools/llvm-exegesis/lib/BenchmarkResult.cpp
@@ -355,7 +355,17 @@ struct MappingContextTraits<exegesis::Benchmark, YamlContext> {
     Io.mapRequired("key", Obj.Key, Context);
     Io.mapRequired("cpu_name", Obj.CpuName);
     Io.mapRequired("llvm_triple", Obj.LLVMTriple);
-    Io.mapRequired("num_repetitions", Obj.NumRepetitions);
+    // Optionally map num_repetitions and min_instructions to the same
+    // value to preserve backwards compatibility.
+    // TODO(boomanaiden154): Move min_instructions to mapRequired and
+    // remove num_repetitions once num_repetitions is ready to be removed
+    // completely.
+    if (Io.outputting())
+      Io.mapRequired("min_instructions", Obj.MinInstructions);
+    else {
+      Io.mapOptional("num_repetitions", Obj.MinInstructions);
+      Io.mapOptional("min_instructions", Obj.MinInstructions);
+    }
     Io.mapRequired("measurements", Obj.Measurements);
     Io.mapRequired("error", Obj.Error);
     Io.mapOptional("info", Obj.Info);
diff --git a/llvm/tools/llvm-exegesis/lib/BenchmarkResult.h b/llvm/tools/llvm-exegesis/lib/BenchmarkResult.h
index e84e6a0a6f55..43f03ff54133 100644
--- a/llvm/tools/llvm-exegesis/lib/BenchmarkResult.h
+++ b/llvm/tools/llvm-exegesis/lib/BenchmarkResult.h
@@ -116,7 +116,7 @@ struct Benchmark {
   const MCInst &keyInstruction() const { return Key.Instructions[0]; }
   // The number of instructions inside the repeated snippet. For example, if a
   // snippet of 3 instructions is repeated 4 times, this is 12.
-  unsigned NumRepetitions = 0;
+  unsigned MinInstructions = 0;
   enum RepetitionModeE {
     Duplicate,
     Loop,
diff --git a/llvm/tools/llvm-exegesis/lib/BenchmarkRunner.cpp b/llvm/tools/llvm-exegesis/lib/BenchmarkRunner.cpp
index 81ac7e7ebfde..a8bc438e9810 100644
--- a/llvm/tools/llvm-exegesis/lib/BenchmarkRunner.cpp
+++ b/llvm/tools/llvm-exegesis/lib/BenchmarkRunner.cpp
@@ -522,7 +522,7 @@ Expected<SmallString<0>> BenchmarkRunner::assembleSnippet(
 
 Expected<BenchmarkRunner::RunnableConfiguration>
 BenchmarkRunner::getRunnableConfiguration(
-    const BenchmarkCode &BC, unsigned NumRepetitions, unsigned LoopBodySize,
+    const BenchmarkCode &BC, unsigned MinInstructions, unsigned LoopBodySize,
     const SnippetRepetitor &Repetitor) const {
   RunnableConfiguration RC;
 
@@ -532,7 +532,7 @@ BenchmarkRunner::getRunnableConfiguration(
       std::string(State.getTargetMachine().getTargetCPU());
   BenchmarkResult.LLVMTriple =
       State.getTargetMachine().getTargetTriple().normalize();
-  BenchmarkResult.NumRepetitions = NumRepetitions;
+  BenchmarkResult.MinInstructions = MinInstructions;
   BenchmarkResult.Info = BC.Info;
 
   const std::vector<MCInst> &Instructions = BC.Key.Instructions;
@@ -558,12 +558,12 @@ BenchmarkRunner::getRunnableConfiguration(
       return std::move(Err);
   }
 
-  // Assemble NumRepetitions instructions repetitions of the snippet for
-  // measurements.
+  // Assemble enough repetitions of the snippet so we have at least
+  // MinInstructios instructions.
   if (BenchmarkPhaseSelector >
       BenchmarkPhaseSelectorE::PrepareAndAssembleSnippet) {
     auto Snippet =
-        assembleSnippet(BC, Repetitor, BenchmarkResult.NumRepetitions,
+        assembleSnippet(BC, Repetitor, BenchmarkResult.MinInstructions,
                         LoopBodySize, GenerateMemoryInstructions);
     if (Error E = Snippet.takeError())
       return std::move(E);
@@ -634,13 +634,13 @@ std::pair<Error, Benchmark> BenchmarkRunner::runConfiguration(
   if (Error E = NewMeasurements.takeError()) {
     return {std::move(E), std::move(BenchmarkResult)};
   }
-  assert(BenchmarkResult.NumRepetitions > 0 && "invalid NumRepetitions");
+  assert(BenchmarkResult.MinInstructions > 0 && "invalid MinInstructions");
   for (BenchmarkMeasure &BM : *NewMeasurements) {
     // Scale the measurements by instruction.
-    BM.PerInstructionValue /= BenchmarkResult.NumRepetitions;
+    BM.PerInstructionValue /= BenchmarkResult.MinInstructions;
     // Scale the measurements by snippet.
     BM.PerSnippetValue /=
-        std::ceil(BenchmarkResult.NumRepetitions /
+        std::ceil(BenchmarkResult.MinInstructions /
                   static_cast<double>(BenchmarkResult.Key.Instructions.size()));
   }
   BenchmarkResult.Measurements = std::move(*NewMeasurements);
diff --git a/llvm/tools/llvm-exegesis/lib/BenchmarkRunner.h b/llvm/tools/llvm-exegesis/lib/BenchmarkRunner.h
index 9a0cdea197c4..9b4bb1d41149 100644
--- a/llvm/tools/llvm-exegesis/lib/BenchmarkRunner.h
+++ b/llvm/tools/llvm-exegesis/lib/BenchmarkRunner.h
@@ -63,7 +63,7 @@ public:
 
   Expected<RunnableConfiguration>
   getRunnableConfiguration(const BenchmarkCode &Configuration,
-                           unsigned NumRepetitions, unsigned LoopUnrollFactor,
+                           unsigned MinInstructions, unsigned LoopUnrollFactor,
                            const SnippetRepetitor &Repetitor) const;
 
   std::pair<Error, Benchmark>
diff --git a/llvm/tools/llvm-exegesis/lib/ResultAggregator.cpp b/llvm/tools/llvm-exegesis/lib/ResultAggregator.cpp
index e86e206cca38..ba2ae52e9d67 100644
--- a/llvm/tools/llvm-exegesis/lib/ResultAggregator.cpp
+++ b/llvm/tools/llvm-exegesis/lib/ResultAggregator.cpp
@@ -47,10 +47,10 @@ void MiddleHalfResultAggregator::AggregateMeasurement(
     const Benchmark &Result) const {
   Measurement.RawValue = NewMeasurement.RawValue - Measurement.RawValue;
   Measurement.PerInstructionValue = Measurement.RawValue;
-  Measurement.PerInstructionValue /= Result.NumRepetitions;
+  Measurement.PerInstructionValue /= Result.MinInstructions;
   Measurement.PerSnippetValue = Measurement.RawValue;
   Measurement.PerSnippetValue /=
-      std::ceil(Result.NumRepetitions /
+      std::ceil(Result.MinInstructions /
                 static_cast<double>(Result.Key.Instructions.size()));
 }
 
diff --git a/llvm/tools/llvm-exegesis/llvm-exegesis.cpp b/llvm/tools/llvm-exegesis/llvm-exegesis.cpp
index 02ed09d11533..90de3e5bcf1d 100644
--- a/llvm/tools/llvm-exegesis/llvm-exegesis.cpp
+++ b/llvm/tools/llvm-exegesis/llvm-exegesis.cpp
@@ -152,9 +152,10 @@ static cl::opt<bool>
                          cl::cat(BenchmarkOptions), cl::init(false));
 
 static cl::opt<unsigned>
-    NumRepetitions("num-repetitions",
-                   cl::desc("number of time to repeat the asm snippet"),
-                   cl::cat(BenchmarkOptions), cl::init(10000));
+    MinInstructions("min-instructions",
+                    cl::desc("The minimum number of instructions that should "
+                             "be included in the snippet"),
+                    cl::cat(BenchmarkOptions), cl::init(10000));
 
 static cl::opt<unsigned>
     LoopBodySize("loop-body-size",
@@ -426,10 +427,10 @@ static void runBenchmarkConfigurations(
   if (BenchmarkMeasurementsPrintProgress)
     Meter.emplace(Configurations.size());
 
-  SmallVector<unsigned, 2> MinInstructions = {NumRepetitions};
+  SmallVector<unsigned, 2> MinInstructionCounts = {MinInstructions};
   if (RepetitionMode == Benchmark::MiddleHalfDuplicate ||
       RepetitionMode == Benchmark::MiddleHalfLoop)
-    MinInstructions.push_back(NumRepetitions * 2);
+    MinInstructionCounts.push_back(MinInstructions * 2);
 
   for (const BenchmarkCode &Conf : Configurations) {
     ProgressMeter<>::ProgressMeterStep MeterStep(Meter ? &*Meter : nullptr);
@@ -437,7 +438,7 @@ static void runBenchmarkConfigurations(
 
     for (const std::unique_ptr<const SnippetRepetitor> &Repetitor :
          Repetitors) {
-      for (unsigned IterationRepetitions : MinInstructions) {
+      for (unsigned IterationRepetitions : MinInstructionCounts) {
         auto RC = ExitOnErr(Runner.getRunnableConfiguration(
             Conf, IterationRepetitions, LoopBodySize, *Repetitor));
         std::optional<StringRef> DumpFile;
@@ -572,9 +573,9 @@ void benchmarkMain() {
     }
   }
 
-  if (NumRepetitions == 0) {
+  if (MinInstructions == 0) {
     ExitOnErr.setBanner("llvm-exegesis: ");
-    ExitWithError("--num-repetitions must be greater than zero");
+    ExitWithError("--min-instructions must be greater than zero");
   }
 
   // Write to standard output if file is not set.
diff --git a/llvm/unittests/tools/llvm-exegesis/Mips/BenchmarkResultTest.cpp b/llvm/unittests/tools/llvm-exegesis/Mips/BenchmarkResultTest.cpp
index 9e2016d0d348..83ea6c0ba8e4 100644
--- a/llvm/unittests/tools/llvm-exegesis/Mips/BenchmarkResultTest.cpp
+++ b/llvm/unittests/tools/llvm-exegesis/Mips/BenchmarkResultTest.cpp
@@ -64,7 +64,7 @@ TEST_F(MipsBenchmarkResultTest, WriteToAndReadFromDisk) {
   ToDisk.Mode = Benchmark::Latency;
   ToDisk.CpuName = "cpu_name";
   ToDisk.LLVMTriple = "llvm_triple";
-  ToDisk.NumRepetitions = 1;
+  ToDisk.MinInstructions = 1;
   ToDisk.Measurements.push_back(BenchmarkMeasure::Create("a", 1, {}));
   ToDisk.Measurements.push_back(BenchmarkMeasure::Create("b", 2, {}));
   ToDisk.Error = "error";
@@ -98,7 +98,7 @@ TEST_F(MipsBenchmarkResultTest, WriteToAndReadFromDisk) {
     EXPECT_EQ(FromDisk.Mode, ToDisk.Mode);
     EXPECT_EQ(FromDisk.CpuName, ToDisk.CpuName);
     EXPECT_EQ(FromDisk.LLVMTriple, ToDisk.LLVMTriple);
-    EXPECT_EQ(FromDisk.NumRepetitions, ToDisk.NumRepetitions);
+    EXPECT_EQ(FromDisk.MinInstructions, ToDisk.MinInstructions);
     EXPECT_THAT(FromDisk.Measurements, ToDisk.Measurements);
     EXPECT_THAT(FromDisk.Error, ToDisk.Error);
     EXPECT_EQ(FromDisk.Info, ToDisk.Info);
@@ -115,7 +115,7 @@ TEST_F(MipsBenchmarkResultTest, WriteToAndReadFromDisk) {
     EXPECT_EQ(FromDisk.Mode, ToDisk.Mode);
     EXPECT_EQ(FromDisk.CpuName, ToDisk.CpuName);
     EXPECT_EQ(FromDisk.LLVMTriple, ToDisk.LLVMTriple);
-    EXPECT_EQ(FromDisk.NumRepetitions, ToDisk.NumRepetitions);
+    EXPECT_EQ(FromDisk.MinInstructions, ToDisk.MinInstructions);
     EXPECT_THAT(FromDisk.Measurements, ToDisk.Measurements);
     EXPECT_THAT(FromDisk.Error, ToDisk.Error);
     EXPECT_EQ(FromDisk.Info, ToDisk.Info);
diff --git a/llvm/unittests/tools/llvm-exegesis/ResultAggregatorTest.cpp b/llvm/unittests/tools/llvm-exegesis/ResultAggregatorTest.cpp
index f316baf1eb22..a96fef915b8e 100644
--- a/llvm/unittests/tools/llvm-exegesis/ResultAggregatorTest.cpp
+++ b/llvm/unittests/tools/llvm-exegesis/ResultAggregatorTest.cpp
@@ -57,8 +57,8 @@ TEST(ResultAggregatorTest, MiddleHalfAggregator) {
   Results[0].Key.Instructions.push_back(MCInst());
   Results[1].Key.Instructions.push_back(MCInst());
 
-  Results[0].NumRepetitions = 1;
-  Results[1].NumRepetitions = 3;
+  Results[0].MinInstructions = 1;
+  Results[1].MinInstructions = 3;
 
   Benchmark &Result = Results[0];
 
diff --git a/llvm/unittests/tools/llvm-exegesis/X86/BenchmarkResultTest.cpp b/llvm/unittests/tools/llvm-exegesis/X86/BenchmarkResultTest.cpp
index 415b22f91146..4636029f3501 100644
--- a/llvm/unittests/tools/llvm-exegesis/X86/BenchmarkResultTest.cpp
+++ b/llvm/unittests/tools/llvm-exegesis/X86/BenchmarkResultTest.cpp
@@ -83,7 +83,7 @@ TEST(BenchmarkResultTest, WriteToAndReadFromDisk) {
   ToDisk.Mode = Benchmark::Latency;
   ToDisk.CpuName = "cpu_name";
   ToDisk.LLVMTriple = "llvm_triple";
-  ToDisk.NumRepetitions = 1;
+  ToDisk.MinInstructions = 1;
   ToDisk.Measurements.push_back(BenchmarkMeasure::Create("a", 1, {}));
   ToDisk.Measurements.push_back(BenchmarkMeasure::Create("b", 2, {}));
   ToDisk.Error = "error";
@@ -134,7 +134,7 @@ TEST(BenchmarkResultTest, WriteToAndReadFromDisk) {
     EXPECT_EQ(FromDisk.Mode, ToDisk.Mode);
     EXPECT_EQ(FromDisk.CpuName, ToDisk.CpuName);
     EXPECT_EQ(FromDisk.LLVMTriple, ToDisk.LLVMTriple);
-    EXPECT_EQ(FromDisk.NumRepetitions, ToDisk.NumRepetitions);
+    EXPECT_EQ(FromDisk.MinInstructions, ToDisk.MinInstructions);
     EXPECT_THAT(FromDisk.Measurements, ToDisk.Measurements);
     EXPECT_THAT(FromDisk.Error, ToDisk.Error);
     EXPECT_EQ(FromDisk.Info, ToDisk.Info);
@@ -153,7 +153,7 @@ TEST(BenchmarkResultTest, WriteToAndReadFromDisk) {
     EXPECT_EQ(FromDisk.Mode, ToDisk.Mode);
     EXPECT_EQ(FromDisk.CpuName, ToDisk.CpuName);
     EXPECT_EQ(FromDisk.LLVMTriple, ToDisk.LLVMTriple);
-    EXPECT_EQ(FromDisk.NumRepetitions, ToDisk.NumRepetitions);
+    EXPECT_EQ(FromDisk.MinInstructions, ToDisk.MinInstructions);
     EXPECT_THAT(FromDisk.Measurements, ToDisk.Measurements);
     EXPECT_THAT(FromDisk.Error, ToDisk.Error);
     EXPECT_EQ(FromDisk.Info, ToDisk.Info);