util: update README and docs[skip ci]

README.md

@@ -1,6 +1,15 @@
 # About
 
-This is the gem5 simulator for Xiangshan (XS-GEM5), which currently scores similar with Kunminghu on SPEC CPU 2006.
+XS-GEM5 is a gem5-based, full-system RISC-V simulator for XiangShan.
+
+XS-GEM5 is the ONLY open-source RISC-V simulator strictly calibrated against high-performance RTL (XiangShan Nanhu/Kunminghu), achieving >95% correlation on SPECCPU 2006.
+
+In our current SPECCPU06 checkpoint evaluation:
+- `idealkmhv3.py` exceeds 20 points/GHz, making XS-GEM5 one of the highest-performance open-source simulators.
+- `kmhv3.py`, the RTL-aligned configuration, exceeds 15 points/GHz.
+- We are co-developing with the XiangShan RTL team to push Kunminghu-v3 RTL towards 20 points/GHz as soon as possible.
+
+XS-GEM5 diverged from [upstream gem5](https://github.com/gem5/gem5) in June 2022. Since XS-GEM5 focuses on cycle-accurate alignment with the XiangShan RTL, it is often difficult to upstream changes directly. We will keep actively merging new features from upstream gem5, and we also aim to contribute XS-GEM5 features back to upstream when possible. Contributions and collaboration from developers are welcome.
 
 Our Chinese website is [here](https://xs-gem5.readthedocs.io/zh-cn/latest/), welcome to visit!
 
@@ -236,7 +245,7 @@ Press enter to continue, or ctrl-c to abort:
 
 Users must properly prepare workloads before running GEM5, plz read [Workflows](#workflows-how-to-run-workloads) first.
 
-[The example running script](util/xs_scripts/kmh_6wide.sh) contains the default command for simulate XS-GEM5.
+[The example running script](util/xs_scripts/kmh_v3_btb.sh) contains the default command for simulate XS-GEM5 (Kunminghu V3).
 [The example batch running script](util/xs_scripts/parallel_sim.sh) shows an example to simulate multiple workloads in parallel.
 
 ### Environment variables
@@ -273,7 +282,7 @@ If above branches are not working, you can try the following commits:
 
 **NOTE**:
 - Current scripts enforce Difftest (cosimulating against NEMU or spike).
-If a user does not want Difftest, please manually edit `configs/example/xiangshan.py` and `configs/common/XSConfig.py` to disable it.
+If a user does not want Difftest, please manually edit `configs/common/xiangshan.py` (see `xiangshan_system_init()`) to disable it.
 Simulation error without Difftest **will NOT be responded.**
 - When running a GCB checkpoint, it is OK to use GCBV reference design but not vice versa.
 - When running a GCB checkpoint, user must use GCB restorer but not GCBV restorer.
@@ -291,11 +300,12 @@ wget https://github.com/OpenXiangShan/GEM5/releases/download/2024-10-16/riscv64-
 # set environment variables
 export GCBV_REF_SO=`realpath riscv64-nemu-interpreter-c1469286ca32-so`
 # run the workload
-./build/RISCV/gem5.opt ./configs/example/xiangshan.py --raw-cpt --generic-rv-cpt=./ready-to-run/coremark-2-iteration.bin
+./build/RISCV/gem5.opt ./configs/example/kmhv3.py --raw-cpt --generic-rv-cpt=./ready-to-run/coremark-2-iteration.bin
 # get the ipc
 grep 'cpu.ipc' m5out/stats.txt
 ```
-xiangshan.py is the default configuration for XS-GEM5.
+kmhv3.py is the recommended configuration for XS-GEM5.
+If you still run a legacy entrypoint named `xiangshan.py`, `configs/common/xiangshan.py` will emit a deprecation warning.
 
 raw-cpt means the input is a single binary file.
 
@@ -307,16 +317,16 @@ Otherwise, if you want to run a checkpoint, you should ensure GEM5 is properly b
 ``` shel
 mkdir util/xs_scripts/example
 cd util/xs_scripts/example
-bash ../kmh_6wide.sh /path/to/a/single/checkpoint.gz
+bash ../kmh_v3_btb.sh /path/to/a/single/checkpoint.gz
 ```
 
 Then, for running multiple workloads in parallel, one can use the batch running script:
 ``` shel
 mkdir util/xs_scripts/example
 cd util/xs_scripts/example
-bash ../parallel_sim.sh `realpath ../kmh_6wide.sh` $workloads_lst /top/dir/of/checkpoints a_fancy_simulation_tag
+bash ../parallel_sim.sh `realpath ../kmh_v3_btb.sh` $workloads_lst /top/dir/of/checkpoints a_fancy_simulation_tag
 ```
-In this example, parallel_sim.sh will invoke kmh_6wide.sh with GNU parallel to run multiple workloads.
+In this example, parallel_sim.sh will invoke kmh_v3_btb.sh with GNU parallel to run multiple workloads.
 Through this, parallel simulation infrastructure is decouple from the simulation script.
 
 #### run xs-gem5 in docker
@@ -329,7 +339,7 @@ A line of `workload_lst` is a space-separated list of workload parameters.
 For example, "hmmer_nph3_15858 hmmer_nph3/15858 0 0 20 20" represents the workload name, checkpoint path, skip insts (usually 0), functional warmup insts (usually 0),
 detailed warmup insts (usually 20), and sample insts (usually 20), respectively.
 `parallel_sim.sh` will `find hmmer_nph3/15858/*.gz` in the /top/dir/of/checkpoints to obtain the checkpoint gz file.
-Then the gz file will be passed to `kmh_6wide.sh` to run the simulation.
+Then the gz file will be passed to `kmh_v3_btb.sh` to run the simulation.
 
 
 More details can be found in comments and code of the example running scripts.

configs/common/xiangshan.py

@@ -61,6 +61,34 @@ class XiangshanECore2Read(XiangshanCore):
 
 addToPath('../')
 
+_warned_deprecated_entrypoint = False
+
+
+def _warn_if_deprecated_xiangshan_entrypoint():
+    """
+    Defensive UX: historically some docs/scripts used `configs/example/xiangshan.py`.
+
+    We no longer keep that entrypoint in this repo. If users still run a legacy
+    config script named `xiangshan.py`, emit a warning and point them to the
+    maintained entrypoints.
+    """
+    global _warned_deprecated_entrypoint
+    if _warned_deprecated_entrypoint:
+        return
+
+    # In gem5, sys.argv[0] is typically the config script path.
+    argv0 = os.path.basename(sys.argv[0]) if sys.argv else ""
+    argv_joined = " ".join(sys.argv) if sys.argv else ""
+
+    if argv0 == "xiangshan.py" or "configs/example/xiangshan.py" in argv_joined:
+        warn(
+            "Deprecated config entrypoint detected (xiangshan.py). "
+            "Please use configs/example/kmhv3.py (RTL-aligned) or "
+            "configs/example/idealkmhv3.py (ideal/perf)."
+        )
+        _warned_deprecated_entrypoint = True
+
+
 def _trace_timing_ptw_settings(args: argparse.Namespace):
     enabled = bool(getattr(args, 'trace_timing_ptw', False))
     if not enabled:
@@ -671,6 +699,7 @@ def build_xiangshan_system(args):
 
 
 def xiangshan_system_init():
+    _warn_if_deprecated_xiangshan_entrypoint()
     # Add args
     parser = argparse.ArgumentParser()
     Options.addCommonOptions(parser, configure_xiangshan=True)

docs/Gem5_Docs/frontend/AI_unitTest.md

@@ -173,7 +173,7 @@ memcpy(dec_ptr->moreBytesPtr(), fetchBuffer[tid] + blk_offset * instSize, instSi
 
 每次回答前，先阅读以下内容：
 
-1. 阅读configs/example/xiangshan.py 文件，了解XiangShan 开源处理器的基本配置
+1. 阅读configs/example/kmhv3.py 文件，了解当前推荐的昆明湖V3（KmhV3）配置入口（以及其如何复用 common/xiangshan.py 的系统搭建逻辑）
 2. 阅读README.cn.md 文件，了解项目的基本信息
 3. 阅读src/cpu/pred/README.md 文件，了解分支预测器的基本信息
 
@@ -184,4 +184,3 @@ memcpy(dec_ptr->moreBytesPtr(), fetchBuffer[tid] + blk_offset * instSize, instSi
 请在回答中，使用中文，但是凡是涉及到代码的地方，请使用英文，生成代码给出合适的英文注释
 生成commit message 时，使用英文！
 ```
-

docs/Gem5_Docs/frontend/fetch_frontend_analysis.md

@@ -215,7 +215,8 @@ stateDiagram-v2
   - Fetch、FetchVerbose、DecoupleBP、DecoupleBPProbe、FTB、LoopPredictor
   - 示例：`--debug-flags=Fetch,DecoupleBP --debug-file=fetch.trace`
 - 快速运行（香山配置）：
-  - `./build/RISCV/gem5.opt ./configs/example/xiangshan.py --raw-cpt --generic-rv-cpt=<path> [--ideal-kmhv3 --bp-type=DecoupledBPUWithBTB]`
+  - `./build/RISCV/gem5.opt ./configs/example/kmhv3.py --raw-cpt --generic-rv-cpt=<path> [--bp-type=DecoupledBPUWithBTB]`
+  - 理想化模型：将配置脚本替换为 `./configs/example/idealkmhv3.py`（也可用 `util/xs_scripts/kmh_v3_ideal.sh`）
 - 系统测试：
   - `cd tests && ./main.py run --length quick --variant opt --isa RISCV`
 - 重构/性能对比：
@@ -238,4 +239,3 @@ stateDiagram-v2
 ——
 
 如需我进一步将文档保持与代码演进同步、或顺手提交一个小 PR 修正“未匹配回包未释放内存”和“usedUpFetchTargets per-thread 化”的问题，可继续告知。
-

docs/Gem5_Docs/frontend/ftb_test.md

@@ -97,7 +97,7 @@ t2的变化：0,1,2,3,4,5,6,7...
 首先看CommitTrace 查看小测试执行情况是否如预期， 这表示程序最终commit 顺序
 
 ```cpp
-./build/RISCV/gem5.debug  --outdir=debug/tage1 --debug-flags=CommitTrace --debug-file=tage1.commit ./configs/example/xiangshan.py --generic-rv-cpt=/nfs/home/yanyue/tools/nexus-am-xs/tests/cputest/build/tage1-riscv64-xs.bin --raw-cpt
+./build/RISCV/gem5.debug  --outdir=debug/tage1 --debug-flags=CommitTrace --debug-file=tage1.commit ./configs/example/kmhv3.py --generic-rv-cpt=/nfs/home/yanyue/tools/nexus-am-xs/tests/cputest/build/tage1-riscv64-xs.bin --raw-cpt
 ```
 
 ```cpp
@@ -152,7 +152,7 @@ system.cpu.branchPred.ftb.updateHit              6485                       # hi
 最后可以看看 各类debug-flags=DecoupleBP,FTB
 
 ```bash
-./build/RISCV/gem5.debug  --outdir=debug/tage1 --debug-flags=DecoupleBP,FTB --debug-file=tage1.bp2 --debug-end=1000000 ./configs/example/xiangshan.py --generic-rv-cpt=/nfs/home/yanyue/tools/nexus-am-xs/tests/cputest/build/tage1-riscv64-xs.bin --raw-cpt
+./build/RISCV/gem5.debug  --outdir=debug/tage1 --debug-flags=DecoupleBP,FTB --debug-file=tage1.bp2 --debug-end=1000000 ./configs/example/kmhv3.py --generic-rv-cpt=/nfs/home/yanyue/tools/nexus-am-xs/tests/cputest/build/tage1-riscv64-xs.bin --raw-cpt
 ```
 
 输出文件位置在/nfs/home/yanyue/workspace/GEM5/debug/tage1/tage1.bp2 
@@ -230,4 +230,3 @@ ftb=  0x8000013a  FTB entry: valid 1, tag 0, fallThruAddr:0x8000015a, slots:
         pc:0x8000013e, size:4, target:0x80000144, cond:1, indirect:0, call:0, return:0
 
 会生成并使用一个新的ftb entry, 同时产生新的ftq, fsq 项！
-

docs/Gem5_Docs/frontend/tage_test.md

@@ -103,7 +103,7 @@ system.cpu.branchPred.tage.bank_0.updateUseAltWrong            7
 关注debug-flags=FTBTAGE
 
 ```plain
-./build/RISCV/gem5.debug  --outdir=debug/tage2 --debug-flags=FTBTAGE --debug-file=tage2.tage --debug-end=1000000 ./configs/example/xiangshan.py --generic-rv-cpt=/nfs/home/yanyue/tools/nexus-am-xs/tests/cputest/build/tage2-riscv64-xs.bin --raw-cpt
+./build/RISCV/gem5.debug  --outdir=debug/tage2 --debug-flags=FTBTAGE --debug-file=tage2.tage --debug-end=1000000 ./configs/example/kmhv3.py --generic-rv-cpt=/nfs/home/yanyue/tools/nexus-am-xs/tests/cputest/build/tage2-riscv64-xs.bin --raw-cpt
 ```
 
 先看预测阶段
@@ -220,4 +220,3 @@ system.cpu.branchPred.tage.bank_0.updateUseAltWrong            7
 能看出对于T0, 他在预测时后，indexFoldedHist 变化过255->247->255
 
 本质原因是全局历史从8个1，变成011, 又变回8个1了，不同的全局历史产生不同的index 索引，进而影响到不同表项。对于低级表，其历史只会关注全局历史低部分位，关注历史长度有限。
-

docs/NEMU + XS-GEM5 使用流程.md → docs/Gem5_Docs/top/NEMU_XS-GEM5_usage.md

@@ -684,7 +684,7 @@ scons build/RISCV/gem5.opt --gold-linker -j$(nproc)
 
 ```bash
 cd $gem5_home
-./build/RISCV/gem5.opt ./configs/example/xiangshan.py --generic-rv-cpt=/path/to/a/single/checkpoint.gz
+./build/RISCV/gem5.opt ./configs/example/kmhv3.py --generic-rv-cpt=/path/to/a/single/checkpoint.gz
 ```
 
 ​	即可成功运行该切片`checkpoint.gz`，同时需要注意的是，存在`checkpoint.zstd`的切片，XS-GEM5均兼容，具体产生的类型取决于3节中的`--checkpoint-format`选项，如果想要了解具体有什么类型的参数，可以查阅https://github.com/OpenXiangShan/GEM5/blob/xs-dev/configs/common/Options.py，特别需要注意的是`--maxinsts`选项，当XS-GEM5运行到其所指定的指令数后就会停止，可以指定其为 0 从而避免停止。

docs/Gem5_Docs/top/gem5_Top.md

@@ -124,10 +124,10 @@ class KunminghuScheduler(Scheduler):
 
 ### 参数传递
 ```python
-./build/RISCV/gem5.opt configs/example/xiangshan.py --generic-rv-cpt /nfs/share/zyy/spec06_rv64gcb_O3_20m_gcc12.2.0-intFpcOff-jeMalloc/zstd-checkpoint-0-0-0/libquantum/98457/_98457_0.048839_.zstd
+./build/RISCV/gem5.opt configs/example/kmhv3.py --generic-rv-cpt /nfs/share/zyy/spec06_rv64gcb_O3_20m_gcc12.2.0-intFpcOff-jeMalloc/zstd-checkpoint-0-0-0/libquantum/98457/_98457_0.048839_.zstd
 ```
 
-xiangshan.py 接受--generic-rv-cpt
+kmhv3.py 接受 --generic-rv-cpt
 
 ```python
 # Add args
@@ -152,4 +152,3 @@ test_sys = build_test_system(args.num_cpus)
 scons build/RISCV/gem5.opt --gold-linker -j100
 
 
-

docs/Gem5_Docs/top/gem5_learn.md

@@ -54,7 +54,7 @@ python3 simpoint_cpt/compute_weighted.py \
 
 [Python 与 C++ 交互 --- Python Interaction with C++ (narkive.com)](https://gem5-users.gem5.narkive.com/TyNxYz3Z/python-interaction-with-c)
 
-python 主要配置系统，把每个SimObject 的参数设置好，用xiangshan.py来配置
+python 主要配置系统，把每个SimObject 的参数设置好，通常用 kmhv3.py（或历史入口 xiangshan.py）来配置
 
 然后对每个SimObject 依次调用m5.instantiate() 来调用C++对象的构造函数
 
@@ -162,4 +162,3 @@ void Rename::renameInsts(ThreadID tid)
 OpDesc 描述操作类延迟
 FUDesc 
 ```
-

docs/Gem5_Docs/top/gem5_tutorial.md

@@ -31,12 +31,12 @@ export GCBV_REF_SO="/nfs/home/share/gem5_ci/ref/normal/riscv64-nemu-interpreter-
 # 设置 GCB_RESTORE 为空
 export GCB_RESTORER=""
 # 跑一个 bin (非 ckpt)
-./build/RISCV/gem5.opt configs/example/xiangshan.py --generic-rv-cpt /nfs/home/share/gem5_ci/checkpoints/coremark-riscv64-xs.bin --raw-cpt
+./build/RISCV/gem5.opt configs/example/kmhv3.py --generic-rv-cpt /nfs/home/share/gem5_ci/checkpoints/coremark-riscv64-xs.bin --raw-cpt
 # 跑一个 ckpt
-./build/RISCV/gem5.opt configs/example/xiangshan.py --generic-rv-cpt /nfs/home/share/jiaxiaoyu/simpoint_checkpoint_archive/spec06_rv64gcb_O3_20m_gcc12.2.0-intFpcOff-jeMalloc/zstd-checkpoint-0-0-0/lbm/12578/_12578_0.231430_.zstd
-# log 和性能计数器在 m5out/ 下，可以指定./build/RISCV/gem5.opt --outdir=xxx configs/example/xiangshan.py 来更换
-# 加上 --ideal-kmhv3 参数来使用理想化设置的模型运行
-./build/RISCV/gem5.opt configs/example/xiangshan.py --ideal-kmhv3 --generic-rv-cpt /nfs/home/share/gem5_ci/checkpoints/coremark-riscv64-xs.bin --raw-cpt
+./build/RISCV/gem5.opt configs/example/kmhv3.py --generic-rv-cpt /nfs/home/share/jiaxiaoyu/simpoint_checkpoint_archive/spec06_rv64gcb_O3_20m_gcc12.2.0-intFpcOff-jeMalloc/zstd-checkpoint-0-0-0/lbm/12578/_12578_0.231430_.zstd
+# log 和性能计数器在 m5out/ 下，可以指定./build/RISCV/gem5.opt --outdir=xxx configs/example/kmhv3.py 来更换
+# 理想化设置的模型：使用 idealkmhv3.py（而不是传 --ideal-kmhv3）
+./build/RISCV/gem5.opt configs/example/idealkmhv3.py --generic-rv-cpt /nfs/home/share/gem5_ci/checkpoints/coremark-riscv64-xs.bin --raw-cpt
 ```
 
 ```shell
@@ -50,7 +50,7 @@ export GEM5_HOME=$(pwd)
 mkdir -p $GEM5_HOME/util/xs_scripts/test
 cd $GEM5_HOME/util/xs_scripts/test
 # 批量跑 ckpt
-bash ../parallel_sim.sh `realpath ../kmh_6wide.sh` \
+bash ../parallel_sim.sh `realpath ../kmh_v3_btb.sh` \
       /nfs/home/share/gem5_ci/spec06_cpts/spec_0.8c_int.lst \ # 跑 ckpt 的 list，类似于 json
       $CHECKPOINT_ROOT \
       spec_all # 输出的 log 所在文件夹名
@@ -106,8 +106,8 @@ bash example-scripts/gem5-score-ci.sh \
           // "--debug-start=569430",
           "--debug-flags=LSQ,LSQUnit",
           //   "--debug-file=debug.log",
-          "${workspaceFolder}/configs/example/xiangshan.py",
-          //   "--ideal-kmhv3",
+          "${workspaceFolder}/configs/example/kmhv3.py",
+          // 若需要理想化模型：将上一行脚本替换为 "${workspaceFolder}/configs/example/idealkmhv3.py"
           "--raw-cpt",
           //   "--generic-rv-cpt=/nfs/home/yanyue/tools/nexus-am-xs/tests/cputest/build/dummy-riscv64-xs.bin",
           "--generic-rv-cpt=/nfs/home/share/gem5_ci/checkpoints/coremark-riscv64-xs.bin",
@@ -433,4 +433,3 @@ DcachePort::recvTimingResp()->LSQRequest::recvTimingResp()
       ->IEW::instToCommit()
 IEW::tick()->IEW::writebackInsts()
 ```
-