cpu-o3: add fine-grained branch type stats to BPU

[jensen-yan]

Implement fine-grained RISC-V branch classification stats in the decoupled BPU so we can track per-class resolve squashes and commit mispredictions (e.g., cond, direct/indirect call, return, direct/indirect jump) via DBPBTBStats.

Change-Id: Ie0b99fa76844505dc8688b99b5760fa48a15d8c9

Summary by CodeRabbit

• New Features
  • Enhanced branch prediction statistics with fine-grained classification by branch type (conditional, calls, returns, jumps).
  • Added per-class tracking of branch prediction accuracy and control flow squash events for improved performance visibility and diagnostics.

_{✏️ Tip: You can customize this high-level summary in your review settings.}

[coderabbitai]

Walkthrough

Introduces branch classification capabilities to DecoupledBPUWithBTB, adding a BranchClass enum with eight classification types and per-class statistics collection infrastructure. Instruments commit and squash paths to track branch-specific metrics including counts, misses, and control squashes.

Changes

Cohort / File(s)	Summary
Header declarations src/cpu/pred/btb/decoupled_bpred.hh	Added BranchClass enum with eight classification types (CondBranch, DirectCall, IndirectCall, Return, DirectJump, IndirectJump, Unknown, NumClasses). Added public methods: classifyBranch(DynInstPtr/StaticInstPtr), branchClassName(), addBranchClassStat(), addControlSquashCommitStat(). Added member vectors for per-class statistics: branchClassCounts, branchClassMisses, controlSquashByClass. Extended DBPBTBStats with corresponding statistics fields.
Implementation logic src/cpu/pred/btb/decoupled_bpred.cc	Implemented branch classification framework within anonymous namespace using classifyBranchImpl template. Added per-class statistics aggregation helpers with bounds checking. Instrumented commitBranch to record branch class and update per-class stats. Instrumented controlSquash to increment per-class squash counters. Initialized per-class counter names from BranchClassLabels.

Sequence Diagram

sequenceDiagram
    participant Commit as Commit Path
    participant Classify as Branch Classification
    participant Stats as Per-Class Stats
    participant Squash as Squash Path

    Commit->>Classify: classifyBranch(DynInstPtr)
    Classify-->>Commit: BranchClass
    Commit->>Stats: addBranchClassStat(class, mispred)
    Stats->>Stats: Update branchClassCounts,<br/>branchClassMisses

    Squash->>Classify: classifyBranch(DynInstPtr)
    Classify-->>Squash: BranchClass
    Squash->>Stats: addControlSquashCommitStat(class)
    Stats->>Stats: Update controlSquashByClass

Loading

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

• Classification logic: Review the classifyBranchImpl template and enum mapping to ensure correct branch type identification across DynInstPtr and StaticInstPtr
• Statistics integration: Verify proper bounds checking in addBranchClassStat and addControlSquashCommitStat, and confirm counter initialization with correct labels
• Instrumentation points: Audit commitBranch and controlSquash methods to ensure per-class stat collection doesn't introduce logic errors or double-counting
• Member variable initialization: Check that all three new statistics vectors are properly initialized in constructors and seeded with metadata

Poem

🐰 Branches now wear labels so fine,
By type and by class they align,
When squash or commit does appear,
Stats gather their fates crystal clear,
Classification counts every line! 🌿

Pre-merge checks and finishing touches

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 14.29% which is insufficient. The required threshold is 80.00%.	You can run @coderabbitai generate docstrings to improve docstring coverage.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The pull request title accurately describes the main change: adding fine-grained branch type statistics to the BPU with per-class tracking.

✨ 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 add-bpu-stats

Tip

📝 Customizable high-level summaries are now available in beta!

You can now customize how CodeRabbit generates the high-level summary in your pull requests — including its content, structure, tone, and formatting.

• Provide your own instructions using the high_level_summary_instructions setting.
• Format the summary however you like (bullet lists, tables, multi-section layouts, contributor stats, etc.).
• Use high_level_summary_in_walkthrough to move the summary from the description to the walkthrough section.

Example instruction:

"Divide the high-level summary into five sections:

1. 📝 Description — Summarize the main change in 50–60 words, explaining what was done.
2. 📓 References — List relevant issues, discussions, documentation, or related PRs.
3. 📦 Dependencies & Requirements — Mention any new/updated dependencies, environment variable changes, or configuration updates.
4. 📊 Contributor Summary — Include a Markdown table showing contributions:
   | Contributor | Lines Added | Lines Removed | Files Changed |
5. ✔️ Additional Notes — Add any extra reviewer context.
   Keep each section concise (under 200 words) and use bullet or numbered lists for clarity."

Note: This feature is currently in beta for Pro-tier users, and pricing will be announced later.

---

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

[coderabbitai]

Actionable comments posted: 2

📜 Review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 756a401 and bbd2e6e.

📒 Files selected for processing (2)

• src/cpu/pred/btb/decoupled_bpred.cc (7 hunks)
• src/cpu/pred/btb/decoupled_bpred.hh (4 hunks)

🧰 Additional context used

🧬 Code graph analysis (1)

src/cpu/pred/btb/decoupled_bpred.cc (1)

src/cpu/pred/btb/decoupled_bpred.hh (3)

• cls (884-884)
• cls (885-885)
• cls (886-886)

⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (1)

• GitHub Check: Quick Build, Unit Tests & Smoke Test

🔇 Additional comments (10)

src/cpu/pred/btb/decoupled_bpred.hh (3)

838-854: Well-structured branch classification enum.

The enum design is clean with a NumClasses sentinel for sizing stat containers. The uint8_t underlying type is appropriate for the small number of values.

---

313-316: Statistics vector declarations look correct.

The per-class statistics vectors align with the classification framework and will provide granular misprediction tracking.

---

882-886: Good API surface for branch classification.

The method signatures provide a complete interface: classification from both DynInstPtr and StaticInstPtr, name lookup, and stat accumulation helpers.

src/cpu/pred/btb/decoupled_bpred.cc (7)

496-528: Classification logic is well-ordered.

The priority order (Return → Call → CondCtrl → IndirectCtrl → DirectCtrl) correctly handles the RISC-V control flow taxonomy. Returns are checked first since they're technically indirect, and conditional branches take precedence over indirect jumps.

---

1025-1031: Clean integration of per-class squash tracking.

The classification and stat update are correctly scoped to commit-path squashes only (fromCommit == true).

---

1418-1428: Clean delegation to template implementation.

The two overloads correctly delegate to the common template, avoiding code duplication.

---

1430-1438: Bounds check present but incomplete for current array state.

The bounds check idx < BranchClassLabels.size() passes for idx = 7, but BranchClassLabels[7] is currently nullptr. After fixing the array initialization (adding the 8th element), this function will work correctly.

---

1440-1457: Proper bounds checking before stat updates.

The guard idx >= NumBranchClasses prevents out-of-bounds access to the statistics vectors. The debug logging provides useful traceability.

---

1459-1473: Consistent pattern with addBranchClassStat.

Follows the same defensive bounds-checking pattern. Good consistency.

---

1491-1492: Fine-grained classification complements existing CFI tracking.

The new per-class stats augment the existing coarse addCfi() tracking (COND/UNCOND/RETURN/OTHER) with more specific categories.

[github-actions]

🚀 Coremark Smoke Test Results

Branch	IPC	Change
Base (xs-dev)	1.9489	-
This PR	1.9489	➡️ 0.0000 (0.00%)

✅ Difftest smoke test passed!