cpu-o3: Refactor numWays to support per-table configuration

[CJ362ff]

Summary by CodeRabbit

• Refactor
  • Enhanced BTB TAGE predictor configuration to support per-table associativity (ways) specification instead of global settings, enabling more granular table customization.
  • Expanded predictor statistics to track prediction sources, distinguishing between base predictor and individual TAGE table contributions for improved diagnostic insights.

[coderabbitai]

📝 Walkthrough

Walkthrough

The BTBTAGE branch predictor is refactored to support per-table numbers of ways instead of a global value, and enhanced with final provider tracking to record whether predictions originate from the base predictor or specific TAGE tables. Configuration parameters are made explicit in Python declarations.

Changes

Cohort / File(s)	Summary
Configuration Parameters src/cpu/pred/BranchPredictor.py	Changed BTBTAGE configuration from compact list notation to explicit eight-element vectors for tableSizes (e.g., [2048]*8 → [2048, 2048, ...]) and numWays (scalar Unsigned(2) → vector [2]*8), altering the declaration from single per-set width to per-table width specification.
Header Definition src/cpu/pred/btb/btb_tage.hh	Extended TagePrediction struct with finalProviderTable and finalProviderIsAlt fields to track prediction sources. Changed numWays from scalar to std::vector<unsigned>. Added new statistics fields (predFinalSourceBase, updateFinalSourceBase{Correct,Wrong}, and per-table vectors predFinalSourceTable, updateFinalSourceTable{Correct,Wrong}). Added getNumWays(unsigned table) helper method.
Implementation Logic src/cpu/pred/btb/btb_tage.cc	Updated constructor to accept numWaysPerTable and resize numWays as a vector. Modified table allocation and access patterns to use per-table ways via getNumWays(i). Extended prediction path to track final source provider (table index or base) and populate final_provider_table and final_provider_is_alt in predictions. Enhanced statistics tracking with final-source metrics and corresponding per-table breakdowns.
Test Updates src/cpu/pred/btb/test/btb_tage.test.cc	Updated test iterations over ways from fixed bounds to dynamic per-table queries using getNumWays(t), allowing tests to adapt to variable ways per table while preserving test logic and assertions.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~30 minutes

Possibly related PRs

• Microtage merage  #775: Both PRs modify TAGE-style BTB predictor to use per-table numWays and extend predictor metadata tracking for final-source information across BTBTAGE implementations.
• bpu,configs: Add optional BTBTAGE upper-bound mode for kmhv3 #770: Both PRs modify BTBTAGE predictor implementation and its Python SimObject configuration across multiple files in the same subsystem.
• cpu-o3: update tage index #627: Both PRs modify TAGE index/tag computation logic in BTBTAGE predictor implementation.

Suggested labels

perf, align-kmhv3

Suggested reviewers

• jensen-yan

Poem

🐰 A TAGE predictor hops with glee,
Per-table ways, now wild and free!
Final sources tracked with care,
Statistics blooming everywhere! 🎲✨

🚥 Pre-merge checks | ✅ 2 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 72.22% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title 'cpu-o3: Refactor numWays to support per-table configuration' accurately describes the main change: converting the numWays representation from a single scalar value to a per-table vector across multiple files in the BTBTAGE branch predictor implementation.

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

✨ Finishing Touches

• 📝 Generate docstrings (stacked PR)
• 📝 Generate docstrings (commit on current branch)

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch tage-table-tuning-align

📝 Coding Plan

• Generate coding plan for human review comments

---

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.}

Tip

CodeRabbit can use TruffleHog to scan for secrets in your code with verification capabilities.

Add a TruffleHog config file (e.g. trufflehog-config.yml, trufflehog.yml) to your project to customize detectors and scanning behavior. The tool runs only when a config file is present.

[coderabbitai]

🧹 Nitpick comments (2)

src/cpu/pred/BranchPredictor.py (2)

1047-1050: Minor formatting inconsistency in list literals.

Line 1048 has 2048,2048] missing a space before the last element, while other list literals in this file use consistent spacing.

🧹 Suggested formatting fix

     tableSizes = VectorParam.Unsigned(
-        [2048, 2048, 2048, 2048, 2048, 2048, 2048,2048],
+        [2048, 2048, 2048, 2048, 2048, 2048, 2048, 2048],
         "the TAGE T0~Tn length")

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@src/cpu/pred/BranchPredictor.py` around lines 1047 - 1050, The list literal
for tableSizes has a minor spacing inconsistency; update the
VectorParam.Unsigned call that defines tableSizes so the last two elements are
separated with a space (change "...,2048]" to "..., 2048]") to match the file's
list formatting style; verify the related VectorParam.Unsigned for TTagBitSizes
remains unchanged and consistent.

---

1054-1056: Same formatting inconsistency in histLengths.

Line 1055 has 211,397] missing a space before the last element.

🧹 Suggested formatting fix

     histLengths = VectorParam.Unsigned(
-        [4, 9, 17, 29, 56, 109, 211,397],
+        [4, 9, 17, 29, 56, 109, 211, 397],
         "the BTB TAGE T0~Tn history length")

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@src/cpu/pred/BranchPredictor.py` around lines 1054 - 1056, The histLengths
VectorParam.Unsigned list in BranchPredictor.py contains a formatting
inconsistency ("211,397") — update the histLengths definition (the
VectorParam.Unsigned call) so there is a space after the comma between 211 and
397 (i.e., "211, 397") to match the surrounding formatting.

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Nitpick comments:
In `@src/cpu/pred/BranchPredictor.py`:
- Around line 1047-1050: The list literal for tableSizes has a minor spacing
inconsistency; update the VectorParam.Unsigned call that defines tableSizes so
the last two elements are separated with a space (change "...,2048]" to "...,
2048]") to match the file's list formatting style; verify the related
VectorParam.Unsigned for TTagBitSizes remains unchanged and consistent.
- Around line 1054-1056: The histLengths VectorParam.Unsigned list in
BranchPredictor.py contains a formatting inconsistency ("211,397") — update the
histLengths definition (the VectorParam.Unsigned call) so there is a space after
the comma between 211 and 397 (i.e., "211, 397") to match the surrounding
formatting.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 20cc153f-4d0a-43c3-a800-425d32be70f6

📥 Commits

Reviewing files that changed from the base of the PR and between 6cc70c4 and 1299406.

📒 Files selected for processing (4)

• src/cpu/pred/BranchPredictor.py
• src/cpu/pred/btb/btb_tage.cc
• src/cpu/pred/btb/btb_tage.hh
• src/cpu/pred/btb/test/btb_tage.test.cc

[XiangShanRobot]

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

Align BTB Performance

Overall Score

	PR	Master	Diff(%)
Score	18.27	18.26	+0.03 🟢

[XiangShanRobot]

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

Align BTB Performance

Overall Score

	PR	Master	Diff(%)
Score	18.27	18.26	+0.03 🟢