MARS Plus — MIPS X-Ray, reimagined for the classroom

Step through MIPS. Watch the single-cycle datapath light up. Ask MARS Plus why the ALU just did that—without leaving MARS.

This fork keeps the familiar MARS simulator you already use with Computer Organization and Design, then layers on a clearer MIPS X-Ray experience and an optional Gemini-powered tutor tuned to the instruction you are on right now.

---

Why this exists

• Less context switching: Encoding, control signals, and the diagram stay in one window next to your questions.
• Closer to how you learn: Stage focus, micro-steps, and wire highlights line up with how textbooks walk the datapath.
• Honest AI help: MARS Plus gets a silent snapshot of PC, signals, and registers—it should answer like a coach who is looking at your run, not a generic slideshow.

---

Try it in about a minute

1. Clone the repo and from the root run: java Mars.
2. Open Tools → MIPS X-Ray.
3. Load test_xray.asm, press Assemble (F3), then Step (F7).
4. Use Next on the playback bar to move through micro-steps and watch paths on the canvas.
5. Optional: set your Gemini key (see below) and ask MARS Plus what the current beat is doing.

Tip

Toggle Dark on the playback bar if the lab room lights are low—the whole tool chrome follows.

---

What ships in this repo

Planning and acceptance criteria live under issues/ (parent specs: issues/prd.md, Phase 2 chat: issues/prd-phase2-ai-chat.md).

Focus	You get
Trace & encoding	Program list that tracks the PC; R/I/J fields and hex for the active word.
Stage strip	FETCH through WRITEBACK (or FULL) to declutter the diagram.
Playback	Prev / Play / Next / Reset plus speed presets; works with micro-step mode.
Wires & tooltips	Animated paths with live values; hover for detail; classic click-to-zoom behavior preserved.
Control table	RegDst, ALUSrc, memory controls, ALU op/result, Zero—color-highlighted.
MARS Plus	Styled chat (no raw dumps in the UI); transcript saved under ~/.mars/marsplus_transcript.log; Reset does not wipe your chat.
Help	In-tool HTML guide (layout, keys, credits).

flowchart LR
  subgraph left [Left column]
    T[Program trace]
    E[Instruction encoding]
  end
  subgraph center [Center]
    S[Stage strip]
    D[Datapath canvas]
    P[Playback bar]
  end
  subgraph right [Right column]
    C[Control signals]
    M[MARS Plus chat]
  end
  left --> center
  center --> right

Loading

---

Run

This repo includes compiled .class files for MIPS X-Ray and MARS Plus, so after you git clone you can run MARS immediately:

cd path\to\this\repo
java Mars

If you edit any .java file, recompile before running again (same layout as upstream MARS: compile all sources from the repo root with javac, or use your IDE’s build). The JVM always loads bytecode, not the .java sources—pushing only source changes without rebuilding would leave the old tool behavior until you compile.

---

MARS Plus (Gemini) setup

1. Create an API key in Google AI Studio.
2. Supply it one of these ways: the Key button in the chat panel, the GEMINI_API_KEY environment variable, or ~/.mars/gemini_key.txt.

Caution

Never commit keys. If a key ever appeared in chat or in git history, rotate it in AI Studio.

---

Demo program

test_xray.asm mixes load/store, add, addi, and a branch—enough to exercise the table and the diagram in a short demo, not a full homework.

---

Credits

• MARS (original simulator) — Pete Sanderson, Ken Vollmar; community distribution and docs (see the MARS site).
• MIPS X-Ray (original diagram tool) — Márcio Roberto, Guilherme Sales, Fabrício Vivas, Flávio Cardeal, Fábio Lúcio.
• This teaching refresh & MARS Plus — Nouman Zahid, Hasanat Ahmad, with Dr. Mehmood Qureshi as faculty advisor.

If you use this in a course, cite both the original MARS/X-Ray authors and this refresh so students know where the ideas came from.