Skip to content

quick-start.md

Latest commit

 

History

History
270 lines (197 loc) · 5.5 KB

quick-start.md

File metadata and controls

270 lines (197 loc) · 5.5 KB

Quick Start Guide

Get started with MapacheSPIM in 5 minutes. This guide will help you install the simulator and debug your first RISC-V program.

Prerequisites

You'll need:

  • macOS or Linux (Windows via WSL)
  • Python 3.8+

Check your Python version:

python3 --version  # Should be 3.8 or higher

Installation

# Clone the repository
git clone https://github.com/UCSBarchlab/MapacheSPIM.git
cd MapacheSPIM

# Create virtual environment (recommended)
python3 -m venv venv
source venv/bin/activate

# Install Python package
pip install -e .

# Verify installation
mapachespim --version

Your First Program

Let's debug a simple Fibonacci program that's already included.

Step 1: Start the Console

mapachespim

You'll see:

Welcome to MapacheSPIM. Type help or ? to list commands.
(mapachespim)

Step 2: Load a Program

(mapachespim) load examples/riscv/fibonacci/fibonacci
Loaded examples/riscv/fibonacci/fibonacci
Entry point: 0x0000000080000000

Step 3: See Available Symbols

(mapachespim) info symbols

You'll see function names and their addresses.

Step 4: Set a Breakpoint

(mapachespim) break main
Breakpoint set at main (0x80000030)

Step 5: Run to Breakpoint

(mapachespim) run
Breakpoint hit at main (0x80000030)

Step 6: Step Through Code

(mapachespim) step
[0x80000030] 0x13050005  addi x10, x0, 0x5  <main>
Register changes:
  x10 (  a0) : 0x0000000000000000 -> 0x0000000000000005  *

You just saw:

  • The address (0x80000030)
  • The function name ()
  • The instruction bytes (0x13050005)
  • The disassembly (addi x10, x0, 0x5)
  • Which register changed

Step 7: Inspect Registers

(mapachespim) regs

See all 32 registers with their ABI names and values.

Step 8: Continue Execution

(mapachespim) step 5

Step through 5 more instructions to see the program flow.

Step 9: Quit

(mapachespim) quit
Goodbye!

Essential Commands

Here are the commands you'll use most:

Command Example What it does
load load examples/riscv/fibonacci/fibonacci Load a program
break break main Set breakpoint at function
run run Run until breakpoint/halt
step step or step 5 Execute 1 or N instructions
regs regs Show all registers
mem mem 0x80000000 64 Show memory contents
disasm disasm 0x80000000 10 Disassemble instructions
info symbols info symbols List all symbols
info breakpoints info breakpoints List breakpoints
delete delete 0x80000030 Remove breakpoint
clear clear Remove all breakpoints
pc pc Show program counter
quit quit or Ctrl-D Exit console

Tip: Many commands have short aliases:

  • step -> s
  • break -> b
  • run -> r
  • continue -> c
  • disasm -> d
  • quit -> q

Debugging Tips

1. Use Symbolic Breakpoints

(mapachespim) break fibonacci
(mapachespim) run

Much easier than memorizing addresses.

2. Watch Register Changes

Single-step automatically shows what changed:

(mapachespim) step
[0x80000000] 0x9302a000  addi x5, x0, 0xa  <_start>
Register changes:
  x5  (  t0) : 0x0000000000000000 -> 0x000000000000000a  *

3. Disassemble to Understand Code

(mapachespim) disasm 0x80000000 10

See the next 10 instructions before executing them.

4. Multi-step for Known-Good Code

(mapachespim) step 10

Skip over initialization code quickly.

5. Check Memory Contents

(mapachespim) mem 0x80000000 32

See the raw instruction bytes.

Example Debugging Session

Here's a complete session debugging the Fibonacci program:

$ mapachespim
(mapachespim) load examples/riscv/fibonacci/fibonacci
Loaded examples/riscv/fibonacci/fibonacci

(mapachespim) info symbols
  0x80000000  _start
  0x80000030  main
  0x80000038  fibonacci
  ...

(mapachespim) break main
Breakpoint set at main (0x80000030)

(mapachespim) run
Breakpoint hit at main (0x80000030)

(mapachespim) step
[0x80000030] 0x13050005  addi x10, x0, 0x5  <main>
Register changes:
  x10 (  a0) : 0x0000000000000000 -> 0x0000000000000005  *

(mapachespim) step
[0x80000034] 0x040000ef  jal ra, fibonacci  <main+4>
Register changes:
  x1  (  ra) : 0x0000000000000000 -> 0x0000000080000038  *

(mapachespim) regs
x0  (zero) = 0x0000000000000000  x1  (  ra) = 0x0000000080000038  ...
x10 (  a0) = 0x0000000000000005  ...

(mapachespim) continue
Program halted after 42 instructions

(mapachespim) quit
Goodbye!

Next Steps

Now that you've run your first program:

  1. Console Guide - Learn all commands in detail
  2. Examples - Explore more example programs
  3. Write Your Own - Create and debug your own RISC-V programs

Troubleshooting

Command Not Found: mapachespim

If the console doesn't start, try:

# Make sure your virtual environment is activated
source venv/bin/activate

# Or run from Python package
python3 -m mapachespim.console

Import Error

Make sure you installed the Python package:

pip3 install -e .

Still Stuck?

What's Next?

After mastering the basics, explore:

  • Advanced Debugging - Watchpoints, conditional breakpoints (future)
  • Multiple ISAs - ARM and CHERI support (future)
  • Custom Programs - Write and compile your own RISC-V code
  • C++ Console - Native performance console (future)