An educational RV32I FPGA CPU/SoC project organized around the JYD RISC-V contest requirements.

This repository is an early-stage, educational, competition-oriented cleanup of a Vivado/SystemVerilog project. It is intended for learning digital design, computer organization, RV32I CPU structure, FPGA SoC integration, simulation, and reproducible Vivado project reconstruction.

This is an independent educational cleanup of a contest-oriented project. It is not an official JYD repository unless explicitly stated.

New to FPGA, Vivado, or this repository? Start with docs/getting-started.md.

• Scope: RV32I contest-oriented CPU/SoC for FPGA.
• RTL status: source files have been copied from the working project without changing CPU logic.
• Verification status: a private-memory XSim record observes the RV32I 37/37 display. The memory images are not included, so this is not a public no-memory reproduction artifact.
• Public smoke status: repository-owned public smoke memory images are included under tests/public-memory/. They are generated from tools/gen_public_smoke_memory.py and do not claim RV32I 37/37 coverage.
• Branch directed status: repository-owned branch directed memory images are generated under tests/branch-memory/ by tools/gen_branch_directed_memory.py. They require explicit JYD_MEMORY_PROFILE=branch selection and do not claim RV32I 37/37 coverage.
• Load/store directed status: repository-owned load/store directed memory images are generated under tests/load-store-memory/ by tools/gen_load_store_directed_memory.py. They require explicit JYD_MEMORY_PROFILE=load-store selection and do not claim RV32I 37/37 coverage.
• Project maturity: early-stage educational release, not an industrial-grade or fully verified core.

This project does not claim RV32IM support, full formal verification, production readiness, external user adoption, CI coverage beyond lightweight repository hygiene checks, releases, stars, or benchmark leadership.

The repository is currently suitable for a v0.1.0-preview milestone, not a formal stable release.

The preview includes public smoke, branch-directed, and load/store-directed XSim verification records. It does not include contest-private memory images, public RV32I 37/37 memory images, or official performance benchmark results.

This repository is suitable for public preview, but not yet a formal stable release. A private-memory XSim verification record observed seg_wdata = 32'h37000000, corresponding to the contest-style RV32I 37/37 display. The memory initialization files used for that run are not included or redistributed.

The repository also includes a public self-generated smoke memory image. It writes raw value 0x00000037 to SEG MMIO address 0x8020_0020 as a smoke-test marker. This marker is not an RV32I 37/37 instruction-test result.

The repository also includes a public self-generated branch directed memory image. It expects success SEG raw value 0x0000BEEF and failure SEG raw value 0x0000BAD0. This directed test is limited to basic branch behavior and is not complete RV32I verification.

The repository also includes a public self-generated load/store directed memory image. It expects success SEG raw value 0x0000C0DE and failure SEG raw value 0x0000BAD0. This directed test is limited to basic load/store byte, halfword, and word behavior and is not complete RV32I verification.

See docs/test-profiles.md for the public smoke, branch-directed, load/store-directed, and private contest-memory profile selection rules.

The referenced JYD contest requirements target the RV32I base integer ISA. The contest instruction test covers 37 instructions. fence, ebreak, and ecall are not tested by the contest and may be implemented as no-ops or documented as reserved behavior.

Memory and peripheral map summary:

See docs/memory-map.md for an editable Mermaid diagram and address table.

The CPU-facing interface includes cpu_rst, cpu_clk, irom_addr, irom_data, perip_addr, perip_wen, perip_mask, perip_wdata, and perip_rdata.

rtl/core/          CPU top-level and core logic
rtl/pipeline/      IFU, IDU, EXU, LSU, WBU, hazard, predictor, pipeline regs
rtl/soc/           top, student_top, peripheral bridge, DRAM driver
rtl/peripherals/   counter, UART, seven-segment display, twin controller
rtl/common/        small shared helper modules
tb/                XSim-oriented testbenches
fpga/constraints/  XDC constraints
fpga/ip/           Vivado XCI configuration files
fpga/ip-optional/  copied XCI files retained for audit, not imported by default
fpga/vivado/       project reconstruction Tcl
mem/               user-supplied memory initialization files
docs/              architecture, verification, Vivado, and release notes
scripts/           repository hygiene scripts
tests/public-smoke/ public RV32I smoke-test source
tests/public-memory/ generated public smoke-test COE files
tests/branch-directed/ public RV32I branch-directed source
tests/branch-memory/ generated branch-directed COE files
tests/load-store-directed/ public RV32I load/store directed source
tests/load-store-memory/ generated load/store directed COE files
tools/             repository utility scripts

1. Regenerate the public smoke memory images if needed:

python tools/gen_public_smoke_memory.py

The generated tests/public-memory/irom.coe and tests/public-memory/dram.coe files are public, repository-owned smoke images. Private memory files, if used, must live under mem/ as mem/irom.coe, mem/dram.coe, mem/IROM.mif, or mem/DRAM.mif, and must not be committed. 2. Run the clean-repository check:

powershell -ExecutionPolicy Bypass -File scripts/check_clean_repo.ps1

3. Recreate the Vivado project:

cd <repo-root>
source fpga/vivado/create_project.tcl

4. When mem/irom.coe and mem/dram.coe are present, the Tcl flow uses those private files first. Otherwise, it uses the public smoke files under tests/public-memory/ when they are present.

Use this path when you do not have private contest memory files.

python tools/gen_public_smoke_memory.py
vivado -mode batch -source fpga/vivado/create_project.tcl

When mem/irom.coe and mem/dram.coe are absent, the Vivado reconstruction script uses the public smoke memory under tests/public-memory/ by default. The expected public smoke SEG raw marker is 0x00000037.

This marker is only a minimal public smoke-test observation. It is not an RV32I 37/37 instruction-test result.

For the full memory selection priority across all public and private profiles, see docs/test-profiles.md.

To run the public branch directed memory instead of the default public smoke memory, regenerate the branch memory and explicitly select the branch profile:

python tools/gen_branch_directed_memory.py
$env:JYD_MEMORY_PROFILE = "branch"
vivado -mode batch -source fpga/vivado/create_project.tcl

To run the public load/store directed memory instead of the default public smoke memory, regenerate the load/store memory and explicitly select the load-store profile:

python tools/gen_load_store_directed_memory.py
$env:JYD_MEMORY_PROFILE = "load-store"
vivado -mode batch -source fpga/vivado/create_project.tcl

This repository includes a lightweight GitHub Actions workflow for repository hygiene checks.

The current CI checks:

• repository cleanliness using scripts/check_clean_repo.ps1
• whitespace issues in tracked files using git diff --check

The current CI does not run Vivado, XSim, synthesis, implementation, bitstream generation, FPGA board tests, or RV32I correctness verification. Hardware and CPU correctness evidence must be documented separately in verification records.

The recommended entry point is fpga/vivado/create_project.tcl. It uses relative paths, adds RTL, testbench files, XDC constraints, and the checked-in XCI files, then sets top as the synthesis top and tb_top as the simulation top.

Prerequisites:

• Vivado installed and available from Vivado Tcl shell or command line.
• FPGA part support for xc7k325tffg900-2.
• User-provided memory initialization files when running program-dependent simulation or implementation.
• A reasonably short local checkout path is recommended because Vivado warns on long Windows paths.

If an IP cannot regenerate in a fresh Vivado installation, update the Tcl script with explicit IP creation commands and document the required parameters. Do not commit generated IP output directories.

The script creates local build output under build/vivado. This directory is ignored and should not be committed.

The script currently imports the IPs instantiated by the copied RTL: IROM, DRAM, and pll. The default PLL source is fpga/ip-optional/pll_1/pll.xci because it provides both clk_out1 and clk_out2, matching rtl/soc/top.sv. Additional copied XCI files under fpga/ip-optional/ are retained for audit but are not imported by default unless their need and IP repository requirements are confirmed.

The reconstruction script prefers private mem/irom.coe and mem/dram.coe files when they are present. If those private files are absent, it uses the public smoke memory images under tests/public-memory/ by default. Set JYD_MEMORY_PROFILE=branch to explicitly use public branch directed memory under tests/branch-memory/, or JYD_MEMORY_PROFILE=load-store to explicitly use public load/store directed memory under tests/load-store-memory/. If the selected source is unavailable, it warns that simulation may not run meaningful CPU code.

Current testbenches:

• tb/tb_myCPU.sv
• tb/tb_top.sv
• tb/tb_uart.sv

The original working directory contained XSim output and waveform files, but generated simulation products are intentionally excluded. See docs/simulation.md for the intended workflow.

The expected verification target is:

• RV32I instruction test: 37/37 pass.
• Performance test: correct computation result and counter display.
• Display behavior: SEG and LED output match the contest requirement.

The repository includes a private-memory XSim verification record observing seg_wdata = 32'h37000000, interpreted as the RV32I 37/37 display. The private memory images are excluded from Git. The public smoke memory writes raw value 0x00000037 to SEG as a minimal path marker only; it is not an RV32I 37/37 result. The public branch directed memory writes 0x0000BEEF on success and 0x0000BAD0 on failure for directed branch cases only. The public load/store directed memory writes 0x0000C0DE on success and 0x0000BAD0 on failure for directed load/store cases only. See docs/verification.md and docs/verification-record-template.md for the evidence format.

The performance counter is memory-mapped at 0x8020_0050. According to the contest specification, writing 0x8000_0000 to the counter address starts counting, and writing 0xFFFF_FFFF ends counting.

The current repository still needs RTL-level and simulation-level evidence proving that the implementation fully matches that specification. Seven-segment display timing in milliseconds is part of the contest output behavior.

Performance numbers are not claimed unless accompanied by a verification record that identifies the commit hash, memory image source, environment, and whether the result came from simulation or a board run. See docs/performance.md and docs/performance-verification-template.md.

No official performance number is included yet.

• Confirm file licensing.
• Keep the private-memory XSim verification record, and add a public-memory or authorized-memory release record before a formal release.
• Validate fpga/vivado/create_project.tcl on a clean machine.
• Run scripts/check_clean_repo.ps1.
• Review docs/packaging.md before creating a source archive.
• Confirm XCI/IP regeneration.

• Do not commit generated Vivado artifacts.
• Do not commit contest memory images unless redistribution rights are confirmed.
• Do not hard-code behavior for fixed IROM/DRAM programs.

• Private contest memory initialization files are excluded pending authorization review.
• Private-memory XSim reached the RV32I 37/37 display, but the public repository still does not include redistributable memory images.
• Public smoke memory is self-generated from repository-owned source and only checks a minimal reproducible path.
• Public branch directed memory is self-generated from repository-owned source and only checks selected branch cases.
• Public load/store directed memory is self-generated from repository-owned source and only checks selected load/store cases.
• XCI files may still require manual Vivado/IP validation.
• The checked-in Vivado .xci files are included for public-preview reconstruction convenience. Their source and redistribution status still require human confirmation before a formal release. Generated Vivado IP outputs are intentionally excluded.
• CI is limited to lightweight repository hygiene and whitespace checks.
• Some testbench comments may contain encoding artifacts inherited from the working project.
• Licensing of XDC, XCI, testbench, and memory material must be confirmed before a public release.
• The FPGA constraint file is included for public-preview reconstruction convenience, but its source and redistribution status still require human confirmation before a formal release.

See docs/roadmap.md.

Contributions should include clear verification evidence and must not target fixed test programs with hard-coded behavior. See CONTRIBUTING.md.

The repository uses the MIT License for files confirmed as original project work. Contest-provided materials, generated Vivado files, memory initialization programs, and third-party code are excluded unless redistribution rights are confirmed.

See THIRD_PARTY_NOTICES.md for current licensing cautions and files requiring human confirmation.