Split utage align

[CJ362ff]

Summary by CodeRabbit

• New Features

  • Adds a full MicroTAGE BTB branch predictor: configurable, bank-aware TAGE-style predictor with folded-history, multi-table indexing, allocation/update flows, unit-test hooks, and extensive telemetry.
  • Expanded MicroTAGE parameter set for fine-grained tuning and runtime control.

• Chores

  • Integrated MicroTAGE into build/init and enabled it in the example configuration.

• Bug Fixes

  • Updated defaults: bank-conflict simulation disabled by default; a uBTB predictor update option now defaults to off.

[coderabbitai]

📝 Walkthrough

Walkthrough

Adds a full MicroTAGE BTB predictor (header + implementation), exposes it to the Python predictor API and build system, updates DecoupledBPUWithBTB to reference MicroTAGE, adjusts BTBTAGE/UBTB defaults, and enables MicroTAGE in the kmhv3 example config.

Changes

Cohort / File(s)	Summary
Configuration configs/example/kmhv3.py	Enable DecoupledBPUWithBTB MicroTAGE by setting cpu.branchPred.microtage.enabled = True.
Python predictor API src/cpu/pred/BranchPredictor.py	Add MicroTAGE Param class with many parameters; change DecoupledBPUWithBTB.microtage to Param.MicroTAGE(...); set BTBTAGE.enableBankConflict default to False; change UBTB.usingS3Pred default to False.
Build & registration src/cpu/pred/SConscript	Register MicroTAGE in branch-predictor type list and add btb/microtage.cc to build sources.
BTB predictor integration (C++) src/cpu/pred/btb/decoupled_bpred.hh	Include microtage.hh; change member microtage type from BTBTAGE * to MicroTAGE *.
MicroTAGE header src/cpu/pred/btb/microtage.hh	New MicroTAGE class declaration: TAGE nested types, public prediction/update/allocation APIs, folded-history/index/tag fields, bank-conflict scaffolding, stats, and UNIT_TEST guards.
MicroTAGE implementation src/cpu/pred/btb/microtage.cc	Add complete MicroTAGE implementation: constructors, prediction/update/allocation flows, folded-history/indexing, bank-aware handling, LRU, stats, tracing, and UNIT_TEST scaffolding.

Sequence Diagram(s)

sequenceDiagram
    rect rgba(200,220,255,0.5)
    participant Fetch as Fetch/BTB
    end
    rect rgba(200,255,200,0.5)
    participant Micro as MicroTAGE
    end
    rect rgba(255,230,200,0.5)
    participant Hist as HistoryMgmt
    end
    rect rgba(255,200,200,0.5)
    participant Tables as TableLookup
    end

    Fetch->>Micro: putPCHistory(startPC, history)
    Micro->>Hist: fold history / snapshot
    Hist-->>Micro: folded histories
    Micro->>Tables: generateSinglePrediction(btb_entry, startPC, folded_hist)
    loop probe tables
        Tables->>Tables: compute index/tag & match
        alt tag match
            Tables-->>Micro: main/alt prediction
        end
    end
    Micro-->>Fetch: return prediction (taken, target, meta)

Loading

sequenceDiagram
    rect rgba(220,220,255,0.5)
    participant Commit as Commit/Resolution
    participant Micro as MicroTAGE
    participant Update as UpdateLogic
    participant Tables as TableUpdate
    end

    Commit->>Micro: update(FetchStream with outcomes)
    Micro->>Micro: canResolveUpdate() (bank/conflict check)
    alt conflict
        Micro-->>Commit: defer update
    else no conflict
        Micro->>Update: doResolveUpdate()
        Update->>Micro: prepareUpdateEntries()
        Micro->>Update: updatePredictorStateAndCheckAllocation()
        alt allocation needed
            Update->>Tables: handleNewEntryAllocation()
        end
        loop per-entry
            Tables->>Tables: update counters/useful bits/LRU
        end
        Update-->>Micro: updates applied
    end

Loading

Estimated code review effort

🎯 5 (Critical) | ⏱️ ~120 minutes

Possibly related PRs

• cpu-o3: update tage index #627 — Shares BTB/TAGE API changes (generateSinglePrediction, lookupHelper, putPCHistory) used by MicroTAGE.
• align RTL: tage window method, block resolveQ if update failed due to bank conflict. #644 — Overlaps bank-conflict handling and two-phase resolve (canResolveUpdate/doResolveUpdate) behavior used by MicroTAGE.
• Tage1 align #615 — Modifies TAGE/BTB parameter surfaces (numBanks, enableBankConflict, tag/index bits) relevant to the new MicroTAGE parameters.

Suggested labels

perf, align-kmhv3

Suggested reviewers

• jensen-yan
• Yakkhini
• tastynoob

Poem

🐇 I hop through folded histories and tags,
Banks and tables bustling like tiny flags,
Counters whisper, indices sing,
MicroTAGE hums — a branching spring,
I nudge a jump and watch code spring.

🚥 Pre-merge checks | ✅ 1 | ❌ 2

❌ Failed checks (1 warning, 1 inconclusive)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 57.14% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.
Title check	❓ Inconclusive	The title 'Split utage align' is vague and does not clearly convey the main changes. The PR primarily introduces a new MicroTAGE class, updates branch predictor configurations, and disables certain predictors, but the title uses generic/unclear terminology that doesn't summarize these changes.	Revise the title to be more descriptive and specific, such as 'Introduce MicroTAGE branch predictor implementation' or 'Replace BTBTAGE with MicroTAGE in DecoupledBPU', to clearly communicate the primary purpose of the changes.

✅ Passed checks (1 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing touches

• 📝 Generate docstrings

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch split-utage-align

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 1

🤖 Fix all issues with AI agents

In `@src/cpu/pred/BranchPredictor.py`:
- Around line 1063-1088: The MicroTAGE class has mismatched parameter counts:
numPredictors is 1 but vector params tableSizes, TTagBitSizes, TTagPcShifts, and
histLengths have 2 elements, which can trigger constructor asserts; fix by
making these consistent—either set numPredictors = 2 to match the two-element
vectors or shrink each VectorParam (tableSizes, TTagBitSizes, TTagPcShifts,
histLengths) to a single-element list to match numPredictors = 1; update the
explanatory comment ("Keep vector parameters...") accordingly so numPredictors
and all vector lengths are always aligned.

🧹 Nitpick comments (5)

src/cpu/pred/btb/microtage.hh (1)

382-390: Consider using struct instead of typedef struct for C++ idiom.

The typedef struct TageMeta { ... } TageMeta; pattern is a C idiom. In C++, struct TageMeta { ... }; is sufficient and more idiomatic.

✨ Suggested refactor

-    typedef struct TageMeta
+    struct TageMeta
     {
         std::unordered_map<Addr, TagePrediction> preds;
         std::vector<PathFoldedHist> tagFoldedHist;
         std::vector<PathFoldedHist> indexFoldedHist;
         std::vector<PathFoldedHist> altTagFoldedHist;
         bitset history;     // for viewing
         TageMeta() {}
-    } TageMeta;
+    };

src/cpu/pred/btb/microtage.cc (4)

95-99: tableTagBits.resize() may overwrite values set from parameters.

On line 70, tableTagBits is initialized from p.TTagBitSizes. Then on line 98, tableTagBits.resize(numPredictors) is called, which could truncate the vector if it had more elements, or extend it with default values (0). This seems intentional as a safety measure, but the comment on line 119 (assert(tableTagBits.size() >= numPredictors)) suggests the expectation is that the params provide enough elements.

Since you want exactly numPredictors entries, consider keeping the resize but document the intent, or remove it if the params are expected to be correctly sized.

---

282-290: Consider documenting the dry run purpose.

The dryRunCycle method sets lastPredBankId and predBankValid but has a comment saying "No operation". The bank tracking is a meaningful operation for conflict detection. Consider updating the comment to reflect the actual purpose.

📝 Suggested documentation update

 void
 MicroTAGE::dryRunCycle(Addr startPC) {
-    // No operation in dry run cycle for MicroTAGE
     // Record prediction bank for next tick's conflict detection
     lastPredBankId = getBankId(startPC);
     predBankValid = true;
-
-    return;
 }

---

520-532: Consider const-correctness for the weakish check.

Minor: The weakish variable could use a more descriptive name like isWeakCounter for clarity.

---

1074-1074: Spacing inconsistency after else.

Minor formatting: The else{ on line 1074 should have a space before the brace for consistency with the rest of the codebase.

✨ Suggested fix

-    }else{
+    } else {

[coderabbitai]

⚠️ Potential issue | 🟠 Major

Parameter count mismatch: numPredictors=1 but vector parameters have 2 elements.

The comment on line 1071 states "Keep vector parameters consistent with numPredictors to avoid constructor asserts", but:

• numPredictors = 1
• tableSizes = [512]*2 (2 elements)
• TTagBitSizes = [16]*2 (2 elements)
• TTagPcShifts = [1]*2 (2 elements)
• histLengths = [9,18] (2 elements)

This inconsistency may cause unexpected behavior. Either increase numPredictors to 2 or reduce the vector sizes to 1 element.

🔧 Suggested fix (Option A: increase numPredictors)

-    numPredictors = Param.Unsigned(1, "Number of TAGE predictors")
-    tableSizes = VectorParam.Unsigned([512]*2,"the TAGE T0~Tn length")
+    numPredictors = Param.Unsigned(2, "Number of TAGE predictors")
+    tableSizes = VectorParam.Unsigned([512]*2,"the TAGE T0~Tn length")

🔧 Suggested fix (Option B: reduce vector sizes)

-    tableSizes = VectorParam.Unsigned([512]*2,"the TAGE T0~Tn length")
-    TTagBitSizes = VectorParam.Unsigned([16]*2 ,"the T0~Tn entry's tag bit size")
-    TTagPcShifts = VectorParam.Unsigned([1]*2 ,"when the T0~Tn entry's tag generating, PC right shift")
+    tableSizes = VectorParam.Unsigned([512],"the TAGE T0~Tn length")
+    TTagBitSizes = VectorParam.Unsigned([16],"the T0~Tn entry's tag bit size")
+    TTagPcShifts = VectorParam.Unsigned([1],"when the T0~Tn entry's tag generating, PC right shift")
     ...
-    histLengths = VectorParam.Unsigned([9,18],"the BTB TAGE T0~Tn history length")
+    histLengths = VectorParam.Unsigned([9],"the BTB TAGE T0~Tn history length")

🧰 Tools

🪛 Ruff (0.14.14)

[error] 1069-1069: Param may be undefined, or defined from star imports

(F405)

---

[error] 1070-1070: Param may be undefined, or defined from star imports

(F405)

---

[error] 1072-1072: Param may be undefined, or defined from star imports

(F405)

---

[error] 1073-1073: VectorParam may be undefined, or defined from star imports

(F405)

---

[error] 1074-1074: VectorParam may be undefined, or defined from star imports

(F405)

---

[error] 1075-1075: VectorParam may be undefined, or defined from star imports

(F405)

---

[error] 1076-1076: Param may be undefined, or defined from star imports

(F405)

---

[error] 1078-1078: VectorParam may be undefined, or defined from star imports

(F405)

---

[error] 1079-1079: Param may be undefined, or defined from star imports

(F405)

---

[error] 1080-1080: Param may be undefined, or defined from star imports

(F405)

---

[error] 1081-1081: Param may be undefined, or defined from star imports

(F405)

---

[error] 1082-1082: Param may be undefined, or defined from star imports

(F405)

---

[error] 1083-1083: Param may be undefined, or defined from star imports

(F405)

---

[error] 1084-1084: Param may be undefined, or defined from star imports

(F405)

---

[error] 1085-1085: Param may be undefined, or defined from star imports

(F405)

---

[error] 1086-1086: Param may be undefined, or defined from star imports

(F405)

---

[error] 1087-1087: Param may be undefined, or defined from star imports

(F405)

---

[error] 1088-1088: Param may be undefined, or defined from star imports

(F405)

🤖 Prompt for AI Agents

In `@src/cpu/pred/BranchPredictor.py` around lines 1063 - 1088, The MicroTAGE
class has mismatched parameter counts: numPredictors is 1 but vector params
tableSizes, TTagBitSizes, TTagPcShifts, and histLengths have 2 elements, which
can trigger constructor asserts; fix by making these consistent—either set
numPredictors = 2 to match the two-element vectors or shrink each VectorParam
(tableSizes, TTagBitSizes, TTagPcShifts, histLengths) to a single-element list
to match numPredictors = 1; update the explanatory comment ("Keep vector
parameters...") accordingly so numPredictors and all vector lengths are always
aligned.

[XiangShanRobot]

[Generated by GEM5 Performance Robot]
commit: 537cda4
workflow: gem5 Align BTB Performance Test(0.3c)

Align BTB Performance

Overall Score

	PR	Master	Diff(%)
Score	17.71	17.55	+0.92 🟢

[Generated by GEM5 Performance Robot]
commit: 537cda4
workflow: gem5 Align BTB Performance Test(0.3c)

Align BTB Performance

Overall Score

	PR	Previous Commit	Diff(%)
Score	17.71	17.62	+0.49 🟢

[XiangShanRobot]

[Generated by GEM5 Performance Robot]
commit: fd4c0ea
workflow: gem5 Align BTB Performance Test(0.3c)

Align BTB Performance

Overall Score

	PR	Master	Diff(%)
Score	17.80	17.55	+1.43 🟢

[Generated by GEM5 Performance Robot]
commit: fd4c0ea
workflow: gem5 Align BTB Performance Test(0.3c)

Align BTB Performance

Overall Score

	PR	Previous Commit	Diff(%)
Score	17.80	17.83	-0.16 🔴