Cycle delay fix

.gitignore

@@ -369,3 +369,7 @@ riscof_work/
 .ammonite/
 metals.sbt
 mem_data/
+
+.docs_venv/
+docs/_build/
+

.readthedocs.yaml

@@ -0,0 +1,27 @@
+# Read the Docs configuration file
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+# Required
+version: 2
+
+# Set the OS, Python version, and other tools you might need
+build:
+  os: ubuntu-24.04
+  tools:
+    python: "3.11"
+
+# Build documentation in the "docs/" directory with Sphinx
+sphinx:
+   configuration: docs/conf.py
+
+python:
+  install:
+    - requirements: docs/requirements.txt
+
+# Optionally, but recommended,
+# declare the Python requirements required to build your documentation
+# See https://docs.readthedocs.io/en/stable/guides/reproducible-builds.html
+# python:
+#    install:
+#    - requirements: docs/requirements.txt
+

docs/Makefile

@@ -1,4 +1,3 @@
-
 # Minimal makefile for Sphinx documentation
 #
 
@@ -7,7 +6,7 @@
 SPHINXOPTS    ?=
 SPHINXBUILD   ?= sphinx-build
 SOURCEDIR     = .
-BUILDDIR      = build
+BUILDDIR      = _build
 
 # Put it first so that "make" without argument is like "make help".
 help:

docs/concepts/configuration.rst

@@ -0,0 +1,51 @@
+Configuring NucleusRV: Extensions and Core Options
+==================================================
+
+NucleusRV is highly configurable via the ``Configs`` case class in Scala/Chisel.
+
+The Configs Case Class
+----------------------
+
+.. code-block:: scala
+
+   case class Configs(
+     XLEN : Int = 32,
+     M : Boolean = true,
+     F : Boolean = true,
+     C : Boolean = false,
+     A : Boolean = true,
+     Zicsr : Boolean = true,
+     TRACE : Boolean = true,
+     HARTID : Int = 1,
+     ARCHID : Int = 1
+   )
+
+Parameter Reference
+-------------------
+
+- ``XLEN``: Data width (currently only 32 is supported).
+- ``M``: Enable/Disable Integer Multiply/Divide.
+- ``F``: Enable/Disable Floating-Point Unit.
+- ``C``: Enable/Disable Compressed instruction support.
+- ``A``: Enable/Disable Atomic Memory Operations.
+- ``Zicsr``: Enable/Disable CSR instructions.
+- ``TRACE``: Enable/Disable RVFI tracing (useful for verification).
+- ``HARTID``: Hardware Thread ID (drives ``mhartid`` CSR).
+- ``ARCHID``: Architecture ID (drives ``marchid`` CSR).
+
+Instantiating with Custom Configuration
+--------------------------------------
+
+In your top-level Chisel module, you can instantiate the core with a custom config:
+
+.. code-block:: scala
+
+   implicit val config: Configs = Configs(M = true, C = true, TRACE = false)
+   val core = Module(new Core())
+
+Common Configurations
+---------------------
+
+- **Minimal RV32I**: Disable all optional extensions to minimize area.
+- **Full RV32IMAFC**: Enable all supported extensions.
+- **Synthesis Config**: Disable ``TRACE`` when synthesizing for hardware to save area.

docs/concepts/isa-support.rst

@@ -0,0 +1,43 @@
+RISC-V ISA Extensions Supported by NucleusRV
+==========================================
+
+NucleusRV implements the RV32IMAFC instruction set.
+
+Supported Extensions
+--------------------
+
+- **I (Base Integer)**: Always enabled. Includes ALU, Load/Store, and Branch instructions.
+- **M (Integer Multiply/Divide)**: Configurable. Implements multiplication and division.
+- **A (Atomic Memory Operations)**: Configurable. Implements Load-Reserved/Store-Conditional and Atomic Memory Operations.
+- **F (Single-Precision Floating-Point)**: Configurable. Implements IEEE 754 floating-point instructions.
+- **C (Compressed Instructions)**: Configurable. Implements 16-bit compressed instructions to reduce code size.
+- **Zicsr (CSR Instructions)**: Configurable. Enables access to Control and Status Registers.
+
+Extension Details
+-----------------
+
+M Extension
+~~~~~~~~~~~
+- Multiplier: Single-cycle multiplication.
+- Divider: Multi-cycle (up to 34 cycles) division/remainder unit.
+
+A Extension
+~~~~~~~~~~~
+- LR.W / SC.W: Implemented using a reservation file.
+- AMOs: Two-cycle read-modify-write sequence.
+
+C Extension
+~~~~~~~~~~~
+- Realigner: Handles misaligned instruction boundaries.
+- CompressedDecoder: Expands 16-bit instructions to 32-bit equivalents.
+
+MISA Register
+-------------
+
+The ``misa`` register reports the supported extensions based on the core configuration.
+The extensions bits are:
+- Bit 8 (I): Base Integer.
+- Bit 12 (M): Multiplication.
+- Bit 0 (A): Atomics.
+- Bit 5 (F): Floating-Point.
+- Bit 2 (C): Compressed.

docs/concepts/memory-interface.rst

@@ -0,0 +1,36 @@
+NucleusRV Memory Interface: Instruction and Data Ports
+======================================================
+
+NucleusRV uses separate instruction and data memory ports (Harvard architecture) based on a simple Decoupled request/response protocol.
+
+Bundle Definitions
+------------------
+
+The memory interface uses ``MemRequestIO`` and ``MemResponseIO`` bundles wrapped in ``Decoupled`` interfaces.
+
+MemRequestIO Fields
+~~~~~~~~~~~~~~~~~~~
+
+- ``addrRequest``: 32-bit byte address.
+- ``dataRequest``: 32-bit write data (ignored on reads).
+- ``activeByteLane``: 4-bit byte-enable mask.
+- ``isWrite``: 1 for write, 0 for read.
+
+MemResponseIO Fields
+~~~~~~~~~~~~~~~~~~~~
+
+- ``dataResponse``: 32-bit read data.
+
+Handshake Protocol
+------------------
+
+A transaction occurs when both ``valid`` and ``ready`` are asserted on the same clock edge.
+
+- **Request**: Core drives ``valid`` and request fields; Memory drives ``ready``.
+- **Response**: Memory drives ``valid`` and ``dataResponse``; Core drives ``ready``.
+
+Timing
+------
+
+- **Instruction Port**: Fetches occur every cycle unless stalled or waiting for response.
+- **Data Port**: Stores and loads initiate in the EX/MEM stage transition and complete when ``dmemRsp.valid`` is asserted.

docs/concepts/pipeline.rst

@@ -0,0 +1,26 @@
+NucleusRV 5-Stage Pipeline Architecture
+=======================================
+
+NucleusRV uses a classic 5-stage pipeline to achieve balanced throughput and frequency.
+
+Pipeline Stages
+---------------
+
+1. **Instruction Fetch (IF)**: Fetches instructions from instruction memory. Includes the PC unit, Realigner, and Compressed Decoder.
+2. **Instruction Decode (ID)**: Decodes the instruction, reads the register file, and generates control signals. Includes the Immediate Generator and Hazard Unit.
+3. **Execute (EX)**: Performs ALU operations, multiplication, division, and floating-point operations. Handles data forwarding.
+4. **Memory (MEM)**: Accesses data memory for load and store instructions. Manages atomic memory operations.
+5. **Write-Back (WB)**: Writes results back to the register file.
+
+Hazard Handling
+---------------
+
+- **Data Hazards**: Handled via forwarding from EX and MEM stages to the ID stage.
+- **Load-Use Hazards**: Handled by stalling the pipeline for one cycle.
+- **Control Hazards**: Branches and jumps are resolved in the ID stage, resulting in a 1-cycle penalty for taken branches.
+- **Atomic Hazards**: Special handling for read-modify-write sequences in the MEM stage.
+
+Pipeline Registers
+------------------
+
+Inter-stage registers are named following the ``<stage>_reg_<signal>`` pattern (e.g., ``if_reg_pc``, ``ex_reg_result``).

docs/conf.py

@@ -1,35 +1,27 @@
 # Configuration file for the Sphinx documentation builder.
 
-# -- Project information
-
 project = 'NucleusRV'
-copyright = '2022, Usman Zain'
-author = 'Usman Zain'
+copyright = '2026, Kinza Fatima'
+author = 'Kinza Fatima'
 
 release = '0.1'
 version = '0.1.0'
 
-# -- General configuration
-
 extensions = [
     'sphinx.ext.duration',
     'sphinx.ext.doctest',
     'sphinx.ext.autodoc',
     'sphinx.ext.autosummary',
     'sphinx.ext.intersphinx',
+    'sphinx_copybutton',
 ]
 
-intersphinx_mapping = {
-    'python': ('https://docs.python.org/3/', None),
-    'sphinx': ('https://www.sphinx-doc.org/en/master/', None),
-}
-intersphinx_disabled_domains = ['std']
-
 templates_path = ['_templates']
-
-# -- Options for HTML output
+exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
 
 html_theme = 'sphinx_rtd_theme'
 
-# -- Options for EPUB output
-epub_show_urls = 'footnote'
+intersphinx_mapping = {
+    'python': ('https://docs.python.org/3/', None),
+    'sphinx': ('https://www.sphinx-doc.org/en/master/', None),
+}

docs/guides/arch-tests.rst

@@ -0,0 +1,37 @@
+Run RISC-V Architecture Compliance Tests
+========================================
+
+Validate NucleusRV against official RISC-V architectural test suites using the ``riscof`` framework.
+
+Setup the Environment
+---------------------
+
+1. Create a Python virtual environment:
+
+   .. code-block:: bash
+
+      python3 -m venv .venv
+      source .venv/bin/activate
+
+2. Install ``riscof`` and required plugins:
+
+   .. code-block:: bash
+
+      pip3 install git+https://github.com/riscv/riscof.git
+      pip3 install -e riscof/riscv-arch-test/riscv-ctg riscof/riscv-arch-test/riscv-isac
+
+Run the Tests
+-------------
+
+Execute the test runner script:
+
+.. code-block:: bash
+
+   python3 run_riscv_arch_tests.py
+
+This script invokes ``riscof``, which runs tests on both NucleusRV (the DUT) and Spike (the reference), comparing their memory signatures.
+
+Review Results
+--------------
+
+Results are stored in ``riscof/riscof_work/``. View the ``report.html`` file for a detailed pass/fail summary.

docs/guides/building-c-programs.rst

@@ -0,0 +1,32 @@
+Build and Run C Programs on NucleusRV
+=====================================
+
+NucleusRV includes a build system to compile C programs for the core.
+
+Create a Test Directory
+-----------------------
+
+Create a directory for your C project in ``tools/tests/``:
+
+.. code-block:: bash
+
+   mkdir tools/tests/my_test
+
+Add your C source files and a ``main.c``.
+
+Build with Make
+---------------
+
+Run ``make`` from the ``tools/`` directory:
+
+.. code-block:: bash
+
+   cd tools
+   make PROGRAM=my_test
+
+This will generate ``out/program.hex``, which you can use for simulation.
+
+Simulate
+--------
+
+Generate Verilog using ``NRVDriver`` and run with Verilator as described in the :doc:`../quickstart`.