Skip to content

GETTING_STARTED.md

Latest commit

 

History

History
266 lines (203 loc) · 5.79 KB

GETTING_STARTED.md

File metadata and controls

266 lines (203 loc) · 5.79 KB

Getting Started with DRAM Controller

This guide will help you get up and running with the DRAM controller project.

Table of Contents

  1. Installation
  2. First Simulation
  3. Understanding the Output
  4. Viewing Waveforms
  5. Modifying Parameters
  6. Next Steps

Installation

Step 1: Install Prerequisites

Windows

  1. Download and install Icarus Verilog from https://bleyer.org/icarus/
  2. Add to PATH: C:\iverilog\bin
  3. GTKWave is included with the installation

Linux (Ubuntu/Debian)

sudo apt-get update
sudo apt-get install iverilog gtkwave

macOS

brew install icarus-verilog gtkwave

Step 2: Clone the Repository

git clone https://github.com/0xSA7/dram-controller.git
cd dram-controller

First Simulation

Quick Start

Windows:

cd scripts
simulate.bat

Linux/Mac:

cd scripts
chmod +x simulate.sh
./simulate.sh

What Happens During Simulation

  1. Compilation Phase

    • All Verilog files are compiled
    • Include paths are resolved
    • Syntax is checked

  2. Simulation Phase

    • Testbench initializes the controller
    • Multiple test cases run:
      • Write operations
      • Read operations
      • Sequential operations
      • Refresh cycles

  3. Output Generation

    • Console shows test progress
    • VCD waveform file is created
    • Pass/fail summary is displayed

Understanding the Output

Console Output

========================================
  DRAM Controller Testbench
========================================

[65000] TEST #1: Write - Addr=0x012345, Data=0xabcd
[DRAM Model] Time 95000: ACTIVATE - Row=0091
[DRAM Model] Time 135000: WRITE - Col=145, Data=abcd
[85000] Write complete

[85000] TEST #2: Read - Addr=0x012345, Expected=0xabcd
[DRAM Model] Time 195000: READ - Col=145, Data=abcd
[105000] Read complete - Data=0xabcd [PASS]

========================================
  Test Summary
========================================
Total Tests: 7
Passed: 7
Failed: 0
========================================

*** ALL TESTS PASSED ***

Test Results

  • ✅ PASS - Operation completed successfully with correct data
  • ❌ FAIL - Data mismatch or timing violation
  • Timeout - Operation didn't complete within expected time

Viewing Waveforms

Launch GTKWave

Windows:

cd sim_output
C:\iverilog\gtkwave\bin\gtkwave.exe dram_controller.vcd

Linux/Mac:

cd sim_output
gtkwave dram_controller.vcd

Important Signals to View

Add these signals to see controller operation:

Top Level:

  • dram_controller_tb.clk - Clock signal
  • dram_controller_tb.rst_n - Reset

CPU Interface:

  • dut.cpu_addr - Address from CPU
  • dut.cpu_data_in - Write data
  • dut.cpu_data_out - Read data
  • dut.cpu_read_req - Read request
  • dut.cpu_write_req - Write request
  • dut.cpu_ready - Controller ready
  • dut.cpu_data_valid - Data valid flag

DRAM Interface:

  • dut.dram_addr - Address to DRAM
  • dut.dram_dq - Data bus
  • dut.dram_ras_n - Row Address Strobe
  • dut.dram_cas_n - Column Address Strobe
  • dut.dram_we_n - Write Enable

Internal State:

  • dut.u_dram_fsm.current_state - FSM state
  • dut.u_timing_generator.counter_value - Timing counter

Understanding the Timing

Look for these patterns in waveforms:

  1. RAS goes low → Row activation
  2. Wait tRCD cycles → RAS to CAS delay
  3. CAS goes low → Column access
  4. Data appears → After CAS latency
  5. Precharge → Row deactivation

Modifying Parameters

Change Timing Parameters

Edit rtl/dram_controller_top.v or instantiate with different parameters:

dram_controller_top #(
    .T_RCD(5),              // Change RAS-to-CAS delay
    .T_RP(5),               // Change precharge time
    .T_CAS(3),              // Change CAS latency
    .REFRESH_INTERVAL(600)  // Change refresh interval
) dut (
    // ... connections
);

Change Memory Size

dram_controller_top #(
    .ROW_ADDR_WIDTH(14),    // Increase row address
    .COL_ADDR_WIDTH(10),    // Increase column address
    .DATA_WIDTH(32)         // Wider data bus
) dut (
    // ... connections
);

Recompile and Test

After making changes:

cd scripts
./simulate.sh

Next Steps

Learn More

  1. Read Architecture Guide for design details
  2. Study Project Tree for code organization
  3. Check Examples for usage patterns

Experiment

  1. Modify timing parameters and observe effects
  2. Add new test cases to the testbench
  3. Try different address patterns

Contribute

  1. Fix bugs or add features
  2. Improve documentation
  3. Share your use case
  4. See Contributing Guide

Common Issues

Compilation Errors

Problem: Include file not found

Solution: Check that all files exist in rtl/ directory

Problem: Syntax error

Solution: Check Verilog syntax, ensure Verilog-2012 support (-g2012)

Simulation Issues

Problem: Simulation timeout

Solution: Check FSM is transitioning properly, verify timing parameters

Problem: Data mismatch

Solution: Check address mapping, verify DRAM model behavior

Tool Issues

Problem: Command not found: iverilog

Solution: Install Icarus Verilog, add to PATH

Problem: Cannot open VCD file

Solution: Check sim_output/ directory exists and has write permissions

Getting Help

Happy Simulating! 🚀