Add FPGA project workspace layout

FPGA/README.md

@@ -0,0 +1,4 @@
+# FPGA/
+
+Everything that ends up on the FPGA: SystemVerilog source, testbenches,
+constraints, memory init files, and the Vivado project.

FPGA/constraints/README.md

@@ -0,0 +1,4 @@
+# FPGA/constraints/
+
+Vivado XDC constraint files: pin assignments for the Arty A7, clock
+definitions, and timing constraints.

FPGA/mem/README.md

@@ -0,0 +1,4 @@
+# FPGA/mem/
+
+BRAM init files (`.mem`) in hex format, one 32-bit word per line. Loaded by
+`$readmemh` into instruction/data BRAM at elaboration.

FPGA/rtl/README.md

@@ -0,0 +1,4 @@
+# FPGA/rtl/
+
+Synthesizable SystemVerilog source. One module per file, filename matches
+module name (e.g. `rv32_alu.sv`).

FPGA/rtl/core/README.md

@@ -0,0 +1,4 @@
+# FPGA/rtl/core/
+
+CPU core modules: ALU, M unit, decoder, register file, fetch, LSU, datapath,
+and (later) CSR file and MMU. Module names follow `rv32_<block>`.

FPGA/rtl/periph/README.md

@@ -0,0 +1,4 @@
+# FPGA/rtl/periph/
+
+Memory-mapped peripherals: UART (Phase 7), CLINT timer (Phase 13), PLIC
+(Phase 14), and any future devices. Each peripheral is a slave on the D-bus.

FPGA/rtl/pkg/README.md

@@ -0,0 +1,4 @@
+# FPGA/rtl/pkg/
+
+Shared SystemVerilog packages — the type contract for the design.
+`rv32_pkg.sv` (enums, stage-boundary structs, bus payloads) lives here.

FPGA/rtl/top/README.md

@@ -0,0 +1,5 @@
+# FPGA/rtl/top/
+
+Top-level modules and SoC integration: clock/reset wrapping (MMCM, reset
+synchronizer), bus arbitration, address decode, and the board-level top that
+maps to the Arty A7 pins.

FPGA/tb/README.md

@@ -0,0 +1,4 @@
+# FPGA/tb/
+
+SystemVerilog testbenches, one per module under test. Naming: `tb_<module>.sv`.
+Run with the Vivado simulator (xsim).

FPGA/vivado/.gitignore

@@ -0,0 +1,34 @@
+# Vivado-generated project state. The committed source of truth is
+# create_project.tcl — everything below (including the .xpr itself, which
+# embeds machine-specific paths) is regenerated by running that script.
+
+# The project file itself — regenerated from create_project.tcl
+*.xpr
+
+# Project-wide generated directories (named after the .xpr basename)
+*.cache/
+*.hw/
+*.sim/
+*.runs/
+*.ip_user_files/
+*.gen/
+*.srcs/
+
+# Vivado scratch / temp
+.Xil/
+xsim.dir/
+
+# Logs, journals, autosave backups
+*.jou
+*.log
+*.str
+*.backup.*
+*.wdb
+*.pb
+vivado*.jou
+vivado*.log
+
+# Webtalk telemetry
+webtalk*.jou
+webtalk*.log
+usage_statistics_webtalk.*

FPGA/vivado/README.md

@@ -0,0 +1,19 @@
+# FPGA/vivado/
+
+The Vivado project workspace. The committed source of truth is
+`create_project.tcl`; the project file (`FPGA-Core.xpr`) and all of Vivado's
+generated state (`*.runs/`, `*.cache/`, `*.hw/`, `*.sim/`, `*.ip_user_files/`,
+`*.gen/`, `*.srcs/`) are git-ignored — `.xpr` files embed machine-specific
+paths and are regenerated locally.
+
+RTL and testbench files are added to the project as **references** to
+`../rtl/...` / `../tb/...` so the actual source of truth stays in version
+control, not inside the project file.
+
+To generate the project, run from the repo root:
+
+```sh
+vivado -mode batch -source FPGA/vivado/create_project.tcl
+```
+
+Then open the resulting `FPGA/vivado/FPGA-Core.xpr` in the Vivado GUI.

FPGA/vivado/create_project.tcl

@@ -0,0 +1,43 @@
+# create_project.tcl — generate FPGA/vivado/FPGA-Core.xpr
+#
+# Usage (from the repo root):
+#   vivado -mode batch -source FPGA/vivado/create_project.tcl
+#
+# Or from inside FPGA/vivado/:
+#   vivado -mode batch -source create_project.tcl
+#
+# Then open the resulting .xpr in the Vivado GUI. To regenerate from scratch,
+# delete FPGA-Core.xpr and its sibling *.cache / *.runs / *.hw / *.sim /
+# *.ip_user_files / *.gen directories, then re-run.
+
+set script_dir [file normalize [file dirname [info script]]]
+set fpga_dir   [file normalize "$script_dir/.."]
+set proj_name  "FPGA-Core"
+set part       "xc7a100tcsg324-1"
+
+if {[file exists "$script_dir/$proj_name.xpr"]} {
+    puts "Project already exists: $script_dir/$proj_name.xpr"
+    puts "Delete it (and its sibling *.cache, *.runs, ... dirs) first."
+    return
+}
+
+create_project $proj_name $script_dir -part $part
+
+set_property target_language    Verilog [current_project]
+set_property simulator_language Mixed   [current_project]
+
+# RTL and testbenches are added as references (not copied) so the source of
+# truth stays in git, not inside the .xpr. Passing a directory makes Vivado
+# recursively pick up all HDL files under it.
+add_files                "$fpga_dir/rtl"
+add_files -fileset sim_1 "$fpga_dir/tb"
+
+set xdc_files [glob -nocomplain "$fpga_dir/constraints/*.xdc"]
+if {[llength $xdc_files] > 0} {
+    add_files -fileset constrs_1 $xdc_files
+}
+
+update_compile_order -fileset sources_1
+update_compile_order -fileset sim_1
+
+puts "Created $script_dir/$proj_name.xpr"