Skip to content

About

MIPS32 single cycle processor implemented in Verilog to demonstrate core CPU architecture concepts.

Topics

Resources

Stars

1 star

Watchers

1 watching

Forks

Latest commit

 

History

84 Commits

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

MIPS32 Single-Cycle Processor in Verilog

A visual, beginner-friendly journey from basic Verilog modules to a working CPU.

This repository presents a small MIPS32-style single-cycle processor in Verilog. It is intended for readers who can read simple Verilog, such as an ALU, but are still learning what a CPU, an instruction set, registers, memory, and a datapath actually are.

Readers do not need previous knowledge of:

  • MIPS or RISC-V assembly;
  • CPU architecture;
  • instruction encoding;
  • pipelining;
  • operating systems;
  • FPGA or ASIC design.

The project uses an intentionally educational design. Readers can study the small RTL modules, run the testbenches to see how each block behaves, and connect textbook concepts to the actual files in rtl/.


Table of contents

  1. Start here
  2. The big idea: what a CPU does
  3. What does single-cycle mean?
  4. The processor at a glance
  5. How one instruction travels
  6. The repository as a book
  7. The beginner learning path
  8. The instruction formats
  9. A complete addi walkthrough
  10. Loads, stores, branches, and jumps
  11. Current instruction subset
  12. Repository structure
  13. Run the processor
  14. Understand the testbenches
  15. What this project does not cover
  16. Further reading
  17. References

Start here

Readers who are completely new to CPUs should follow this order:

  1. Read the short explanation in The big idea.
  2. Look at the CPU overview.
  3. Read rtl/alu.v and run tb/alu_tb.v.
  4. Learn state with rtl/pc.v and rtl/register_file.v.
  5. Read the beginner learning path.
  6. Run the complete CPU simulation.
  7. Read the architecture chapter while following the wires in rtl/datapath.v.

Readers should not try to memorize every control signal on the first reading. The goal is to understand the journey of one instruction. Once that journey is clear, the individual Verilog signals become much easier to recognize.


The big idea: what a CPU does

A CPU can be understood as repeatedly performing this simple loop:

1. Find the next instruction.
2. Understand what the instruction says.
3. Read the values it needs.
4. Calculate a result or an address.
5. Read or write memory if required.
6. Save the result.
7. Decide where to find the next instruction.

For example, an instruction might say:

addi $t0, $zero, 5

In plain English:

Take the value in $zero, add 5, and store the result in $t0.

The CPU performs that sentence using hardware:

instruction bits
      ↓
control unit interprets them
      ↓
register file supplies $zero
      ↓
ALU adds 0 and 5
      ↓
register file stores 5 in $t0

The ALU is only one part of the CPU. The CPU also requires storage, instruction interpretation, memory, and connections between those blocks.


What does single-cycle mean?

Here, one instruction completes during one clock period. The processor does not use separate fetch, decode, execute, and write-back cycles; those activities happen as one combinational path between clock edges. This organization follows the classic single-cycle datapath model described by Patterson and Hennessy [5].

Single-cycle instruction flow

Figure 1. Single-cycle instruction flow from fetch through write-back.

Keep this distinction in mind:

Combinational work Clocked state
ALU result Program counter
Control signals Register-file writes
Immediate extension Data-memory writes
Next-PC selection

At a rising edge, the processor remembers the new PC, register values, and memory values. During the rest of the cycle, combinational logic calculates what should happen next.

This design is easy to understand because each instruction has a complete visible path. Although it is not the fastest CPU architecture, it is an excellent first CPU architecture.


The processor at a glance

The top-level module is rtl/mips32_cpu.v. It wires together the PC, instruction memory, control unit, datapath, and data memory.

CPU overview

Figure 2. Organization of the MIPS32 processor and its primary modules.

The large boxes in the diagram correspond to real RTL modules:

Concept Repository file Responsibility
Program counter rtl/pc.v Remembers the current instruction address
Instruction memory rtl/instruction_memory.v Returns the instruction at the PC
Control unit rtl/control_unit.v Interprets opcode and function fields
Register file rtl/register_file.v Stores 32 general-purpose registers
ALU rtl/alu.v Performs arithmetic and logical operations
Datapath rtl/datapath.v Connects operands, results, memory, and PC choices
Data memory rtl/data_memory.v Stores and returns program data
Complete CPU rtl/mips32_cpu.v Instantiates and wires everything together

The datapath acts as the road system of the processor. Values travel along wires, and multiplexers choose which road each value takes.


How one instruction travels

Every supported instruction follows the same broad story:

1. Fetch

The PC supplies a byte address, and instruction memory uses that address to return a 32-bit instruction.

Normal sequential execution advances by four bytes:

next PC = current PC + 4

Instructions are four bytes wide, so the low two address bits must be zero.

2. Decode

The control unit reads the instruction's opcode and, for R-type instructions, its function field. It produces signals such as:

  • should the ALU use a register or an immediate?
  • should the result be written to rd or rt?
  • should data memory be read or written?
  • is this a branch or jump?
  • which ALU operation is required?

3. Read operands

The register file reads two registers at the same time. The datapath also forms a 32-bit immediate from the instruction's 16-bit field.

Different instructions use different immediate rules:

  • arithmetic offsets are sign-extended;
  • logical immediates are zero-extended;
  • lui moves the value into the upper 16 bits;
  • branch offsets are shifted left by two.

4. Execute

The ALU performs the operation. For a memory instruction, it calculates an effective address:

effective address = base register + offset

For a branch, subtraction produces the zero flag used to decide equality.

5. Memory

lw reads data memory. sw writes data memory. Other instructions do not access data memory.

6. Write back

The result can come from:

  • the ALU;
  • data memory;
  • PC + 4 for jal.

The destination can be rd, rt, or register 31 ($ra).

7. Select the next PC

The datapath chooses the next PC from:

PC + 4
branch target
jump target
register target for jr

The priority is jr, then j/jal, then a taken branch, and finally the normal sequential address.


The repository as a book

The project can be studied as a sequence of chapters. Each chapter has three parts:

  1. a hardware idea;
  2. an RTL module;
  3. an executable testbench.
Chapter Read Then run
1. Combinational logic rtl/alu.v tb/alu_tb.v
2. Clocked state rtl/pc.v tb/pc_tb.v
3. Register storage rtl/register_file.v tb/register_file_tb.v
4. Program storage rtl/instruction_memory.v tb/instruction_memory_tb.v
5. Instruction interpretation rtl/control_unit.v tb/control_unit_tb.v
6. Data storage rtl/data_memory.v tb/data_memory_tb.v
7. Connecting the datapath rtl/datapath.v tb/datapath_tb.v
8. The complete machine rtl/mips32_cpu.v tb/mips32_cpu_tb.v

The full beginner course is in docs/beginner-roadmap.md. It presents the same sequence in lesson form and includes exercises.


The beginner learning path

Chapter 1: Begin with the ALU

Readers can start with a familiar circuit. The ALU receives two 32-bit values and an operation code, then produces a result and a zero flag.

result = a + b;

At this stage, there is no memory and no instruction decoding. The ALU only reacts to its inputs, providing an example of combinational logic.

Questions to answer:

  • What changes when a changes?
  • Why does the ALU not need a clock?
  • How is signed slt different from bitwise operations?
  • Why is the zero flag useful for branches?

Chapter 2: Add time with the PC

The PC is a 32-bit register. Unlike the ALU, it remembers a value across clock edges:

always @(posedge clk) begin
    pc <= next_pc;
end

Reset gives the processor a known starting address.

Chapter 3: Add registers

The register file contains 32 registers. A five-bit address selects one:

2^5 = 32

The register file has two asynchronous read ports and one synchronous write port. $zero is hard-wired to zero, which is a common and useful CPU convention.

Chapter 4: Store instructions

Instruction memory maps addresses to 32-bit instruction words. In simulation, the memory can be initialized with $readmemh or directly from a testbench.

This is the point where a bit pattern becomes an instruction.

Chapter 5: Decode instructions

The control unit is an interpreter implemented as combinational RTL. It maps instruction fields to control signals, while its default controls keep unsupported instructions safe and inert.

Chapter 6: Store data

Data memory is separate from instruction memory. A store changes memory at a clock edge, while a read returns data combinationally.

Chapter 7: Connect the datapath

The datapath combines the register file, immediate formation, ALU, write-back muxes, branch logic, and jump logic.

Chapter 8: Build the complete CPU

The top-level CPU connects the pieces and executes a small program. At that point, the processor is a machine that changes state according to instructions rather than a collection of isolated modules.


The instruction formats

The processor uses three simple instruction shapes.

R-type: register operations

R-type instruction format

Figure 3. Field encoding of R-type MIPS32 instructions.

Example:

add $t2, $t0, $t1

The CPU reads $t0 and $t1, adds them, and writes the result to $t2.

I-type: immediate and memory operations

I-type instruction format

Figure 4. Field encoding of I-type MIPS32 instructions.

Example:

addi $t0, $zero, 5

The CPU reads $zero, forms the immediate value 5, and writes the result to $t0.

J-type: control-flow operations

J-type instruction format

Figure 5. Field encoding of J-type MIPS32 instructions.

j and jal use the target field to construct a new PC.

More complete encoding tables are in docs/instruction-set.md. The instruction formats, register conventions, and operation semantics are based on the MIPS32 architecture references [1][2]; this repository implements an intentionally smaller educational subset.


A complete addi walkthrough

The walkthrough traces:

addi $t0, $zero, 5

Instruction bits arrive

Instruction memory returns a 32-bit value, and the control unit sees the opcode for addi.

The control unit decides

Use these conceptual control settings:

alu_src   = 1       // use the immediate as ALU input B
reg_dst   = 0       // destination is rt
reg_write = 1       // write a register
alu_op    = ADD

No memory access and no branch are enabled.

The register file reads $zero

Register 0 always returns zero:

register_data1 = 0

The immediate is extended

The 16-bit value 5 becomes:

0x00000005

The ALU calculates

0 + 5 = 5

The destination is selected

For an I-type instruction, the destination is rt. In this encoding, rt is register 8, conventionally named $t0.

The clock edge saves the result

At the rising edge:

register[8] <= 5

The next PC is PC + 4.

Tracing addi through the datapath

Figure 6. Datapath trace for the `addi $t0, $zero, 5` instruction.

This is the most important walkthrough in the repository. Every other instruction is a variation on which values are selected, which operation is performed, and which state is updated.


Loads, stores, branches, and jumps

lw: load a word

lw $t0, 4($t1)
  1. Read $t1.
  2. Sign-extend 4.
  3. Add them in the ALU.
  4. Read data memory at the resulting address.
  5. Write the memory value into $t0.

sw: store a word

sw $t0, 4($t1)
  1. Read $t1 as the base.
  2. Sign-extend 4.
  3. Add them in the ALU.
  4. Send $t0 as memory write data.
  5. Store it at the clock edge.

beq: branch if equal

beq $t0, $t1, offset

The ALU subtracts the operands. If the result is zero, the target is:

PC + 4 + (sign_extended_offset << 2)

The shift by two converts an instruction offset into a byte offset.

bne: branch if not equal

bne uses the same subtraction, but takes the branch when the ALU zero flag is false. The explicit branch_ne signal tells the datapath to invert the condition.

j: jump

j builds a target from the instruction's 26-bit field and the upper four bits of PC + 4.

jal and jr: call and return

jal:

$ra = PC + 4
PC  = jump target

jr $ra reads register 31 and uses it as the next PC. The integration testbench demonstrates this complete call-and-return path.


Current instruction subset

Class Instructions
R-type add, sub, and, or, xor, slt, sll, jr
I-type addi, andi, ori, xori, lui, slti, lw, sw, beq, bne
J-type j, jal

Compatibility note: This is an educational MIPS32-style subset, not a fully compliant MIPS32 implementation. It intentionally omits features such as delay slots, exceptions, interrupts, privileged modes, and overflow handling.

Use these implementation conventions:

  • register 0 ($zero) always reads as zero;
  • register 31 ($ra) stores the return address for jal;
  • instruction and data addresses must be word-aligned;
  • invalid memory addresses read as zero and ignore writes;
  • reset is synchronous and active high;
  • unsupported instructions safely advance the PC without changing state.

Repository structure

rtl/ — Processor implementation
File Purpose
alu.v Arithmetic and logic operations
control_unit.v Opcode and function decoding
data_memory.v Data memory
datapath.v Datapath connections
instruction_memory.v Instruction storage
mips32_cpu.v Complete CPU
pc.v Program counter
register_file.v Register storage
tb/ — Testbenches
File Purpose
alu_tb.v ALU tests
control_unit_tb.v Control-unit tests
data_memory_tb.v Data-memory tests
datapath_tb.v Datapath tests
instruction_memory_tb.v Instruction-memory tests
mips32_cpu_tb.v Complete CPU integration test
pc_tb.v Program-counter tests
register_file_tb.v Register-file tests
docs/ — Documentation and diagrams
File or directory Purpose
beginner-roadmap.md Beginner learning path
architecture.md Datapath and control explanation
instruction-set.md Instruction formats and encodings
verification.md Testbench and CI strategy
learning-notes.md Design notes and experiments
diagrams/ SVG diagrams and Mermaid sources

Run the processor

Requirements

Install Git and at least one Verilog simulator. Icarus Verilog is the simplest option for beginners; Verilator is a faster compiled simulator and also provides useful lint checks. The RTL uses Verilog/SystemVerilog language constructs standardized by IEEE 1364 and IEEE 1800 [3][4].

Ubuntu/Debian:

sudo apt-get update
sudo apt-get install -y iverilog verilator

Run the complete CPU test

From the repository root:

iverilog -g2012 -o cpu_sim tb/mips32_cpu_tb.v rtl/*.v && vvp cpu_sim

The testbench loads a small program into instruction memory and verifies register results, memory behavior, branches, jumps, jal, jr, and PC sequencing.

Alternative: run the complete CPU with Verilator

Verilator compiles the Verilog into a native executable. The --timing option is required because the testbench contains clock delays and waits such as always #5 clk = ~clk and @(posedge clk).

From the repository root:

verilator --binary --timing --top-module mips32_cpu_tb \
  tb/mips32_cpu_tb.v rtl/*.v \
  && ./obj_dir/Vmips32_cpu_tb

The Verilator executable should print the same PASS checks as the Icarus simulation and finish with:

PASS: CPU integration test completed with no failures

Verilator is an additional method, not a replacement for understanding the RTL. Icarus remains useful for simple, traditional Verilog simulation, while Verilator is useful for fast execution and lint-style feedback.

Generate a waveform for GTKWave

GTKWave needs a waveform file such as VCD or FST. Add these lines near the beginning of the initial block in tb/mips32_cpu_tb.v:

$dumpfile("cpu.vcd");
$dumpvars(0, mips32_cpu_tb);

Then compile with Verilator tracing enabled:

verilator --binary --timing --trace --top-module mips32_cpu_tb \
  tb/mips32_cpu_tb.v rtl/*.v \
  && ./obj_dir/Vmips32_cpu_tb
gtkwave cpu.vcd

The waveform lets readers inspect signals over time, including clk, reset, pc, instruction, next_pc, memory controls, and datapath results. The same $dumpfile and $dumpvars lines also work with the Icarus command.

Run an individual unit test

For the ALU:

iverilog -g2012 -o alu_sim tb/alu_tb.v rtl/alu.v
vvp alu_sim

The other unit tests use the same compile-and-run pattern. CI runs all eight testbenches on pushes, pull requests, and manual workflow dispatches.


Verification results

The processor was verified with eight unit and integration testbenches.

Icarus Verilog 12.0 | Verilator 5.020 | Ubuntu 24.04.5 LTS

On commit 9189f61, all eight testbenches passed:

Testbench Result
alu_tb.v PASS
register_file_tb.v PASS
control_unit_tb.v PASS
pc_tb.v PASS
instruction_memory_tb.v PASS
data_memory_tb.v PASS
datapath_tb.v PASS
mips32_cpu_tb.v PASS

Representative output:

PASS: CPU integration test completed with no failures
8/8 testbenches passed.

The same tests passed in GitHub Actions; the workflow also uploads the complete simulator logs.

Exact local command sequence

From the repository root:

iverilog -g2012 -o alu_sim tb/alu_tb.v rtl/alu.v && vvp alu_sim
iverilog -g2012 -o regfile_sim tb/register_file_tb.v rtl/register_file.v && vvp regfile_sim
iverilog -g2012 -o control_unit_sim tb/control_unit_tb.v rtl/control_unit.v && vvp control_unit_sim
iverilog -g2012 -o pc_sim tb/pc_tb.v rtl/pc.v && vvp pc_sim
iverilog -g2012 -o instruction_memory_sim tb/instruction_memory_tb.v rtl/instruction_memory.v && vvp instruction_memory_sim
iverilog -g2012 -o data_memory_sim tb/data_memory_tb.v rtl/data_memory.v && vvp data_memory_sim
iverilog -g2012 -o datapath_sim tb/datapath_tb.v rtl/datapath.v rtl/control_unit.v rtl/register_file.v rtl/alu.v && vvp datapath_sim
iverilog -g2012 -o cpu_sim tb/mips32_cpu_tb.v rtl/*.v && vvp cpu_sim

Understand the testbenches

Verification is layered:

Level What it proves
ALU test Operations and zero flag
Register-file test Reads, writes, reset, and $zero
Control-unit test Decoding and safe defaults
PC test Reset and next-PC loading
Instruction-memory test Alignment, bounds, and reads
Data-memory test Reads, writes, reset, alignment, and bounds
Datapath test Muxes, write-back, branches, jumps, and memory interface
CPU test Complete program execution

Each testbench is an executable specification. Read the test before the RTL when a module feels unfamiliar: the checks explain what behavior the module promises.

More detail is available in docs/verification.md.


What this project does not cover

This processor is intentionally small. It does not yet include:

  • pipelining;
  • forwarding or hazard detection;
  • caches;
  • exceptions and interrupts;
  • privileged modes or operating systems;
  • coprocessors;
  • branch delay slots;
  • arithmetic overflow exceptions;
  • a real memory bus or memory controller;
  • synthesis-specific timing constraints.

These are not missing prerequisites for understanding this repository. They are the next chapters after the single-cycle design becomes familiar.


Contributing and testing an instruction

Adding a new instruction should follow the same hardware-and-verification pattern used throughout the repository:

  1. Add the instruction encoding and expected behavior to docs/instruction-set.md.
  2. Extend rtl/control_unit.v with the required opcode/function decoding and control signals. Keep default behavior safe for unsupported instructions.
  3. Implement or adjust the datapath in rtl/datapath.v if the instruction needs new operand, write-back, memory, or PC behavior.
  4. Add focused RTL tests to tb/control_unit_tb.v, tb/datapath_tb.v, or the relevant unit testbench, then add an integration program to tb/mips32_cpu_tb.v.
  5. Run the relevant testbench first, followed by the complete CPU test with both Icarus Verilog and, where available, Verilator.
  6. Update the supported-instruction table and documentation diagrams when the design changes.

New instructions should include positive behavior checks, $zero behavior, alignment or invalid-address cases where relevant, and an unchanged-CPU-state check for unsupported or malformed instructions.


Further reading

References

  1. MIPS Technologies, Inc., MIPS32 Architecture For Programmers Volume I: Introduction to the MIPS32 Architecture, Revision 2.60, MD00082. PDF mirror
  2. MIPS Technologies, Inc., MIPS32 Architecture For Programmers Volume II: The MIPS32 Instruction Set, Revision 2.00, MD00086. Internet Archive record
  3. IEEE, IEEE Standard for Verilog Hardware Description Language, IEEE Std 1364-2005. IEEE standard
  4. IEEE, IEEE Standard for SystemVerilog—Unified Hardware Design, Specification, and Verification Language, IEEE Std 1800-2017. IEEE standard
  5. David A. Patterson and John L. Hennessy, Computer Organization and Design RISC-V Edition: The Hardware/Software Interface, 2nd ed., Morgan Kaufmann, 2021. Publisher page

License

See LICENSE.

About

MIPS32 single cycle processor implemented in Verilog to demonstrate core CPU architecture concepts.

Topics

Resources

Stars

1 star

Watchers

1 watching

Forks

Contributors

Languages