[mca] New option -scheduling-info

JulienVillette · JulienVillette · commit 885ba9063758 · 2025-02-11T14:50:31.000+01:00
Outputs micro ops, latency, bypass latency, throughput, llvm opcode
name, used resources and parsed assembly instruction with comments.

This option is used to compare scheduling info from micro architecture documents.
Reference scheduling information (from Architecture and micro
architecture) are in comment section after each instruction (// or
/* */).

These information may be generated from Architecture Description Language.
By this way, it is easy to compare information from llvm and from
documentation/ADL.

LLVM Opcode name help to find right instruction regexp to fix in
Target Scheduling Info specification.

Example:
  Input:      abs D20, D11  // ABS &lt;V&gt;&lt;d&gt;, &lt;V&gt;&lt;n&gt;
      \\ ASIMD arith, basic  \\ 1 2  2  4.0 V1UnitV
  Output:  1 | 2 | 2 | 4.00 | V1UnitV | ABSv1i64 |
           abs     d20, d11              // ABS &lt;V&gt;&lt;d&gt;, &lt;V&gt;&lt;n&gt;
      \\ ASIMD arith, basic  \\ 1 2  2  4.0 V1UnitV
diff --git a/llvm/docs/CommandGuide/llvm-mca.rst b/llvm/docs/CommandGuide/llvm-mca.rst
@@ -170,6 +170,20 @@ option specifies "``-``", then the output will also be sent to standard output.
   Enable extra scheduler statistics. This view collects and analyzes instruction
   issue events. This view is disabled by default.
 
+.. option:: -scheduling-info
+
+  Enable scheduling info view. This view reports scheduling information defined
+  in LLVM target description in the form:
+  uOps | Latency | Bypass Latency | Throughput | LLVM OpcodeName | Resources
+  units | assembly instruction and its comment (// or /* */) if defined.
+  It allows to compare scheduling info with architecture documents and fix them
+  in target description by fixing InstrRW for the reported LLVM opcode.
+  Scheduling information can be defined in the same order in each instruction
+  comments to check easily reported and reference scheduling information.
+  Suggested information in comment:
+  ``// <architecture instruction form> \\ <scheduling documentation title> \\
+     <uOps>, <Latency>, <Bypass Latency>, <Throughput>, <Resources units>``
+
 .. option:: -retire-stats
 
   Enable extra retire control unit statistics. This view is disabled by default.
diff --git a/llvm/include/llvm/MC/MCSchedule.h b/llvm/include/llvm/MC/MCSchedule.h
@@ -402,6 +402,10 @@ struct MCSchedModel {
   static unsigned getForwardingDelayCycles(ArrayRef<MCReadAdvanceEntry> Entries,
                                            unsigned WriteResourceIdx = 0);
 
+  /// Returns the maximum forwarding delay for maximum write latency.
+  static unsigned getForwardingDelayCycles(const MCSubtargetInfo &STI,
+                                           const MCSchedClassDesc &SCDesc);
+
   /// Returns the default initialized model.
   static const MCSchedModel Default;
 };
diff --git a/llvm/lib/MC/MCSchedule.cpp b/llvm/lib/MC/MCSchedule.cpp
@@ -174,3 +174,40 @@ MCSchedModel::getForwardingDelayCycles(ArrayRef<MCReadAdvanceEntry> Entries,
 
   return std::abs(DelayCycles);
 }
+
+unsigned
+MCSchedModel::getForwardingDelayCycles(const MCSubtargetInfo &STI,
+                                       const MCSchedClassDesc &SCDesc) {
+
+  ArrayRef<MCReadAdvanceEntry> Entries = STI.getReadAdvanceEntries(SCDesc);
+  if (Entries.empty())
+    return 0;
+
+  unsigned Latency = 0;
+  unsigned maxLatency = 0;
+  unsigned WriteResourceID = 0;
+  unsigned DefEnd = SCDesc.NumWriteLatencyEntries;
+
+  for (unsigned DefIdx = 0; DefIdx != DefEnd; ++DefIdx) {
+    // Lookup the definition's write latency in SubtargetInfo.
+    const MCWriteLatencyEntry *WLEntry =
+        STI.getWriteLatencyEntry(&SCDesc, DefIdx);
+    // Early exit if we found an invalid latency.
+    // Consider no bypass
+    if (WLEntry->Cycles < 0)
+      return 0;
+    maxLatency = std::max(Latency, static_cast<unsigned>(WLEntry->Cycles));
+    if (maxLatency > Latency) {
+      WriteResourceID = WLEntry->WriteResourceID;
+    }
+    Latency = maxLatency;
+  }
+
+  for (const MCReadAdvanceEntry &E : Entries) {
+    if (E.WriteResourceID == WriteResourceID) {
+      return E.Cycles;
+    }
+  }
+
+  llvm_unreachable("WriteResourceID not found in MCReadAdvanceEntry entries");
+}
diff --git a/llvm/test/tools/llvm-mca/AArch64/Neoverse/V1-scheduling-info.s b/llvm/test/tools/llvm-mca/AArch64/Neoverse/V1-scheduling-info.s
diff --git a/llvm/tools/llvm-mca/CMakeLists.txt b/llvm/tools/llvm-mca/CMakeLists.txt
@@ -19,6 +19,7 @@ add_llvm_tool(llvm-mca
   Views/BottleneckAnalysis.cpp
   Views/DispatchStatistics.cpp
   Views/InstructionInfoView.cpp
+  Views/SchedulingInfoView.cpp
   Views/InstructionView.cpp
   Views/RegisterFileStatistics.cpp
   Views/ResourcePressureView.cpp
diff --git a/llvm/tools/llvm-mca/Views/InstructionInfoView.h b/llvm/tools/llvm-mca/Views/InstructionInfoView.h
@@ -66,6 +66,7 @@ class InstructionInfoView : public InstructionView {
   struct InstructionInfoViewData {
     unsigned NumMicroOpcodes = 0;
     unsigned Latency = 0;
+    unsigned Advance = 0; // ReadAvance Bypasses cycles
     std::optional<double> RThroughput = 0.0;
     bool mayLoad = false;
     bool mayStore = false;
diff --git a/llvm/tools/llvm-mca/Views/SchedulingInfoView.cpp b/llvm/tools/llvm-mca/Views/SchedulingInfoView.cpp
@@ -0,0 +1,212 @@
+//===--------------------- SchedulingInfoView.cpp --------------*- 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
+//
+//===----------------------------------------------------------------------===//
+/// \file
+///
+/// This file implements the SchedulingInfoView API.
+///
+//===----------------------------------------------------------------------===//
+
+#include "Views/SchedulingInfoView.h"
+#include "llvm/Support/FormattedStream.h"
+#include "llvm/Support/JSON.h"
+
+namespace llvm {
+namespace mca {
+
+void SchedulingInfoView::getComment(const MCInst &MCI,
+                                    std::string &CommentString) const {
+  StringRef s = MCI.getLoc().getPointer();
+  std::string InstrStr;
+  size_t pos = 0, pos_cmt = 0;
+
+  // Recognized comments are after assembly instructions on the same line.
+  // It is usefull to add in comment scheduling information from architecture
+  // specification.
+  // '#' comment mark is not supported by llvm-mca
+
+  CommentString = "";
+  if ((pos = s.find("\n")) != std::string::npos) {
+    InstrStr = s.substr(0, pos);
+    // C style comment
+    if (((pos_cmt = InstrStr.find("/*")) != std::string::npos) &&
+        ((pos = InstrStr.find("*/")) != std::string::npos)) {
+      CommentString = InstrStr.substr(pos_cmt, pos);
+      return;
+    }
+    // C++ style comment
+    if ((pos_cmt = InstrStr.find("//")) != std::string::npos) {
+      CommentString = InstrStr.substr(pos_cmt, pos);
+      return;
+    }
+  }
+  return;
+}
+
+void SchedulingInfoView::printView(raw_ostream &OS) const {
+  std::string Buffer;
+  std::string CommentString;
+  raw_string_ostream TempStream(Buffer);
+  formatted_raw_ostream FOS(TempStream);
+
+  ArrayRef<MCInst> Source = getSource();
+  if (!Source.size())
+    return;
+
+  IIVDVec IIVD(Source.size());
+  collectData(IIVD);
+
+  FOS << "\n\nResources:\n";
+  const MCSchedModel &SM = getSubTargetInfo().getSchedModel();
+  for (unsigned I = 1, ResourceIndex = 0, E = SM.getNumProcResourceKinds();
+       I < E; ++I) {
+    const MCProcResourceDesc &ProcResource = *SM.getProcResource(I);
+    unsigned NumUnits = ProcResource.NumUnits;
+    // Skip invalid resources with zero units.
+    if (!NumUnits)
+      continue;
+
+    FOS << '[' << ResourceIndex << ']';
+    FOS.PadToColumn(6);
+    FOS << "- " << ProcResource.Name << ':' << NumUnits;
+    if (ProcResource.SubUnitsIdxBegin) {
+      FOS.PadToColumn(20);
+      for (unsigned U = 0; U < NumUnits; ++U) {
+        FOS << SM.getProcResource(ProcResource.SubUnitsIdxBegin[U])->Name;
+        if ((U + 1) < NumUnits) {
+          FOS << ", ";
+        }
+      }
+    }
+    FOS << '\n';
+    ResourceIndex++;
+  }
+
+  FOS << "\n\nScheduling Info:\n";
+  FOS << "[1]: #uOps\n[2]: Latency\n[3]: Bypass Latency\n"
+      << "[4]: Throughput\n[5]: Resources\n"
+      << "[6]: LLVM OpcodeName\n[7]: Instruction\n"
+      << "[8]: Comment if any\n";
+
+  // paddings for each scheduling info output. Start at [2]
+  std::vector<unsigned> paddings = {7, 12, 18, 27, 94, 113, 150};
+  for (unsigned i = 0; i < paddings.size(); i++) {
+    FOS << " [" << i + 1 << "]";
+    FOS.PadToColumn(paddings[i]);
+  }
+  FOS << "[" << paddings.size() + 1 << "]\n";
+
+  for (const auto &[Index, IIVDEntry, Inst] : enumerate(IIVD, Source)) {
+    getComment(Inst, CommentString);
+
+    FOS << "  " << IIVDEntry.NumMicroOpcodes;
+    FOS.PadToColumn(paddings[0]);
+    FOS << "| " << IIVDEntry.Latency;
+    FOS.PadToColumn(paddings[1]);
+    FOS << "| " << IIVDEntry.Bypass;
+    FOS.PadToColumn(paddings[2]);
+    if (IIVDEntry.Throughput) {
+      double RT = *IIVDEntry.Throughput;
+      FOS << "| " << format("%.2f", RT);
+    } else {
+      FOS << "| -";
+    }
+    FOS.PadToColumn(paddings[3]);
+    FOS << "| " << IIVDEntry.Resources;
+    FOS.PadToColumn(paddings[4]);
+    FOS << "| " << IIVDEntry.OpcodeName;
+    FOS.PadToColumn(paddings[5]);
+    FOS << "| " << printInstructionString(Inst);
+    FOS.PadToColumn(paddings[6]);
+    FOS << ' ' << CommentString << '\n';
+  }
+
+  FOS.flush();
+  OS << Buffer;
+}
+
+void SchedulingInfoView::collectData(
+    MutableArrayRef<SchedulingInfoViewData> IIVD) const {
+  const MCSubtargetInfo &STI = getSubTargetInfo();
+  const MCSchedModel &SM = STI.getSchedModel();
+  for (const auto &[Inst, IIVDEntry] : zip(getSource(), IIVD)) {
+    const MCInstrDesc &MCDesc = MCII.get(Inst.getOpcode());
+
+    // Obtain the scheduling class information from the instruction
+    // and instruments.
+    auto IVecIt = InstToInstruments.find(&Inst);
+    unsigned SchedClassID =
+        IVecIt == InstToInstruments.end()
+            ? MCDesc.getSchedClass()
+            : IM.getSchedClassID(MCII, Inst, IVecIt->second);
+    unsigned CPUID = SM.getProcessorID();
+
+    // Try to solve variant scheduling classes.
+    while (SchedClassID && SM.getSchedClassDesc(SchedClassID)->isVariant())
+      SchedClassID =
+          STI.resolveVariantSchedClass(SchedClassID, &Inst, &MCII, CPUID);
+
+    const MCSchedClassDesc &SCDesc = *SM.getSchedClassDesc(SchedClassID);
+    IIVDEntry.OpcodeName = (std::string)MCII.getName(Inst.getOpcode());
+    IIVDEntry.NumMicroOpcodes = SCDesc.NumMicroOps;
+    IIVDEntry.Latency = MCSchedModel::computeInstrLatency(STI, SCDesc);
+    IIVDEntry.Bypass =
+        IIVDEntry.Latency - MCSchedModel::getForwardingDelayCycles(STI, SCDesc);
+    IIVDEntry.Throughput =
+        1.0 / MCSchedModel::getReciprocalThroughput(STI, SCDesc);
+    raw_string_ostream TempStream(IIVDEntry.Resources);
+
+    const MCWriteProcResEntry *Index = STI.getWriteProcResBegin(&SCDesc);
+    const MCWriteProcResEntry *Last = STI.getWriteProcResEnd(&SCDesc);
+    auto sep = "";
+    for (; Index != Last; ++Index) {
+      if (!Index->ReleaseAtCycle)
+        continue;
+      const MCProcResourceDesc *MCProc =
+          SM.getProcResource(Index->ProcResourceIdx);
+      if (Index->ReleaseAtCycle != 1) {
+        // Output ReleaseAtCycle between [] if not 1 (default)
+        TempStream << sep
+                   << format("%s[%d]", MCProc->Name, Index->ReleaseAtCycle);
+      } else {
+        TempStream << sep << format("%s", MCProc->Name);
+      }
+      sep = ", ";
+    }
+    TempStream.flush();
+  }
+}
+
+// Construct a JSON object from a single SchedulingInfoViewData object.
+json::Object
+SchedulingInfoView::toJSON(const SchedulingInfoViewData &IIVD) const {
+  json::Object JO({{"NumMicroOpcodes", IIVD.NumMicroOpcodes},
+                   {"Latency", IIVD.Latency},
+                   {"LatencyWithBypass", IIVD.Bypass},
+                   {"Throughput", IIVD.Throughput.value_or(0.0)}});
+  return JO;
+}
+
+json::Value SchedulingInfoView::toJSON() const {
+  ArrayRef<MCInst> Source = getSource();
+  if (!Source.size())
+    return json::Value(nullptr);
+
+  IIVDVec IIVD(Source.size());
+  collectData(IIVD);
+
+  json::Array InstInfo;
+  for (const auto &I : enumerate(IIVD)) {
+    const SchedulingInfoViewData &IIVDEntry = I.value();
+    json::Object JO = toJSON(IIVDEntry);
+    JO.try_emplace("Instruction", (unsigned)I.index());
+    InstInfo.push_back(std::move(JO));
+  }
+  return json::Object({{"InstructionList", json::Value(std::move(InstInfo))}});
+}
+} // namespace mca.
+} // namespace llvm
diff --git a/llvm/tools/llvm-mca/Views/SchedulingInfoView.h b/llvm/tools/llvm-mca/Views/SchedulingInfoView.h
@@ -0,0 +1,97 @@
+//===--------------------- SchedulingInfoView.h ----------------*- 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
+//
+//===----------------------------------------------------------------------===//
+/// \file
+///
+/// This file implements the instruction scheduling info view.
+///
+/// The goal fo the instruction scheduling info view is to print the latency,
+/// latency with bypass,
+//  throughput, pipeline ressources and uOps information for every instruction
+//  in the input sequence.
+///
+/// Example:
+///
+/// Instruction Info:
+/// [1]: #uOps
+/// [2]: Latency
+/// [3]: Bypass latency
+/// [3]: Throughput
+/// [4]: Resources
+///
+/// [1]    [2]    [3]    [4]    [5]    [6]	Instructions:
+///  1      4     1                 	        vmulps	%xmm0, %xmm1, %xmm2
+///  1      3     1.00                    	vhaddps	%xmm2, %xmm2, %xmm3
+///  1      3     1.00                    	vhaddps	%xmm3, %xmm3, %xmm4
+//
+//===----------------------------------------------------------------------===//
+
+#ifndef LLVM_TOOLS_LLVM_MCA_SCHEDULINGINFOVIEW_H
+#define LLVM_TOOLS_LLVM_MCA_SCHEDULINGINFOVIEW_H
+
+#include "Views/InstructionView.h"
+#include "llvm/ADT/ArrayRef.h"
+#include "llvm/ADT/SmallVector.h"
+#include "llvm/MC/MCInst.h"
+#include "llvm/MC/MCInstPrinter.h"
+#include "llvm/MC/MCInstrInfo.h"
+#include "llvm/MC/MCSubtargetInfo.h"
+#include "llvm/MCA/CodeEmitter.h"
+#include "llvm/MCA/CustomBehaviour.h"
+#include "llvm/Support/raw_ostream.h"
+
+#define DEBUG_TYPE "llvm-mca"
+
+namespace llvm {
+namespace mca {
+
+/// A view that prints out generic instruction information.
+class SchedulingInfoView : public InstructionView {
+  const llvm::MCInstrInfo &MCII;
+  CodeEmitter &CE;
+  using UniqueInst = std::unique_ptr<Instruction>;
+  ArrayRef<UniqueInst> LoweredInsts;
+  const InstrumentManager &IM;
+  using InstToInstrumentsT =
+      DenseMap<const MCInst *, SmallVector<mca::Instrument *>>;
+  const InstToInstrumentsT &InstToInstruments;
+
+  struct SchedulingInfoViewData {
+    unsigned NumMicroOpcodes = 0;
+    unsigned Latency = 0;
+    unsigned Bypass = 0; // ReadAvance Bypasses cycles
+    std::optional<double> Throughput = 0.0;
+    std::string OpcodeName = "";
+    std::string Resources = "";
+  };
+  using IIVDVec = SmallVector<SchedulingInfoViewData, 16>;
+
+  /// Place the data into the array of SchedulingInfoViewData IIVD.
+  void collectData(MutableArrayRef<SchedulingInfoViewData> IIVD) const;
+
+public:
+  SchedulingInfoView(const llvm::MCSubtargetInfo &ST,
+                     const llvm::MCInstrInfo &II, CodeEmitter &C,
+                     llvm::ArrayRef<llvm::MCInst> S, llvm::MCInstPrinter &IP,
+                     ArrayRef<UniqueInst> LoweredInsts,
+                     const InstrumentManager &IM,
+                     const InstToInstrumentsT &InstToInstruments)
+      : InstructionView(ST, IP, S), MCII(II), CE(C), LoweredInsts(LoweredInsts),
+        IM(IM), InstToInstruments(InstToInstruments) {}
+
+  /// Extract comment (//, /* */) from the source assembly placed just after
+  /// instruction.
+  void getComment(const llvm::MCInst &Inst, std::string &CommentString) const;
+  void printView(llvm::raw_ostream &OS) const override;
+  StringRef getNameAsString() const override { return "SchedulingInfoView"; }
+  json::Value toJSON() const override;
+  json::Object toJSON(const SchedulingInfoViewData &IIVD) const;
+};
+} // namespace mca
+} // namespace llvm
+
+#endif
diff --git a/llvm/tools/llvm-mca/llvm-mca.cpp b/llvm/tools/llvm-mca/llvm-mca.cpp
