From e0c77d80585428818c32886eb8c26755ea8ed159 Mon Sep 17 00:00:00 2001
From: Richard-Qin-X <richard.qin.001@gmail.com>
Date: Sat, 1 Aug 2026 18:17:33 +0800
Subject: [CodeGen] Track debug instruction identities

Add monotonic MIR debug instruction numbers and structured value substitutions. Verify live number uniqueness, meta-instruction exclusion, substitution graph integrity, and target subregister references while preserving debug identities during cloning.
---
 backend/include/rcc/CodeGen/MachineFunction.h      |  4 ++++
 .../include/rcc/CodeGen/MachineFunctionRecords.h   | 28 ++++++++++++++++++++++
 backend/include/rcc/CodeGen/MachineInstr.h         | 13 ++++++++++
 3 files changed, 45 insertions(+)

(limited to 'backend/include')

diff --git a/backend/include/rcc/CodeGen/MachineFunction.h b/backend/include/rcc/CodeGen/MachineFunction.h
index c067ee1..8addd4e 100644
--- a/backend/include/rcc/CodeGen/MachineFunction.h
+++ b/backend/include/rcc/CodeGen/MachineFunction.h
@@ -16,6 +16,7 @@
 #include "rcc/Support/Error.h"
 
 #include <cstddef>
+#include <cstdint>
 #include <memory>
 #include <span>
 #include <string>
@@ -176,6 +177,8 @@ public:
 
 private:
   MachineFunction(std::string Name, MachineFunctionStableID StableID);
+  [[nodiscard]] Expected<std::uint32_t> allocateDebugInstrNumber();
+  void observeDebugInstrNumber(std::uint32_t Number) noexcept;
 
   std::string Name;
   MachineFunctionStableID StableID;
@@ -195,6 +198,7 @@ private:
   std::vector<const MachineMemOperand *> AllMemOperands;
   StableIDGenerator<MachineBlockStableID> BlockIDGenerator;
   StableIDGenerator<MachineInstrStableID> InstrIDGenerator;
+  std::uint32_t DebugInstrNumberingCount = 0;
   std::unique_ptr<MachineArena> Arena;
 
   friend class MachineBasicBlock;
diff --git a/backend/include/rcc/CodeGen/MachineFunctionRecords.h b/backend/include/rcc/CodeGen/MachineFunctionRecords.h
index 7050072..7929ed3 100644
--- a/backend/include/rcc/CodeGen/MachineFunctionRecords.h
+++ b/backend/include/rcc/CodeGen/MachineFunctionRecords.h
@@ -18,6 +18,25 @@ namespace rcc {
 
 class MachineFunctionCloneContext;
 
+inline constexpr std::uint32_t MachineDebugMemoryOperandNumber = 1'000'000;
+
+struct MachineDebugValueReference final {
+  std::uint32_t InstructionNumber = 0;
+  std::uint32_t OperandNumber = 0;
+
+  friend constexpr bool operator==(MachineDebugValueReference Left,
+                                   MachineDebugValueReference Right) noexcept = default;
+};
+
+struct MachineDebugValueSubstitution final {
+  MachineDebugValueReference Source;
+  MachineDebugValueReference Destination;
+  SubRegIndex Subregister;
+
+  friend constexpr bool operator==(MachineDebugValueSubstitution Left,
+                                   MachineDebugValueSubstitution Right) noexcept = default;
+};
+
 struct MachineCallSiteArgument final {
   PhysicalRegister Reg;
   std::uint16_t ArgumentNumber = 0;
@@ -95,6 +114,14 @@ public:
 
   [[nodiscard]] Expected<void> addPrefetchTarget(MachinePrefetchTarget Target);
 
+  [[nodiscard]] std::span<const MachineDebugValueSubstitution>
+  debugValueSubstitutions() const noexcept {
+    return DebugValueSubstitutions;
+  }
+
+  [[nodiscard]] Expected<void>
+  addDebugValueSubstitution(MachineDebugValueSubstitution Substitution);
+
   [[nodiscard]] Expected<void> verify() const;
   [[nodiscard]] Expected<MachineFunctionRecords>
   clone(const MachineFunctionCloneContext &CloneContext) const;
@@ -107,6 +134,7 @@ private:
   std::vector<MachineCallSiteInfo> CallSites;
   std::vector<MachineCalledGlobal> CalledGlobals;
   std::vector<MachinePrefetchTarget> PrefetchTargets;
+  std::vector<MachineDebugValueSubstitution> DebugValueSubstitutions;
 };
 
 } // namespace rcc
diff --git a/backend/include/rcc/CodeGen/MachineInstr.h b/backend/include/rcc/CodeGen/MachineInstr.h
index bcae306..78d48cb 100644
--- a/backend/include/rcc/CodeGen/MachineInstr.h
+++ b/backend/include/rcc/CodeGen/MachineInstr.h
@@ -9,6 +9,7 @@
 #include "rcc/Support/Error.h"
 
 #include <cstddef>
+#include <cstdint>
 #include <functional>
 #include <optional>
 #include <span>
@@ -132,6 +133,17 @@ public:
     Origin.reset();
   }
 
+  [[nodiscard]] std::uint32_t debugInstrNumber() const noexcept {
+    return DebugInstrNumber;
+  }
+
+  [[nodiscard]] Expected<void> setDebugInstrNumber(std::uint64_t Number);
+  [[nodiscard]] Expected<std::uint32_t> assignDebugInstrNumber();
+
+  void clearDebugInstrNumber() noexcept {
+    DebugInstrNumber = 0;
+  }
+
 private:
   MachineInstr(MachineFunction &OwnerFunction, Opcode InstructionOpcode,
                MachineInstrStableID StableID);
@@ -153,6 +165,7 @@ private:
   MachineInstrFlags Flags;
   std::optional<SourceLocation> Location;
   std::optional<OriginID> Origin;
+  std::uint32_t DebugInstrNumber = 0;
 
   friend class MachineArena;
   friend class MachineBasicBlock;
-- 
cgit v1.2.3