# poornachandra-29/coa architecture

> Architecture diagram of the GitHub repository poornachandra-29/coa, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-11). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/poornachandra-29/coa
- Repository: https://github.com/poornachandra-29/coa

## Overview

This repository implements a five-stage pipelined CPU for a small MIPS-like ISA, with assembler and reference-model tools. The principal workflow is instruction fetch, decode, execute, memory access, and write-back; hazard detection, forwarding, and pipeline registers preserve correctness across stages. The datapath relationships below are based on the architecture depicted in `tools/make_diagram.py`; RTL source was not sampled, so implementation details beyond that diagram are not asserted.

Main entry points: [`pipeline_cpu/src/pipeline_id_ex.v`](https://github.com/poornachandra-29/coa/blob/main/pipeline_cpu/src/pipeline_id_ex.v) (ID/EX register), [`pipeline_cpu/src/pipeline_if_id.v`](https://github.com/poornachandra-29/coa/blob/main/pipeline_cpu/src/pipeline_if_id.v) (IF/ID register), [`pipeline_cpu/src/pipeline_mem_wb.v`](https://github.com/poornachandra-29/coa/blob/main/pipeline_cpu/src/pipeline_mem_wb.v) (MEM/WB register), [`pipeline_cpu/src/pipeline_ex_mem.v`](https://github.com/poornachandra-29/coa/blob/main/pipeline_cpu/src/pipeline_ex_mem.v) (EX/MEM register)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_fetch_decode["Fetch and Decode"]
  node_pc["Program counter<br/>[program_counter.v]"]
  node_instruction_memory[("Instruction memory")]
  node_if_id["IF/ID register<br/>[pipeline_if_id.v]"]
  node_control_unit["Control unit<br/>[control_unit.v]"]
  node_register_file[("Register file<br/>[register_file.v]")]
  node_sign_extend["Sign extension<br/>[sign_extend.v]"]
end

subgraph group_execute_control["Execute and Control"]
  node_hazard_unit["Hazard detection"]
  node_id_ex["ID/EX register<br/>[pipeline_id_ex.v]"]
  node_forwarding_unit["Forwarding unit<br/>[forwarding_unit.v]"]
  node_alu_control["ALU control<br/>[alu_control.v]"]
  node_alu["ALU<br/>[alu.v]"]
  node_mux2["2-way muxes<br/>[mux2.v]"]
  node_mux3["3-way muxes<br/>[mux3.v]"]
end

subgraph group_memory_writeback["Memory and Writeback"]
  node_ex_mem["EX/MEM register<br/>[pipeline_ex_mem.v]"]
  node_data_memory[("Data memory<br/>[data_memory.v]")]
  node_mem_wb["MEM/WB register<br/>[pipeline_mem_wb.v]"]
end

subgraph group_program_tools["Program Tools"]
  node_assembler["Assembler<br/>[assemble.py]"]
  node_golden_model["ISA reference model<br/>[golden.py]"]
end

node_user(("Program author"))
node_program_image["Program image"]

node_user -->|"writes source"| node_assembler
node_assembler -->|"emits image"| node_program_image
node_pc -->|"addresses"| node_instruction_memory
node_instruction_memory -->|"passes instruction"| node_if_id
node_if_id -->|"supplies instruction"| node_control_unit
node_if_id -->|"selects registers"| node_register_file
node_if_id -->|"supplies immediate"| node_sign_extend
node_control_unit -->|"passes controls"| node_id_ex
node_register_file -->|"passes operands"| node_id_ex
node_sign_extend -->|"passes immediate"| node_id_ex
node_hazard_unit -->|"stalls fetch"| node_pc
node_hazard_unit -->|"holds or flushes"| node_if_id
node_hazard_unit -->|"inserts bubble"| node_id_ex
node_id_ex -->|"supplies operation"| node_alu_control
node_id_ex -->|"supplies register IDs"| node_forwarding_unit
node_forwarding_unit -->|"selects operands"| node_mux3
node_id_ex -->|"supplies immediate"| node_mux2
node_mux3 -->|"provides forwarded inputs"| node_alu
node_mux2 -->|"selects operand B"| node_alu
node_alu_control -->|"controls operation"| node_alu
node_alu -->|"passes result"| node_ex_mem
node_ex_mem -->|"accesses memory"| node_data_memory
node_ex_mem -->|"passes ALU result"| node_mem_wb
node_data_memory -->|"passes read data"| node_mem_wb
node_mem_wb -->|"selects writeback data"| node_mux2
node_mem_wb -->|"writes registers"| node_register_file
node_ex_mem -->|"provides result"| node_forwarding_unit
node_mem_wb -->|"provides writeback data"| node_forwarding_unit
node_golden_model -->|"reads image"| node_program_image

click node_assembler "https://github.com/poornachandra-29/coa/blob/main/pipeline_cpu/tools/assemble.py"
click node_program_image "https://github.com/poornachandra-29/coa/tree/main/pipeline_cpu/programs"
click node_golden_model "https://github.com/poornachandra-29/coa/blob/main/pipeline_cpu/tools/golden.py"
click node_pc "https://github.com/poornachandra-29/coa/blob/main/pipeline_cpu/src/program_counter.v"
click node_instruction_memory "https://github.com/poornachandra-29/coa/blob/main/pipeline_cpu/src/instruction_memory.v"
click node_if_id "https://github.com/poornachandra-29/coa/blob/main/pipeline_cpu/src/pipeline_if_id.v"
click node_control_unit "https://github.com/poornachandra-29/coa/blob/main/pipeline_cpu/src/control_unit.v"
click node_register_file "https://github.com/poornachandra-29/coa/blob/main/pipeline_cpu/src/register_file.v"
click node_sign_extend "https://github.com/poornachandra-29/coa/blob/main/pipeline_cpu/src/sign_extend.v"
click node_hazard_unit "https://github.com/poornachandra-29/coa/blob/main/pipeline_cpu/src/hazard_detection_unit.v"
click node_id_ex "https://github.com/poornachandra-29/coa/blob/main/pipeline_cpu/src/pipeline_id_ex.v"
click node_forwarding_unit "https://github.com/poornachandra-29/coa/blob/main/pipeline_cpu/src/forwarding_unit.v"
click node_alu_control "https://github.com/poornachandra-29/coa/blob/main/pipeline_cpu/src/alu_control.v"
click node_alu "https://github.com/poornachandra-29/coa/blob/main/pipeline_cpu/src/alu.v"
click node_ex_mem "https://github.com/poornachandra-29/coa/blob/main/pipeline_cpu/src/pipeline_ex_mem.v"
click node_data_memory "https://github.com/poornachandra-29/coa/blob/main/pipeline_cpu/src/data_memory.v"
click node_mem_wb "https://github.com/poornachandra-29/coa/blob/main/pipeline_cpu/src/pipeline_mem_wb.v"
click node_mux2 "https://github.com/poornachandra-29/coa/blob/main/pipeline_cpu/src/mux2.v"
click node_mux3 "https://github.com/poornachandra-29/coa/blob/main/pipeline_cpu/src/mux3.v"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_pc,node_instruction_memory,node_if_id,node_control_unit,node_register_file,node_sign_extend toneBlue
class node_hazard_unit,node_id_ex,node_forwarding_unit,node_alu_control,node_alu,node_mux2,node_mux3 toneAmber
class node_ex_mem,node_data_memory,node_mem_wb toneMint
class node_assembler,node_golden_model toneRose
class node_user toneIndigo
class node_program_image toneTeal
```

## Components

### Fetch and Decode

- [Program counter](https://github.com/poornachandra-29/coa/blob/main/pipeline_cpu/src/program_counter.v): `pipeline_cpu/src/program_counter.v`
- [Instruction memory](https://github.com/poornachandra-29/coa/blob/main/pipeline_cpu/src/instruction_memory.v): `pipeline_cpu/src/instruction_memory.v`
- [IF/ID register](https://github.com/poornachandra-29/coa/blob/main/pipeline_cpu/src/pipeline_if_id.v): `pipeline_cpu/src/pipeline_if_id.v`
- [Control unit](https://github.com/poornachandra-29/coa/blob/main/pipeline_cpu/src/control_unit.v): `pipeline_cpu/src/control_unit.v`
- [Register file](https://github.com/poornachandra-29/coa/blob/main/pipeline_cpu/src/register_file.v): `pipeline_cpu/src/register_file.v`
- [Sign extension](https://github.com/poornachandra-29/coa/blob/main/pipeline_cpu/src/sign_extend.v): `pipeline_cpu/src/sign_extend.v`

### Execute and Control

- [Hazard detection](https://github.com/poornachandra-29/coa/blob/main/pipeline_cpu/src/hazard_detection_unit.v): `pipeline_cpu/src/hazard_detection_unit.v`
- [ID/EX register](https://github.com/poornachandra-29/coa/blob/main/pipeline_cpu/src/pipeline_id_ex.v): `pipeline_cpu/src/pipeline_id_ex.v`
- [Forwarding unit](https://github.com/poornachandra-29/coa/blob/main/pipeline_cpu/src/forwarding_unit.v): `pipeline_cpu/src/forwarding_unit.v`
- [ALU control](https://github.com/poornachandra-29/coa/blob/main/pipeline_cpu/src/alu_control.v): `pipeline_cpu/src/alu_control.v`
- [ALU](https://github.com/poornachandra-29/coa/blob/main/pipeline_cpu/src/alu.v): `pipeline_cpu/src/alu.v`
- [2-way muxes](https://github.com/poornachandra-29/coa/blob/main/pipeline_cpu/src/mux2.v): `pipeline_cpu/src/mux2.v`
- [3-way muxes](https://github.com/poornachandra-29/coa/blob/main/pipeline_cpu/src/mux3.v): `pipeline_cpu/src/mux3.v`

### Memory and Writeback

- [EX/MEM register](https://github.com/poornachandra-29/coa/blob/main/pipeline_cpu/src/pipeline_ex_mem.v): `pipeline_cpu/src/pipeline_ex_mem.v`
- [Data memory](https://github.com/poornachandra-29/coa/blob/main/pipeline_cpu/src/data_memory.v): `pipeline_cpu/src/data_memory.v`
- [MEM/WB register](https://github.com/poornachandra-29/coa/blob/main/pipeline_cpu/src/pipeline_mem_wb.v): `pipeline_cpu/src/pipeline_mem_wb.v`

### Program Tools

- [Assembler](https://github.com/poornachandra-29/coa/blob/main/pipeline_cpu/tools/assemble.py): `pipeline_cpu/tools/assemble.py`
- [ISA reference model](https://github.com/poornachandra-29/coa/blob/main/pipeline_cpu/tools/golden.py): `pipeline_cpu/tools/golden.py`

### Other components

- **Program author**
- [Program image](https://github.com/poornachandra-29/coa/tree/main/pipeline_cpu/programs): `pipeline_cpu/programs`

## Connections

- Program author → Assembler: writes source (evidence: `pipeline_cpu/tools/assemble.py`)
- Assembler → Program image: emits image (evidence: `pipeline_cpu/tools/assemble.py`)
- Program counter → Instruction memory: addresses
- Instruction memory → IF/ID register: passes instruction
- IF/ID register → Control unit: supplies instruction
- IF/ID register → Register file: selects registers
- IF/ID register → Sign extension: supplies immediate
- Control unit → ID/EX register: passes controls
- Register file → ID/EX register: passes operands
- Sign extension → ID/EX register: passes immediate
- Hazard detection → Program counter: stalls fetch
- Hazard detection → IF/ID register: holds or flushes
- Hazard detection → ID/EX register: inserts bubble
- ID/EX register → ALU control: supplies operation
- ID/EX register → Forwarding unit: supplies register IDs
- Forwarding unit → 3-way muxes: selects operands
- ID/EX register → 2-way muxes: supplies immediate
- 3-way muxes → ALU: provides forwarded inputs
- 2-way muxes → ALU: selects operand B
- ALU control → ALU: controls operation
- ALU → EX/MEM register: passes result
- EX/MEM register → Data memory: accesses memory
- EX/MEM register → MEM/WB register: passes ALU result
- Data memory → MEM/WB register: passes read data
- MEM/WB register → 2-way muxes: selects writeback data
- MEM/WB register → Register file: writes registers
- EX/MEM register → Forwarding unit: provides result
- MEM/WB register → Forwarding unit: provides writeback data
- ISA reference model → Program image: reads image (evidence: `pipeline_cpu/tools/golden.py`)