mrve32 0.1.0__tar.gz

mrve32-0.1.0/.gitignore

@@ -0,0 +1,10 @@
+/target
+*.so
+*.pyd
+__pycache__/
+*.pyc
+.pytest_cache/
+/fuzz/target
+/fuzz/corpus
+/fuzz/artifacts
+/fuzz/coverage

mrve32-0.1.0/CHANGELOG.md

@@ -0,0 +1,62 @@
+# Changelog
+
+All notable changes to this project are documented in this file. The format
+is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and the
+project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html)
+(before 1.0, a minor version bump may contain breaking changes).
+
+The Rust crates (`mrve32`, `mrve32-snn`) and the Python packages of the same
+names share version numbers. The device C ABI (`include/mrve32_device.h`) is
+versioned separately by `MRVE32_DEVICE_ABI_VERSION`.
+
+To release: rename `[Unreleased]` to `[X.Y.Z] - YYYY-MM-DD`, set the same
+version in both `Cargo.toml` files, and push a `vX.Y.Z` tag (see
+`.github/workflows/release.yml`).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-11-03
+
+First public release.
+
+### Added
+
+- RV32IMAC + Zicsr + Zifencei hart, machine mode only: precise exceptions
+  (`mcause`/`mepc`/`mtval`), strict CSR access checks, WARL fields,
+  IALIGN 16/32 (C can be disabled at runtime, `misa.C`).
+- RV32A: LR/SC with a single-hart reservation, all AMOs; misaligned atomics
+  raise address-misaligned exceptions. Failing `sc.w` to unmapped address faults.
+- RV32C (Zca) with variable-length fetch; fetch faults report the failing
+  half.
+- Interrupts: machine timer/software/external, `WFI` with idle detection,
+  `mcycle`/`minstret` and their unprivileged shadows, `mcountinhibit`.
+- Pluggable devices: the `BusDevice` trait (read/write, `tick`, IRQ lines,
+  exit requests, `is_mapped`); a versioned C ABI (version 2) and `ForeignDevice`
+  for devices built as separate native libraries; Python devices.
+- Standard peripherals with a QEMU `virt`-like map: RAM, CLINT, NS16550A
+  UART subset, `sifive,test0` test finisher.
+- Coprocessor slot for custom-0/custom-1 instructions (`trait Coprocessor`,
+  or a Python object via `Emulator.set_coprocessor`), with atomic register
+  commit.
+- `Machine`: breakpoints, tracing hook, `run_until` with stop reasons
+  (step limit, breakpoint, trap, idle, exit, abort).
+- ELF32 loader with symbols.
+- GNU objdump-compatible disassembler (pseudo-instructions, all standard
+  CSR names), checked against binutils 2.46 over the whole 16-bit space and
+  random 32-bit words.
+- `mrve32` command-line runner: UART console, finisher exit codes,
+  `--trace`, `--stats`, `--isa rv32imac|rv32ima`, configurable memory map,
+  `--htif` (HTIF `tohost` exit and console) and `--signature FILE`
+  (Sail-format signature dump) for compliance suites.
+- `Htif`: a wrapper device that watches `tohost` in RAM (riscv-tests, Sail
+  and Spike-style tests).
+- Python package `mrve32` (abi3 wheels for CPython >= 3.10) with type stubs.
+- `mrve32-snn`: SNN layer accelerator device (behavioural model, spec v0)
+  as a separate crate and Python package, with a NumPy reference model.
+- RISC-V Architectural Certification Tests (ACT4): device configuration
+  (`tests/arch-test/`), `scripts/arch-test.sh` for the Sail flow and for a
+  Sail-free differential flow against QEMU (104 unprivileged tests agree),
+  CI workflow.
+- Verification: 75 riscv-tests (rv32ui/um/ua/uc/mi) on RV32IMAC and RV32IMA,
+  exhaustive decoder tests, cargo-fuzz targets (weekly CI), interpreter
+  throughput benchmark (`cargo bench --bench mips`), MSRV 1.88 checked in CI.

mrve32-0.1.0/Cargo.lock

@@ -0,0 +1,140 @@
+# This file is automatically @generated by Cargo.
+# It is not intended for manual editing.
+version = 4
+
+[[package]]
+name = "heck"
+version = "0.5.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "2304e00983f87ffb38b55b444b5e3b60a884b5d30c0fca7d82fe33449bbe55ea"
+
+[[package]]
+name = "libc"
+version = "0.2.191"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "65cd87c9a6d60536580b316ad985726104730a5151c99845f2490428ef91240a"
+
+[[package]]
+name = "mrve32"
+version = "0.1.0"
+dependencies = [
+ "pyo3",
+]
+
+[[package]]
+name = "mrve32-snn"
+version = "0.1.0"
+dependencies = [
+ "mrve32",
+ "pyo3",
+]
+
+[[package]]
+name = "once_cell"
+version = "1.21.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9f7c3e4beb33f85d45ae3e3a1792185706c8e16d043238c593331cc7cd313b50"
+
+[[package]]
+name = "portable-atomic"
+version = "1.15.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "05c8b63e8d9609db387f0324918f81d68fe27748f084ef092fb35954d0539a85"
+
+[[package]]
+name = "proc-macro2"
+version = "1.0.107"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "985e7ec9bb745e6ce6535b544d84d6cd6f7ad8bd711c398938ae983b91a766d9"
+dependencies = [
+ "unicode-ident",
+]
+
+[[package]]
+name = "pyo3"
+version = "0.30.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "229ca13b8a15bb0d1487b81ab975bfcd97513416499a8312011b6036e42e0de4"
+dependencies = [
+ "libc",
+ "once_cell",
+ "portable-atomic",
+ "pyo3-build-config",
+ "pyo3-ffi",
+ "pyo3-macros",
+]
+
+[[package]]
+name = "pyo3-build-config"
+version = "0.30.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "70130e2b6dd1ee589a8788026a429561ca5c40fa7a2fa7914c2282eddae24700"
+dependencies = [
+ "target-lexicon",
+]
+
+[[package]]
+name = "pyo3-ffi"
+version = "0.30.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "5e7ff73c555c286d212d4ce7e5fbda845a973c4f61bd5f160f5f2c3c2a04d1c4"
+dependencies = [
+ "libc",
+ "pyo3-build-config",
+]
+
+[[package]]
+name = "pyo3-macros"
+version = "0.30.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "c46d2e5862c7bb8207e3b639f713dda3c499933444784154c11d013c5a691b60"
+dependencies = [
+ "proc-macro2",
+ "pyo3-macros-backend",
+ "quote",
+ "syn",
+]
+
+[[package]]
+name = "pyo3-macros-backend"
+version = "0.30.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "38b89f066f2ae72a2aef52d1537ca2fcd104440ebfadee06e97aa90738a25b9b"
+dependencies = [
+ "heck",
+ "proc-macro2",
+ "quote",
+ "syn",
+]
+
+[[package]]
+name = "quote"
+version = "1.0.47"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1fbf4db142a473a8d80c26bbf18454ed458bf8d26c8219c331daecfdbd079001"
+dependencies = [
+ "proc-macro2",
+]
+
+[[package]]
+name = "syn"
+version = "3.0.9"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d78c8dee4c7bf0e14673097256fed6142ce9d3b85a408189d07482442145823b"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "unicode-ident",
+]
+
+[[package]]
+name = "target-lexicon"
+version = "0.13.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "adb6935a6f5c20170eeceb1a3835a49e12e19d792f6dd344ccc76a985ca5a6ca"
+
+[[package]]
+name = "unicode-ident"
+version = "1.0.27"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "a2c754d6c33795a1c324727428e5a7dedb5b06195f9890bdbcba760d3e246563"

mrve32-0.1.0/Cargo.toml

@@ -0,0 +1,30 @@
+[package]
+name = "mrve32"
+version = "0.1.0"
+edition = "2024"
+license = "Apache-2.0"
+description = "RV32IMAC machine-mode RISC-V MCU emulator with pluggable memory-mapped devices"
+rust-version = "1.88"
+repository = "https://github.com/vladimirmitnovitskiy/MRVE32"
+readme = "README.md"
+keywords = ["risc-v", "emulator", "riscv", "microcontroller", "simulator"]
+categories = ["emulators", "simulation", "embedded"]
+# Python package sources, fuzzing and CI files are not part of the crate.
+exclude = ["/python", "/tests/python", "/fuzz", "/.github", "/pyproject.toml", "/modules"]
+
+[workspace]
+exclude = ["fuzz"]
+
+[dependencies]
+pyo3 = { version = "0.30", features = ["extension-module", "abi3-py310"], optional = true }
+
+[features]
+default = []
+# Helpers for device modules that ship as Python packages (capsule export).
+python-device = ["dep:pyo3"]
+# The `mrve32` Python package itself.
+python = ["python-device"]
+
+[[bench]]
+name = "mips"
+harness = false

mrve32-0.1.0/LICENSE

@@ -0,0 +1,52 @@
+ Apache License
+Version 2.0, January 2004
+http://www.apache.org/licenses/
+
+TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+1. Definitions.
+
+"License" shall mean the terms and conditions for use, reproduction, and distribution as defined by Sections 1 through 9 of this document.
+
+"Licensor" shall mean the copyright owner or entity authorized by the copyright owner that is granting the License.
+
+"Legal Entity" shall mean the union of the acting entity and all other entities that control, are controlled by, or are under common control with that entity. For the purposes of this definition, "control" means (i) the power, direct or indirect, to cause the direction or management of such entity, whether by contract or otherwise, or (ii) ownership of fifty percent (50%) or more of the outstanding shares, or (iii) beneficial ownership of such entity.
+
+"You" (or "Your") shall mean an individual or Legal Entity exercising permissions granted by this License.
+
+"Source" form shall mean the preferred form for making modifications, including but not limited to software source code, documentation source, and configuration files.
+
+"Object" form shall mean any form resulting from mechanical transformation or translation of a Source form, including but not limited to compiled object code, generated documentation, and conversions to other media types.
+
+"Work" shall mean the work of authorship, whether in Source or Object form, made available under the License, as indicated by a copyright notice that is included in or attached to the work (an example is provided in the Appendix below).
+
+"Derivative Works" shall mean any work, whether in Source or Object form, that is based on (or derived from) the Work and for which the editorial revisions, annotations, elaborations, or other modifications represent, as a whole, an original work of authorship. For the purposes of this License, Derivative Works shall not include works that remain separable from, or merely link (or bind by name) to the interfaces of, the Work and Derivative Works thereof.
+
+"Contribution" shall mean any work of authorship, including the original version of the Work and any modifications or additions to that Work or Derivative Works thereof, that is intentionally submitted to Licensor for inclusion in the Work by the copyright owner or by an individual or Legal Entity authorized to submit on behalf of the copyright owner. For the purposes of this definition, "submitted" means any form of electronic, verbal, or written communication sent to the Licensor or its representatives, including but not limited to communication on electronic mailing lists, source code control systems, and issue tracking systems that are managed by, or on behalf of, the Licensor for the purpose of discussing and improving the Work, but excluding communication that is conspicuously marked or otherwise designated in writing by the copyright owner as "Not a Contribution."
+
+"Contributor" shall mean Licensor and any individual or Legal Entity on behalf of whom a Contribution has been received by Licensor and subsequently incorporated within the Work.
+
+2. Grant of Copyright License. Subject to the terms and conditions of this License, each Contributor hereby grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable copyright license to reproduce, prepare Derivative Works of, publicly display, publicly perform, sublicense, and distribute the Work and such Derivative Works in Source or Object form.
+
+3. Grant of Patent License. Subject to the terms and conditions of this License, each Contributor hereby grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable (except as stated in this section) patent license to make, have made, use, offer to sell, sell, import, and otherwise transfer the Work, where such license applies only to those patent claims licensable by such Contributor that are necessarily infringed by their Contribution(s) alone or by combination of their Contribution(s) with the Work to which such Contribution(s) was submitted. If You institute patent litigation against any entity (including a cross-claim or counterclaim in a lawsuit) alleging that the Work or a Contribution incorporated within the Work constitutes direct or contributory patent infringement, then any patent licenses granted to You under this License for that Work shall terminate as of the date such litigation is filed.
+
+4. Redistribution. You may reproduce and distribute copies of the Work or Derivative Works thereof in any medium, with or without modifications, and in Source or Object form, provided that You meet the following conditions:
+
+    You must give any other recipients of the Work or Derivative Works a copy of this License; and
+    You must cause any modified files to carry prominent notices stating that You changed the files; and
+    You must retain, in the Source form of any Derivative Works that You distribute, all copyright, patent, trademark, and attribution notices from the Source form of the Work, excluding those notices that do not pertain to any part of the Derivative Works; and
+    If the Work includes a "NOTICE" text file as part of its distribution, then any Derivative Works that You distribute must include a readable copy of the attribution notices contained within such NOTICE file, excluding those notices that do not pertain to any part of the Derivative Works, in at least one of the following places: within a NOTICE text file distributed as part of the Derivative Works; within the Source form or documentation, if provided along with the Derivative Works; or, within a display generated by the Derivative Works, if and wherever such third-party notices normally appear. The contents of the NOTICE file are for informational purposes only and do not modify the License. You may add Your own attribution notices within Derivative Works that You distribute, alongside or as an addendum to the NOTICE text from the Work, provided that such additional attribution notices cannot be construed as modifying the License.
+
+You may add Your own copyright statement to Your modifications and may provide additional or different license terms and conditions for use, reproduction, or distribution of Your modifications, or for any such Derivative Works as a whole, provided Your use, reproduction, and distribution of the Work otherwise complies with the conditions stated in this License.
+
+5. Submission of Contributions. Unless You explicitly state otherwise, any Contribution intentionally submitted for inclusion in the Work by You to the Licensor shall be under the terms and conditions of this License, without any additional terms or conditions. Notwithstanding the above, nothing herein shall supersede or modify the terms of any separate license agreement you may have executed with Licensor regarding such Contributions.
+
+6. Trademarks. This License does not grant permission to use the trade names, trademarks, service marks, or product names of the Licensor, except as required for reasonable and customary use in describing the origin of the Work and reproducing the content of the NOTICE file.
+
+7. Disclaimer of Warranty. Unless required by applicable law or agreed to in writing, Licensor provides the Work (and each Contributor provides its Contributions) on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied, including, without limitation, any warranties or conditions of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A PARTICULAR PURPOSE. You are solely responsible for determining the appropriateness of using or redistributing the Work and assume any risks associated with Your exercise of permissions under this License.
+
+8. Limitation of Liability. In no event and under no legal theory, whether in tort (including negligence), contract, or otherwise, unless required by applicable law (such as deliberate and grossly negligent acts) or agreed to in writing, shall any Contributor be liable to You for damages, including any direct, indirect, special, incidental, or consequential damages of any character arising as a result of this License or out of the use or inability to use the Work (including but not limited to damages for loss of goodwill, work stoppage, computer failure or malfunction, or any and all other commercial damages or losses), even if such Contributor has been advised of the possibility of such damages.
+
+9. Accepting Warranty or Additional Liability. While redistributing the Work or Derivative Works thereof, You may choose to offer, and charge a fee for, acceptance of support, warranty, indemnity, or other liability obligations and/or rights consistent with this License. However, in accepting such obligations, You may act only on Your own behalf and on Your sole responsibility, not on behalf of any other Contributor, and only if You agree to indemnify, defend, and hold each Contributor harmless for any liability incurred by, or claims asserted against, such Contributor by reason of your accepting any such warranty or additional liability.
+
+END OF TERMS AND CONDITIONS

mrve32-0.1.0/PKG-INFO

@@ -0,0 +1,327 @@
+Metadata-Version: 2.4
+Name: mrve32
+Version: 0.1.0
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Rust
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: Implementation :: CPython
+Classifier: Topic :: System :: Emulators
+Classifier: Topic :: System :: Hardware
+Classifier: Typing :: Typed
+Requires-Dist: pytest>=7 ; extra == 'test'
+Provides-Extra: test
+License-File: LICENSE
+Summary: Deterministic RV32IMAC microcontroller emulator with pluggable memory-mapped devices
+Keywords: risc-v,riscv,emulator,microcontroller,testbench
+License-Expression: Apache-2.0
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
+Project-URL: Changelog, https://github.com/vladimirmitnovitskiy/MRVE32/blob/main/CHANGELOG.md
+Project-URL: Issues, https://github.com/vladimirmitnovitskiy/MRVE32/issues
+Project-URL: Repository, https://github.com/vladimirmitnovitskiy/MRVE32
+
+[![Rust](https://img.shields.io/badge/rust-stable%202024-orange.svg)](https://www.rust-lang.org)
+[![Crates.io](https://img.shields.io/crates/v/mrve32.svg)](https://crates.io/crates/mrve32)
+[![Docs.rs](https://docs.rs/mrve32/badge.svg)](https://docs.rs/mrve32)
+[![PyPI](https://img.shields.io/pypi/v/mrve32.svg)](https://pypi.org/project/mrve32/)
+[![License: Apache 2.0](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](LICENSE)
+[![CI](https://github.com/vladimirmitnovitskiy/MRVE32/actions/workflows/ci.yml/badge.svg)](https://github.com/vladimirmitnovitskiy/MRVE32/actions/workflows/ci.yml)
+
+# MRVE32 (Modular RISC-V Emulator 32-bit)
+
+
+**A modular, deterministic RV32IMAC bare-metal microcontroller emulator in Rust, with pluggable devices.**
+
+MRVE32 is a lightweight RV32IMAC emulator designed for bare-metal firmware execution, custom SoC peripheral development, and hardware coprocessor prototyping. The core is a CPU, a memory-mapped I/O (MMIO) bus, RAM, a CLINT and an ELF loader; every other peripheral is a **device module** that anyone can write — in Rust, in Python, or as a separately built native package through a small, versioned C ABI. Python bindings make it a testbench engine.
+
+---
+
+## Key Architecture & Features
+
+- **RV32IMAC + Zicsr + Zifencei**: base integer ISA, multiplication/division, atomics (`lr.w`/`sc.w` and all `amo*.w`), compressed 16-bit instructions (C/Zca), CSR instructions, `fence`/`fence.i`. C can be switched off (`Cpu::set_compressed(false)`, `--isa rv32ima`, `Emulator(compressed=False)`) to model a core without it, with IALIGN = 32 and `misa.C` following it.
+- **Machine-mode privileged architecture**: precise synchronous exceptions (illegal instruction, misaligned jump target, instruction/load/store access faults, `ecall`, `ebreak`) delivered through `mtvec` with `mepc`/`mcause`/`mtval`/`mstatus` updated as hardware does; `mret`.
+- **Interrupts & timer**: machine external, software and timer interrupts with spec priority (MEI > MSI > MTI), direct and vectored `mtvec`, `wfi` that stalls the hart until an interrupt is pending. A CLINT device (`msip`, `mtime`, `mtimecmp`, SiFive memory map) is included; any device can raise interrupt lines through `BusDevice::irq_lines`.
+- **Counters (Zicntr)**: 64-bit `mcycle`/`minstret` with `mcountinhibit`, read-only `cycle`/`instret` shadows; `mhpmcounter*`/`mhpmevent*` are hardwired to zero.
+- **Strict CSR file**: accesses to unimplemented CSRs and writes to read-only CSRs raise illegal-instruction exceptions; WARL fields (`mstatus`, `mtvec`, `mepc`, `mie`, `mip`) are masked. Implemented: `mstatus`, `mstatush`, `misa`, `mie`, `mip`, `mtvec`, `mscratch`, `mepc`, `mcause`, `mtval`, `mcountinhibit`, `mcycle[h]`, `minstret[h]`, `cycle[h]`, `instret[h]`, `mvendorid`, `marchid`, `mimpid`, `mhartid`, `mconfigptr`.
+- **Tested against riscv-tests**: passes all 75 applicable tests from [`riscv-tests`](https://github.com/riscv-software-src/riscv-tests) (`rv32ui-p-*`, `rv32um-p-*`, `rv32ua-p-*`, `rv32uc-p-rvc` and the M-mode `rv32mi-p-*` tests); every test except `rvc` runs both with and without C. The [RISC-V Architectural Certification Tests](tests/arch-test/README.md) (`riscv-arch-test`, ACT4) have a device configuration for MRVE32: the 104 unprivileged tests for RV32IMAC agree with QEMU at every signature point, and CI runs the full Sail-based flow.
+- **Bare-Metal & Deterministic**: Machine mode only, no MMU, virtual memory, or OS overhead.
+- **Modular Bus Architecture**: Devices, RAM, and memory-mapped peripherals implement the `BusDevice` trait. The bus performs offset translation and address routing.
+- **Hardware Coprocessor Slot**: extension point via `trait Coprocessor` (or a Python object, `Emulator.set_coprocessor`) for custom instructions (opcodes `0x0B` and `0x2B`). Register updates are committed atomically and `x0` stays zero.
+- **Unidirectional Ownership**: Clean Rust ownership model (`cpu.step(&mut bus)`). The CPU core maintains zero references to the system bus.
+- **No dependencies**: the core library depends only on Rust `std`.
+- **Standard peripherals**: RAM, CLINT, an NS16550A-compatible UART and a `sifive,test0` test finisher (firmware sets the exit status), in the QEMU `virt` register layout so existing drivers work unchanged.
+- **Command-line runner**: `mrve32 firmware.elf` runs an ELF on a QEMU-virt-like memory map, streams the UART to stdout and exits with the firmware's status; `--trace` prints every instruction (GNU objdump-style disassembler), `--stop-on-trap`, `--max-steps`, double-fault detection; `--htif` and `--signature` for compliance suites (HTIF `tohost`, Sail-format signature dump).
+- **Pluggable devices**: a device is anything implementing `BusDevice` (Rust), a Python object with `read`/`write` methods, or a native module built separately against the device C ABI ([`include/mrve32_device.h`](include/mrve32_device.h), `mrve32::plugin`). Devices get `tick()` time and can raise interrupt lines. See [`docs/devices.md`](docs/devices.md).
+- **Python package (PyO3)**: `pip install`-able `mrve32` module with an `Emulator` class (ELF loading, symbols, breakpoints, run control, instruction tracing, memory/register/CSR access, `map_device`), `Uart`, `TestFinisher` and `disassemble`. Typed (`py.typed` stubs).
+
+### Device modules
+
+| Module | Description |
+|---|---|
+| [`mrve32-snn`](modules/snn) | SNN layer accelerator model (draft v0): LIF/IF neurons, `i16` potentials, `i8` weights, a bit-exact golden model behind a swappable `SnnBackend`, an analytical cycle model, a completion interrupt, and a NumPy reference. [Spec](modules/snn/docs/snn-accelerator-v0.md). |
+
+Modules live in `modules/` for now but depend on the core only through its public API and could be moved to their own repositories unchanged.
+
+### Not implemented (yet)
+
+The `time`/`timeh` CSRs (read `mtime` from the CLINT instead), an interrupt controller (PLIC; the UART drives MEIP directly), User/Supervisor modes, PMP, debug triggers, HTIF/semihosting, the F/D extensions, and Zcb/Zcmp. Atomics assume a single hart: `aq`/`rl` have no effect and a trap clears the LR reservation.
+Build firmware with `-march=rv32imac_zicsr_zifencei -mabi=ilp32` (or any subset, e.g. `rv32imc_zicsr`). Misaligned loads and stores are performed in hardware rather than trapped.
+
+---
+
+## Command-line runner
+
+```bash
+cargo install --path .           # installs the `mrve32` binary
+mrve32 firmware.elf              # UART -> stdout, exit status from the finisher
+mrve32 --trace --max-steps 20 firmware.elf
+mrve32 --htif --signature out.sig test.elf  # Sail/Spike-style tests: HTIF tohost, signature dump
+mrve32 --help
+```
+
+Default memory map (QEMU `virt`-compatible, every address configurable):
+
+| Device | Base | Notes |
+|---|---|---|
+| RAM | `0x8000_0000` | `--ram-size`, default 128 MiB |
+| UART (NS16550A) | `0x1000_0000` | output to stdout; `--input FILE\|-` feeds its receiver |
+| Test finisher (`sifive,test0`) | `0x0010_0000` | write `0x5555` to pass, `(code << 16) \| 0x3333` to fail |
+| CLINT | `0x0200_0000` | `mtime`, `mtimecmp`, `msip` |
+
+Exit status is the firmware's (0–255), or 123 (idle in `wfi` forever),
+124 (`--max-steps`), 125 (usage/load error), 126 (trap with
+`--stop-on-trap`, or a double fault such as running without `mtvec`).
+[`tests/firmware`](tests/firmware) is a minimal freestanding C example
+(startup, linker script, UART, finisher) built by
+`scripts/build-test-firmware.sh`.
+
+---
+
+## Architecture Overview
+
+```text
+        +------------------------------------+
+        |        CPU Core (RV32IMAC)         |
+        |  - 32x Regs (x0 hardwired to zero) |<--- [ Coprocessor Slot ]
+        |  - Program Counter (PC)            |     (Custom opcodes 0x0B, 0x2B)
+        +-----------------+------------------+
+                            | cpu.step(&mut bus)
+        +-----------------v------------------+
+        |             System Bus             |
+        +--------+------------------+--------+
+                |                  |
+        +----------v---------+  +-----v--------------+
+        |        RAM         |  | CLINT, Custom      |
+        | (Little-Endian MM) |  | Peripherals, IRQs  |
+        +--------------------+  +--------------------+
+```
+---
+
+## Rust Usage
+
+Add MRVE32 to your `Cargo.toml`, then use the core:
+
+```rust
+use mrve32::{Bus, BusDevice, Cpu, Ram};
+
+fn main() -> Result<(), Box<dyn std::error::Error>> {
+    let mut bus = Bus::new();
+    let mut ram = Ram::new(1024);
+
+    // Write machine instructions into RAM:
+    // addi x1, x0, 42  (0x02A0_0093)
+    ram.write_u32(0, 0x02A0_0093)?;
+    bus.map_device(0x1000, 1024, Box::new(ram))?;
+
+    let mut cpu = Cpu::new(0x1000);
+
+    // `step` returns `Some(trap)` if the instruction raised an exception.
+    // The trap has already been taken: `pc` points to the `mtvec` handler.
+    if let Some(trap) = cpu.step(&mut bus) {
+        return Err(trap.into());
+    }
+
+    assert_eq!(cpu.read_reg(1), 42);
+    assert_eq!(cpu.pc, 0x1004);
+
+    Ok(())
+}
+```
+
+### Time and interrupts
+
+Each `step` is one clock cycle: the CPU samples `mip` from the bus
+interrupt lines, takes an enabled pending interrupt (or executes one
+instruction), then calls `BusDevice::tick(1)` on every mapped device.
+Map a `Clint` to get `mtime`/`mtimecmp` and software interrupts:
+
+```rust
+use mrve32::devices::clint::CLINT_SIZE;
+use mrve32::{Bus, Clint};
+
+let mut bus = Bus::new();
+// mtime advances once every 10 CPU cycles
+bus.map_device(0x0200_0000, CLINT_SIZE, Box::new(Clint::with_divider(10)))
+    .unwrap();
+```
+
+Custom peripherals raise interrupts by overriding `BusDevice::irq_lines`
+(return a mask of `MIP_MEIP`/`MIP_MSIP`/`MIP_MTIP`) and advance their own
+state in `BusDevice::tick`; see [`docs/devices.md`](docs/devices.md).
+
+---
+## Python Testbenches (PyO3)
+
+Install the `mrve32` package (builds the extension with [maturin](https://www.maturin.rs/);
+needs a Rust toolchain and Python >= 3.10):
+
+```bash
+pip install .                 # or, for development: pip install -e ".[test]"
+```
+
+Run firmware and inspect the machine:
+
+```python
+import mrve32
+
+# RAM at 0x8000_0000 and a CLINT at 0x0200_0000 by default
+# (clint_base=None omits it); add a UART and a test finisher as in QEMU virt.
+emu = mrve32.Emulator(ram_size=1 << 20)
+uart = mrve32.Uart()
+emu.map_device(0x1000_0000, uart)
+emu.map_device(0x0010_0000, mrve32.TestFinisher())
+
+entry = emu.load_elf("firmware.elf")      # path or bytes; sets pc to the entry
+res = emu.run(1_000_000, stop_on_trap=True)
+print(res.reason, res.steps)              # "exit" | "max_steps" | "breakpoint" | "trap" | "idle"
+print(res.exit_code, uart.output())       # finisher status, bytes sent on the UART
+if res.trap:
+    print(hex(res.trap.cause), res.trap.description)
+
+print(emu.regs, hex(emu.pc), emu.cycles, emu.instret)
+emu.add_breakpoint(emu.symbol("main"))
+emu.set_tracer(lambda pc, word, trap: print(hex(pc), mrve32.disassemble(word, pc) if word else trap))
+data = emu.read_bytes(emu.symbol("buffer"), 64)  # raises mrve32.BusError if unmapped
+```
+
+Attach devices: native modules or plain Python objects ([`docs/devices.md`](docs/devices.md)):
+
+```python
+class Gpio:
+    size = 4
+    def __init__(self): self.pins = 0
+    def read(self, offset, width): return self.pins
+    def write(self, offset, width, value): self.pins = value
+
+emu.map_device(0x1000_0000, Gpio())          # Python device
+emu.map_device(0x2000_0000, mrve32.Ram(4096))  # native device
+print(emu.devices)   # [(base, size, name), ...]
+```
+
+Prototype custom instructions (custom-0 `0x0B` / custom-1 `0x2B`) with a Python
+coprocessor; register writes are committed only if `execute` succeeds:
+
+```python
+class Mac:
+    def execute(self, call):              # call: mrve32.CoprocessorCall
+        if call.funct3 != 0:
+            return False                  # illegal instruction trap
+        acc = call.read_reg(call.rd) + call.read_reg(call.rs1) * call.read_reg(call.rs2)
+        call.write_reg(call.rd, acc & 0xFFFF_FFFF)
+        # call.read_u32(addr) / call.write_u32(addr, v): bus access
+        # (an uncaught BusError becomes a load/store access fault);
+        # call.next_pc = target: branch
+
+emu.set_coprocessor(Mac())                # None detaches it
+```
+
+For example, with the SNN module (`pip install ./modules/snn`):
+
+```python
+import numpy as np
+from mrve32 import Emulator
+from mrve32_snn import SnnAccelerator, SnnDriver, reference_step
+
+emu = Emulator()
+emu.map_device(0x1000_0000, SnnAccelerator())
+dev = SnnDriver(emu, 0x1000_0000)
+
+weights = np.random.randint(-128, 128, size=(64, 32), dtype=np.int8)
+dev.load_layer(weights, v_th=100, leak_shift=4)
+
+vmem = np.zeros(32, np.int16)
+for t in range(10):
+    spikes = np.random.rand(64) < 0.2
+    out = dev.step(spikes)                # write inputs, START, wait, read outputs
+    expected, vmem = reference_step(spikes, weights, vmem, v_th=100, leak_shift=4)
+    assert (out == expected).all() and (dev.read_vmem() == vmem).all()
+    print(t, out.sum(), "spikes,", dev.cycles, "cycles")
+```
+
+Run the Python tests:
+
+```bash
+pytest tests/python modules/snn/tests/python
+```
+
+---
+## Verification & Quality Assurance
+
+Run the full test suite (unit tests, README examples, an interrupt-driven firmware test and the riscv-tests suite):
+
+```bash
+cargo test --workspace
+```
+
+Run only the riscv-tests suite (per-test results are printed):
+
+```bash
+cargo test --test compliance -- --nocapture
+```
+
+The test ELF files in `tests/isa/` are built reproducibly from source with a
+pinned `riscv-tests` revision (requires a RISC-V GCC cross toolchain):
+
+```bash
+scripts/build-riscv-tests.sh
+```
+
+RISC-V Architectural Certification Tests (needs a RISC-V GCC; `--qemu` also
+runs every self-checking ELF on QEMU; the Sail-based flow is described in
+[`tests/arch-test/README.md`](tests/arch-test/README.md)):
+
+```bash
+scripts/arch-test.sh local --qemu
+```
+
+Robustness: `tests/decoder_fuzz.rs` runs every 16-bit encoding, every
+opcode/funct3/funct7 combination and a million random words through the
+decoders and the disassembler, and random programs through the CPU.
+Coverage-guided targets for `cargo-fuzz` are in [`fuzz/`](fuzz/README.md)
+(CI runs them weekly). The disassembler was cross-checked against GNU objdump
+2.46: the only differences are encodings the spec reserves on RV32
+(`slli`/`srli`/`srai` with shamt[5] = 1, `c.addi16sp` with immediate 0),
+which objdump decodes and MRVE32 rejects, and the names of C HINT encodings.
+
+Interpreter throughput (MIPS) for a few instruction mixes:
+
+```bash
+cargo bench --bench mips
+```
+
+Run static analysis and linter checks:
+
+```bash
+cargo clippy --workspace --all-targets --all-features -- -D warnings
+```
+
+The minimum supported Rust version (MSRV) is **1.88** (checked in CI).
+Changes are listed in [`CHANGELOG.md`](CHANGELOG.md).
+---
+## License
+
+Licensed under Apache License, Version 2.0.
+