Mgsc align to RTL (#686)

* pred: add BTBMGSC prediction statistics

- Updated calculatePercsum and calculateScaledPercsum documentation for clarity.
- Enhanced MgscStats to include new statistics for weight scale sensitivity and prediction correctness.

* bpu: test mgsc score

Change-Id: I5992adb066d5c5c75bd16141564ac55264aa7e0a

* bpu: add mgsc dosc

Change-Id: Ieaef1b35cd968cb97679b982eab6db54b0b74b4c

* bpu: update scaling formula in calculateScaledPercsum

- Enhanced the scaling formula in the calculateScaledPercsum function to implement a 4-level granularity for weight adjustments.
- The new scaling logic provides more nuanced control over the importance of percsum based on weight ranges.

Change-Id: I45dda73bec5d79d3521fec3ce7244c8e3c52dcab

* bpu: disable weight table for test

Change-Id: Ib26755301387cbf1ce4b12bb26e988d43a49eea8

* bpu: test force use SC not use tage

Change-Id: I69ef16d0b2d973de03e8ccd381ff359bc640d5f1

* bpu: test no tage, only use SC

Change-Id: Ia279ea56c55b79261163bee4400befe6014e8c12

* Revert "bpu: test no tage, only use SC"

This reverts commit 2cfb00c.

* bpu: align RTL: only enable bias and path, disable pcThreshold

Change-Id: I6ecce2060d5a9dc85312ff87188ee8804a694f2a

* bpu: add mgsc trace

Change-Id: I2b8451ff6ec9abbda07d71a32a942fb116f0abd9

* bpu: mgsc,enable global

global + bias + path

Change-Id: I58b509b2361a76b681a3862bb3d9bcc140d5ac52

* bpu: mgsc,enable IMLI

IMLI + global + bias + path

Change-Id: I5a9c8470901455db75597a3d0aa07204a008a291

* bpu: mgsc,enable backward

backward + IMLI + global + bias + path

Change-Id: I7aabaafa68660f82a75a19e002f0b44376751c79

* bpu: mgsc,enable local

local + backward + IMLI + global + bias + path

Change-Id: I6ec878fc09049b5cab9a840ed7e4b568f39168fd

* bpu: disable sc now, waiting for RTL implementation

Change-Id: I07ece3caa9617ff7c1aa094d00ef9710d476b41e

* bpu: remove duplicated params in kmhv3.py

Change-Id: I102752018085baeae8aaba087b361758e6af2ab4

Author: jensen-yan

docs/Gem5_Docs/frontend/mgsc_notes.md

@@ -0,0 +1,54 @@
+# MGSC 预测器备忘
+
+面向本仓库 BTB 侧的 MGSC（Multi-Geometric Statistical Corrector）总结：设计特点、关键结构、改进思路、统计计数器、以及便于验证的敏感小测试。
+
+## 1. MGSC 设计要点
+- 核心角色：TAGE 做“主判官”，MGSC 做“量化纠错”。MGSC 拿到 TAGE 的预测与置信度后，基于多类独立的历史特征表（几何长度）求和，给出一个带权的分数；只有当分数绝对值高于动态阈值时才覆盖 TAGE，否则保持原判。
+- 特征多样性（降维防冲突）：  
+  - **G** 全局方向历史：捕获长程相关；  
+  - **P** 路径历史：区分同一分支的不同来路；  
+  - **L** 局部（per-PC）历史：解决每个分支的重复模式；  
+  - **BW** 后向历史：强化循环/尾递归偏好；  
+  - **I/IMLI** 迭代计数：对“第 N 次迭代取反”类模式敏感；  
+  - **Bias** 静态偏置：兜底偏好。  
+  这些表使用折叠历史压缩到较短索引位宽，降低端口和存储压力，同时减少与 TAGE 的直接结构耦合。
+- 决策与门控：各表计数器 percsum 做线性求和，并用简化权重（1x/2x 档）缩放，合成 `total_sum`。阈值由全局+PC 两级组成，并根据 TAGE 置信度动态放宽/收紧（高/中/低置信度对应 |sum| > thres/2, /4, /8）。这样在 TAGE 自信时，需要更强证据才覆盖。
+- 自适应更新：仅在 SC 预测错或低置信时更新，避免破坏已稳定的正确判决；权重只在“该表是否关键到翻转决策”时调整；阈值在 SC 与真实冲突时上调，吻合时下调，使覆盖策略自动收敛到合适激进度。
+
+## 2. 关键数据结构（参考 `src/cpu/pred/btb/btb_mgsc.hh/.cc`）
+- `MgscPrediction`：一次预测的完整快照，包含：  
+  - 总分 `total_sum`，是否使用 MGSC (`use_mgsc`)，最终 taken 判定；  
+  - TAGE 原始预测与置信度（高/中/低）；  
+  - 各表索引、raw/scaled percsum、`weight_scale_diff`（权重翻倍/归零是否翻转决策）、组合阈值。  
+  这些字段既驱动训练，也被统计模块消费。
+- 折叠历史：`index{G,P,Bw,L,I}FoldedHist`，把长历史折叠成较短索引用；Bias 索引还混入 TAGE 主预测、低置信标志，形成轻量级“条件偏置”。
+- 预测与权重表：六类计数器矩阵 `bw/l/i/g/p/biasTable[table][index][way]`，存储方向倾向；对应的 `*_WeightTable[index]` 只用 PC hash，提供 1x/2x 缩放权重（-32..31，经简化映射）。
+- 阈值：全局 `updateThreshold`（单计数器）+ PC 表 `pUpdateThreshold`（按 PC hash 的多计数器），共同决定覆盖门槛，随误差自适应。
+- 元数据：`MgscMeta` 在 fetch 时缓存预测与折叠历史，用于后续恢复/回滚，保证推测一致性。
+
+## 3. 新增统计计数器及含义（已合入）
+路径：`system.cpu.branchPred.mgsc.*`
+- SC/TAGE 关系：`scCorrectTageWrong`、`scWrongTageCorrect`、`scCorrectTageCorrect`、`scWrongTageWrong`、`scUsed`、`scNotUsed`、`scPredCorrect/Wrong`、`predHit/Miss`。
+- 权重关键性：`*WeightScaleDiff`（bw/l/i/g/p/bias）——该表权重翻倍/去掉会翻转决策的次数。
+- Raw percsum 符号正确率：`*PercsumCorrect/Wrong` —— 该表自身方向是否与真实一致。
+- 阈值方向：`pcThresholdInc/Dec`、`globalThresholdInc/Dec` —— SC 与真实冲突多则递增，反之递减。
+- 按 TAGE 置信度分桶的 SC 使用/绕过：`scHigh/Mid/LowUseCorrect/Wrong`、`scHigh/Mid/LowBypass`。
+
+解读小贴士：
+- 某表 `WeightScaleDiff` 高且 `PercsumCorrect` 高：表在“起关键作用”。若后者低，则可能误导。
+- `pc/globalThresholdDec` ≫ `Inc`：SC 表现好，门槛在下降；反之说明冲突多。
+- `scCorrectTageWrong` ≫ `scWrongTageCorrect`：SC 对 TAGE 有正纠错价值。
+
+## 4. 改进方向（未实现，仅供参考）
+1) 权重档位更细（0.5/1/1.5/2 等），提升相关性刻画精度。  
+2) 权重表索引加入部分历史哈希（而非仅 PC），降低别名。  
+3) 阈值更新考虑 TAGE 置信度（高置信错时更快抬阈，低置信错时慢抬），减少误覆盖。  
+4) 更丰富的可观测性：按表/置信度输出热分支热点，或导出 per-PC 纠错热度。
+
+## 5. MGSC 敏感小测试（C 版，放在 'nexus-am/tests/frontendtest/mgsc_test/tests/`）
+已提供源码，可按现有 Makefile 通配编译：
+- `long_period_flip.c`：长周期偶发翻转 + 噪声。期望 I/G/P 纠偏远距稀疏翻转。  
+- `xor_dependency.c`：B2 方向 = 上一轮 B0^B1，跨分支相关。期望路径/局部/全局组合纠错。  
+- `alias_many_branches.c`：16 个相邻分支，各有不同小周期，制造索引/标签冲突。期望 MGSC 通过局部/路径缓解别名。
+
+使用建议：开/关 MGSC 对比 `condMiss`、`mgsc.scCorrectTageWrong/scWrongTageCorrect`、各表 `*PercsumWrong` 与阈值增减，定位是哪类表在纠错或噪声。必要时可缩短 TAGE 历史或减小表尺寸以放大差异。 

src/cpu/pred/BranchPredictor.py

@@ -1143,6 +1143,16 @@ class BTBMGSC(TimedBaseBTBPredictor):
     # How many counters readed per prediction (usually per cycle)
     numCtrsPerLine = Param.Unsigned(8, "Counters per SRAM line")
 
+    # Test switches for SC tables
+    forceUseSC = Param.Bool(False, "Force use SC prediction, ignore TAGE confidence")
+    enableBwTable = Param.Bool(True, "Enable BW (backward) table")
+    enableLTable = Param.Bool(True, "Enable L (local) table")
+    enableITable = Param.Bool(True, "Enable I (IMLI) table")
+    enableGTable = Param.Bool(True, "Enable G (global) table")
+    enablePTable = Param.Bool(True, "Enable P (path) table")
+    enableBiasTable = Param.Bool(True, "Enable Bias table")
+    enablePCThreshold = Param.Bool(False, "Enable PC-indexed threshold table")
+
     numDelay = 2
 
 class DecoupledBPUWithBTB(BranchPredictor):