openxiangshan/xiangshanlab/analyze-xiangshan-kunminghu

Analyze XiangShan Kunminghu

Objective

Use this skill to produce code-grounded explanations of XiangShan Kunminghu modules, including branch-to-branch module comparisons when requested. Always obtain XiangShan source code directly from https://github.com/OpenXiangShan/XiangShan.git unless the user explicitly provides a local path. Default single-branch analysis to branch kunminghu-v2 unless the user explicitly asks for another branch or commit. For comparison analysis, require two branch/commit names and one or more modules/paths from the user; if any of these are missing, ask for the missing branch/module fields before analyzing. If the prompt contains a conflicting branch/path, state the source URL and branch/commit being analyzed before explaining.

Primary source roots:

• Weekly sync helper: scripts/weekly_sync.py and references/weekly-sync.md
• Analysis output saver: scripts/save_analysis.py and references/analysis-output.md
• Predictor paper search: paper-search-agent-mcp via mcp__paper_search_agent, plus references/predictor-papers.md
• AIA/IOPMP/AXI analysis: references/aia-iopmp-axi.md
• Difftest signal and architectural-state analysis: references/difftest.md
• Verification special attention: references/verification-special-attention.md, derived from tools/verification-driver/skills
• XiangShan source: https://github.com/OpenXiangShan/XiangShan.git, source root src/main/scala/xiangshan
• XiangShan Design Doc: https://github.com/OpenXiangShan/XiangShan-Design-Doc.git
• XiangShanLab course repo: https://github.com/OpenXiangShan/XiangShanLab.git
• XSCache repo: https://github.com/OpenXiangShan/XSCache.git
• Course background: XiangShanLab course system 4 implementation docs, especially superscalar/out-of-order basics and XiangShan high-performance out-of-order pipeline docs, plus course system 5 dynamic instruction execution docs
• Required analysis style: answer every module through who, why, how, from what, and to what

Workflow

Before step 1, read references/weekly-sync.md and run scripts/weekly_sync.py unless the user explicitly asks not to sync. This performs a 7-day guarded sync check for local Design Doc, XiangShanLab, and course analysis directories; XiangShan source itself must be fetched or inspected directly from https://github.com/OpenXiangShan/XiangShan.git. The sync helper must never reset, clean, or overwrite dirty worktrees.

1. Locate the requested module by fetching or inspecting https://github.com/OpenXiangShan/XiangShan.git at the requested branch/commit. Use local XiangShan source only when the user explicitly provides a local path or when GitHub/network access is unavailable and the fallback is clearly stated.
2. Locate matching foundational theory material before code analysis. Read references/xiangshanlab-course-map.md and references/theory-code-mapping.md, then inspect relevant XiangShanLab superscalar/out-of-order course markdown when available.
3. Locate matching design documentation before explaining broad intent. Read references/design-doc-map.md for Design Doc navigation and then inspect the relevant markdown files when available.
4. For predictor analysis, read references/predictor-papers.md and use paper-search-agent-mcp (mcp__paper_search_agent.search_papers) to find the relevant branch-prediction paper(s) before explaining algorithm principles.
5. Read the real Scala/Chisel files from https://github.com/OpenXiangShan/XiangShan.git before explaining implementation. Do not infer behavior from names or documentation alone. Record the analyzed source commit (git rev-parse HEAD for local checkouts, or the GitHub commit/branch SHA when browsing remote source). Use line-numbered reads such as nl -ba or editor line references so every algorithm, port, connection, and datapath claim can cite exact Chisel lines.
6. Identify the enclosing subsystem and load the matching reference:

• Theory-to-code mapping: read references/theory-code-mapping.md
• XiangShanLab course navigation: read references/xiangshanlab-course-map.md
• Backend pipeline: read references/backend.md
• Frontend fetch and prediction: read references/frontend.md
• Predictor paper search and algorithm principles: read references/predictor-papers.md for branch/target/indirect/RAS/statistical-corrector predictor analysis
• chiselAIA/chiselIOPMP/AXI bus behavior: read references/aia-iopmp-axi.md for APLIC/IMSIC, IOPMP, AXI master/slave, and AXI protocol control-signal analysis
• Memory/cache instruction behavior: read references/mem-cache.md
• XSCache cache subsystem: read references/xscache.md
• Load/store instruction taxonomy: read references/load-store-instruction-taxonomy.md
• Instruction latency and throughput: read references/instruction-latency-throughput.md
• Algorithms, FSMs, control path, and data path: read references/algorithm-control-dataflow.md
• Exceptions, interrupts, debug, and privilege: read references/exception-debug-privilege.md
• Difftest architectural-state, cache-state, queue-state, exception, interrupt, and memory-address signals: read references/difftest.md
• Queue and buffer capacity logic: read references/queue-buffer-capacity.md
• Mermaid and waveform-draw timing diagrams: read references/diagrams.md
• Output structure and question checklist: read references/analysis-template.md
• Weekly repository sync: read references/weekly-sync.md before source inspection; this syncs local docs/course inputs, not the authoritative XiangShan source
• Analysis output saving: read references/analysis-output.md before writing generated Markdown
• Verification special attention: always read references/verification-special-attention.md before writing; select the applicable predictor, BPU, FTQ, queue, RAS, ICache, exception/virtualization, conflict, FSM, forward-progress, and performance rows

1. Separate theory, design intent from effective code:

• Use XiangShanLab course docs to define architecture concepts such as superscalar issue, hazards, register renaming, Tomasulo/scoreboard ideas, issue queues, bypass, physical registers, ROB, and dynamic instruction execution.
• Use Design Doc/course implementation docs to describe motivation and intended XiangShan architecture.
• Use active source files, instantiated modules, actual IO connections, and parameter values to describe what the implementation really does.
• If theory/docs and code disagree or a concept is implemented differently, state the difference and prefer code for behavior.

1. Trace interfaces first: IO(...), bundle classes, Decoupled/Valid handshakes, difftest bundles/events, AXI/TL/APB channels, redirect/flush signals, wakeup/writeback channels, interrupt lines, MMU/cache request-response channels, and ROB/FTQ/LSQ pointers. For AXI, explicitly identify master/slave role and AW/W/B/AR/R channel direction before explaining behavior.
2. For memory/cache/XSCache targets, build a per-stage pipeline map before summarizing behavior. For every visible stage (s0/s1/s2, request, TLB, tag/meta, data, miss, refill, writeback, replay, commit, or named FSM stage), state what work the stage performs, which payload/control registers it owns, what index/address/allocation decision is computed there, what can stall/flush/replay/cancel it, and what leaves the stage.
3. Trace index and address calculations before summarizing any table, array, queue, cache, bank, entry, pointer, allocation slot, free-list slot, MSHR entry, replay entry, PTW entry, victim way, or selector access. For every index, explain exactly how it is computed from fields/signals/parameters, which bits are used, how bank/set/way/entry slices are formed, how wraparound or pointer arithmetic works, how the allocation/free algorithm chooses the index, and where the computed index is consumed. Include first-cycle or reset-time index behavior when registers or counters are involved.
4. Trace state updates: RegInit, RegEnable, RegNext, SyncDataModule, SRAM/data arrays, queues, tables, valid bits, pointers, snapshots, replay queues, FSM state registers, refill/writeback buffers, and replacement metadata. For every explicit FSM or implicit valid/status lifecycle, document reset state, state meaning, why the state exists, a concrete scenario that enters or uses the state, entry condition, transition condition, stage action, output action, blocking condition, and exit/clear condition. For every valid/status bit, explicitly state reset/initial value, set condition, clear condition, hold condition, flush/cancel condition, why the bit exists, an example transaction scenario, and all consumers that observe it. For every storage structure, analyze it through update, release, replace, and search/read/probe: the exact timing, enable/fire condition, index calculation, payload fields updated/read/released/replaced, valid-bit effect, conflict priority when multiple operations happen together, and downstream effect. For every read/write port on a storage structure, analyze conflict scenarios: same-cycle read/write same index, multiple writes same index, multiple reads contending for a limited port, read-after-write/write-after-read/write-after-write behavior, bypass/forwarding or assert behavior, and which request wins or stalls. For every queue/buffer, inspect empty/full/almost-full/allow-enqueue/allow-dequeue/backpressure logic.
5. Trace algorithms and paths: replacement, allocation/free index selection, arbitration, selection, prediction, replay, redirect, dependency, forwarding, merge/split, miss handling, permission checking, AIA interrupt delivery/priority, IOPMP permission match/deny, AXI address routing/outstanding/burst/response handling, exception/interrupt/debug/privilege checks, and exception priority algorithms. For every algorithm, port/interface, inter-module connection, and datapath segment, cite exact Chisel source line numbers and include a short core code snippet from the analyzed commit. For every key control signal or state transition that changes behavior, explain why it exists and give at least one concrete scenario, such as a stall, replay, redirect, miss, exception, full queue, conflicting request, probe, refill, or commit release. For each algorithm, describe how it works from initialization/reset, how the first real transaction/request is handled, all major cases/branches, tie or priority behavior, invalid/empty/full behavior, and how state evolves after each case. For every arbiter or priority selector, explicitly analyze the simultaneous-request scenario: all requesters that can assert together, request qualification, priority/age/round-robin rule, grant generation, ready/backpressure, losing request behavior, and same-cycle update effects.

12a. For every frontend branch predictor or predictor-like component (BPU/Composer, Bim/base table, FTB, FauFTB/uFTB, Tage, SC, ITTAGE, RAS/newRAS), add an Algorithm Example Walkthrough section. The walkthrough must use a concrete example input and state, such as a fetch PC, branch slot, folded/global history bits, table valid/tag/counter/useful state, RAS pointer/top state, FTQ update metadata, or redirect metadata. Step through lookup, selection, prediction response, update/training, allocation/replacement, and recovery/redirect effects as applicable. Each step must cite the source lines that implement the rule and explicitly state the example input, intermediate state changes, and output. If the component is not effective in the analyzed commit, still provide a non-effective example based on the commented/dead code and clearly label it as non-effective.