# RISC-V Simulator - README

## Project Overview

A custom simulator implementation for a subset of the **RV32I (RISC-V 32-bit integer)** instruction set architecture. This simulator executes binary machine code and generates execution traces showing register states after each instruction and final memory snapshots.

---

## Course Information

* **Assignment:** Computer Organization Project (Question 2)
* **Instructor:** Sujay Deb
* **Evaluation Weight:** 80% of total assignment grade
* **ISA:** RV32I (RISC-V 32-bit Integer Base Instruction Set)

---

## Functionality

### Input

* **Binary Code File:** Text file containing 32-bit binary instructions (one instruction per line)
* Generated by a compatible RISC-V assembler
* Each line represents a single 32-bit instruction encoded in ASCII '0' and '1' characters

### Output

The simulator generates a trace file containing:

**1. Per-Instruction Execution Trace:**
`{PC} {x0} {x1} {x2} ... {x31}`

* Program Counter and all 32 register values after each instruction execution
* All values in 32-bit binary format

**2. Final Memory Dump (after Virtual Halt):**

* 32 lines of 32-bit binary data
* Represents the 128-byte data memory section (0x00010000 - 0x0001007F)

---

## Execution Flow

1. Initialize all registers to zero (except PC)
2. Load binary instructions into program memory
3. Execute instructions sequentially:
* Fetch instruction at PC
* Decode opcode and operands
* Execute operation
* Update registers and memory
* Log register state to trace file


4. Halt on Virtual Halt instruction (`beq zero,zero,0`)
5. Dump final memory state

---

## Supported Instructions

### R-Type (Register Operations)

* `add` - Addition
* `sub` - Subtraction
* `slt` - Set Less Than (signed comparison)
* `srl` - Shift Right Logical
* `or` - Bitwise OR
* `and` - Bitwise AND

### I-Type (Immediate Operations)

* `lw` - Load Word from memory
* `addi` - Add Immediate
* `jalr` - Jump and Link Register (subroutine return)

### S-Type (Store Operations)

* `sw` - Store Word to memory

### B-Type (Branch Operations)

* `beq` - Branch if Equal
* `bne` - Branch if Not Equal
* `blt` - Branch if Less Than (signed)

### J-Type (Jump Operations)

* `jal` - Jump and Link (subroutine call)

---

## Memory Architecture

| Memory Section | Address Range | Size | Purpose |
| --- | --- | --- | --- |
| **Program Memory** | 0x00000000 - 0x000000FF | 256 bytes (64 instructions) | Instruction storage |
| **Stack Memory** | 0x00000100 - 0x0000017F | 128 bytes (32 locations) | Stack operations (grows downward) |
| **Data Memory** | 0x00010000 - 0x0001007F | 128 bytes (32 locations) | Data storage |

---

## Special Features

### Register File

* **x0 (zero):** Hardwired to 0 (writes ignored)
* **x1 (ra):** Return address register
* **x2 (sp):** Stack pointer
* **x3-x31:** General purpose registers

### Virtual Halt

* Execution terminates on `beq zero,zero,0` instruction
* Must be the last instruction in program
* Triggers final memory dump

---

## Technical Implementation Details

### Instruction Execution Cycle

1. **Fetch:** Read 32-bit instruction from program memory at PC
2. **Decode:** Extract opcode, funct3, funct7, and operand fields
3. **Execute:** Perform operation based on instruction type
4. **Memory Access:** Load/Store operations access data memory
5. **Write Back:** Update destination register
6. **PC Update:** Increment by 4 or branch to new address

### Sign Extension

* Immediate values are sign-extended to 32 bits before arithmetic operations
* Branch/Jump offsets use 2's complement representation

### Error Handling

* Invalid memory access detection
* Illegal instruction detection
* Missing Virtual Halt instruction
* Outputs error message with line number to terminal

---

## Testing

### Test Case Categories

* **simpleBin:** Basic instruction sequences
* **hardGen:** Complex programs with subroutines, loops, and edge cases

### Evaluation Criteria

* Correctness of register state traces
* Accurate memory operations
* Proper branch/jump behavior
* Correct handling of edge cases (overflow, sign extension)

---

## Usage Example

**Input Binary (sample.bin):**

```text
00000000000000000010000100010011
00000000000000000010001000010011
...
00000000000000000000110011100011

```

**Output Trace (trace.txt):**

```text
00000000000000000000000000000000 00000000000000000000000000000000 00000000000000000000000000000001 ...
00000000000000000000000000000100 00000000000000000000000000000000 00000000000000000000000000000001 ...
...
[32 lines of memory dump]

```

---

## Compliance Notes

* Implements RV32I base integer instruction set (subset)
* Load-store architecture (memory operations only through registers)
* 32-bit word-addressable memory
* Little-endian byte ordering (where applicable)
* Overflow ignored in arithmetic operations

---

## Development Guidelines

* Code must work on Linux-based systems (Ubuntu/WSL)
* Version controlled via GitHub
* Periodic commits required for backup
* No platform-specific dependencies

> **Note:** This simulator is designed specifically for educational purposes as part of the Computer Organization course assignment. It implements a subset of RV32I and may not support all RISC-V extensions or features.

---